Claude Platform 101 — Resumen de estudio

Paths: Developer · Architect · FDE · 14 lecciones, 13 videos

Construir sobre la Claude Platform (API) desde la primera llamada hasta los managed agents. (El quiz final no lo has presentado; hazlo en Skilljar.)

1. Qué es la Claude Platform

• La infraestructura de Anthropic para usar Claude por código: REST API, SDKs, CLIs y la Console (API keys, uso, managed agents, pruebas de prompts).
• Tres capas: "build with primitives, scale on infrastructure, run with control".
  • Primitives: Messages API, tool use, files, web search, code execution, MCP servers, Skills.
  • Infrastructure: managed agents, retries, colas, observabilidad.
  • Controls: dashboards, evals.
• La idea: pasar de "le pregunto algo a Claude" a "Claude es parte de mi producto" (p. ej. un botón que redacta la respuesta a un ticket de soporte con Haiku y un system prompt con el tono del equipo).

2. Primera llamada

• API key desde platform.claude.com (requiere comprar créditos) → guárdala en .env.local, nunca en el código. Instala con npm install @anthropic-ai/sdk.
• messages.create: model + max_tokens + messages (roles user/assistant) + system opcional para el rol o persona.
• response.content es un array de bloques (text, tool_use, thinking…): recórrelo y revisa block.type.
• El mismo patrón, dentro de un route handler, es el motor de un endpoint de "resumir".

3. Elegir modelo

• Fable (por encima de Opus, bastante más caro) · Opus (razonamiento profundo; el más lento y caro de los tres principales) · Sonnet (el punto medio, sirve para casi toda producción) · Haiku (volumen: clasificar, extraer, enrutar).
• Haz un eval simple antes de producción: 20–30 ejemplos reales, empieza por Haiku y sube solo si la calidad no alcanza.
• El modelo correcto es el más barato cuya salida de verdad publicarías.
• response.usage devuelve los tokens de input y output (es lo que se factura).
• Enruta por tarea en un mismo endpoint: clasificar con Haiku, borradores con Sonnet, respuestas a RFPs con Opus.

4. El agent loop

• Agente: Claude en un loop de observar, decidir, actuar y repetir, sin un humano en medio.
• Loop:
  1. Envías mensajes + tools.
  2. Si stop_reason == "tool_use", ejecutas cada bloque tool_use (run_tool).
  3. Añades la respuesta del asistente + los tool_result (tool_use_id = block.id) como mensaje user.
  4. Repites hasta end_turn.
• "Tú controlas el loop y las tools; Claude, el razonamiento." El mismo loop escala de una demo del clima a un agente de compliance que transmite por SSE y guarda resultados en la base de datos.

5. Tool use

• Una tool es una función que tú defines; Claude decide cuándo llamarla y tu código la ejecuta.
• JSON schema: name, description, input_schema. Una descripción vaga es la causa nº 1 de agentes que fallan.
• Varias tools: despacha por nombre (switch). Claude elige según la descripción (get_weather = hoy vs get_forecast = próximos días), a veces en el mismo turno.
• Tool runner (SDK de TypeScript, Python y Ruby): genera el schema a partir de tus funciones y maneja todo el loop. client.beta.messages.toolRunner({... tools:[getWeather, getForecast]}) → runner.untilDone().

6. Extended thinking

• Claude razona paso a paso antes de responder y el razonamiento es visible.
• Opus 4.7: adaptive → thinking={"type":"adaptive"}, sin presupuesto de tokens. La profundidad se controla con effort dentro de output_config (no junto a thinking): low · medium · high (default) · xhigh · max.
• Úsalo en matemáticas o lógica de varios pasos, debugging, análisis regulatorio y trade-offs. Omítelo en clasificar, extraer o código repetitivo (solo añade latencia y costo).

7. Tools integradas

• Server tools (las ejecuta Anthropic, sin loop; el resultado viene en la misma respuesta):
  • Web search (web_search_20260209, con citas).
  • Code execution (code_execution_20260120, Python en sandbox).
  • Web fetch.
  • Bloques nuevos: server_tool_use y bash_code_execution_tool_result.
• Client tools (corren donde corre tu código, pero el SDK trae el schema y el runner): Memory y Bash.
• ⚠️ Que algo esté en internet no lo hace cierto: verifica.

8. Skills en la API

