Cómo utilizar Claude Managed Agents: una guía de configuración paso a paso

Crear un agente de IA implica mucho más que realizar una llamada al modelo. Debes gestionar el bucle del agente, ejecutar herramientas, proporcionar un entorno de ejecución, mantener el estado de la sesión, gestionar permisos y observar lo que hace el agente.

Claude Managed Agents se encarga de gran parte de esta infraestructura por ti. En lugar de crear y operar tu propio entorno de ejecución de agentes, defines el agente, configuras dónde se ejecuta y creas sesiones para que realice tareas. El entorno de ejecución gestionado se encarga de las llamadas al modelo y de la ejecución de herramientas, mientras tu aplicación interactúa con el agente a través de eventos.

En esta guía, te mostraremos cómo utilizar Claude Managed Agents paso a paso desde la creación de tu primer agente y la configuración de su entorno hasta la ejecución de una sesión, la adición de herramientas y servidores MCP, y la gestión de eventos del agente.

Si prefieres empezar por los conceptos básicos, consulta nuestra guía sobre qué son los Claude Managed Agents y cómo funciona su arquitectura. Esta guía asume que ya estás listo para empezar a desarrollar.

Requisitos previos

Antes de crear un Managed Agent, necesitarás:

1. Una cuenta en la consola de Claude
2. Una clave de API de Anthropic
3. El SDK de Anthropic
4. Python, TypeScript u otro lenguaje compatible

Paso 1: Instalar la CLI y el SDK

Para Python, instala el SDK:

A continuación, establece tu clave de API como variable de entorno:

Anthropic también proporciona un ant CLI para gestionar recursos de Managed Agents.

El SDK lee la clave de tu entorno, por lo que no necesitas incluirla directamente en el código de tu aplicación.

Habilitar la API de Managed Agents

Claude Managed Agents está disponible actualmente a través de la API beta de Anthropic. La versión beta de Managed Agents se identifica mediante la:

managed-agents-2026-04-01cabecera beta.

Cuando utilizas el SDK oficial, este gestiona dicha cabecera automáticamente al acceder a las API de Managed Agents.

La configuración básica del cliente tiene este aspecto:

En este punto, tu aplicación ya está lista para trabajar con la API de Managed Agents.

El siguiente paso es crear el agente en sí: definir qué modelo de Claude utiliza, qué instrucciones sigue y a qué herramientas puede acceder.

Paso 2: Define tu agente

Un agente es un archivo Markdown. El frontmatter contiene la configuración del agente, mientras que el cuerpo contiene su system prompt.

Aquí tienes un ejemplo de un agente que redacta notas de lanzamiento a partir de un repositorio:‍


Elagent_toolset_20260401 El conjunto de herramientas proporciona al agente acceso a las herramientas preconfiguradas de Anthropic, incluyendo capacidades como comandos de shell y operaciones de archivo. También puedes configurar herramientas individuales si no necesitas el conjunto completo. Consulta la referencia de herramientas para ver las opciones disponibles.

Guarda la configuración como release-notes-agent.md, y luego aplícala con la CLI de ant :

ant apply release-notes-agent.md


Esto crea el agente y devuelve su ID.

El agente es un recurso persistente. Lo creas una vez y luego haces referencia a su ID cada vez que inicies una sesión que lo utilice; no es necesario volver a crear el agente para cada tarea.

A continuación, crearás el entorno donde se ejecutarán las sesiones de tu agente.

Paso 3: Crear un entorno

El entorno define el espacio aislado (sandbox) donde se ejecutarán las sesiones de tu agente.

Crea un archivo environment.yaml :‍


Luego aplícalo:

ant apply environment.yaml


También puedes aplicar el agente y el entorno juntos:

Elnetworking: unrestricted , este ajuste otorga al espacio aislado acceso total a la red. Para agentes que trabajen con sistemas internos o datos confidenciales, utiliza una configuración de red más restrictiva.

Ya tienes los dos recursos necesarios para ejecutar un agente:

• Agente: define qué es el agente y qué puede hacer.
• Entorno: define dónde se ejecuta el agente.

