Claude Agent SDK

Claude Agent SDK es la librería oficial de Anthropic para construir agentes autónomos sobre Claude usando la misma infraestructura que mueve Claude Code. En lugar de programar tú el bucle de llamadas a la API, la ejecución de herramientas y la gestión del contexto, el SDK te lo da resuelto y tú defines el objetivo, las herramientas permitidas y los límites. Nació como Claude Code SDK y se renombró cuando quedó claro que servía para mucho más que programar.

Cómo funciona

El núcleo es el bucle de agente: Claude recibe una tarea, decide qué herramienta usar, el SDK la ejecuta, devuelve el resultado al modelo y el ciclo se repite hasta que la tarea termina. Sobre ese bucle el SDK aporta piezas que en un desarrollo desde cero tendrías que construir tú:

• Herramientas integradas: leer, escribir y editar archivos, ejecutar comandos en terminal, buscar con patrones (Glob, Grep) y consultar la web.
• Herramientas propias: funciones de tu código expuestas al agente, normalmente como servidores MCP, ya sea en el mismo proceso o externos.
• Gestión de contexto: compactación automática cuando la conversación se acerca al límite de la ventana de contexto.
• Permisos y hooks: qué herramientas puede usar el agente, cuándo debe pedir confirmación y qué código se ejecuta antes o después de cada acción.
• Subagentes, skills y sesiones: delegar subtareas con contexto aislado, cargar capacidades empaquetadas y retomar conversaciones.

Se instala como claude-agent-sdk en Python o @anthropic-ai/claude-agent-sdk en TypeScript, y se autentica con una clave de la API de Anthropic o a través de proveedores cloud compatibles.

Por qué importa

La diferencia con usar la API de Messages directamente es de alcance. Con la API tienes llamadas sueltas y tú orquestas todo: el bucle, el reintento, el estado, la ejecución segura de comandos. Con el Agent SDK partes de un agente probado en producción por miles de developers y te concentras en la lógica de negocio. Eso acorta semanas de trabajo en agentes de soporte, investigación, revisión de código, automatización de operaciones o análisis de documentos. La contrapartida: el agente actúa sobre un entorno real (sistema de archivos, terminal), así que diseñar bien permisos y aislamiento deja de ser opcional.

Ejemplo mínimo

Un agente de solo lectura que revisa un repositorio:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        system_prompt="Eres un revisor de seguridad estricto.",
        allowed_tools=["Read", "Grep", "Glob"],
    )
    async for message in query(
        prompt="Revisa src/ y lista riesgos de seguridad",
        options=options,
    ):
        print(message)

asyncio.run(main())

Al limitar allowed_tools a lectura, el agente puede explorar el código pero no modificarlo ni ejecutar comandos. Para conversaciones de varios turnos con estado se usa el cliente persistente del SDK en lugar de query(). Si quieres profundizar en cómo construir agentes que se integran vía MCP con sistemas externos, es el siguiente paso natural tras dominar este patrón.

Errores comunes

• Confundirlo con la API de Messages: el SDK funciona sobre ella, pero añade orquestación, herramientas y contexto. No es un simple cliente HTTP.
• Pensar que solo sirve para código: hereda de Claude Code, pero el patrón de dar al agente un entorno y herramientas sirve para cualquier flujo de trabajo.
• Dar todos los permisos por comodidad: un agente con terminal sin restricciones y entrada no confiable es una superficie de ataque. Empieza con lo mínimo y amplía.
• Confundirlo con Agent Skills: las skills son capacidades empaquetadas que el agente carga; el SDK es el motor que las ejecuta.