• Tools = qué puede hacer Claude; Skills = cómo quieres que lo haga (un procedimiento: plantilla de reporte, checklist).
• Carga progresiva: primero solo el nombre y la descripción.
• Se suben una vez con client.beta.skills.create(display_title=..., files=...) → skill.id.
• Se adjuntan con client.beta.messages.create(..., betas=["skills-2025-10-02","code-execution-2025-08-25"], container={"skills":[{"type":"custom","skill_id":id,"version":"latest"}]}, tools=[code_execution]).
  • container.skills es una lista (puedes apilar varios).
  • Se combinan bien con code execution.

9. MCP en la API

• Por qué existe: que el proveedor mantenga la integración (Asana, Slack y Google publican sus servidores).
• "Las tools son para tus cosas, los Skills para tus procesos y MCP para las cosas de los demás."
• mcp_servers=[{"type":"url","url":"https://mcp.linear.app/mcp","name":"linear","authorization_token":...}] + tools=[{"type":"mcp_toolset","mcp_server_name":"linear"}] + betas=["mcp-client-2025-11-20"]. Claude descubre las tools solo.
• Limitar tools: default_config: {"enabled": False} + configs: {"search_messages": {"enabled": True}, ...} (p. ej. Slack en solo lectura).

10. Manejo de contexto (4 patrones)

• El contexto incluye: system prompt, historial, definiciones y resultados de tools, archivos, Skills y bloques de thinking. Lo pagas, y si se llena, el request falla.
• Just-in-time: carga lo necesario y deja que las tools traigan el resto (es un patrón de diseño).
• Compactación del lado del servidor: context_management={"edits":[{"type":"compact"}]}; resume al pasar un umbral.
• Prompt caching: las partes estables (system, tools, documentos) a una fracción del costo.
• Memory tool: Claude lee y escribe un directorio de memoria; tú implementas el almacenamiento. Anthropic inyecta la instrucción de revisarlo al empezar.
• Se suelen combinar. Los managed agents traen caching y compactación activados por defecto.

11. Managed Agents

• El agent loop alojado por Anthropic: contenedor aislado con filesystem, bash y web search. Habilitado por defecto en todas las cuentas de API.
• Bloques: agents, sessions, environments, tools (también custom de tu backend), MCP, memory store, outcomes (rúbricas + un grader aparte que evalúa y Claude itera), coordinación multi-agente y políticas de permisos (acciones sensibles esperan a un humano).
• Ejemplos:
  • Un tablero Kanban: el ticket pasa a "in progress" → sesión → Lighthouse llega a 96 con la rúbrica. Corren en paralelo.
  • Un investigador de precios SaaS con memoria (compara con la semana anterior).
  • Respuesta a incidentes: coordinador + 3 especialistas, con aprobación antes de publicar en Slack.
• Los 4 primitives en orden:
  1. Agent: modelo + system + toolset; reutilizable.
  2. Environment: cloud o local, red.
  3. Session: una ejecución, la unidad de trabajo.
  4. Events: lo que entra y sale. No hay un while: envías y lees eventos.

agent = client.beta.agents.create(name=..., model=..., system=..., tools=[{"type":"agent_toolset_20260401","default_config":{"enabled":True}}])
env = client.beta.environments.create(name=..., config={"type":"cloud","networking":{"type":"unrestricted"}})
session = client.beta.sessions.create(agent=agent.id, environment_id=env.id, title=...)
with client.beta.sessions.events.stream(session_id=session.id) as stream:   # ABRE EL STREAM PRIMERO
    client.beta.sessions.events.send(session_id=session.id, events=[{"type":"user.message","content":[...]}])
    for e in stream: # agent.message · agent.tool_use · session.status_idle (= terminó)

• ⚠️ El stream solo entrega los eventos posteriores a su apertura: ábrelo antes de enviar el primer mensaje.
• Cuándo usarlos: loops largos (minutos u horas), muchos archivos, que deben sobrevivir a cortes de red. Si quieres control total, usa un loop manual.

12. Construir con Claude Code

• Skill integrado Claude API (/claude-api, o se activa solo al detectar el SDK). Si falta: /plugin marketplace add AnthropicsSkills (con "s").
• Un buen prompt nombra el archivo, el patrón y el estado final. Claude Code completa el código, lo ejecuta y corrige errores.
• El patrón de casi todo: define una tool → pásala a un runner → devuelve el resultado. "Haz el esqueleto, delega y revisa el diff."