A continuación, crearás una sesión que los conecte.

Paso 4: Iniciar una sesión

Una sesión es una instancia en ejecución de tu agente trabajando en una tarea específica.

Crea una sesión pasando los ID de tu agente y de tu entorno:

El ID de sesión identifica esta ejecución en particular. Lo usarás para enviar mensajes, transmitir eventos y seguir interactuando con el agente.

El mismo agente puede tener varias sesiones. Por ejemplo, tu Release Notes Agent podría ejecutar una sesión independiente para cada versión manteniendo la misma configuración del agente.

Paso 5: Enviar un mensaje y transmitir la respuesta

Con la sesión en marcha, asígnale una tarea al agente.

Abre primero el flujo de eventos y, a continuación, envía el mensaje del usuario:‍


Detrás de esta llamada, el entorno de ejecución gestionado aprovisiona el sandbox a partir de la configuración de tu entorno, inicia el bucle del agente, permite que Claude seleccione y ejecute herramientas, y transmite los eventos de vuelta a tu aplicación.

Los tres tipos de eventos anteriores son los que normalmente gestionarás primero:

• agent.message — el agente envía una respuesta.
• agent.tool_use — el agente utiliza una herramienta.
• session.status_idle — el agente ha terminado su tarea actual.

Para consultar la lista completa de eventos, incluidos los cambios de estado y los errores, visita la referencia de eventos y streaming.

En este punto, ya tienes un Agente Gestionado operativo: lo has definido, le has proporcionado un entorno de ejecución, has iniciado una sesión y le has enviado una tarea.

A continuación, veremos cómo dirigir un agente en ejecución y gestionar sesiones de larga duración.

Paso 6: Dirigir un agente en ejecución

No tienes que esperar a que un agente termine para cambiar su rumbo.

Puedes enviar un user.interrupt evento para detener el turno actual, seguido de un user.message con la nueva instrucción:

La interrupción detiene la respuesta actual del modelo y devuelve el control a la sesión. Si el agente está en medio de una llamada a una herramienta, la interrupción puede tardar más en aplicarse mientras dicha herramienta finaliza. Una vez procesada la interrupción, la sesión vuelve al estado idle, y el siguiente user.message inicia el siguiente turno.

Esto resulta útil para tareas de larga duración en las que te das cuenta de que el agente se está desviando. En lugar de finalizar la sesión y empezar de cero, puedes reutilizar la misma sesión y redirigirla con contexto adicional.

También puedes interrumpir una sesión en ejecución sin enviar inmediatamente una nueva instrucción:‍


La sesión permanece disponible tras la interrupción, por lo que puedes examinar lo ocurrido y decidir qué enviar a continuación.

A continuación, verás cómo gestionar lo que sucede cuando tu aplicación pierde la conexión con una sesión en curso.

Paso 7: Gestionar desconexiones y reanudar sesiones

Una conexión en streaming puede desconectarse mientras un agente sigue trabajando. Eso no significa que la sesión o su trabajo se pierdan.

Managed Agents conserva el historial de eventos de la sesión en el servidor, por lo que tu aplicación puede volver a conectarse a la misma sesión en lugar de reiniciar la tarea.

Lo importante es mantén el ID de sesión cuando crees la sesión:‍

Si tu aplicación pierde la conexión, utiliza el mismo session_id para volver a conectar y seguir interactuando con la sesión.

Esto es importante para los agentes de larga duración. El cierre de una pestaña del navegador, el reinicio de un proceso o un fallo temporal de red no deberían obligar al agente a empezar la tarea desde cero.

Para aplicaciones en producción, trata el ID de sesión como un estado persistente de la aplicación: guárdalo en un lugar donde tu aplicación pueda recuperarlo tras reiniciar el proceso, en lugar de mantenerlo solo en la memoria.

El flujo de eventos es solo la conexión entre tu aplicación y la sesión en ejecución. La sesión en sí sigue existiendo independientemente de esa conexión.

