Claude Agent SDK: Construyendo Agentes AI de Grado Producción

¿Qué es el Claude Agent SDK?

El Claude Agent SDK es el framework oficial de Anthropic para construir agentes AI autónomos en Python y TypeScript. Provee las mismas capacidades agénticas que potencian a Claude Code -- lectura de archivos, ejecución de código, navegación web y uso de herramientas -- como una biblioteca programable que embebes en tus propias aplicaciones. Python requiere 3.10+ y TypeScript requiere Node 18+.

En su base, el SDK implementa un ciclo agéntico de 4 fases: (1) el agente recibe una tarea, (2) razona sobre qué herramientas usar, (3) ejecuta llamadas a herramientas y recolecta resultados, y (4) evalúa si la tarea está completa o necesita más iteración. Este ciclo corre autónomamente hasta que el agente determina que la tarea está terminada o alcanza un límite configurado.

El SDK abstrae las complejidades de llamadas a herramientas, parsing de respuestas, manejo de errores y gestión de conversaciones. Tú defines el system prompt de tu agente, las herramientas disponibles y las restricciones. El SDK maneja el resto: construcción de llamadas API, parsing de respuestas, ejecución de herramientas, retroalimentación de resultados, gestión de límites de ventana de contexto y streaming de salida. También se integra nativamente con servidores MCP.

Cómo Lo Uso

Uso el Claude Agent SDK para construir agentes de automatización personalizados que van más allá de lo que Claude Code ofrece. Mi caso de uso principal es construir agentes especializados para clientes -- agentes que entienden su dominio de negocio específico, se conectan a sus herramientas internas y automatizan sus flujos de trabajo únicos.

Para el proyecto, construye un agente de despliegue que lee el git log, determina qué microservicios cambiaron, genera valores de Helm charts, valida manifiestos de Kubernetes y dispara despliegues. Este agente redujo errores de despliegue a casi cero.

Otro agente en producción maneja validación de migraciones de base de datos. Lee archivos de migración propuestos, los analiza contra el esquema actual, verifica compatibilidad hacia atrás, estima tiempo de ejecución y genera scripts de rollback.

También construyo agentes con salidas JSON estructuradas para pipelines de procesamiento de datos. Estos agentes analizan datos no estructurados, extraen información estructurada según un esquema definido y alimentan resultados a sistemas downstream.

Primeros Pasos

Instala el SDK y construye tu primer agente en menos de 20 líneas. El SDK de Python requiere Python 3.10+ y el de TypeScript requiere Node 18+.

# Install the Python SDK
pip install claude-agent-sdk

# Or the TypeScript SDK
npm install @anthropic-ai/claude-agent-sdk

Crea un agente mínimo con un system prompt y herramientas integradas. Este agente puede leer archivos, buscar código y ejecutar comandos.

# minimal_agent.py - Python example
from claude_agent_sdk import Agent, BuiltinTools

agent = Agent(
    model="claude-sonnet-4-6",
    system_prompt="""You are a code review assistant.
    Analyze code for bugs, security issues, and
    style violations. Be concise and actionable.""",
    tools=[
        BuiltinTools.Read,
        BuiltinTools.Glob,
        BuiltinTools.Grep,
        BuiltinTools.Bash
    ],
    max_iterations=20
)

result = agent.run(
    "Review the Python files in ./src/ for common "
    "security vulnerabilities and suggest fixes."
)
print(result.text)

Agrega una herramienta personalizada para extender las capacidades de tu agente. En Python, las herramientas se definen como funciones decoradas con parámetros tipados.

# Custom tool definition (Python)
from claude_agent_sdk import tool

@tool(description="Query the user database")
def query_users(
    filter: str = "Filter expression (e.g. 'active=true')",
    limit: int = "Maximum results to return"
) -> str:
    """Execute a filtered query against the user table."""
    results = db.users.find(parse_filter(filter), limit=limit)
    return json.dumps([u.to_dict() for u in results])

# Add to agent
agent = Agent(
    model="claude-sonnet-4-6",
    system_prompt="You are a data analyst assistant.",
    tools=[BuiltinTools.Read, query_users],
    max_iterations=10
)

En TypeScript, las herramientas se definen como objetos con nombre, descripción, JSON Schema para inputs y una función execute.

// Custom tool definition (TypeScript)
import { Agent, Tool } from "@anthropic-ai/claude-agent-sdk";

const queryUsers: Tool = {
  name: "query_users",
  description: "Query the user database",
  inputSchema: {
    type: "object",
    properties: {
      filter: {
        type: "string",
        description: "Filter expression (e.g. 'active=true')"
      },
      limit: {
        type: "number",
        description: "Maximum results to return"
      }
    },
    required: ["filter"]
  },
  async execute(input) {
    const results = await db.users.find(
      parseFilter(input.filter),
      { limit: input.limit ?? 10 }
    );
    return JSON.stringify(results);
  }
};

const agent = new Agent({
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a data analyst assistant.",
  tools: [queryUsers],
  maxIterations: 10
});

Conecta servidores MCP para dar a tu agente acceso a servicios externos directamente desde código.

# MCP integration example (Python)
from claude_agent_sdk import Agent, BuiltinTools, MCPServer

