Despliegues programados

Un scheduled deployment (despliegue programado) permite que un agente inicie sesiones de forma autónoma, habilitando la finalización de tareas con una cadencia predecible.

Crear un despliegue programado

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

• Los despliegues requieren configuración de agente y configuración de entorno, y opcionalmente aceptan archivos, GitHub, almacenes de memoria y vaults.
• Los despliegues también requieren un evento inicial user.message que inicia el trabajo de la sesión.
• En el schedule, defines una expression cron y una timezone. La granularidad máxima admitida es a nivel de minuto.

La respuesta incluye un objeto de despliegue con un schedule.upcoming_runs_at poblado con los próximos tiempos de activación, para confirmar que tu horario 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 se basan en el horario exacto configurado. Sin embargo, para distribuir la carga, los despliegues pueden aplicar un jitter de hasta 10 segundos.

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

Semántica de cron y zona horaria

• Expression: Cron POSIX estándar (minute hour day-of-month month day-of-week). Puedes generar y validar estas expresiones cron en la Claude Console.
• Timezone: Identificador de zona horaria IANA (por ejemplo, "America/Los_Angeles").
• DST: Los horarios cron usan coincidencia literal de hora de reloj, por lo que "0 20 * * *" en America/New_York se activa a las 8
  PM hora local independientemente de si está en vigor EST o EDT.

Ejecuciones de despliegue

Los despliegues pueden fallar al activarse por una variedad de razones: por ejemplo, si el recurso environment ha sido archivado, o si la creación de sesiones está limitada por el 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 independientemente 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 los webhooks.

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

Adicionalmente, puedes filtrar las ejecuciones de despliegue con errores:

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).

{
  "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"
}

Gestión del ciclo de vida del despliegue

Pause (pausar) suprime los activadores programados de aquí 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.

Unpause (reanudar) reanuda el horario desde la siguiente ocurrencia programada. Los activadores perdidos no se recuperan retroactivamente.

Archive (archivar), a diferencia de pause, es terminal: el horario termina y el despliegue no puede modificarse.

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; el horario intenta de nuevo en la siguiente ocurrencia programada. Los límites de velocidad en las llamadas subyacentes a la API dentro de una sesión son manejados por la propia sesión.

Si el agente de un despliegue ha sido archivado o eliminado, el despliegue se archiva automáticamente en la misma operación; no se registra ninguna ejecución de despliegue. Si un subagente referenciado por el agente ha sido archivado, el siguiente activador 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.

Activar una ejecución manual

Para ejecutar un despliegue fuera de su horario, 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 el horario.