A continuación, veremos cómo dotar a tu agente de capacidades adicionales con servidores y herramientas MCP.

Ejecución en tu propia infraestructura

El entorno aislado (sandbox) en la nube es la opción predeterminada, y es la razón por la que algunos equipos no pueden implementar esto. Si la residencia de datos o el cumplimiento normativo descartan la ejecución alojada por Anthropic, los entornos aislados autohospedados permiten que las sesiones se ejecuten en una infraestructura bajo tu control, mientras Anthropic sigue gestionando el bucle.

Ten en cuenta qué se mueve y qué no: la ejecución se traslada a tu infraestructura, mientras que la orquestación permanece en Anthropic.

Programación de ejecuciones recurrentes

Para los agentes que deben ejecutarse de forma periódica en lugar de bajo demanda, las implementaciones programadas ejecutan una sesión siguiendo una programación cron. Un proceso de triaje nocturno o un informe semanal encajan aquí sin necesidad de que configures un programador.

Controlar la factura

La facturación de Claude Managed Agents se basa en dos dimensiones: los tokens del modelo y un cargo por tiempo de ejecución de aproximadamente 0,08 $ por hora de sesión, que cubre el tiempo de contenedor.

Tres cosas que conviene saber desde el principio:

El tiempo de inactividad es gratuito, por lo que una sesión a la espera de una respuesta humana no genera cargos por tiempo de ejecución. No existen descuentos por procesamiento por lotes, por lo que el trabajo que normalmente procesaría así cuesta lo mismo aquí. Además, la búsqueda web se factura por separado del conjunto de herramientas.

El cargo por hora de sesión suele ser la cifra menor. Los tokens son el factor principal, y la cantidad de tokens que consume una ejecución depende de cómo gestione el contexto el sistema, no de ninguna configuración que usted realice. Hemos desglosado la estructura de costes completa en Precios de Claude Managed Agents.

Dónde encuentran límites los equipos

Suelen aparecer dos limitaciones una vez que el prototipo funciona. El modelo es de Anthropic, por lo que no es posible cambiar a uno más económico cuando aumenta el volumen. Además, el bucle está gestionado por Anthropic, por lo que la estrategia de contexto no es un parámetro que usted pueda controlar.

Si está evaluando opciones en lugar de estar comprometido con una, Alternativas a Claude Managed Agents cubre el sector.

TrueForge: una alternativa de código abierto a los agentes gestionados de Claude, hasta un 75 % más económica

TrueForgees el entorno de agentes de código abierto y neutral respecto al proveedor de TrueFoundry para equipos que desean un mayor control sobre cómo se ejecutan sus agentes en producción. En lugar de vincular el tiempo de ejecución a un único proveedor de modelos, TrueForge le permite utilizar sus propios modelos, servidores MCP e infraestructura, mientras gestiona el bucle del agente, la ejecución de herramientas, la gestión del contexto, las aprobaciones y el aislamiento (sandboxing).

Mientras que un agente autohospedado como Hermes deja gran parte de la infraestructura de producción en manos del desarrollador, TrueForge proporciona el plano de control necesario para operar agentes en distintos equipos y entornos. Esto incluye acceso y credenciales MCP centralizados, aprobaciones con intervención humana, ejecución aislada, observabilidad y gobernanza.

Puede ejecutarlo localmente connpx @truefoundry/trueforgeo desplegarlo para un equipo mediante Docker Compose o Helm.

TrueForge también separa el tiempo de ejecución del agente de la capa del modelo. Esto significa que los equipos pueden cambiar de modelo o dirigir las cargas de trabajo a diferentes proveedores sin tener que reconstruir el agente. Junto con la puerta de enlace de IA (AI Gateway) de TrueFoundry, los equipos también pueden aplicar el enrutamiento de modelos y controles de costes para evitar el uso de modelos de vanguardia costosos en tareas que no los requieren. El resultado es un punto intermedio entre un tiempo de ejecución totalmente gestionado y la creación de toda la infraestructura del agente por su cuenta:un entorno de agentes de código abierto con los controles operativos necesarios para ejecutar agentes en producción a escala.‍

