El Claude Agent SDK toma el harness que impulsa Claude Code — bucle agéntico, herramientas de archivo, bash, gestión de contexto — y lo empaqueta como una librería que puedes correr en tu propia infraestructura.
Construir un agente sobre la Claude API directa implica escribir tú mismo el bucle `while stop_reason == "tool_use"`, definir cada herramienta con su esquema JSON, manejar la ejecución de comandos de shell, gestionar permisos, y decidir cómo comprimir el contexto cuando la conversación crece. El Claude Agent SDK (`claude-agent-sdk` en Python, `@anthropic-ai/claude-agent-sdk` en TypeScript) resuelve todo eso de fábrica: viene con Read, Write, Edit, Bash, Glob, Grep, WebSearch y WebFetch ya implementadas, gestión de contexto integrada, soporte de hooks, subagentes, y el mismo sistema de permisos que usa Claude Code.
Es importante no confundirlo con el "tool runner" de la API estándar (`client.beta.messages.tool_runner`), que es un helper mucho más liviano que solo automatiza el ciclo de llamar-ejecutar-repetir sobre herramientas que tú defines, sin ninguna herramienta incorporada ni acceso a sistema de archivos. El Agent SDK es Claude Code empaquetado como librería; el tool runner es un helper sobre `POST /v1/messages`. Ambos requieren que tú alojes el cómputo — ninguno incluye infraestructura gestionada (eso es lo que ofrece Managed Agents, un producto distinto).
El punto de entrada es la función `query(prompt, options)`, que devuelve un stream de eventos según el agente va razonando, usando herramientas y produciendo texto:
Detrás de esto corre el mismo modelo Claude que usarías vía API directa, con el harness completo de gestión de turnos, ejecución de herramientas y compactación de contexto ya resuelto.
El SDK expone un sistema de permisos con tres modos: `default` (pide confirmación en acciones sensibles), `acceptEdits` (aprueba automáticamente ediciones de archivo pero no comandos de shell) y un modo de autonomía total solo para entornos ya aislados como un contenedor efímero. Para control más granular, los hooks permiten interceptar cada invocación de herramienta antes o después de ejecutarse — útil para logging de auditoría, validación de entrada, o bloquear patrones específicos de comando.
Este patrón es el mismo que usa Claude Code internamente para su sistema de `settings.json` — el SDK simplemente te da el mismo mecanismo programáticamente.
Igual que Claude Code, el SDK soporta subagentes: instancias con su propio prompt de sistema, conjunto de herramientas restringido y contexto aislado, invocadas para tareas delimitadas sin contaminar el contexto principal con el detalle intermedio. Esto es particularmente valioso en agentes de larga duración — un agente de revisión de código, por ejemplo, puede delegar "revisa el módulo de autenticación en busca de vulnerabilidades" a un subagente, recibir solo el resumen de hallazgos, y continuar con el contexto principal intacto.
Para conversaciones largas, el SDK gestiona automáticamente la compactación cuando el contexto se acerca al límite del modelo — resumiendo turnos antiguos en vez de truncarlos, preservando la coherencia de la tarea en ejecución sin que tengas que implementar esa lógica tú mismo.
El SDK acepta servidores MCP con la misma configuración que Claude Code, lo que te permite conectar el agente a sistemas internos (bases de datos, APIs corporativas, sistemas de tickets) sin escribir el conector de integración desde cero — solo declaras el servidor MCP y el conjunto de tools que expone. También puedes definir herramientas propias con esquema JSON estándar cuando la lógica es específica de tu aplicación y no amerita un servidor MCP separado.
Si necesitas un agente con capacidades tipo "asistente de codificación" corriendo en tu propia infraestructura — CI/CD, un backend interno, una herramienta de soporte técnico con acceso a archivos y comandos — el Agent SDK es la opción más directa: menos código propio que un bucle manual, control total sobre dónde corre. Si en cambio quieres que Anthropic aloje tanto el bucle del agente como el sandbox de ejecución (sesiones persistentes, contenedores por sesión, sin infraestructura propia que mantener), la opción correcta es Managed Agents, un producto distinto con su propia API. Y si solo necesitas automatizar un puñado de herramientas propias sin todo el aparato de Claude Code, el tool runner de la API estándar es más liviano y suficiente.
Carlos Montiel es arquitecto de soluciones IA empresarial. Implementa LLMs, Agentes, RAG y orquestadores en empresas de Guatemala y Latinoamérica. Contáctalo para una consultoría.
Contactar a Carlos Montiel