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. Você cria e gerencia implantações com a Deployments API, parte da Claude API.

Para o contexto do lançamento e exemplos do que as equipes executam em agendamentos, consulte implantações agendadas e vaults no Claude Managed Agents no blog.

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.

• As implantações exigem configuração de agente e configuração de ambiente, e opcionalmente aceitam arquivos, GitHub, memory stores e vaults. Uma implantação que tem como alvo um ambiente auto-hospedado pode anexar memory stores; os recursos file e github_repository exigem um ambiente em nuvem. O formulário de implantação do Claude Console atualmente não oferece memory stores para ambientes auto-hospedados; anexe-os por meio da API ou de um SDK.
• As implantações também exigem pelo menos um evento inicial, um user.message ou user.define_outcome, que inicia o trabalho de cada sessão. Em um arquivo de implantação para ant apply, o texto abaixo do frontmatter se torna esse user.message.
• No schedule, você define uma expression cron e um timezone. A granularidade máxima suportada é no nível 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.

A resposta inclui um objeto de implantação com schedule.upcoming_runs_at preenchido com os próximos horários de disparo, para confirmar que seu agendamento foi configurado 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 refletem exatamente o agendamento configurado. No entanto, para distribuir a carga, a execução real aplica um "jitter" (variação aleatória) de até 15% do intervalo entre execuções, com um mínimo de 5 segundos e um máximo de 9 minutos.

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

Consulte a referência de Create Deployment para ver todos os parâmetros e o esquema de resposta.

Semântica de cron e fuso horário

• Expressão: 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.
• Fuso horário: Identificador de fuso horário IANA (por exemplo, "America/Los_Angeles").
• Horário de verão: Os agendamentos cron usam correspondência literal com o horário do relógio local, então "0 20 * * *" em America/New_York dispara às 20h no horário local, independentemente de EST ou EDT estar em vigor.

Definir um orçamento para cada execução

Passe o objeto opcional budget ao criar ou atualizar a implantação. Ele tem o mesmo formato de um orçamento de sessão. A implantação copia o limite para cada sessão que inicia, de modo que o orçamento limita cada execução separadamente, em vez de atuar como um teto cumulativo entre execuções: uma implantação com um limite de "2000" pode gastar até cerca de $20 em cada execução.

Uma sessão iniciada pela implantação se comporta exatamente como qualquer outra sessão com orçamento: ela pausa com budget_reached quando seu próprio custo de tabela atinge o limite. Alterar o orçamento da implantação se aplica às execuções iniciadas depois disso; uma sessão já em execução mantém o limite com o qual começou, que você pode alterar por meio da própria sessão. Diferentemente de um orçamento de sessão, o orçamento de uma implantação pode ser removido com budget=None e definido novamente mais tarde.

O exemplo a seguir define um orçamento em uma implantação 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.

Execuções de implantação

As implantações podem falhar ao disparar por diversos motivos: por exemplo, se o recurso environment tiver sido arquivado, ou se a criação de sessões estiver sujeita a "rate limit" (limite de 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 por meio do fluxo de eventos ou de webhooks. As mudanças no ciclo de vida da implantação e o resultado de cada execução agendada também são entregues como eventos de webhook, listados nas abas Deployment events e Deployment run events de Tipos de eventos suportados.

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

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

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

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)

Uma execução com falha inclui um error com um type que descreve por que a criação da sessão foi rejeitada (por exemplo, environment_archived_error, agent_archived_error ou session_rate_limited_error). Consulte a referência de List Deployment Runs para ver todos os parâmetros de filtro e o esquema de resposta.

{
  "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 uma única execução por ID, chame GET /v1/deployment_runs/{deployment_run_id}. Um evento de webhook deployment_run carrega o ID da execução como seu data.id.

Gerenciando o ciclo de vida da implantação

Cada mudança no ciclo de vida emite um evento de webhook, para que você possa reagir a uma implantação pausada, retomada ou arquivada sem fazer polling; consulte a aba Deployment events.

Pausar suprime os disparos agendados daqui em diante; as sessões em execução de uma execução de implantação anterior continuam sendo executadas. Execuções manuais por meio do endpoint run ainda são permitidas enquanto a implantação está pausada. Pausar define paused_reason como {"type": "manual"}; retomar o limpa.

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

Retomar reinicia o agendamento a partir da próxima ocorrência agendada. Disparos perdidos não são executados retroativamente.

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

Arquivar, diferentemente de pausar, é definitivo: o agendamento é encerrado e a implantação não pode ser modificada.

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

Comportamento em caso de falha

Respostas de limite de taxa na criação de sessões são registradas imediatamente como uma execução session_rate_limited_error sem nova tentativa; o agendamento 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 tiver sido arquivado, a implantação é arquivada automaticamente na mesma operação. Se o agente tiver sido excluído, o próximo disparo agendado detecta o agente ausente e arquiva automaticamente a implantação. Em ambos os casos, nenhuma execução de implantação é registrada. Se um subagente referenciado pelo agente tiver sido arquivado, o próximo disparo registra uma execução com falha com error.type: "agent_archived_error" e a implantação é pausada automaticamente para que você possa atualizar o agente e retomá-la. Outros erros irrecuperáveis de criação de sessão, como um ambiente ou vault arquivado, se comportam da mesma forma: o disparo registra uma execução com falha e a implantação é pausada automaticamente. O paused_reason.error.type da implantação espelha o error.type da execução com falha.

Disparar uma execução manual

Para executar uma implantação fora de seu agendamento, 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 agendamento.

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