Agent SDK: construir agentes autónomos con Claude

Hasta ahora has aprendido a llamar a Claude puntualmente: envías un mensaje, obtienes una respuesta y cierras. Pero en la práctica, muchas aplicaciones necesitan que Claude actúe de forma más autónoma: que tome decisiones, llame herramientas, evalúe resultados y decida si seguir adelante o cambiar de estrategia. Eso es un agente.

El Agent SDK de Anthropic es el marco oficial para construir agentes que usan Claude como razonador central. A diferencia de orquestaciones manuales o frameworks genéricos, el Agent SDK está diseñado específicamente para el modelo Claude y sus capacidades: tool use robusto, razonamiento extendido y manejo eficiente de contexto.

En esta lección descubrirás cómo funciona un agente, qué problemas resuelve, cómo organizar subagentes y cuándo conviene usar un agente frente a una simple llamada a la API.

Qué es el Agent SDK y por qué lo necesitas

El Agent SDK es una librería que encapsula el patrón de ejecución de agentes: un bucle donde Claude razona, usa herramientas, recibe resultados y decide si continuar, cambiar de dirección o terminar.

Sin Agent SDK, implementarías este bucle manualmente:

while True:
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1024,
        tools=[...],
        messages=messages
    )
    if response.stop_reason == "tool_use":
        # Procesa cada tool use
        # Añade resultados a messages
        # Continúa el bucle
    else:
        break

Con Agent SDK, delegas esa lógica repetitiva:

from anthropic import Anthropic

client = Anthropic()
agent = client.agents.create(
    model="claude-3-5-sonnet-20241022",
    tools=[...],
    name="analyzer"
)

response = client.agents.run(
    agent_id=agent.id,
    input="Analiza esto"
)

El SDK maneja automáticamente el bucle, el manejo de tool_use/tool_result, reintentos y transiciones de estado. Esto es especialmente valioso si tu agente usa múltiples herramientas, tiene lógica condicional compleja o necesita escalar a múltiples agentes.

El bucle de un agente: razonamiento, acción y reflexión

Todo agente sigue un ciclo fundamental:

Razonamiento: Claude recibe el estado actual (mensajes, contexto, herramientas disponibles) y decide qué hacer.
Acción: Claude puede:
- Llamar a una herramienta (via tool_use)
- Responder directamente (stop_reason == "end_turn")
- Pedir más información
Reflexión y retroalimentación: Los resultados de las herramientas vuelven al contexto como tool_result. Claude los analiza y decide si necesita más información, llamar otra herramienta o finalizar.

Ejemplo de ciclo en producción:

Supongamos un agente de compras que debe reservar un vuelo:

Iteración 1: Claude recibe "Reserva un vuelo a Madrid el 15 de marzo"
- Razona: "Necesito verificar disponibilidad"
- Acción: Llama a search_flights con parámetros
- Resultado: Le devuelven 3 opciones
Iteración 2: Claude ve las opciones
- Razona: "Tengo opciones, pero necesito confirmar el presupuesto"
- Acción: Llama a check_user_budget
- Resultado: Usuario tiene máximo 800€
Iteración 3: Claude ve presupuesto
- Razona: "Una opción encaja. Puedo reservar"
- Acción: Llama a confirm_booking
- Resultado: Éxito, ID de reserva
Iteración 4: Claude finaliza
- stop_reason == "end_turn"
- Respuesta al usuario con resumen

El Agent SDK automatiza este ciclo, incluyendo reintentos en caso de fallos de herramientas, límites de iteraciones para evitar bucles infinitos y contexto persistente.

Subagentes: divide y conquista

A menudo un problema es demasiado complejo para un único agente. El Agent SDK permite crear subagentes: agentes especializados que otros agentes pueden delegar trabajo.

Ejemplo de arquitectura con subagentes:

Un agente principal de "Gestor de proyectos" que delega a:

Subagente "Planificador": desglosa tareas
Subagente "Asignador": asigna a equipos
Subagente "Monitor": verifica progreso

Cada subagente tiene:

Su propio modelo (mismo o distinto)
Sus propias herramientas especializadas
Su contexto independiente
Su memoria o estado

Ventajas:

Claridad: Cada agente responsable de un dominio
Escala: Puedes escalar subagentes en paralelo
Mantenibilidad: Cambias un subagente sin tocar otros
Costo: Reutilizas subagentes; no repites trabajo

# El gestor usa el resultado del planificador
planner_agent = client.agents.create(
    model="claude-3-5-sonnet-20241022",
    tools=[create_task, estimate_effort],
    name="planner"
)

manager_agent = client.agents.create(
    model="claude-3-5-sonnet-20241022",
    tools=[
        {"name": "delegate_to_planner", "agent_id": planner_agent.id},
        assign_team
    ],
    name="manager"
)

La clave está en que el gestor recibe la salida del planificador como un tool_result, la integra en su contexto y continúa su razonamiento.

