Has decidido implementar un agente de IA en producción con Claude. La primera decisión arquitectónica es dónde ejecutar el bucle del agente: ¿delegarlo a Anthropic con Claude Managed Agents, o mantenerlo dentro de tu propio proceso con el Claude Agent SDK? La diferencia no es solo de API: afecta residencia de datos, costos, observabilidad, ejecución de herramientas y quién responde cuando algo falla a las 2 a.m.
En resumen
Elige Claude Managed Agents si quieres que Anthropic aloje el bucle del agente, el sandbox y el estado de sesión para trabajos largos o asíncronos. Elige Claude Agent SDK si necesitas ejecutar el bucle en tu propia infraestructura, con control granular sobre herramientas, permisos, datos y costos operativos. Ambos usan modelos Claude y pueden conectarse a herramientas externas mediante MCP.
Introducción
En 2026, “construir un agente de IA” ya no significa envolver una llamada de chat en un while. Anthropic ofrece dos formas distintas de ejecutar agentes en producción:
- Claude Managed Agents: API REST alojada. Anthropic ejecuta el bucle, el sandbox y la sesión.
- Claude Agent SDK: biblioteca Python/TypeScript. Tú ejecutas el bucle dentro de tu proceso.
La elección define:
- dónde viven los datos del cliente;
- cómo se ejecutan herramientas y APIs;
- qué observabilidad tienes;
- cómo se calcula el costo;
- qué equipo opera el runtime.
La mayoría de los agentes reales no solo “responden”: llaman APIs. Por ejemplo:
- emitir un reembolso;
- crear un ticket;
- consultar inventario;
- ejecutar una acción interna;
- leer o escribir archivos;
- llamar un servidor MCP.
Por eso, antes de decidir el modelo de alojamiento, necesitas probar las APIs y herramientas que el agente usará. Con Apidog puedes mockear dependencias, validar contratos y probar servidores MCP antes de conectar el agente a datos reales. Si quieres profundizar en la opción alojada, consulta la guía de Claude Managed Agents.
Qué es Claude Managed Agents
Claude Managed Agents es un runtime gestionado por Anthropic para ejecutar agentes. En lugar de implementar tu propio bucle, sandbox, estado y orquestación de herramientas, defines un agente y Anthropic lo ejecuta.
Se lanzó en beta pública en abril de 2026 y requiere el encabezado beta:
anthropic-beta: managed-agents-2026-04-01
El SDK puede configurarlo por ti.
Conceptos principales
Claude Managed Agents se organiza alrededor de cuatro conceptos:
| Concepto | Qué representa |
|---|---|
| Agente | Modelo, prompt del sistema, herramientas, servidores MCP y habilidades. |
| Entorno | Plantilla de contenedor con paquetes, runtime y reglas de red. |
| Sesión | Ejecución concreta de un agente dentro de un entorno. Mantiene historial y archivos. |
| Eventos | Mensajes entre tu aplicación y el agente: entrada del usuario, resultados de herramientas, estado y respuestas. |
El flujo típico es:
- Crear un agente.
- Configurar un entorno.
- Iniciar una sesión.
- Enviar eventos de usuario.
- Recibir respuestas por streaming.
- Recuperar el historial completo para auditoría o debugging.
Ejemplo conceptual:
App → crea sesión → envía evento de usuario
Managed Agent → razona → solicita herramienta
App → ejecuta herramienta personalizada → devuelve resultado
Managed Agent → continúa → transmite respuesta final
Herramientas disponibles
Managed Agents incluye herramientas integradas como:
- Bash;
- lectura, escritura y edición de archivos;
- glob y grep;
- búsqueda web;
- obtención de contenido web;
- conexión a servidores MCP.
Para herramientas personalizadas, el patrón es importante:
- Claude decide llamar la herramienta.
- Tu aplicación ejecuta la herramienta.
- Tu aplicación devuelve el resultado al flujo de eventos.
Es decir: Anthropic aloja el bucle y el sandbox, pero tus acciones internas sensibles pueden seguir ejecutándose en tu infraestructura.
Cuándo encaja mejor
Usa Managed Agents cuando tu agente:
- corre durante minutos u horas;
- hace muchas llamadas a herramientas;
- funciona de forma asíncrona;
- necesita estado persistente entre interacciones;
- no justifica que operes tu propio sandbox;
- puede mantener el estado de sesión en infraestructura de Anthropic o AWS.
Ten en cuenta que algunas capacidades, como resultados y multiagente, pueden estar restringidas detrás de una vista previa de investigación. Verifica siempre la documentación actual antes de diseñar sobre esas funciones. Para entender el patrón general, consulta el artículo sobre arquitectura de IA agéntica.
Qué es Claude Agent SDK
Claude Agent SDK es una biblioteca para Python y TypeScript que expone el bucle de agente, herramientas integradas y gestión de contexto que impulsan Claude Code. Antes se llamaba Claude Code SDK; el cambio de nombre refleja que ahora apunta a agentes de propósito general, no solo tareas de código.
Instalación:
pip install claude-agent-sdk
O en Node.js:
npm install @anthropic-ai/claude-agent-sdk
La diferencia clave frente al Client SDK básico es que no tienes que implementar manualmente el bucle:
while response.stop_reason == "tool_use":
ejecutar_herramienta()
enviar_resultado()
El Agent SDK ya trae esa maquinaria.
Ejemplo mínimo en Python
Un agente mínimo se parece a esto a nivel conceptual:
from claude_agent_sdk import query, ClaudeAgentOptions
options = ClaudeAgentOptions(
allowed_tools=["Read", "Write", "Edit", "Bash", "Grep"]
)
async for message in query(
prompt="Revisa este proyecto y sugiere mejoras en la configuración.",
options=options
):
print(message)
El agente puede leer archivos, ejecutar comandos y editar contenido según los permisos configurados.
Capacidades relevantes
El SDK incluye:
| Capacidad | Uso práctico |
|---|---|
| Herramientas integradas |
Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch, Monitor, AskUserQuestion. |
| Hooks | Validar, registrar, bloquear o transformar acciones en puntos del ciclo de vida. |
| Subagentes | Delegar subtareas especializadas y rastrear qué subagente hizo qué. |
| MCP | Conectar bases de datos, navegadores, APIs y servicios externos. |
| Permisos | Aprobar herramientas seguras, bloquear acciones peligrosas o requerir aprobación humana. |
| Sesiones | Reanudar o bifurcar contexto usando estado local JSONL. |
Ejemplo de regla con hooks:
def pre_tool_use_hook(tool_name, tool_input):
if tool_name == "Bash" and "rm -rf" in tool_input.get("command", ""):
raise PermissionError("Comando bloqueado por política interna")
return tool_input
Ese tipo de control es difícil de replicar si el bucle completo vive fuera de tu proceso.
Configuración local
Como el SDK corre en tu proceso, también puede leer configuración usada por Claude Code:
-
.claude/skills/; - comandos de barra;
-
CLAUDE.md; - plugins;
- estado de sesión local.
La autenticación puede ir por:
- API directa de Anthropic;
- Amazon Bedrock;
- Claude Platform en AWS;
- Google Vertex AI;
- Azure AI Foundry.
Si necesitas una guía práctica, revisa cómo configurar Claude Agent SDK con un plan de Claude y cómo construir tu propio Claude Code.
Nota de facturación
A partir del 15 de junio de 2026, el uso del Agent SDK y claude -p en planes de suscripción se extrae de un crédito mensual separado del Agent SDK, distinto de los límites interactivos. Si tu forecast asumía que todo compartía el mismo pool, revísalo con los términos actuales de Anthropic.
Comparación: Managed Agents vs Agent SDK
Antes de presupuestar, confirma precios en la página de precios de Anthropic y en la documentación de Managed Agents.
| Dimensión | Claude Managed Agents | Claude Agent SDK |
|---|---|---|
| Dónde se ejecuta el bucle | Infraestructura gestionada por Anthropic | Tu proceso e infraestructura |
| Interfaz | API REST + eventos SSE | Biblioteca Python o TypeScript |
| Control del bucle | Configuración y dirección vía eventos | Hooks, permisos y lógica en proceso |
| Costos | Tokens Claude + tarifa por hora de sesión activa | Tokens Claude + tu infraestructura |
| Operación | Baja carga operativa | Tú escalas, monitoreas y operas |
| Observabilidad | Registro de eventos alojado y recuperable | Hooks, logs y trazas que tú instrumentes |
| Latencia | Salto al runtime alojado | Bucle cercano a tus datos y servicios |
| Residencia de datos | Sandbox y estado en Anthropic o AWS | Estado y herramientas en tu infraestructura |
| Herramientas personalizadas | Claude solicita; tu app ejecuta y devuelve resultado | Funciones Python/TypeScript en proceso |
| Mejor para | Agentes largos, asíncronos y con poca infraestructura propia | Agentes cercanos a datos internos, VPC o filesystem |
Costo
Managed Agents añade una tarifa por tiempo de sesión activa. Si el agente “piensa” durante mucho tiempo o queda activo entre llamadas de herramientas, ese tiempo cuenta.
Con el SDK no pagas esa tarifa de runtime a Anthropic, pero sí pagas:
- servidores;
- escalado;
- monitoreo;
- sandboxing;
- ingeniería de guardia.
No compares solo el precio unitario. Compara el costo total de operar el sistema.
Operación
Managed Agents elimina de tu backlog:
- sandbox;
- persistencia de sesión;
- escalado del runtime;
- parte de la observabilidad.
El SDK te da control sobre todo eso, pero también te obliga a operarlo.
Residencia de datos
Con el SDK:
- las herramientas corren en tu infraestructura;
- el estado de sesión puede quedarse en tu filesystem o almacenamiento;
- solo la inferencia va a Claude.
Con Managed Agents:
- el sandbox vive en infraestructura gestionada por Anthropic o AWS;
- el historial de eventos queda alojado;
- debes validar si cumple tus requisitos regulatorios.
Para datos regulados, esta suele ser la decisión principal.
Observabilidad
Managed Agents te da un registro de eventos recuperable.
Con el SDK, debes instrumentar:
- hooks;
- logs estructurados;
- trazas;
- métricas por herramienta;
- auditoría de decisiones sensibles.
Ejemplo de eventos útiles en un agente con SDK:
{
"session_id": "refund-123",
"tool": "payments.refund",
"amount": 129.99,
"approved_by_human": true,
"status": "success",
"latency_ms": 842
}
Prueba y depuración de las APIs que llaman tus agentes
Da igual dónde ejecutes el bucle: la fiabilidad del agente depende de las APIs y herramientas que llama.
Un agente de reembolso puede razonar bien, pero si el endpoint de pagos es ambiguo ante un 504, puedes terminar emitiendo dos reembolsos.
Prueba tres capas antes de producción.
1. Contratos de API
Cada herramienta del agente tiene un contrato:
- entrada esperada;
- salida esperada;
- errores posibles;
- semántica de reintentos;
- idempotencia.
Con Apidog puedes:
- definir el esquema del endpoint;
- crear mocks para pagos, tickets o inventario;
- ejecutar pruebas de contrato;
- detectar cambios incompatibles antes de que lleguen al agente.
Ejemplo de contrato esperado para una herramienta de reembolso:
{
"transaction_id": "txn_123",
"amount": 49.99,
"reason": "duplicate_charge",
"idempotency_key": "refund_txn_123_duplicate_charge"
}
Respuesta esperada:
{
"refund_id": "ref_456",
"status": "succeeded",
"transaction_id": "txn_123"
}
Si el backend cambia status por state, el agente puede romperse silenciosamente. Una prueba de contrato debe fallar antes.
Para más detalles, revisa la guía sobre cómo probar agentes de IA que llaman APIs.
2. Servidores MCP
Ambas opciones pueden enrutar herramientas externas vía MCP. Un servidor MCP también debe probarse como cualquier API.
Casos típicos de fallo:
- una herramienta devuelve un payload distinto;
- un timeout no está normalizado;
- un error devuelve texto libre en vez de JSON;
- la descripción de la herramienta induce llamadas incorrectas;
- faltan validaciones de entrada.
Antes de conectarlo al agente:
- enumera las herramientas que expone el servidor MCP;
- ejecuta cada herramienta con entradas válidas;
- prueba entradas inválidas;
- valida errores y timeouts;
- verifica que los esquemas coincidan con lo que el agente espera.
La guía de pruebas de servidor MCP con Apidog cubre este flujo.
3. Patrón real de llamadas del agente
Los agentes no llaman APIs como humanos. Pueden hacer:
- reintentos en ráfaga;
- llamadas parciales;
- lecturas repetidas;
- loops sobre el mismo endpoint;
- secuencias inesperadas de herramientas.
Reproduce tráfico realista contra mocks antes de producción.
Ejemplo de escenario que debes probar:
1. El agente llama payments.refund.
2. El endpoint responde 504.
3. El reembolso sí se procesó internamente.
4. El agente intenta llamar payments.refund otra vez.
5. La API debe bloquear el duplicado vía idempotency_key.
Si descubres esto en staging, es una prueba útil. Si lo descubres con dinero real, es un incidente.
Apidog también incluye un agente de IA y un depurador A2A para inspeccionar tráfico de solicitudes y respuestas generado por agentes. Puedes descargar Apidog y validar dependencias antes de conectar el agente a clientes reales.
Marco de decisión
No elijas por features aisladas. Responde estas preguntas en orden.
Elige Claude Managed Agents si
- Tu agente corre durante minutos u horas.
- El trabajo es asíncrono.
- No quieres operar workers, sandbox ni almacén de sesiones.
- Tu equipo es pequeño y la restricción principal es operación.
- Quieres un registro de eventos alojado.
- Tus requisitos permiten que el sandbox y el estado vivan en Anthropic o AWS.
- Puedes trabajar con una beta y validar funciones disponibles.
Elige Claude Agent SDK si
- El agente debe correr dentro de tu VPC.
- Necesitas acceso a bases de datos o servicios privados.
- No quieres que el estado de sesión salga de tu infraestructura.
- Necesitas hooks para auditoría, seguridad o aprobación humana.
- Quieres lógica de herramientas en proceso.
- Debes usar contratos existentes con Bedrock, Vertex o Azure.
- Estás prototipando localmente sobre tu filesystem.
Camino común
Un flujo razonable es:
- Prototipar con Agent SDK localmente.
- Probar herramientas y APIs con mocks.
- Instrumentar llamadas reales.
- Evaluar costos y carga operativa.
- Migrar a Managed Agents si el ahorro operativo compensa la pérdida de control.
Pero no lo trates como un switch de configuración. Cambian:
- la interfaz;
- el manejo de eventos;
- la ejecución de herramientas personalizadas;
- el estado de sesión;
- la observabilidad.
Si también estás comparando modelos o agentes de coding, la comparación de Claude vs Codex para 2026 puede servir como lectura complementaria.
Casos de uso reales
1. Agente de reembolso de pagos
Escenario:
Un equipo de soporte fintech quiere un agente que:
- lea un ticket;
- busque la transacción;
- valide la política de reembolso;
- llame la API de pagos;
- escriba el resumen en el ticket.
Este agente mueve dinero. Necesita:
- contratos de API estrictos;
- idempotencia;
- auditoría;
- aprobación humana para casos sensibles;
- ejecución dentro de la VPC.
La mejor opción suele ser Claude Agent SDK.
Ejemplo de política con hook:
REFUND_APPROVAL_THRESHOLD = 100
def pre_tool_use(tool_name, tool_input):
if tool_name == "payments.refund":
amount = tool_input["amount"]
if amount > REFUND_APPROVAL_THRESHOLD:
if not tool_input.get("human_approval_id"):
raise PermissionError(
"Los reembolsos superiores a 100 requieren aprobación humana"
)
return tool_input
Antes de lanzar, el equipo debería:
- mockear pagos y contabilidad en Apidog;
- probar contratos de búsqueda y reembolso;
- reproducir tickets históricos;
- validar reintentos e idempotencia;
- registrar cada acción sensible.
Un bug típico a buscar: el agente reintenta un reembolso tras un 504, aunque el reembolso original sí se procesó.
2. Agente asíncrono de triaje de tickets
Escenario:
Una empresa SaaS recibe miles de tickets diarios y quiere un agente que:
- clasifique tickets;
- busque logs relacionados;
- redacte una respuesta;
- resuelva o escale.
Cada ticket tarda varios minutos, los datos son de baja sensibilidad y el equipo no quiere operar workers.
La mejor opción suele ser Claude Managed Agents.
Razones:
- carga asíncrona;
- sesiones de varios minutos;
- registro de eventos por ticket;
- menor carga operativa;
- infraestructura gestionada.
Aun así, debes probar:
- API de tickets;
- API de logs;
- servidor MCP;
- cambios de esquema;
- timeouts;
- errores parciales.
El runtime puede estar gestionado, pero la corrección de tus APIs sigue siendo tu responsabilidad.
3. Agente interno de operaciones de datos detrás del firewall
Escenario:
Un equipo de plataforma quiere un agente para solicitudes internas como:
Reprocesa las particiones ETL fallidas de ayer y reporta el estado.
El agente necesita:
- consultar APIs internas;
- ejecutar scripts;
- acceder a servicios privados;
- registrar comandos;
- operar detrás del firewall.
La mejor opción es Claude Agent SDK.
Aquí “corre en tu proceso” no es una preferencia: es un requisito.
Flujo recomendado:
- Exponer servicios internos como herramientas MCP.
- Probar cada herramienta MCP de forma aislada.
- Ejecutar el agente en la red interna.
- Usar hooks para registrar comandos.
- Enviar auditoría a tu pipeline existente.
Para entender por qué los agentes se están convirtiendo en consumidores primarios de API, revisa agentes de IA como los nuevos consumidores de API.
Conclusión
La decisión entre Claude Managed Agents y Claude Agent SDK es una decisión de operación y gobernanza de datos, no solo una elección de API.
Qué recordar:
- Managed Agents aloja el bucle y el sandbox; el SDK los ejecuta en tu proceso.
- Managed Agents reduce operación; el SDK aumenta control.
- El costo cambia de forma: runtime gestionado vs infraestructura propia.
- La residencia de datos puede decidirlo todo.
- Los hooks del SDK son clave para auditoría y políticas sensibles.
- Los eventos de Managed Agents son útiles para debugging y trazabilidad.
- Prueba APIs y servidores MCP antes de producción.
- Prototipar con SDK y producir con Managed Agents es viable, pero requiere migración real.
- Verifica precios y estado beta en la fuente antes de comprometer arquitectura o presupuesto.
Siguiente paso: antes de conectar un agente a cualquier acción que afecte clientes, prueba sus dependencias. Descarga Apidog para mockear endpoints, ejecutar pruebas de contrato y depurar tráfico real de agentes.
Preguntas frecuentes
¿Cuál es la diferencia fundamental entre Claude Managed Agents y Claude Agent SDK?
Claude Managed Agents es una API REST alojada donde Anthropic ejecuta el bucle del agente y un sandbox por sesión. Tú envías eventos y recibes resultados en streaming.
Claude Agent SDK es una biblioteca Python o TypeScript que ejecuta el bucle dentro de tu propio proceso e infraestructura.
Mismos modelos Claude, distinta propiedad operativa.
¿Claude Agent SDK es lo mismo que el antiguo Claude Code SDK?
Sí. Claude Code SDK fue renombrado a Claude Agent SDK para reflejar un alcance más amplio que tareas de coding. Expone la misma maquinaria de bucle de agente, herramientas integradas y gestión de contexto que impulsa Claude Code.
¿Qué opción es más barata?
Depende de la carga.
Managed Agents cobra tokens Claude más tarifa de ejecución por tiempo de sesión activa. El SDK no tiene esa tarifa de runtime de Anthropic, pero tú pagas cómputo, escalado, monitoreo y operación.
Confirma siempre tarifas actuales en la página de precios de Anthropic.
¿Puedo usar servidores MCP con ambos?
Sí. Ambos pueden usar MCP para conectar herramientas externas.
Por eso conviene probar los servidores MCP antes de conectarlos al agente. La guía sobre cómo probar servidores MCP con Apidog muestra cómo ejercitar cada herramienta expuesta.
¿Cómo mantengo datos de cliente fuera de la infraestructura de Anthropic?
Usa Claude Agent SDK y ejecuta el bucle en tu propio entorno.
Con el SDK:
- las herramientas corren en tu infraestructura;
- el estado de sesión permanece bajo tu control;
- solo la inferencia va a Claude.
Con Managed Agents, el sandbox y el registro de eventos residen en infraestructura gestionada por Anthropic o AWS, sujeto a sus condiciones.
¿Claude Managed Agents está listo para producción?
Se lanzó en beta pública en abril de 2026 y requiere el encabezado:
anthropic-beta: managed-agents-2026-04-01
La funcionalidad básica de sesión está disponible para cuentas API, pero algunas capacidades pueden requerir acceso separado de investigación. Trátalo como beta y revisa la documentación actual.
¿Cómo pruebo un agente antes de que toque APIs reales?
Hazlo en tres pasos:
- Mockea cada API y servidor MCP.
- Escribe pruebas de contrato para requests y responses.
- Reproduce tráfico realista del agente contra esos mocks.
Apidog cubre esos flujos, incluyendo agente de IA y depurador A2A para inspeccionar tráfico en vivo. La guía sobre cómo probar agentes de IA que llaman APIs detalla los modos de fallo más comunes.
¿Puedo empezar con uno y cambiar al otro después?
Sí. Un camino común es prototipar con Agent SDK y luego migrar a Managed Agents para producción si conviene operativamente.
Pero no es un cambio trivial. Cambian:
- biblioteca vs REST + eventos;
- ejecución de herramientas personalizadas;
- estado de sesión;
- observabilidad;
- estrategia de permisos.
Planifícalo como una migración.
Top comments (0)