Agent SDK: construir agentes con Claude

En la lección 4 escribiste un bucle de veinte líneas: llamar a la API, ejecutar herramientas, devolver resultados y repetir. Es un agente. Pero en cuanto lo llevas a producción aparecen las preguntas incómodas: ¿quién lee ficheros y ejecuta comandos con seguridad?, ¿cómo evitas que el contexto reviente en la tarea número cuarenta?, ¿cómo retomas una sesión que se cortó?, ¿dónde pones los permisos?

El Claude Agent SDK responde a eso dándote el mismo bucle que usa Claude Code, como librería de Python o TypeScript. Es el corazón del dominio 1 (Agents and Workflows, un 14,7 %), y la guía no solo pregunta cómo se usa, sino cuándo merece la pena un agente y cuándo sobra.

Workflow o agente: la primera decisión

Anthropic distingue dos formas de construir sistemas con modelos, y el examen lo pregunta con escenarios:

Workflow

Los pasos los decide tu código

• Rutas predefinidas: extraer, validar, clasificar, guardar
• Predecible, fácil de probar y de auditar
• Coste y latencia acotados
• Encaja cuando la tarea se puede descomponer de antemano

Agente

Los pasos los decide el modelo

• Claude elige qué herramienta usar y cuándo parar, según lo que va encontrando
• Flexible ante problemas abiertos y caminos imprevisibles
• Más coste, más latencia y errores que se acumulan
• Exige límites, permisos y observabilidad desde el primer día

El consejo oficial: empieza por lo más simple que funcione y añade autonomía solo cuando la tarea la pida.

Un ejemplo SAP. Clasificar cada factura entrante y proponer su cuenta contable es un workflow: siempre los mismos pasos. Investigar por qué un pedido lleva tres semanas bloqueado, mirando entradas de mercancía, facturas, bloqueos y correos del proveedor sin saber de antemano dónde está el problema, pide un agente.

Los patrones de workflow más citados en el artículo de Anthropic Building effective agents son el encadenado de prompts, el enrutado (un paso clasifica y manda a un flujo especializado), la paralelización, el orquestador con trabajadores y el evaluador que revisa y pide correcciones. El orquestador con trabajadores es también la base de las jerarquías supervisor y subagentes que menciona la guía.

El bucle del Agent SDK por dentro

El SDK se instala con pip install claude-agent-sdk o npm install @anthropic-ai/claude-agent-sdk, y se autentica con una clave de API (ANTHROPIC_API_KEY) o con Bedrock, Vertex AI o Foundry. Una advertencia de la documentación que sale en preguntas de seguridad: salvo aprobación previa, un producto de terceros construido con el SDK no puede ofrecer el inicio de sesión ni los límites de uso de claude.ai; va con clave de API.

Recorre una ejecución:

1. initArranca la sesión→
2. TurnoClaude decide→
3. HerramientasEl SDK ejecuta→
4. RepiteHasta que no pida más→
5. ResultCierre con cuentas

Claude recibe tu prompt, el system prompt, las herramientas y el historial. El SDK emite un SystemMessage de subtipo init con los datos de la sesión.

1 de 5

←Siguiente →

Eso es lo que te ahorras: herramientas integradas (Read, Edit, Bash, Glob, Grep, WebSearch…), permisos, compactación automática, sesiones y hooks. Tú pones el objetivo, las herramientas propias y los límites.

Un agente con herramienta propia, subagente y hook

Así queda un agente que investiga pedidos bloqueados. La herramienta propia se registra como servidor MCP en proceso, el subagente trabaja con su propio contexto y un hook impide escribir en ficheros de configuración:

import asyncio
from claude_agent_sdk import (
    query, tool, create_sdk_mcp_server, ClaudeAgentOptions,
    AgentDefinition, HookMatcher, ResultMessage,
)

from sap_cliente import leer_pedido  # tu código, sobre una API publicada de SAP


@tool("consultar_pedido", "Devuelve estado, proveedor y bloqueos de un pedido de compra de S/4HANA. Solo lectura.",
      {"numero_pedido": str})
async def consultar_pedido(args):
    datos = leer_pedido(args["numero_pedido"])
    return {"content": [{"type": "text", "text": str(datos)}]}

sap = create_sdk_mcp_server(name="sap", version="1.0.0", tools=[consultar_pedido])


async def proteger_config(input_data, tool_use_id, context):
    ruta = input_data["tool_input"].get("file_path", "")
    if "/config/" in ruta:
        return {"hookSpecificOutput": {
            "hookEventName": input_data["hook_event_name"],
            "permissionDecision": "deny",
            "permissionDecisionReason": "La configuración no se toca desde el agente",
        }}
    return {}


async def main():
    opciones = ClaudeAgentOptions(
        model="claude-opus-5-5",
        mcp_servers={"sap": sap},
        allowed_tools=["Read", "Grep", "Glob", "Agent", "mcp__sap__consultar_pedido"],
        agents={
            "lector-logs": AgentDefinition(
                description="Busca en los logs de interfaz errores relacionados con un pedido. Úsalo para exploraciones largas.",
                prompt="Revisa los logs y devuelve solo las líneas relevantes con su fecha.",
                tools=["Read", "Grep", "Glob"],
                model="haiku",
            )
        },
        hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[proteger_config])]},
        max_turns=30,
        max_budget_usd=2.0,
    )
    async for mensaje in query(prompt="¿Por qué está bloqueado el pedido 4500012345?", options=opciones):
        if isinstance(mensaje, ResultMessage):
            print(mensaje.subtype, mensaje.result, mensaje.session_id)

