Guías

Claude Agent SDK: cómo usar Claude Code como librería sin perder control

Claude Agent SDK permite meter el motor de Claude Code dentro de tus propios scripts y servicios. La parte difícil no es instalarlo: es acotar permisos, contexto, coste y ejecución.

DevAI Editorial

— 9 min de lectura
Compartir
Claude Agent SDK: cómo usar Claude Code como librería sin perder control

Claude Agent SDK permite meter el motor de Claude Code dentro de tus propios scripts y servicios. La parte difícil no es instalarlo: es acotar permisos, contexto, coste y ejecución.

Claude Agent SDK es la forma oficial de usar el motor de Claude Code desde Python o TypeScript. En vez de abrir Claude Code como herramienta interactiva, lo invocas desde tu propio programa para que lea archivos, ejecute comandos, edite código, use MCP y devuelva eventos que puedes registrar o transformar.

Checklist

Qué cambia frente a usar Claude Code en la terminal

Claude Code interactivo está pensado para una persona que conversa, aprueba acciones y revisa cambios. Claude Agent SDK mueve ese mismo tipo de agente a un proceso programable: un job de CI, una herramienta interna, un servicio de revisión, un bot de documentación o un script que triagea incidencias.

La diferencia práctica es el contrato. En terminal, la sesión puede ser exploratoria. En SDK, tu código decide prompt, directorio de trabajo, herramientas permitidas, modo de permisos, número de turnos, MCP servers, hooks y cómo consumir los mensajes. Eso permite producto interno, pero también elimina parte del freno humano si lo configuras mal.

La definición citable: Claude Agent SDK convierte Claude Code en una librería para construir agentes que operan sobre código y herramientas del sistema con controles programáticos de permisos, contexto y observabilidad.

Recibe una lectura semanal de herramientas IA para devs

Si quieres seguir SDKs de agentes, Claude Code, MCP y automatización para devs sin tragarte cada changelog, DevAI Semanal te lo resume cada semana en un email de 5 minutos.

Suscribirme gratis

Arranque mínimo en Python

La documentación oficial muestra el patrón base con `query()` y `ClaudeAgentOptions`. La idea es crear una corrutina que consume eventos del agente mientras trabaja. En un script real, no imprimiría todo sin filtrar: separaría mensajes de estado, cambios propuestos, errores y métricas.

Ejemplo conceptual: instala `claude-agent-sdk`, ejecuta desde un repo de pruebas y limita herramientas al principio con `allowed_tools=["Read", "Grep", "Edit", "Bash"]`. Si el agente solo debe inspeccionar, quita `Edit` y restringe Bash a comandos de lectura o ejecución de tests.

El error común es empezar con permisos amplios porque el primer demo parece funcionar mejor. Para una automatización mantenible, define antes el scope: directorio, ramas permitidas, comandos aceptables, límites de turnos, qué se considera éxito y dónde se guarda el resultado.

Arranque mínimo en TypeScript

El paquete `@anthropic-ai/claude-agent-sdk` expone el mismo tipo de idea para Node: lanzar una consulta, configurar opciones y procesar mensajes. La documentación indica que el SDK incluye un binario nativo de Claude Code como dependencia opcional; si tu gestor de paquetes omite dependencias opcionales, tendrás que apuntar a un binario `claude` instalado por separado.

Puntos a revisar

Lo que conviene comprobar

TypeScript encaja especialmente bien si el workflow vive cerca de una plataforma interna: GitHub App, cola de trabajos, dashboard de revisión o servicio que dispara tareas desde incidencias. Aun así, no metas el agente dentro de una request HTTP larga. Lánzalo como job, persiste estado y devuelve progreso.

Una arquitectura sana separa tres piezas: una API fina que valida la petición, una cola que ejecuta el agente con límites y un store de resultados con logs, artifacts y enlace al diff. El SDK no sustituye esa infraestructura; solo te da el ejecutor agentic.

Checklist

Permisos: allowed_tools no es decoración

Claude Code parte de un modelo de permisos con lectura por defecto y aprobación para acciones más sensibles. En SDK debes convertir esa filosofía en política explícita. `allowed_tools`, `disallowed_tools` y `permission_mode` no son detalles de ejemplo: son el perímetro de la automatización.

Para un primer piloto, usaría un perfil de solo lectura: `Read`, `Grep`, quizá herramientas MCP de consulta y ningún `Edit` ni `Bash` mutante. El segundo perfil permitiría editar en una rama temporal y ejecutar tests conocidos. El tercer perfil, con herramientas externas o comandos de despliegue, debería requerir revisión humana y entorno aislado.

También conviene versionar los prompts y opciones del agente igual que versionas código. Si cambias permisos, modelo, MCP servers o prompt de sistema, eso es un cambio de comportamiento operativo, no una preferencia local.

