Saltar al contenido principal

Agentes gestionados

Avanzado
What you'll learn
  • Entender qué te delega un bucle de agente gestionado (alojado por Anthropic)
  • Separar los dos objetos centrales: un Agent versionado vs. una Session por ejecución
  • Inyectar secretos de forma segura con los Vaults — sin que el modelo los vea nunca
  • Poner un agente en una programación cron con los Despliegues programados — sin un programador que alojar
  • Saber cuándo lo gestionado supera a un bucle personalizado, y las salvaguardas que siguen aplicando

Si construir tu propio bucle de agente es más infraestructura de la que quieres gestionar, un agente gestionado (alojado por Anthropic) ejecuta el bucle por ti — para que te centres en el trabajo del agente, no en la fontanería de sesiones, los reintentos, el estado y la programación.

Los dos objetos: Agent vs. Session​

Este es el modelo mental del que todo lo demás depende. Están separados a propósito.

  • Un Agent es una configuración persistida y versionada — modelo, system prompt, herramientas, servidores MCP y skills. Lo creas una vez. Cada actualización crea una nueva versión inmutable.
  • Una Session es una instancia en tiempo de ejecución — una ejecución que apunta a un agente por ID. La configuración vive en el agente, nunca en la sesión.
Pro tip

Las sesiones se fijan (pin) a la versión del agente con la que se crearon: las sesiones en ejecución mantienen su versión, las nuevas sesiones obtienen la más reciente. Así es como despliegas cambios de configuración sin romper el trabajo en curso.

Qué te aporta lo "gestionado"​

En lugar de fabricar y alojar el bucle a mano, obtienes bloques de construcción alojados:

  • Sessions — ejecuciones persistentes que creas por ejecución y reanudas; transmiten eventos sobre SSE.
  • Environments — infraestructura de contenedores, ya sea cloud (alojada por Anthropic) o self_hosted (las herramientas se ejecutan en tu propia VPC). Un contenedor por sesión es el espacio de trabajo del agente.
  • Memory stores — estado persistente entre sesiones, con versionado y redacción, sin que tengas que cablear una base de datos.
  • Vaults — secretos para la autenticación MCP y otros servicios.
  • Scheduled deployments — agentes que se ejecutan según una programación cron, de forma desatendida.

Crea un agente (config versionada) y luego ejecuta una sesión contra él

# 1. Create the agent once
POST /v1/agents        -> returns $AGENT_ID
# 2. Each execution is a session pinned to that agent
POST /v1/sessions      { "agent": "$AGENT_ID" }

Vaults: secretos que el modelo nunca ve​

Un agente autónomo a menudo necesita una clave de API — pero el modelo nunca debería leerla. Las credenciales del vault (mcp_oauth, static_bearer, environment_variable) se sustituyen en la salida (egress): una credencial environment_variable se inyecta en el sandbox en tiempo de ejecución y nunca es visible para el modelo.

Watch out

Este es el patrón seguro para dar a un agente acceso potente. No pegues claves en el system prompt ni en un mensaje — pasan a formar parte del contexto que el modelo (y tus logs) pueden ver. Ponlas en un vault.

Despliegues programados: un agente en un cron​

Un deployment asocia una programación cron a un agente. Cuando la programación se dispara, inicia una sesión nueva y completa su tarea — sin un programador que tengas que construir o alojar. Ideal para una sincronización de datos nocturna, un escaneo de cumplimiento semanal o un resumen diario.

Guided walkthrough1 of 4
  1. POST /v1/deployments con agent, environment_id, initial_events (debe incluir un user.message) y un schedule: una expresión cron POSIX más una zona horaria IANA.

Un escaneo de cumplimiento semanal, los viernes a las 20:00 hora de Nueva York

POST /v1/deployments
{
"name": "Weekly compliance scan",
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"initial_events": [
  {"type": "user.message", "content": [{"type": "text", "text": "Run the compliance scan and summarize findings."}]}
],
"schedule": {"type": "cron", "expression": "0 20 * * 5", "timezone": "America/New_York"}
}
Pro tip

Cron es minute hour day-of-month month day-of-week, con granularidad de minutos. El DST usa semántica de reloj de pared: una hora que no existe en el cambio de adelanto (spring-forward) se omite; una hora que ocurre dos veces en el cambio de retraso (fall-back) se dispara dos veces. Elige una zona horaria y una hora que eviten esos casos límite para cualquier cosa sensible.

Cuándo elegir gestionado vs. personalizado​

Elige gestionado cuando…Elige un bucle personalizado / SDK cuando…
Quieres que se encarguen del alojamiento, el estado, la programación y los secretosNecesitas control total sobre el bucle y las herramientas
Estás prototipando rápidoTienes necesidades estrictas de infraestructura/cumplimiento personalizadas
La simplicidad operativa importa más que el controlEstás integrando en profundidad dentro de tu propio stack

Es un espectro — llamada única → flujo de trabajo → agente personalizado (SDK) → gestionado. Empieza tan simple como la tarea permita; sube de nivel solo cuando lo necesites.

Aplican las mismas salvaguardas​

Gestionado o no, un agente autónomo igualmente realiza acciones. Mantén el mínimo privilegio, coste/iteraciones acotados y aprobación humana para los pasos arriesgados — consulta Asegurar agentes y Endurecer ejecuciones autónomas.

Key takeaways
  • Los agentes gestionados delegan el bucle, las sesiones, los entornos, la memoria, los vaults y la programación para que te centres en el trabajo
  • Un Agent es config versionada; una Session es una ejecución que se fija a una versión — la config vive en el agente, no en la sesión
  • Las credenciales environment_variable de vault se inyectan en la ejecución y nunca son visibles para el modelo — la forma segura de dar secretos a un agente
  • Un despliegue programado es una expresión cron + zona horaria IANA; cada disparo crea una ejecución, y reanudar no rellena los disparos perdidos
  • Lo gestionado se sitúa en el extremo alojado de llamada única -> flujo de trabajo -> personalizado -> gestionado; las salvaguardas de autonomía siguen aplicando

Compruébate​

Compruébate

0/3
  1. ¿Cuál es la diferencia entre un Agent y una Session?
  2. ¿Cómo deberías darle a un agente gestionado una clave de API que necesita?
  3. Un despliegue programado estuvo en pausa durante dos días y luego se reanudó. ¿Qué ocurre con los disparos que se habrían producido mientras estaba en pausa?

Siguiente​