asyncio.run(main())

Lo que el examen quiere que veas en este código:

• Herramientas propias como MCP en proceso. @tool define nombre, descripción y esquema; create_sdk_mcp_server las envuelve; su nombre completo es mcp__<servidor>__<herramienta>. Se autorizan en allowed_tools, igual que un servidor MCP externo de la lección 5.
• Subagentes con contexto aislado. Se declaran con AgentDefinition y Claude los invoca a través de la herramienta Agent, que tiene que estar permitida. El subagente usa un modelo más barato y solo herramientas de lectura: la exploración pesada no ensucia el contexto del agente principal.
• Hooks en código. La misma idea que en Claude Code, pero como función de tu aplicación. Un PreToolUse que devuelve deny bloquea la acción pase lo que pase en el prompt.
• Límites explícitos. max_turns y max_budget_usd cortan el bucle; sin ellos, no hay límite por defecto.

Un agente construido con el Agent SDK debe poder borrar ficheros temporales, pero nunca nada fuera de /tmp/trabajo. ¿Dónde pones ese control?

En el system prompt, con la lista de carpetas prohibidasEn un hook PreToolUse que revise la ruta y devuelva deny si está fuera de /tmp/trabajoEn max_turns, para que no le dé tiempo a borrar demasiadoEn la descripción del subagente

Memoria, contexto y sesiones

Un agente largo tiene tres problemas de memoria, y el SDK da una respuesta para cada uno:

• Dentro de una ejecución, el contexto crece con cada resultado de herramienta. La compactación automática resume lo antiguo al acercarse al límite; puedes decir en CLAUDE.md qué debe conservar el resumen. Y los subagentes mantienen fuera lo que no hace falta arrastrar.
• Entre ejecuciones, las sesiones: guarda el session_id del ResultMessage y retoma con resume, o usa continue_conversation=True para seguir con la última sesión del directorio. También se puede bifurcar una sesión para probar otro camino sin perder la original.
• Conocimiento duradero, lo que debe saber siempre: CLAUDE.md y Skills, que el SDK carga desde el sistema de ficheros según setting_sources. Si pasas una lista vacía, el agente arranca sin leer la configuración de usuario ni de proyecto, que es lo que quieres cuando necesitas un comportamiento reproducible.

Agent SDK, bucle propio o Managed Agents

La guía pide distinguir los modelos de despliegue: autoalojado frente a alojado por Anthropic. Hay tres caminos principales:

1Control máximo

Client SDK y tu propio bucle

Llamas a la Messages API y escribes el bucle (o usas el Tool Runner en beta). Tú defines cada herramienta y cada paso. Ideal para workflows y agentes pequeños sin acceso a ficheros ni terminal.

2Autoalojado

Claude Agent SDK

El bucle de Claude Code como librería, en un proceso que tú operas: herramientas integradas, permisos, hooks, sesiones y compactación. Tú pones la infraestructura y el aislamiento.

3Alojado por Anthropic

Claude Managed Agents

Arnés de agente ya hecho en infraestructura de Anthropic (beta, cabecera managed-agents-2026-04-01). Defines agente, entorno y sesión por API; el sandbox puede ser de Anthropic o autoalojado. Pensado para tareas largas y asíncronas.

Los frameworks que cita la guía (Strands, LangGraph, PydanticAI) son capas de abstracción para montar agentes y workflows de varios pasos; pueden usar Claude por debajo. El examen no pide dominar su API, sino saber que existen y cuándo compensa una abstracción frente al SDK oficial o a tu propio bucle.

Para el examen

Dominio · D1 Agents and Workflows (Architecture, Construction, Patterns) · D6 Context Engineering

Lo que tienes que dominar

• ✓Workflow: pasos definidos por el código. Agente: el modelo decide pasos y herramientas. Empieza por lo simple.
• ✓El Agent SDK da el bucle de Claude Code: herramientas integradas, permisos, hooks, sesiones y compactación.
• ✓Herramientas propias con @tool y create_sdk_mcp_server; se llaman mcp__servidor__herramienta y se autorizan en allowed_tools.
• ✓Subagentes con AgentDefinition, invocados por la herramienta Agent: contexto aislado y herramientas limitadas.
• ✓max_turns y max_budget_usd no tienen límite por defecto; el ResultMessage indica por qué terminó.
• ✓Autoalojado (Agent SDK) frente a alojado por Anthropic (Managed Agents, beta).

Donde se suele fallar

• ✕Elegir un agente autónomo para una tarea de pasos fijos.
• ✕Poner las restricciones de seguridad solo en el prompt en lugar de en hooks y permisos.
• ✕Olvidar permitir la herramienta Agent y esperar que se usen los subagentes.
• ✕Ofrecer el login de claude.ai en un producto propio hecho con el SDK.

Checklist para el examen

0 de 6 dominados

Marca lo que ya sabrías responder en el examen.

• Sé decidir entre workflow y agente según el escenario.
• Conozco los patrones de workflow y la jerarquía supervisor y subagentes.
• Sé qué pasa en cada turno del bucle y qué trae el `ResultMessage`.
• Sé añadir herramientas propias, subagentes y hooks en el Agent SDK.
• Sé gestionar contexto y memoria: compactación, subagentes, sesiones y `setting_sources`.
• Distingo bucle propio, Agent SDK y Managed Agents.

Siguiente parada

Próxima lección: poner en producción. Elegir modelo por coste y latencia, prompt caching y batch con números, límites de tasa, observabilidad, evals, depuración de fallos y gestión de claves y secretos.