En la comparativa de TrueFoundry frente a Claude Managed Agents, TrueForge alcanzó aproximadamente la misma precisión en las tareas utilizando cerca de un 40% menos de tokens cuando ambos se ejecutaron en Opus 4.8, lo que lo hace aproximadamente un 30% más barato por ejecución. Cuando se realizó la misma comparativa con GLM-5.2 en TrueForge, se obtuvo la misma puntuación de ~11/14 en las tareas con un coste de unos 2,90 $ por ejecución frente a los 11,80 $ de Claude Managed Agents, aproximadamenteun 75 % menos de coste.

TrueFoundry también ofrece una segunda palanca para reducir los costes de los modelos medianteelenrutamiento automáticode AI Gateway. En lugar de enviar cada solicitud a un modelo de vanguardia, el enrutamiento automático clasifica las solicitudes según su complejidad y las dirige a diferentes niveles de modelos. En la comparativa de TrueFoundry con 550 prompts, el enrutamiento entre Haiku, Sonnet y Opus redujo el coste en un 69 % manteniendo el 98 % de la calidad base, y la latencia media se redujo de 7,6 segundos a 4,0 segundos. En tráfico de producción, la reducción de costes global alcanzó el 80 %.

Estas dos capas abordan diferentes partes de la ecuación de costes.TrueForge reduce la sobrecarga de ejecutar el propio agente, mientras queel enrutamiento de modelos te permite evitar el uso de un modelo costoso cuando la tarea no lo requiere. Para los equipos que ejecutan agentes a gran escala, disponer de ambos controles puede ser más importante que el precio del modelo por sí solo.

TrueForge es de código abierto ycuenta con licencia MIT,mientras que la AI Gateway de TrueFoundry añade la capa operativa que los equipos necesitan al pasar de agentes individuales a producción: acceso centralizado a modelos, presupuestos, barreras de seguridad, gestión de credenciales y trazabilidad unificada.

Si estás comparando los agentes gestionados de Claude con una arquitectura más configurable, merece la pena considerar TrueFoundry cuandola flexibilidad del modelo, el control de la infraestructura y la optimización de costes de los agentesimportan tanto como el propio tiempo de ejecución del agente.

An Open-Source Alternative to Claude Managed Agents, Up to 75% Cheaper

Run production-ready AI agents on your own infrastructure with TrueForge, using your choice of models, tools, and sandbox providers.

View on GitHub

Docs

Lo que los agentes gestionados no cubren

Los agentes gestionados controlan muy bien el tiempo de ejecución de un solo agente. Lo que no hacen es controlar unaflota, que es el problema que surge alrededor del quinto agente, cuando el departamento financiero pregunta cuánto cuesta todo esto y el de seguridad pregunta quién aprobó las credenciales.

Un entorno de ejecución de agentes controlacómo funciona un agente. Una puerta de enlace de IA (AI Gateway) controlacómo accede ese agente a los modelos.

Por ejemplo, una organización podría ejecutar agentes utilizando Claude Managed Agents o TrueForge mientras enruta las solicitudes de modelos a través de una puerta de enlace de IA.
TrueFoundrypuerta de enlace de IA (AI Gateway)se sitúa delante de cada llamada a modelos y MCP que realiza un agente, aplicando un acceso centralizado a los modelos, presupuestos por equipo, límites de tasa, medidas de seguridad, gestión de credenciales y trazabilidad unificada, independientemente de los agentes y marcos de trabajo que utilicen sus equipos. Es compatible con más de 1000 LLM a través de una única API compatible con OpenAI, añade aproximadamente 3-4 ms de sobrecarga y gestiona más de 350 RPS en una sola vCPU, por lo que puede situarse en la ruta crítica de un agente de larga ejecución sin convertirse en un cuello de botella. Se ejecuta en su propia VPC, en sus instalaciones o en entornos aislados (air-gapped).

Esto resulta especialmente útil cuando una organización ejecuta agentes en múltiples modelos en lugar de depender de un único proveedor.