agent = Agent(
    model="claude-sonnet-4-6",
    system_prompt="You are a project management assistant.",
    tools=[BuiltinTools.Read, BuiltinTools.Bash],
    mcp_servers=[
        MCPServer(
            name="github",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-github"],
            env={"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]}
        ),
        MCPServer(
            name="slack",
            command="npx",
            args=["-y", "@modelcontextprotocol/server-slack"],
            env={"SLACK_BOT_TOKEN": os.environ["SLACK_TOKEN"]}
        )
    ],
    max_iterations=15
)

# Agent can now use GitHub and Slack tools natively
result = agent.run(
    "Read PR #42 from repo acme/api, summarize the "
    "changes, and post a summary to #dev-updates on Slack."
)

Técnicas Avanzadas

Pipelines Multi-Agente

Construye pipelines donde agentes especializados se pasan trabajo. Un planificador divide tareas, workers ejecutan y un revisor valida. Cada agente tiene un prompt enfocado y conjunto de herramientas.

# Multi-agent pipeline
planner = Agent(
    model="claude-opus-4-8",
    system_prompt="Break tasks into subtasks. Output JSON.",
    tools=[BuiltinTools.Read, BuiltinTools.Glob]
)

worker = Agent(
    model="claude-sonnet-4-6",
    system_prompt="Execute coding tasks. Write clean code.",
    tools=[BuiltinTools.Read, BuiltinTools.Write,
           BuiltinTools.Bash]
)

reviewer = Agent(
    model="claude-sonnet-4-6",
    system_prompt="Review code for bugs and style issues.",
    tools=[BuiltinTools.Read, BuiltinTools.Grep]
)

# Orchestrate
plan = planner.run("Refactor auth module for OAuth2")
for subtask in plan.structured_output["subtasks"]:
    result = worker.run(subtask["description"])
    review = reviewer.run(f"Review: {result.text}")

Esquemas de Salida Estructurada

Define esquemas JSON que fuercen las respuestas del agente a estructuras predecibles. Esencial para pipelines automatizados. El SDK valida y reintenta en caso de salida inválida.

# Structured output with schema
output_schema = {
    "type": "object",
    "properties": {
        "vulnerabilities": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "severity": {"enum": ["low","medium","high","critical"]},
                    "file": {"type": "string"},
                    "line": {"type": "integer"},
                    "description": {"type": "string"},
                    "fix": {"type": "string"}
                },
                "required": ["severity","file","line","description","fix"]
            }
        },
        "summary": {"type": "string"}
    },
    "required": ["vulnerabilities", "summary"]
}

agent = Agent(
    model="claude-sonnet-4-6",
    system_prompt="Security audit agent.",
    tools=[BuiltinTools.Read, BuiltinTools.Grep],
    output_schema=output_schema
)

Streaming y Output en Tiempo Real

Usa modo streaming para aplicaciones interactivas. El SDK emite eventos para cada token, inicio/fin de llamadas a herramientas y bloques de pensamiento. Modo único para procesamiento por lotes donde el throughput importa más que la latencia.

# Streaming mode (Python)
async for event in agent.stream("Analyze this codebase"):
    if event.type == "text":
        print(event.text, end="", flush=True)
    elif event.type == "tool_start":
        print(f"\n[Using {event.tool_name}...]")
    elif event.type == "thinking":
        print(f"\n[Thinking: {event.summary}]")

Persistencia de Sesión y Recuperación

Guarda el estado de la sesión en disco o base de datos para recuperación entre sesiones. Reanuda exactamente donde quedó la conversación. Incluye historial, resultados de herramientas, memoria y tareas pendientes.

# Session persistence (Python)
from claude_agent_sdk import Agent, SessionStore

store = SessionStore(backend="sqlite", path="./sessions.db")

# Resume or start new session
agent = Agent(
    model="claude-sonnet-4-6",
    system_prompt="You are a project assistant.",
    tools=[BuiltinTools.Read, BuiltinTools.Write],
    session_store=store,
    session_id="user-123-project-abc"
)

# Agent resumes from last checkpoint if session exists
result = agent.run("Continue where we left off.")

Estrategias de Gestión de Costos

Selección de modelo por niveles, cache de resultados de herramientas, presupuestos de tokens y monitoreo de gasto por sesión para optimizar costos.

# Cost tracking (Python)
result = agent.run("Analyze security vulnerabilities")

print(f"Input tokens:  {result.usage.input_tokens}")
print(f"Output tokens: {result.usage.output_tokens}")
print(f"Cache reads:   {result.usage.cache_read_tokens}")
print(f"Total cost:    ${result.usage.total_cost:.4f}")
print(f"Iterations:    {result.iterations}")

Procesamiento por Lotes

Procesa datasets grandes con instancias de agentes en paralelo. Encola tareas, distribuye, recolecta resultados estructurados, maneja fallos sin detener el lote.

# Batch processing (Python)
import asyncio
from claude_agent_sdk import Agent, BuiltinTools

agent = Agent(
    model="claude-haiku-4-5",
    system_prompt="Extract company info from text.",
    output_schema=company_schema
)

async def process_batch(documents):
    tasks = [agent.arun(doc) for doc in documents]
    results = await asyncio.gather(*tasks,
                                    return_exceptions=True)
    return [r.structured_output for r in results
            if not isinstance(r, Exception)]

# Process 500 documents in parallel batches
all_results = await process_batch(documents)

Últimas Actualizaciones del SDK (2025-2026)