Implementaciones programadas

Una "scheduled deployment" (implementación programada) permite que un agente inicie sesiones de forma autónoma, lo que posibilita completar tareas con una cadencia predecible. Creas y administras las implementaciones con la Deployments API, que forma parte de la Claude API.

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

Crear una implementación programada

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

• Las implementaciones requieren configuración del agente y configuración del entorno, y opcionalmente aceptan archivos, GitHub, almacenes de memoria y bóvedas. Una implementación 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 implementación de Claude Console actualmente no ofrece almacenes de memoria para entornos autoalojados; adjúntalos mediante la API o un SDK en su lugar.
• Las implementaciones también requieren al menos un evento inicial, un user.message o user.define_outcome, que inicia el trabajo de cada sesión. En un archivo de implementación para ant apply, el texto debajo del frontmatter se convierte en ese user.message.
• En el schedule, defines una expression cron y una timezone. La granularidad máxima admitida es a nivel de minuto.

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
---

Run the weekly compliance scan.

La respuesta incluye un objeto de implementación con schedule.upcoming_runs_at completado con las próximas horas 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 exactamente la programación configurada. Sin embargo, para distribuir la carga, la ejecución real aplica un "jitter" (variación aleatoria) 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 implementaciones programadas 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").
• Horario de verano (DST): las programaciones cron usan coincidencia literal con la hora del reloj local, 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 para cada ejecución

Pasa el objeto opcional budget cuando crees o actualices la implementación. Tiene la misma forma que un presupuesto de sesión. La implementación copia el límite en cada sesión que inicia, por lo que el presupuesto limita cada ejecución por separado en lugar de actuar como un tope acumulado entre ejecuciones: una implementación con un límite de "2000" puede gastar hasta unos $20 en cada ejecución.

Una sesión iniciada por la implementación 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 de la implementación se aplica a las ejecuciones iniciadas después; una sesión que ya está en ejecución conserva el límite con el que comenzó, que puedes cambiar a través de la propia sesión. A diferencia de un presupuesto de sesión, el presupuesto de una implementación se puede eliminar con budget=None y volver a establecerse más tarde.

El siguiente ejemplo establece un presupuesto en una implementación existente:

ant apply deployment.md

---
name: Weekly compliance scan
agent: agent_011CYm1BLqPXpQRk5khsSXrs
environment_id: env_01595EKxaaTTGwwY3kyXdtbs
schedule:
  type: cron
  expression: "0 20 * * 5"
  timezone: America/New_York
budget:
  type: limit
  max_list_cost:
    amount: "2000"
    currency: USD
---

Run the weekly compliance scan.

Ejecuciones de implementación

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

Las implementaciones exitosas generan sesiones activas, y una ejecución de implementación exitosa contiene el session_id asociado. Para seguir el ciclo de vida de una sesión, haz seguimiento de los eventos de la sesión a través del flujo de eventos o de webhooks. Los cambios en el ciclo de vida de la implementación 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.

Enumera todas las ejecuciones de una implementación de la siguiente manera:

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
):
    print(run.created_at, run.session_id or run.error.type)

Además, puedes filtrar las ejecuciones de implementación con errores:

for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

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 incluye el ID de la ejecución como su data.id.

Administrar el ciclo de vida de la implementación

Cada cambio en el ciclo de vida emite un evento de webhook, por lo que puedes reaccionar a una implementación pausada, reanudada o archivada sin hacer sondeos; consulta la pestaña Deployment events.

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

client.beta.deployments.pause(deployment.id)

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

client.beta.deployments.unpause(deployment.id)

Archivar, a diferencia de pausar, es definitivo: la programación termina y la implementación no se puede modificar.

client.beta.deployments.archive(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 vuelve a intentarlo 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 una implementación se ha archivado, la implementación se archiva automáticamente en la misma operación. Si el agente se ha eliminado, la siguiente activación programada detecta el agente faltante y archiva automáticamente la implementación. En ambos casos no se registra ninguna ejecución de implementación. Si un subagente referenciado por el agente se ha archivado, la siguiente activación registra una ejecución fallida con error.type: "agent_archived_error" y la implementación se pausa automáticamente para que puedas actualizar el agente y reanudarla. Otros errores irrecuperables de creación de sesiones, como un entorno o una bóveda archivados, se comportan de la misma manera: la activación registra una ejecución fallida y la implementación se pausa automáticamente. El paused_reason.error.type de la implementación refleja el error.type de la ejecución fallida.

Activar una ejecución manual

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

run = client.beta.deployments.run(deployment.id)