Checklist

MCP dentro del SDK

El atractivo del SDK sube cuando el agente puede usar MCP: GitHub, issues, documentación, errores de observabilidad, bases internas o herramientas de producto. Pero cada MCP server añade herramientas al contexto y nuevas rutas de exfiltración o acción.

Mi regla: MCP de lectura primero, herramientas mutantes después y solo con nombres estrechos. Un servidor `github_read` que lista issues y lee PRs es mucho más auditable que un servidor genérico con write access. Para salidas críticas, combina MCP con contratos validados como `outputSchema` o validación propia en tu aplicación.

No conectes todos los MCP servers disponibles por comodidad. El agente debería recibir solo las herramientas necesarias para esa tarea, y los nombres de herramientas deberían dejar claro qué hacen. Un prompt no compensa una tool demasiado poderosa.

Métricas mínimas: duración, turnos, coste estimado, herramientas usadas, comandos Bash, archivos tocados, tests ejecutados, tasa de éxito, tasa de rollback y porcentaje de salidas aceptadas por humanos. Si solo mides número de tareas lanzadas, estás midiendo actividad, no productividad.

Checklist de implementación

  • Elige un caso de uso estrecho con salida revisable.
  • Ejecuta el agente en un repo o workspace temporal.
  • Define `allowed_tools` y `disallowed_tools` por perfil.
  • Limita turnos, duración y tamaño de contexto.
  • Empieza con MCP de lectura y scopes mínimos.
  • Registra eventos, herramientas usadas, coste y archivos tocados.
  • Ejecuta tests conocidos antes de aceptar resultados.
  • Guarda artifacts y logs con retención explícita.
  • Requiere revisión humana para cambios mutantes o externos.
  • Documenta rollback antes de integrarlo en CI o producto interno.

Errores que veo venir

El primero es vender el SDK como framework universal de agentes. No lo es. Es una forma potente de programar agentes con capacidades de Claude Code. Si tu dominio no necesita filesystem, comandos o herramientas de desarrollo, probablemente hay opciones más simples.

Puntos a revisar

Lo que conviene comprobar

El segundo es lanzar agentes desde producción con secretos disponibles en el entorno. Si el proceso puede leer variables sensibles, logs o archivos privados, asume que el agente podría incluirlos en contexto o salida si el prompt y las herramientas lo empujan en esa dirección.

El tercero es no diferenciar exploración de ejecución. Un agente exploratorio puede devolver un plan. Un agente ejecutor cambia archivos o llama APIs. Mezclar ambos perfiles hace que las revisiones sean confusas y que los permisos terminen siendo demasiado amplios.

Checklist

Conclusión

Claude Agent SDK es interesante porque evita reimplementar el loop más difícil: lectura de código, uso de herramientas, edición, comandos, contexto y eventos. Pero precisamente por eso merece un diseño serio. No estás llamando a un modelo; estás arrancando un trabajador agentic con acceso a un entorno.

Mi recomendación: empieza con un agente de lectura o revisión, no con un bot que modifica todo. Mide coste y aceptación, restringe tools, usa workspaces temporales, registra eventos y deja que humanos aprueben los cambios. Si el flujo funciona así, ampliar permisos será una decisión técnica, no un acto de fe.

Preguntas frecuentes

¿Qué es Claude Agent SDK?

Claude Agent SDK es el SDK oficial para usar capacidades de Claude Code desde Python o TypeScript dentro de tus propias automatizaciones.

¿Claude Agent SDK reemplaza a Claude Code?

No. Claude Code es la experiencia interactiva; Claude Agent SDK sirve para programar flujos agentic con el mismo tipo de capacidades desde tu aplicación o script.

¿Cuándo conviene usar Claude Agent SDK?

Conviene cuando el agente necesita leer repos, editar archivos, ejecutar comandos, usar herramientas y producir resultados revisables.

¿Claude Agent SDK es mejor que la API normal de Claude?

No siempre. Para tareas simples o salidas estructuradas sin herramientas, la API normal suele ser más simple y controlable.

¿Claude Agent SDK funciona con MCP?

Sí. El SDK puede trabajar con configuración de MCP para que el agente use herramientas externas, pero conviene limitar servidores y permisos.

¿Qué riesgos tiene Claude Agent SDK?

Los riesgos principales son permisos demasiado amplios, exposición de secretos, comandos Bash peligrosos, coste no observado, MCP servers excesivos y falta de revisión humana.

Fuentes y referencias

También te puede interesar

Claude Code Skills y SKILL.mdClaude Code subagents: contexto y permisosHooks para agentes de códigoMCP outputSchema y structuredContentMétricas para agentes de código

Recibe una lectura semanal de herramientas IA para devs

Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.

Suscribirme gratis

Leer más