Despliegues programados

Un "scheduled deployment" (despliegue programado) permite que un agente inicie sesiones de forma autónoma, lo que posibilita completar tareas con una cadencia predecible. Creas y gestionas despliegues con la Deployments API, parte de la Claude API.

Para conocer el contexto del lanzamiento y ejemplos de lo que los equipos ejecutan de forma programada, consulta despliegues programados y vaults en Claude Managed Agents en el blog.

Crear un despliegue programado

Al crear un despliegue, pasas las configuraciones de sesión necesarias para la ejecución, además de un schedule.

• Los despliegues requieren configuración del agente y configuración del entorno, y opcionalmente aceptan archivos, GitHub, almacenes de memoria y vaults. Un despliegue que apunta a un entorno autoalojado puede adjuntar almacenes de memoria; los recursos file y github_repository requieren un entorno en la nube. El formulario de despliegue de la Claude Console actualmente no ofrece almacenes de memoria para entornos autoalojados; adjúntalos a través de la API o de un SDK en su lugar.
• Los despliegues también requieren al menos un evento inicial, un user.message o un user.define_outcome, que inicia el trabajo de cada sesión.
• En el schedule, defines una expression cron y una timezone. La granularidad máxima admitida es a nivel de minuto.

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
name: Weekly compliance scan
agent: $AGENT_ID
environment_id: $ENVIRONMENT_ID
initial_events:
  - type: user.message
    content:
      - type: text
        text: Run the weekly compliance scan.
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
YAML
)

La respuesta incluye un objeto de despliegue con un schedule.upcoming_runs_at poblado con los próximos momentos de activación, para confirmar que tu programación se configuró correctamente.

{
  "id": "depl_01xyz",
  "status": "active",
  "paused_reason": null,
  "schedule": {
    "type": "cron",
    "expression": "0 20 * * 5",
    "timezone": "America/New_York",
    "last_run_at": null,
    "upcoming_runs_at": [
      "2026-05-09T00:00:00Z",
      "2026-05-16T00:00:00Z",
      "2026-05-23T00:00:00Z"
    ]
  }
}

Las marcas de tiempo de las próximas ejecuciones reflejan la programación exacta configurada. Sin embargo, para distribuir la carga, la ejecución real aplica una variación aleatoria (jitter) de hasta el 15% del intervalo entre ejecuciones, con un mínimo de 5 segundos y un máximo de 9 minutos.

Se admite un máximo de 1,000 despliegues programados por organización. Contacta al soporte de Anthropic si necesitas más.

Consulta la referencia de Create Deployment para ver todos los parámetros y el esquema de respuesta.

Semántica de cron y zona horaria

• Expresión: Cron POSIX estándar (minute hour day-of-month month day-of-week). Puedes generar y validar estas expresiones cron en la Claude Console.
• Zona horaria: Identificador de zona horaria IANA (por ejemplo, "America/Los_Angeles").
• DST (horario de verano): Las programaciones cron usan coincidencia literal con la hora del reloj, por lo que "0 20 * * *" en America/New_York se activa a las 8:00 PM hora local, independientemente de si está vigente EST o EDT.

Establecer un presupuesto en cada ejecución

Pasa el objeto opcional budget cuando crees o actualices el despliegue. Tiene la misma forma que un presupuesto de sesión. El despliegue copia el límite en cada sesión que inicia, por lo que el presupuesto acota cada ejecución por separado en lugar de actuar como un techo acumulativo entre ejecuciones: un despliegue con un límite de "2000" puede gastar hasta aproximadamente $20 en cada ejecución.

Una sesión iniciada por el despliegue se comporta exactamente como cualquier otra sesión con presupuesto: se pausa con budget_reached cuando su propio costo de lista alcanza el límite. Cambiar el presupuesto del despliegue se aplica a las ejecuciones iniciadas posteriormente; una sesión que ya está en ejecución conserva el límite con el que comenzó, el cual puedes cambiar a través de la propia sesión. A diferencia de un presupuesto de sesión, el presupuesto de un despliegue puede eliminarse con "budget": null y volver a establecerse más tarde.

El siguiente ejemplo establece un presupuesto en un despliegue existente:

curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}
EOF

