1~
2El 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.
3~
4A 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.
5~
6## Arquitectura
7~
8El SDK sigue un loop simple: **recopilar contexto, actuar, verificar, repetir**.
9~
10```mermaid
11graph TD
12    Input[User Prompt] --> Loop[Agent Loop]
13    Loop --> Reason[Claude Reasons]
14    Reason --> Tool[Call Tool]
15    Tool --> Result[Tool Result]
16    Result --> Loop
17    Reason --> Done[Final Response]
18~
19    subgraph "Built-in Tools"
20        T1[Read / Write / Edit]
21        T2[Bash / Terminal]
22        T3[Glob / Grep]
23        T4[WebSearch / WebFetch]
24    end
25~
26    subgraph "Custom Tools via MCP"
27        M1[Your API]
28        M2[Database]
29        M3[Slack / GitHub / etc.]
30    end
31~
32    Tool --> T1
33    Tool --> M1
34```
35~
36El 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.
37~
38## Primeros pasos
39~
40### Instalacion
41~
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45~
46# Python
47pip install claude-agent-sdk
48```
49~
50Necesitas una clave API de Anthropic configurada como `ANTHROPIC_API_KEY` en tu entorno.
51~
52### Tu primer agente
53~
54```typescript
55import { query } from "@anthropic-ai/claude-agent-sdk";
56~
57const conversation = query({
58  prompt: "Find all TODO comments in the codebase and create a summary",
59  options: {
60    allowedTools: ["Read", "Glob", "Grep"],
61  },
62});
63~
64for await (const message of conversation) {
65  if (message.type === "assistant") {
66    process.stdout.write(message.content);
67  }
68  if (message.type === "result" && message.subtype === "success") {
69    console.log("\nDone:", message.result);
70  }
71}
72```
73~
74Eso 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.
75~
76### Equivalente en Python
77~
78```python
79from claude_agent_sdk import query
80~
81async for message in query(
82    prompt="Find all TODO comments in the codebase and create a summary",
83    options={"allowed_tools": ["Read", "Glob", "Grep"]},
84):
85    if message.type == "assistant":
86        print(message.content, end="")
87    if message.type == "result" and message.subtype == "success":
88        print(f"\nDone: {message.result}")
89```
90~
91## Tools integrados
92~
93El SDK incluye los mismos tools disponibles en Claude Code:
94~
95| Tool | Descripcion |
96|------|-------------|
97| **Read** | Lee el contenido de archivos |
98| **Write** | Crea archivos nuevos |
99| **Edit** | Realiza ediciones puntuales en archivos existentes |
100| **Bash** | Ejecuta comandos shell |
101| **Glob** | Encuentra archivos por patron |
102| **Grep** | Busca en el contenido de archivos con regex |
103| **WebSearch** | Realiza busquedas en la web |
104| **WebFetch** | Descarga una URL y devuelve su contenido |
105| **AskUserQuestion** | Solicita una entrada al usuario |
106~
107Controlas que tools puede usar el agente mediante `allowedTools`. Si un tool no esta en la lista, el agente no puede llamarlo.
108~
109## Modos de permisos
110~
111Dado que los agentes ejecutan comandos reales en sistemas reales, los permisos importan.
112~
113| Modo | Comportamiento | Caso de uso |
114|------|----------|----------|
115| `default` | Un callback `canUseTool` personalizado decide por cada llamada | Control granular |
116| `acceptEdits` | Aprueba automaticamente las operaciones de archivos, pregunta para Bash | Workflows de desarrollo |
117| `dontAsk` | Deniega todo lo que no este en allowedTools | Agentes restringidos |
118| `bypassPermissions` | Aprueba todo automaticamente | Entornos sandbox de confianza |
119| `auto` | Un clasificador del modelo evalua la seguridad | Automatizacion equilibrada |
120~
121```typescript
122const conversation = query({
123  prompt: "Refactor the auth module to use JWT",
124  options: {
125    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
126    permissionMode: "acceptEdits",
127  },
128});
129```
130~
131Para 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.
132~
133## Crear tools personalizados con MCP
134~
135El 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.
136~
137### Ejemplo: tool meteorologico
138~
139```typescript
140import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
141import { z } from "zod";
142~
143const getTemperature = tool(
144  "get_temperature",
145  "Get the current temperature at a location",
146  {
147    latitude: z.number().describe("Latitude"),
148    longitude: z.number().describe("Longitude"),
149  },
150  async ({ latitude, longitude }) => {
151    const res = await fetch(
152      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
153    );
154    const data = await res.json();
155    return {
156      content: [
157        {
158          type: "text",
159          text: `Current temperature: ${data.current.temperature_2m}C`,
160        },
161      ],
162    };
163  }
164);
165~
166const weatherServer = createSdkMcpServer({
167  name: "weather",
168  version: "1.0.0",
169  tools: [getTemperature],
170});
171~
172for await (const message of query({
173  prompt: "What's the weather like in Rome?",
174  options: {
175    mcpServers: { weather: weatherServer },
176    allowedTools: ["mcp__weather__get_temperature"],
177  },
178})) {
179  if (message.type === "result" && message.subtype === "success") {
180    console.log(message.result);
181  }
182}
183```
184~
185Los 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.
186~
187### Ejemplo: tool de consulta a base de datos
188~
189```typescript
190const queryDb = tool(
191  "query_database",
192  "Run a read-only SQL query against the application database",
193  {
194    sql: z.string().describe("SQL SELECT query to execute"),
195  },
196  async ({ sql }) => {
197    // Validate: only allow SELECT queries
198    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
199      return {
200        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
201      };
202    }
203~
204    const result = await pool.query(sql);
205    return {
206      content: [
207        {
208          type: "text",
209          text: JSON.stringify(result.rows, null, 2),
210        },
211      ],
212    };
213  }
214);
215```
216~
217## Conectar servidores MCP externos
218~
219Mas 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.
220~
221```typescript
222for await (const message of query({
223  prompt: "Check the latest issues in the frontend repo and summarize them",
224  options: {
225    mcpServers: {
226      github: {
227        command: "npx",
228        args: ["-y", "@modelcontextprotocol/server-github"],
229        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
230      },
231    },
232    allowedTools: ["mcp__github__*"],
233  },
234})) {
235  // ...
236}
237```
238~
239Puedes combinar varios servidores MCP. El agente ve todos los tools de todos los servidores conectados y los usa segun sea necesario.
240~
241```mermaid
242graph LR
243    Agent[Your Agent] --> SDK[Agent SDK]
244    SDK --> InProcess[In-process MCP\nCustom Tools]
245    SDK --> GitHub[GitHub MCP Server]
246    SDK --> Postgres[PostgreSQL MCP Server]
247    SDK --> Slack[Slack MCP Server]
248```
249~
250## Orquestacion multi-agente
251~
252Para 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.
253~
254```typescript
255for await (const message of query({
256  prompt: "Review the PR, check for security issues, and update the changelog",
257  options: {
258    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
259    agents: [
260      {
261        name: "security-reviewer",
262        description: "Reviews code for security vulnerabilities",
263        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
264        allowedTools: ["Read", "Glob", "Grep"],
265      },
266      {
267        name: "changelog-writer",
268        description: "Updates the CHANGELOG.md file based on recent changes",
269        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
270        allowedTools: ["Read", "Edit", "Bash"],
271      },
272    ],
273  },
274})) {
275  // The parent agent will:
276  // 1. Read the PR diff
277  // 2. Delegate security review to security-reviewer
278  // 3. Delegate changelog update to changelog-writer
279  // 4. Synthesize results
280}
281```
282~
283Incluye `"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.
284~
285```mermaid
286graph TD
287    Parent[Parent Agent] --> SR[Security Reviewer\nRead, Glob, Grep]
288    Parent --> CW[Changelog Writer\nRead, Edit, Bash]
289    SR --> Report[Security Report]
290    CW --> Updated[Updated CHANGELOG]
291    Report --> Parent
292    Updated --> Parent
293    Parent --> Final[Final Summary]
294```
295~
296## Sesiones y continuidad
297~
298Los 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.
299~
300```typescript
301let sessionId: string | undefined;
302~
303// First query
304for await (const message of query({
305  prompt: "Read the project structure and understand the architecture",
306  options: { allowedTools: ["Read", "Glob", "Grep"] },
307})) {
308  if (message.type === "init") {
309    sessionId = message.session_id;
310  }
311}
312~
313// Follow-up query (same session, full context preserved)
314for await (const message of query({
315  prompt: "Now refactor the auth module based on what you learned",
316  resume: sessionId,
317  options: { allowedTools: ["Read", "Edit", "Bash"] },
318})) {
319  // Agent remembers the full project context from the first query
320}
321```
322~
323## Claude Managed Agents
324~
325Si 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.
326~
327```mermaid
328graph LR
329    subgraph "Self-hosted (Agent SDK)"
330        Code[Your Code] --> SDK2[Agent SDK]
331        SDK2 --> API[Claude API]
332        SDK2 --> Tools[Your Tools]
333    end
334~
335    subgraph "Managed Agents"
336        App[Your App] --> MAPI[Managed Agents API]
337        MAPI --> Container[Anthropic-hosted Container]
338        Container --> API2[Claude API]
339        Container --> Tools2[Tools in Container]
340    end
341```
342~
343La 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.
344~
345**Precios:**
346- **Agent SDK**: solo las tarifas estandar por token de la API de Claude. Tu te encargas del alojamiento.
347- **Managed Agents**: tarifas por token mas $0,08 por hora de sesion (facturado al milisegundo).
348~
349## Buenas practicas para produccion
350~
351### 1. Usa siempre un sandbox
352~
353Nunca ejecutes agentes con permisos ilimitados en una maquina de produccion. Usa contenedores (Docker, Fly.io, Modal) o entornos sandbox (E2B, Vercel Sandbox).
354~
355### 2. Limita el acceso a los tools
356~
357Sigue el principio de minimo privilegio. Un agente que genera informes no necesita `Bash` ni `Write`.
358~
359```typescript
360// Too permissive
361allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
362~
363// Better: only what's needed
364allowedTools: ["Read", "Glob", "Grep"]
365```
366~
367### 3. Usa hooks como guardrails
368~
369Los hooks te permiten interceptar las llamadas a tools antes y despues de la ejecucion. Usalos para logging, validacion y rate limiting.
370~
371```typescript
372const conversation = query({
373  prompt: "Analyze the codebase",
374  options: {
375    allowedTools: ["Read", "Glob", "Grep"],
376    hooks: {
377      PreToolUse: async (toolName, input) => {
378        console.log(`Tool call: ${toolName}`, input);
379        // Return false to block the call
380        if (toolName === "Bash" && input.command.includes("rm")) {
381          return false;
382        }
383        return true;
384      },
385    },
386  },
387});
388```
389~
390### 4. Gestiona los errores correctamente
391~
392El 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.
393~
394```typescript
395for await (const message of conversation) {
396  switch (message.type) {
397    case "assistant":
398      // Agent reasoning
399      break;
400    case "tool_use":
401      // Agent is calling a tool
402      break;
403    case "result":
404      if (message.subtype === "error") {
405        console.error("Agent failed:", message.error);
406      }
407      break;
408  }
409}
410```
411~
412### 5. Monitoriza el consumo de tokens
413~
414Los 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.
415~
416## Conclusion
417~
418El 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.
419~
420Empieza 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.
421~
422El agent loop es el mismo que impulsa Claude Code. Si puede crear software, tus agentes tambien pueden.
423~
424> **Checklist para empezar:**
425>
426> - [x] Instalar el SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Configurar `ANTHROPIC_API_KEY` en tu entorno
428> - [x] Crear un agente simple con los tools integrados (Read, Glob, Grep)
429> - [x] Anadir un tool personalizado via servidor MCP in-process
430> - [x] Conectar un servidor MCP externo (GitHub, PostgreSQL, etc.)
431> - [x] Implementar la orquestacion multi-agente con sub-agentes
432> - [x] Configurar un entorno sandbox para produccion
433> - [x] Anadir hooks para logging y guardrails
434~