Construir agentes de IA con el Claude Agent SDK: una guia practica

El Claude Agent SDK te da acceso programatico al mismo agent loop que impulsa Claude Code. Tus agentes pueden leer archivos, ejecutar comandos shell, buscar en la web, modificar codigo, llamar a APIs externas a traves de servidores MCP y orquestar sub-agentes - todo desde unas pocas lineas de TypeScript o Python.

A diferencia del Client SDK estandar de Anthropic, donde construyes tu propio tool loop, el Agent SDK gestiona internamente la ejecucion de tools, la gestion del contexto, los reintentos y la orquestacion. Tu describes lo que quieres, proporcionas las herramientas, y el agente se encarga del resto.

Arquitectura

El SDK sigue un loop simple: recopilar contexto, actuar, verificar, repetir.

El punto de entrada principal es query(), que devuelve un iterador asincrono que transmite mensajes en streaming mientras el agente trabaja. Cada mensaje te indica que esta haciendo el agente: razonando, llamando a un tool, recibiendo un resultado o entregando la salida final.

Primeros pasos

Instalacion

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

# Python
pip install claude-agent-sdk

Necesitas una clave API de Anthropic configurada como ANTHROPIC_API_KEY en tu entorno.

Tu primer agente

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

Eso es todo. El agente usara Glob para encontrar archivos, Grep para buscar patrones TODO, Read para inspeccionar las coincidencias y devolvera un resumen estructurado. No escribes la logica de orquestacion - el SDK se encarga de ello.

Equivalente en Python

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

Tools integrados

El SDK incluye los mismos tools disponibles en Claude Code:

Controlas que tools puede usar el agente mediante allowedTools. Si un tool no esta en la lista, el agente no puede llamarlo.

Modos de permisos

Dado que los agentes ejecutan comandos reales en sistemas reales, los permisos importan.

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

Para uso en produccion, ejecuta siempre los agentes en entornos sandbox (contenedores, VMs) y usa el modo de permisos mas restrictivo que aun permita al agente hacer su trabajo.

Crear tools personalizados con MCP

El verdadero poder del SDK esta en extender los agentes con tus propias herramientas. Los tools personalizados se definen como servidores MCP in-process - sin gestion de subprocesos, sin overhead de red.

Ejemplo: tool meteorologico

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Los tools personalizados siguen la convencion de nombres mcp__{nombre_servidor}__{nombre_tool}. Puedes usar comodines en allowedTools: "mcp__weather__*" habilita todos los tools del servidor meteorologico.

Ejemplo: tool de consulta a base de datos

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

Conectar servidores MCP externos

Mas alla de los tools in-process, puedes conectarte a cualquier servidor MCP existente - los mismos servidores que funcionan con Claude Desktop, Cursor y otros clientes MCP.

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

Puedes combinar varios servidores MCP. El agente ve todos los tools de todos los servidores conectados y los usa segun sea necesario.

Orquestacion multi-agente

Para workflows complejos, puedes definir sub-agentes especializados a los que el agente principal delega. Cada sub-agente tiene su propio prompt, sus propios tools y su area de especializacion.

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

Incluye "Agent" en los allowedTools del padre para habilitar la delegacion. Los sub-agentes se ejecutan con sus propios tools y no pueden acceder a los del padre a menos que se les conceda explicitamente.

Sesiones y continuidad

Los agentes pueden mantener el contexto entre multiples consultas mediante sesiones. Captura el session_id de la primera interaccion y pasalo en resume para las consultas posteriores.

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

Si no quieres alojar tu mismo la infraestructura de los agentes, los Claude Managed Agents (lanzados en abril de 2026) ofrecen un servicio en la nube completamente gestionado. Anthropic se encarga de los contenedores, del escalado y pone a disposicion una API en streaming.

La diferencia clave: con el Agent SDK, ejecutas el agent loop en tu propia infraestructura. Con los Managed Agents, Anthropic aloja y ejecuta el agente por ti. Interactuas a traves de una API basada en sesiones y recibes eventos mediante Server-Sent Events.

Precios:

• Agent SDK: solo las tarifas estandar por token de la API de Claude. Tu te encargas del alojamiento.
• Managed Agents: tarifas por token mas $0,08 por hora de sesion (facturado al milisegundo).

Buenas practicas para produccion

1. Usa siempre un sandbox

Nunca ejecutes agentes con permisos ilimitados en una maquina de produccion. Usa contenedores (Docker, Fly.io, Modal) o entornos sandbox (E2B, Vercel Sandbox).

2. Limita el acceso a los tools

Sigue el principio de minimo privilegio. Un agente que genera informes no necesita Bash ni Write.

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. Usa hooks como guardrails

Los hooks te permiten interceptar las llamadas a tools antes y despues de la ejecucion. Usalos para logging, validacion y rate limiting.

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. Gestiona los errores correctamente

El agent loop puede producir errores - fallos de tools, limites de tasa de la API, desbordamiento de la ventana de contexto. Comprueba siempre los tipos de mensaje.

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. Monitoriza el consumo de tokens

Los agent loops pueden consumir una cantidad significativa de tokens, especialmente con codebases grandes. El SDK incluye compactacion automatica del contexto, pero aun asi deberias monitorizar el uso.

Conclusion

El Claude Agent SDK convierte un LLM de una maquina que responde preguntas en algo mas parecido a un desarrollador junior. Tus agentes pueden leer, escribir, ejecutar, verificar e iterar - el mismo workflow que sigue un ser humano.

Empieza en pequeno: crea un agente con unos pocos tools integrados. Luego anade tools MCP personalizados para tu dominio especifico. Escala hacia la orquestacion multi-agente cuando tus workflows requieran especializacion.

El agent loop es el mismo que impulsa Claude Code. Si puede crear software, tus agentes tambien pueden.

Checklist para empezar:

• Instalar el SDK (npm install @anthropic-ai/claude-agent-sdk)
• Configurar ANTHROPIC_API_KEY en tu entorno
• Crear un agente simple con los tools integrados (Read, Glob, Grep)
• Anadir un tool personalizado via servidor MCP in-process
• Conectar un servidor MCP externo (GitHub, PostgreSQL, etc.)
• Implementar la orquestacion multi-agente con sub-agentes
• Configurar un entorno sandbox para produccion
• Anadir hooks para logging y guardrails