Implantações agendadas

Uma scheduled deployment (implantação agendada) permite que um agente inicie sessões de forma autônoma, possibilitando a conclusão de tarefas em uma cadência previsível.

Criar uma implantação agendada

Ao criar uma implantação, você passa as configurações de sessão necessárias para a execução, além de um schedule.

• Implantações exigem configuração de agente e configuração de ambiente, e opcionalmente aceitam arquivos, GitHub, memory stores e vaults.
• Implantações também exigem um evento user.message inicial que inicia o trabalho da sessão.
• No schedule, você define uma expression cron e um timezone. A granularidade máxima suportada é no nível de minuto.

A resposta inclui um objeto de implantação com um schedule.upcoming_runs_at preenchido com os próximos horários de disparo, para confirmar que seu cronograma foi definido corretamente.

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

Os timestamps das próximas execuções são baseados no cronograma exato configurado. No entanto, para distribuir a carga, as implantações podem aplicar um jitter de até 10 segundos.

Um máximo de 1.000 implantações agendadas é suportado por organização. Entre em contato com o suporte da Anthropic se precisar de mais.

Semântica de cron e fuso horário

• Expression: Cron POSIX padrão (minute hour day-of-month month day-of-week). Você pode gerar e validar essas expressões cron no Claude Console.
• Timezone: Identificador de fuso horário IANA (por exemplo, "America/Los_Angeles").
• DST: Cronogramas cron usam correspondência literal de horário de relógio, então "0 20 * * *" em America/New_York dispara às 20h no horário local, independentemente de EST ou EDT estar em vigor.

Execuções de implantação

Implantações podem falhar ao disparar por uma variedade de razões: por exemplo, se o recurso environment foi arquivado, ou se a criação de sessão está limitada por taxa. Cada tentativa de executar uma implantação gera um registro de deployment run (execução de implantação), permitindo que você acompanhe sucessos e falhas independentemente do ciclo de vida da sessão.

Implantações bem-sucedidas geram sessões ativas, e uma execução de implantação bem-sucedida contém o session_id associado. Para acompanhar o ciclo de vida de uma sessão, rastreie os eventos da sessão através do fluxo de eventos ou webhooks.

Liste todas as execuções de implantação de uma implantação da seguinte forma:

Você também pode filtrar execuções de implantação com erros:

Uma execução com falha inclui um error com um type descrevendo por que a criação da sessão foi rejeitada (por exemplo, environment_archived_error, agent_archived_error ou 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"
}

Gerenciando o ciclo de vida da implantação

Pause suprime disparos agendados daqui em diante; sessões em execução de uma execução de implantação anterior continuam a executar. Execuções manuais através do endpoint run ainda são permitidas enquanto pausado. Pausar define paused_reason como {"type": "manual"}; despausar o limpa.

Unpause retoma o cronograma a partir da próxima ocorrência agendada. Disparos perdidos não são executados retroativamente.

Archive, diferentemente de pause, é terminal: o cronograma é encerrado e a implantação não pode ser modificada.

Comportamento em caso de falha

Respostas de limite de taxa na criação de sessão são registradas imediatamente como uma execução session_rate_limited_error sem nova tentativa; o cronograma tenta novamente na próxima ocorrência agendada. Limites de taxa em chamadas de API subjacentes dentro de uma sessão são tratados pela própria sessão.

Se o agente de uma implantação foi arquivado ou excluído, a implantação é automaticamente arquivada na mesma operação; nenhuma execução de implantação é registrada. Se um subagente referenciado pelo agente foi arquivado, o próximo disparo registra uma execução com falha com error.type: "agent_archived_error" e a implantação é automaticamente pausada para que você possa atualizar o agente e retomar.

Disparar uma execução manual

Para executar uma implantação fora de seu cronograma, chame o endpoint run. Isso cria uma sessão imediatamente e grava uma execução de implantação com trigger_context.type: "manual". Isso permite que você teste uma implantação antes de se comprometer com o cronograma.