Memoria y contexto en agentes

Un agente que olvida lo que hizo hace 3 iteraciones es inútil. La memoria es crítica.

Memoria de sesión (corto plazo)

Todos los mensajes intercambiados en el bucle del agente se mantienen en messages. El Agent SDK gestiona esto automáticamente.

# El SDK mantiene este contexto entre iteraciones
messages = [
    {"role": "user", "content": "Reserva un vuelo"},
    {"role": "assistant", "content": "Voy a buscar opciones...", "tool_use": [...]},
    {"role": "user", "content": "tool_result: [opciones]"},
    # El agente recuerda todo esto
]

Memoria persistente (largo plazo)

Si tu agente debe recordar decisiones entre sesiones distintas (usuario vuelve mañana), necesitas una base de datos o sistema externo:

Herramienta especializada: Tu agente llama a save_decision o load_history
MCP resource: Conectas una base de datos via MCP (ej: SQLite resource)
Contexto en el system prompt: Inyectas resumen de sesiones anteriores

# Inyectar memoria persistente en el system prompt
system_prompt = """Eres un asesor de compras. 
Historial del usuario:
- Compra promedio: 500€
- Preferencia: marcas sostenibles
- Última compra: 2024-01-15

Usa esta información para personalizar recomendaciones."""

Gestión de contexto en agentes grandes

Con muchas iteraciones, el contexto crece. Estrategias:

Truncamiento: Mantén solo las últimas N iteraciones (perdes historia)
Resumen: Cada N iteraciones, pide a Claude que resuma (es una iteración extra)
Prompt caching: Cachea el historial; Claude reutiliza embeddings (ves beneficio en segundas llamadas)

Cuándo usar un agente vs. un flujo simple

No todo necesita un agente. A veces una llamada directa a Claude o un flujo orquestado es mejor.

Usa un agente si:

El problema es iterativo: Necesitas múltiples pasos con retroalimentación
El agente elige el siguiente paso: No está predefinido en tu código
Hay incertidumbre: No sabes de antemano cuántas herramientas necesitarás
Escalas a múltiples agentes: Quieres delegación entre especializados
El usuario espera autonomía: Quieres que Claude sea "proactivo"

Ejemplos:

✅ Análisis de datos complejos (buscar fuentes, procesarlas, validar)
✅ Soporte técnico (diagnóstico iterativo)
✅ Planificación de proyectos
✅ Investigación de mercado

Usa un flujo simple (llamada directa) si:

Es determinista: Los pasos están claros desde el inicio
Una o dos herramientas: No hay decisión de razonamiento
Baja latencia crítica: El bucle del agente añade latencia
Costo un factor: Cada iteración extra cuesta tokens
Contexto pequeño: Poca información para que Claude razone

Ejemplos:

✅ Traducción de texto
✅ Extracción de datos (una estructura conocida)
✅ Formato de salida JSON
✅ Moderación de contenido

Matriz de decisión

Aspecto	Agente	Flujo Simple
Pasos iterativos	✅	❌
Lógica condicional compleja	✅	Parcial
Latencia baja (< 100ms)	❌	✅
Presupuesto ajustado	❌	✅
Autonomía del agente	✅	❌

Para el examen

El examen Claude Certified Developer – Foundations valida que domines:

Concepto de agente: Entiendes el bucle de razonamiento-acción-reflexión y cuándo es necesario frente a una llamada simple.
Agent SDK API: Sabes crear un agente, ejecutarlo, gestionar herramientas y obtener resultados.
Subagentes y delegación: Entiende cómo un agente delega a otro y cómo se integran los resultados en el contexto.
Gestión de memoria: Reconoces cómo la API mantiene el contexto entre iteraciones y cómo añadir memoria persistente.
Decisiones de diseño: Sabes cuándo usar Agent SDK vs. orquestación manual vs. llamada simple, y puedes justificarlo en contextos reales.

Preguntas típicas del examen:

"¿Cuándo es más eficiente usar un agente que una llamada directa?"
"¿Cómo gestiona el Agent SDK el bucle de tool_use/tool_result?"
"¿Qué es un subagente y cuándo lo usarías?"
"Dada una arquitectura, identifica si debería haber uno o múltiples agentes"

Para recordar

El Agent SDK encapsula el bucle: Razonamiento → Acción (herramientas) → Reflexión → Repetir. No tienes que implementarlo manualmente.
Los subagentes permiten especialización y delegación: Un agente complejo es más mantenible si se divide en agentes especializados con contexto e herramientas propios.
La memoria de sesión es automática; la persistencia no: El SDK mantiene messages entre iteraciones, pero para recordar entre sesiones necesitas una herramienta externa o inyección en el system prompt.
No todo es un agente: Usa agentes para problemas iterativos con razonamiento; usa flujos simples para pasos deterministas, baja latencia o presupuesto ajustado.

Próxima lección: Poner en producción: coste, límites y evaluación