Capítulo 1: Introducción al Claude Agent SDK

¿Qué es el Claude Agent SDK?

El Claude Agent SDK (anteriormente Claude Code SDK) permite construir agentes de IA autónomos que pueden:

• Leer y escribir archivos
• Ejecutar comandos de terminal
• Buscar en el código y la web
• Editar código de forma inteligente
• Orquestar flujos de trabajo complejos

Es la misma tecnología que potencia Claude Code, disponible como biblioteca para Python y TypeScript.

Agent SDK vs Client SDK

flowchart LR
    subgraph ClientSDK["CLIENT SDK (Anthropic SDK)"]
        P1[prompt] --> Claude1[Claude API]
        Claude1 --> TL["TÚ implementas<br/>el tool loop"]
        TL --> P1
    end

flowchart LR
    subgraph AgentSDK["AGENT SDK"]
        P2[prompt] --> Agent["Claude + Tools<br/>(Loop automático)"]
        Agent --> Exec["Ejecuta herramientas<br/>automáticamente"]
    end

Diferencias Clave

Característica	Client SDK	Agent SDK
Tool Loop	Tú lo implementas	Automático
Herramientas	Defines todo	Built-in + custom
Complejidad	Mayor control	Más simple
Caso de uso	APIs, chat	Automatización

Código Comparativo

# CLIENT SDK: Implementas el tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = tu_executor_de_tools(response.tool_use)
    response = client.messages.create(tool_result=result, ...)

# AGENT SDK: Claude maneja todo automáticamente
async for message in query(prompt="Corrige el bug en auth.py"):
    print(message)

Ciclo de Retroalimentación del Agente

El Agent SDK implementa un patrón de feedback loop:

flowchart TD
    A["RECOGER CONTEXTO"] --> B["TOMAR ACCIÓN"]
    B --> C["VERIFICAR TRABAJO"]
    C --> D{"¿Listo?"}
    D -->|No| A
    D -->|Sí| E["RESULTADO"]

¿Cuándo Usar el Agent SDK?

Usa Agent SDK para:

• CI/CD Pipelines: Automatizar revisiones, fixes, deployments
• Aplicaciones de automatización: Bots que procesan archivos
• Agentes de soporte: Análisis de logs, diagnósticos
• Investigación: Análisis de código, documentación
• Refactors masivos: Migraciones de código a gran escala

Usa Client SDK para:

• Chatbots simples: Conversación sin herramientas
• APIs personalizadas: Control total del flujo
• Integraciones específicas: Cuando necesitas control fino

Capacidades Principales

flowchart TB
    subgraph Capacidades["CAPACIDADES DEL AGENT SDK"]
        subgraph Fila1[" "]
            direction LR
            Tools["HERRAMIENTAS BUILT-IN<br/>Read, Write, Edit<br/>Bash, Glob, Grep"]
            Hooks["HOOKS<br/>PreToolUse<br/>PostToolUse, Stop"]
            Subagents["SUBAGENTES<br/>Tareas paralelas"]
        end
        subgraph Fila2[" "]
            direction LR
            MCP["MCP<br/>Playwright, Slack<br/>GitHub"]
            Sessions["SESIONES<br/>Resume, Fork<br/>Context"]
            Permisos["PERMISOS<br/>acceptEdits<br/>bypassAll"]
        end
    end

Autenticación

El SDK soporta múltiples proveedores:

Proveedor	Variable de Entorno
Anthropic (default)	ANTHROPIC_API_KEY
Amazon Bedrock	CLAUDE_CODE_USE_BEDROCK=1
Google Vertex AI	CLAUDE_CODE_USE_VERTEX=1
Microsoft Foundry	CLAUDE_CODE_USE_FOUNDRY=1

Resumen

• El Agent SDK es Claude Code como biblioteca
• Maneja automáticamente el loop de herramientas
• Ideal para automatización y agentes autónomos
• Disponible en Python y TypeScript