Tiempo de ejecución del agente:gestiona el bucle del agente, las herramientas, el estado y la ejecución.

Puerta de enlace de IA (AI Gateway):gestiona el acceso a los modelos, el enrutamiento, las políticas, la observabilidad y la abstracción del proveedor.

Esta separación permite a los equipos cambiar o añadir modelos sin tener que rediseñar el agente en sí.

Preguntas frecuentes

P: ¿Cómo se utilizan los Claude Managed Agents?

R: Instala la ant CLI y el SDK de Anthropic, define un agente en un archivo markdown con su modelo, system prompt y herramientas, declara un entorno en YAML para el sandbox, crea una sesión que haga referencia a ambos y transmite sus eventos. Los agentes y entornos se crean una vez y se reutilizan; las sesiones son por tarea. Todo el proceso lleva unos diez minutos.

P: ¿Es necesaria la CLI ant o se puede hacer todo desde el SDK?

R: La CLI es una opción cómoda, pero no obligatoria. Anthropic documenta las rutas de cURL y del SDK nativo para cada paso en la guía de inicio rápido, en Python, TypeScript, Java, Go, C#, Ruby y PHP. Lo que añade la CLI es ant applyyclaude-lock.json, que mantienen las versiones de los ID de agente y entorno junto a tu código en lugar de tener que pegarlos en algún archivo de configuración.

P: ¿Pueden los Claude Managed Agents ejecutarse en tu propia infraestructura?

R: En parte. Los sandboxes autohospedados permiten que las sesiones se ejecuten en una infraestructura bajo tu control, lo cual suele ser suficiente para cumplir con los requisitos de residencia de datos. La capa de orquestación permanece en Anthropic en cualquier caso, por lo que no es lo mismo que ejecutar toda la pila por tu cuenta.

P: ¿Se integra con mi pila de observabilidad actual?

R: La capa de gateway de TrueFoundry es compatible con OpenTelemetry y se integra con Grafana, Datadog, Prometheus o cualquier otra herramienta que ya utilices, rastreando cada solicitud desde el prompt hasta la ejecución de la herramienta y el modelo. Esto es fundamental cuando los agentes de diferentes marcos de trabajo deben aparecer en un mismo lugar.

P: ¿Cómo puedo gobernar modelos y servidores MCP en un gran número de agentes?

R: A través de un gateway, una vez que las claves de API por equipo dejan de ser escalables. El puerta de enlace de IA (AI Gateway) de TrueFoundry pone más de 1000 LLM detrás de una única API compatible con OpenAI con aproximadamente 3 a 4 ms de latencia añadida y más de 350 RPS en una sola vCPU, con RBAC, presupuestos, barreras de seguridad y rotación de credenciales. Los agentes en Claude Managed Agents, LangGraph o cualquier otro se gestionan de la misma manera.

Lecturas relacionadas

• ¿Qué son los Claude Managed Agents?: la arquitectura detrás de los pasos anteriores
• Precios de Claude Managed Agents: el desglose completo de costes con un ejemplo práctico
• Claude Agent SDK frente a Claude Managed Agents: cuál ejecutar en producción
• Alternativas a Claude Managed Agents: el panorama actual, si todavía estás evaluando opciones
• Buenas prácticas para el arnés de agentesdiez reglas que se aplican independientemente del arnés que elijas

Conclusión

Saber cómo utilizar Claude Managed Agents consiste principalmente en conocer cuatro objetos y el orden en que se crean: agente, entorno, sesión y eventos. La configuración es realmente rápida. En lo que merece la pena invertir tiempo es en lo que la guía de inicio rápido pasa por alto: la gestión de desconexiones, la configuración de red de tu entorno y entender qué parte de tu factura puedes controlar realmente.

Si llegas al punto en que la elección del modelo y la estrategia de contexto empiezan a importar más que la velocidad de configuración, esa es la señal para buscar un arnés abierto. npx @truefoundry/trueforge ejecuta uno localmente en aproximadamente un minuto, o reservar una demostración si prefieres probarlo con tu propia carga de trabajo.