Ejecuciones de despliegue

Los despliegues pueden no activarse por diversas razones: por ejemplo, si el recurso environment ha sido archivado, o si la creación de sesiones está sujeta a un límite de velocidad. Cada intento de ejecutar un despliegue genera un registro de "deployment run" (ejecución de despliegue), lo que te permite rastrear éxitos y fallos de forma independiente del ciclo de vida de la sesión.

Los despliegues exitosos generan sesiones activas, y una ejecución de despliegue exitosa contiene el session_id asociado. Para seguir el ciclo de vida de una sesión, rastrea los eventos de la sesión a través del flujo de eventos o de webhooks. Los cambios en el ciclo de vida del despliegue y el resultado de cada ejecución programada también se entregan como eventos de webhook, enumerados en las pestañas Deployment events y Deployment run events de Tipos de eventos admitidos.

Lista todas las ejecuciones de despliegue de un despliegue de la siguiente manera:

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"

Además, puedes filtrar las ejecuciones de despliegue con errores:

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error

Una ejecución fallida incluye un error con un type que describe por qué se rechazó la creación de la sesión (por ejemplo, environment_archived_error, agent_archived_error o session_rate_limited_error). Consulta la referencia de List Deployment Runs para ver todos los parámetros de filtro y el esquema de respuesta.

{
  "type": "deployment_run",
  "id": "drun_01abc124",
  "deployment_id": "depl_01xyz",
  "trigger_context": { "type": "schedule", "scheduled_at": "2026-05-09T00:00:00Z" },
  "session_id": null,
  "error": {
    "type": "environment_archived_error",
    "message": "environment `env_01abc` is archived"
  },
  "agent": { "type": "agent", "id": "agent_01ghi789", "version": 3 },
  "created_at": "2026-05-09T00:00:01Z"
}

Para recuperar una sola ejecución por ID, llama a GET /v1/deployment_runs/{deployment_run_id}. Un evento de webhook deployment_run lleva el ID de la ejecución como su data.id.

Gestionar el ciclo de vida del despliegue

Cada cambio en el ciclo de vida emite un evento de webhook, por lo que puedes reaccionar a un despliegue pausado, reanudado o archivado sin hacer polling; consulta la pestaña Deployment events.

Pausar suprime las activaciones programadas de ahí en adelante; las sesiones en ejecución de una ejecución de despliegue anterior continúan ejecutándose. Las ejecuciones manuales a través del endpoint run siguen permitidas mientras está pausado. Pausar establece paused_reason en {"type": "manual"}; reanudar lo borra.

ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

Reanudar retoma la programación a partir de la siguiente ocurrencia programada. Las activaciones omitidas no se recuperan.

ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"

Archivar, a diferencia de pausar, es terminal: la programación finaliza y el despliegue no puede modificarse.

ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"

Comportamiento ante fallos

Las respuestas de límite de velocidad en la creación de sesiones se registran inmediatamente como una ejecución session_rate_limited_error sin reintento; la programación lo intenta de nuevo en la siguiente ocurrencia programada. Los límites de velocidad en las llamadas a la API subyacentes dentro de una sesión los gestiona la propia sesión.

Si el agente de un despliegue ha sido archivado, el despliegue se archiva automáticamente en la misma operación. Si el agente ha sido eliminado, la siguiente activación programada detecta el agente faltante y archiva automáticamente el despliegue. En ambos casos no se registra ninguna ejecución de despliegue. Si un subagente referenciado por el agente ha sido archivado, la siguiente activación registra una ejecución fallida con error.type: "agent_archived_error" y el despliegue se pausa automáticamente para que puedas actualizar el agente y reanudar. Otros errores irrecuperables en la creación de sesiones, como un entorno o vault archivado, se comportan de la misma manera: la activación registra una ejecución fallida y el despliegue se pausa automáticamente. El paused_reason.error.type del despliegue refleja el error.type de la ejecución fallida.

Activar una ejecución manual

Para ejecutar un despliegue fuera de su programación, llama al endpoint run. Esto crea una sesión inmediatamente y escribe una ejecución de despliegue con trigger_context.type: "manual". Esto te permite probar un despliegue antes de comprometerte con la programación.

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"