≡En resumen
- El Agent SDK es Claude Code empaquetado como librería: el mismo bucle, las mismas herramientas y la misma gestión de contexto.
- Sirve para agentes que trabajan con archivos, comandos, webs y servicios externos durante muchos pasos sin supervisión constante.
- Incluye subagentes, hooks, permisos, sesiones reanudables y soporte de MCP de serie.
- No es lo mismo que el SDK de la API: aquel solo envía mensajes; este ejecuta un agente completo.
- Tú pones la infraestructura; si quieres que Anthropic aloje el agente, la opción es Managed Agents.
01 ¿Qué es el Claude Agent SDK?
El Claude Agent SDK es una librería que pone en tus manos el motor interno de Claude Code, el asistente de programación de Anthropic. En lugar de usarlo desde la terminal, lo llamas desde tu propio código y le das una tarea: el SDK se encarga de que Claude razone, use herramientas, lea los resultados y siga trabajando hasta terminar.
Nació con el nombre de Claude Code SDK. Anthropic lo renombró al comprobar que se estaba usando para mucho más que programar: investigación, soporte, finanzas, operaciones o creación de contenido. Por debajo usa los modelos de la API de Claude, pero añade todo lo que necesita un agente de verdad.
02 Qué incluye el Agent SDK
Herramientas integradas
Leer, escribir y editar archivos, buscar con Glob y Grep, ejecutar Bash, buscar en la web y descargar páginas.
Bucle agéntico
Claude decide la siguiente acción, la ejecuta, observa el resultado y repite hasta cumplir el objetivo o agotar los turnos.
Gestión de contexto
Compactación automática cuando la conversación crece, para que las tareas largas no se queden sin memoria de trabajo.
Subagentes
Agentes especializados con su propio contexto e instrucciones a los que el agente principal delega partes del trabajo.
Hooks y permisos
Código que se ejecuta antes o después de cada herramienta y reglas que deciden qué puede hacer el agente sin preguntar.
MCP y sesiones
Conexión con servidores MCP para usar servicios externos y sesiones que se pueden reanudar más tarde.
Muchas de estas piezas tienen su propia ficha en el glosario: los subagentes, los hooks o el Model Context Protocol. En el SDK funcionan igual que en Claude Code, pero configuradas desde código.
03 Cómo se usa el Claude Agent SDK paso a paso
-
1
Instala el paquete
pip install claude-agent-sdk en Python o npm install @anthropic-ai/claude-agent-sdk en TypeScript.
-
2
Configura la autenticación
Define ANTHROPIC_API_KEY o las variables del proveedor cloud que uses (Bedrock, Vertex AI o Foundry).
-
3
Llama a query()
Pasa el prompt con la tarea y un objeto de opciones. La función devuelve un flujo de mensajes a medida que el agente trabaja.
-
4
Limita herramientas y permisos
Indica qué herramientas puede usar, el modo de permisos, el directorio de trabajo y el número máximo de turnos.
-
5
Añade instrucciones y conexiones
Un system prompt propio, servidores MCP, subagentes y hooks según lo que necesite el caso.
-
6
Procesa el resultado
Lee los mensajes del flujo, guarda el resultado final y registra el coste y los turnos usados.
En TypeScript, una llamada a query() con el prompt «Lee el ticket 4812, busca en /docs la solución y redacta la respuesta» y opciones como allowedTools (Read, Grep, Glob), permissionMode y maxTurns. El agente solo puede leer y buscar, no modificar nada, y devuelve un borrador que una persona revisa antes de enviar. En Python el equivalente usa ClaudeAgentOptions con allowed_tools.
04 Agent SDK, API de Claude y Managed Agents: cuál elegir
| Opción | Qué te da | Quién aloja el agente | Encaja cuando |
|---|---|---|---|
| API + bucle propio | Solo el modelo; programas tú el bucle y las herramientas | Tú | Quieres control total o un flujo muy simple |
| API + tool runner del SDK | Un bucle automático sobre las herramientas que tú defines | Tú | Tu agente usa solo funciones propias |
| Claude Agent SDK | El arnés de Claude Code con herramientas de archivos, terminal y web | Tú | El agente trabaja con archivos, código o comandos en tu infraestructura |
| Managed Agents | Bucle y entorno de ejecución alojados por Anthropic | Anthropic | No quieres operar servidores ni contenedores para el agente |
Si tu caso no necesita leer archivos ni ejecutar comandos, el SDK de la API con herramientas definidas por ti suele ser más ligero. Si prefieres que la ejecución corra en la nube de Anthropic, mira Claude Managed Agents.
05 Casos de uso reales del Agent SDK
Agentes de programación
Revisar pull requests, corregir tests rotos o migrar código como parte de un pipeline de CI.
Operaciones e informes
Leer exportaciones de datos, cruzarlas y dejar un informe en una carpeta compartida cada mañana.
Soporte y documentación
Buscar en la base de conocimiento interna y redactar respuestas o actualizar guías.
Asistentes dentro de tu producto
Un agente embebido en tu SaaS que ejecuta tareas por el usuario con permisos acotados.
En proyectos de desarrollo de SaaS es habitual usar el Agent SDK para añadir un agente que trabaje sobre los datos del cliente sin construir el motor desde cero. Para ver librerías, plantillas y ejemplos de la comunidad, consulta el catálogo de recursos de IA para Claude.
06 Seguridad y buenas prácticas
- ✓Concede solo las herramientas imprescindibles: un agente que solo lee no necesita Bash ni Write.
- ✓Ejecuta el agente en un contenedor o entorno aislado, sin credenciales de producción a su alcance.
- ✓Usa hooks para bloquear comandos peligrosos y registrar cada acción.
- ✓Limita el número de turnos y vigila el coste por ejecución.
- ✓Trata como no fiable todo lo que el agente lee de webs, correos o documentos de terceros.
- ✓Pide confirmación humana antes de acciones irreversibles como borrar, enviar o publicar.
- ✓Fija la versión del paquete y prueba cada actualización antes de desplegarla.
07 Por qué el Agent SDK importa a las empresas
Construir un agente fiable cuesta más de lo que parece: hay que gestionar el contexto cuando crece, reintentar herramientas que fallan, decidir qué puede hacer sin permiso y registrar lo que pasa. El Agent SDK resuelve esas piezas con el mismo código que Anthropic usa en su propio producto, así que el equipo se centra en lo que aporta valor: las herramientas, los datos y las reglas de negocio. Si quieres entender el concepto general antes de elegir tecnología, empieza por qué es un agente de IA. Y si prefieres que alguien lo diseñe y lo ponga en marcha contigo, como agencia de IA trabajamos con estas herramientas a diario.
Preguntas frecuentes sobre Claude Agent SDK
Es una librería de Anthropic para Python y TypeScript que permite crear agentes con el mismo motor de Claude Code: bucle agéntico, herramientas, gestión de contexto, subagentes, hooks y MCP.
Sí. Es el mismo proyecto con otro nombre. Anthropic lo renombró en 2025 porque se usaba para muchos tipos de agentes, no solo de programación, y cambió los nombres de los paquetes.
El SDK de la API envía mensajes al modelo y, como mucho, automatiza el bucle sobre tus propias funciones. El Agent SDK incluye herramientas de archivos, terminal y web, gestión de contexto y permisos.
La librería es gratuita; pagas los tokens que consume el agente en la API de Claude o en tu proveedor cloud, más la infraestructura donde lo ejecutes.
El SDK se encarga de ejecutar el motor de Claude Code por ti. Consulta los requisitos de tu versión en la documentación oficial, porque la forma de distribuirlo ha cambiado con el tiempo.
Sí. Puedes conectar servidores MCP externos o definir herramientas propias dentro del mismo proceso, y el agente las usa como cualquier otra herramienta.
Fuentes consultadas
Sobre el autor
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil y artículos → Ver perfil en LinkedIn ↗