---
title: Implantações agendadas
url: https://platform.claude.com/docs/pt-BR/managed-agents/scheduled-deployments
description: "Crie e gerencie implantações com a Claude API: execute um agente em um agendamento cron recorrente e inspecione seu histórico de execuções."
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Uma **"scheduled deployment"** (implantação agendada) permite que um [agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup) inicie [sessões](https://platform.claude.com/docs/pt-BR/managed-agents/sessions) 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](https://claude.com/blog/whats-new-in-claude-managed-agents) no blog.

## Criar uma implantação agendada

Ao criar uma implantação, você passa as [configurações de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/sessions) necessárias para a execução, além de um `schedule` (csharp, go: `Schedule`).

* As implantações exigem [configuração de agente](https://platform.claude.com/docs/pt-BR/managed-agents/agent-setup) e [configuração de ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/environments), e opcionalmente aceitam [arquivos](https://platform.claude.com/docs/pt-BR/managed-agents/files), [GitHub](https://platform.claude.com/docs/pt-BR/managed-agents/github), [memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/memory) e [vaults](https://platform.claude.com/docs/pt-BR/managed-agents/vaults). Uma implantação que tem como alvo um [ambiente auto-hospedado](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory) 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` (csharp, go: `Schedule`), você define uma `expression` (csharp, go: `Expression`) cron e um `timezone` (csharp, go: `Timezone`). A granularidade máxima suportada é no nível de minuto.

<Note>
  No [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws), cada execução cria sua sessão como uma função IAM na sua conta AWS. Antes de criar a implantação, defina `execution_identity` no agente como `{"type": "aws_role", "role_arn": "arn:aws:iam::123456789012:role/example-role"}`. Criar uma implantação para um agente sem esse campo retorna um erro 400.

  * **Política de confiança:** Permita que o principal de serviço `aws-external-anthropic.amazonaws.com` chame `sts:AssumeRole` e `sts:SetSourceIdentity`.
  * **Permissões da função:** Permita `aws-external-anthropic:CreateSession`, `sts:GetWebIdentityToken` e `sts:TagGetWebIdentityToken`.
  * **Permissões do chamador:** O principal IAM que define a função no agente precisa de `iam:PassRole` nessa função. A função deve estar na mesma conta AWS. Nenhuma [política gerenciada](https://platform.claude.com/docs/pt-BR/api/claude-platform-on-aws-iam-actions#managed-policies) concede `iam:PassRole`.
</Note>

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployments?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 '{
      "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"
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply deployment.md
    ```

    <File filename="deployment.md">
      ```markdown
      ---
      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.
      ```
    </File>

    [`ant apply`](https://platform.claude.com/docs/pt-BR/cli-sdks-libraries/cli/apply) imprime o ID da nova implantação e o registra em `claude-lock.json`. Para ver o objeto da implantação, execute `ant beta:deployments retrieve`.
  </CodeGroupItem>

  ```python Python
  deployment = client.beta.deployments.create(
      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",
      },
  )
  ```

  ```typescript TypeScript
  const deployment = await client.beta.deployments.create({
    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"
    }
  });
  ```

  ```csharp C#
  var deployment = await client.Beta.Deployments.Create(new()
  {
      Name = "Weekly compliance scan",
      Agent = agent.ID,
      EnvironmentID = environment.ID,
      InitialEvents =
      [
          new BetaManagedAgentsUserMessageEventParams
          {
              Type = BetaManagedAgentsUserMessageEventParamsType.UserMessage,
              Content =
              [
                  new BetaManagedAgentsTextBlock
                  {
                      Type = BetaManagedAgentsTextBlockType.Text,
                      Text = "Run the weekly compliance scan.",
                  },
              ],
          },
      ],
      Schedule = new BetaManagedAgentsScheduleParams
      {
          Type = BetaManagedAgentsScheduleParamsType.Cron,
          Expression = "0 20 * * 5",
          Timezone = "America/New_York",
      },
  });
  ```

  ```go Go
  deployment, err := client.Beta.Deployments.New(ctx, anthropic.BetaDeploymentNewParams{
  	Name:          "Weekly compliance scan",
  	Agent:         anthropic.BetaDeploymentNewParamsAgentUnion{OfString: anthropic.String(agent.ID)},
  	EnvironmentID: environment.ID,
  	InitialEvents: []anthropic.BetaManagedAgentsDeploymentInitialEventParamsUnion{{
  		OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{
  			Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage,
  			Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{
  				OfText: &anthropic.BetaManagedAgentsTextBlockParam{
  					Type: anthropic.BetaManagedAgentsTextBlockTypeText,
  					Text: "Run the weekly compliance scan.",
  				},
  			}},
  		},
  	}},
  	Schedule: anthropic.BetaManagedAgentsScheduleParams{
  		Type:       anthropic.BetaManagedAgentsScheduleParamsTypeCron,
  		Expression: "0 20 * * 5",
  		Timezone:   "America/New_York",
  	},
  })
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var deployment = client.beta().deployments().create(
      DeploymentCreateParams.builder()
          .name("Weekly compliance scan")
          .agent(agent.id())
          .environmentId(environment.id())
          .addInitialEvent(
              BetaManagedAgentsUserMessageEventParams.builder()
                  .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE)
                  .addTextContent("Run the weekly compliance scan.")
                  .build()
          )
          .schedule(
              BetaManagedAgentsScheduleParams.builder()
                  .type(BetaManagedAgentsScheduleParams.Type.CRON)
                  .expression("0 20 * * 5")
                  .timezone("America/New_York")
                  .build()
          )
          .build()
  );
  ```

  ```php PHP
  $deployment = $client->beta->deployments->create(
      name: 'Weekly compliance scan',
      agent: $agent->id,
      environmentID: $environment->id,
      initialEvents: [
          [
              'type' => 'user.message',
              'content' => [['type' => 'text', 'text' => 'Run the weekly compliance scan.']],
          ],
      ],
      schedule: [
          'type' => 'cron',
          'expression' => '0 20 * * 5',
          'timezone' => 'America/New_York',
      ],
  );
  ```

  ```ruby Ruby
  deployment = client.beta.deployments.create(
    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"
    }
  )
  ```
</CodeGroup>

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.

```json
{
  "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](https://platform.claude.com/docs/pt-BR/api/beta/deployments/create) 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](https://platform.claude.com/workspaces/default/deployments).
* **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.

<Note>
  Horários de relógio que não existem em um dia de adiantamento do relógio (como 2h da manhã) não são disparados. Horários de relógio que ocorrem duas vezes em um dia de atraso do relógio disparam duas vezes. Agende fora da janela local de 1h às 3h, ou use UTC, quando execuções perdidas ou duplicadas forem inaceitáveis.
</Note>

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

Passe o objeto opcional `budget` (csharp, go: `Budget`) ao criar ou atualizar a implantação. Ele tem o mesmo formato de um [orçamento de sessão](https://platform.claude.com/docs/pt-BR/managed-agents/budgets). 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](https://platform.claude.com/docs/pt-BR/managed-agents/budgets#when-a-session-reaches-its-budget). 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](https://platform.claude.com/docs/pt-BR/managed-agents/session-operations#updating-the-session-budget). Diferentemente de um orçamento de sessão, o orçamento de uma implantação pode ser removido com `"budget": null` (python: `budget=None`; typescript: `budget: null`; ruby: `budget: nil`; go: `Budget: param.NullStruct[anthropic.BetaManagedAgentsBudgetLimitParam]()`; java: `.budget(Optional.empty())`; csharp: `Budget = null`; php: `requestOptions: ['extraBodyParams' => ['budget' => null]]`; cli: `--budget null`) e definido novamente mais tarde.

O exemplo a seguir define um orçamento em uma implantação existente:

<CodeGroup defaultLanguage="CLI">
  ```bash cURL
  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 '{
      "budget": {
        "type": "limit",
        "max_list_cost": {"amount": "2000", "currency": "USD"}
      }
    }'
  ```

  <CodeGroupItem>
    ```bash CLI
    ant apply deployment.md
    ```

    <File filename="deployment.md">
      ```markdown
      ---
      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.
      ```
    </File>
  </CodeGroupItem>

  ```python Python
  updated_deployment = client.beta.deployments.update(
      deployment.id,
      budget={
          "type": "limit",
          "max_list_cost": {"amount": "2000", "currency": "USD"},
      },
  )
  print(updated_deployment.budget.max_list_cost.amount)  # 2000
  ```

  ```typescript TypeScript
  const updatedDeployment = await client.beta.deployments.update(deployment.id, {
    budget: {
      type: "limit",
      max_list_cost: { amount: "2000", currency: "USD" }
    }
  });
  console.log(updatedDeployment.budget?.max_list_cost.amount); // 2000
  ```

  ```csharp C#
  var updatedDeployment = await client.Beta.Deployments.Update(deployment.ID, new()
  {
      Budget = new()
      {
          Type = BetaManagedAgentsBudgetLimitType.Limit,
          MaxListCost = new() { Amount = "2000", Currency = BetaCurrency.Usd },
      },
  });
  Console.WriteLine(updatedDeployment.Budget?.MaxListCost.Amount);  // 2000
  ```

  ```go Go
  updatedDeployment, err := client.Beta.Deployments.Update(ctx, deployment.ID, anthropic.BetaDeploymentUpdateParams{
  	Budget: anthropic.BetaManagedAgentsBudgetLimitParam{
  		Type: anthropic.BetaManagedAgentsBudgetLimitTypeLimit,
  		MaxListCost: anthropic.BetaMonetaryAmountParam{
  			Amount:   "2000",
  			Currency: anthropic.BetaCurrencyUsd,
  		},
  	},
  })
  if err != nil {
  	panic(err)
  }
  fmt.Println(updatedDeployment.Budget.MaxListCost.Amount) // 2000
  ```

  ```java Java
  var updatedDeployment = client.beta().deployments().update(
      deployment.id(),
      DeploymentUpdateParams.builder()
          .budget(BetaManagedAgentsBudgetLimit.builder()
              .type(BetaManagedAgentsBudgetLimit.Type.LIMIT)
              .maxListCost(BetaMonetaryAmount.builder()
                  .amount("2000")
                  .currency(BetaCurrency.USD)
                  .build())
              .build())
          .build()
  );
  IO.println(updatedDeployment.budget().orElseThrow().maxListCost().amount());  // 2000
  ```

  ```php PHP
  $updatedDeployment = $client->beta->deployments->update(
      $deployment->id,
      budget: [
          'type' => 'limit',
          'max_list_cost' => ['amount' => '2000', 'currency' => 'USD'],
      ],
  );
  echo "{$updatedDeployment->budget->maxListCost->amount}\n"; // 2000
  ```

  ```ruby Ruby
  updated_deployment = client.beta.deployments.update(
    deployment.id,
    budget: {
      type: "limit",
      max_list_cost: {amount: "2000", currency: "USD"}
    }
  )
  puts updated_deployment.budget.max_list_cost.amount # 2000
  ```
</CodeGroup>

## 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` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`) associado. Para acompanhar o ciclo de vida de uma sessão, rastreie os eventos da sessão por meio do [fluxo de eventos](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming) ou de [webhooks](https://platform.claude.com/docs/pt-BR/managed-agents/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](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks#supported-event-types).

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"
  ```

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

  ```typescript TypeScript
  for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id
  })) {
    console.log(run.created_at, run.session_id ?? run.error?.type);
  }
  ```

  ```csharp C#
  var runs = await client.Beta.DeploymentRuns.List(
      new() { DeploymentID = deployment.ID }
  );
  await foreach (var run in runs.Paginate())
  {
      // A união Error expõe .Message diretamente; o discriminador é lido
      // de .Json até que um acessador .Type comum seja adicionado.
      var outcome = run.SessionID ?? run.Error!.Json.GetProperty("type").GetString();
      Console.WriteLine($"{run.CreatedAt} {outcome}");
  }
  ```

  ```go Go
  runs := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
  	DeploymentID: anthropic.String(deployment.ID),
  })
  for runs.Next() {
  	run := runs.Current()
  	if run.SessionID != "" {
  		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.SessionID)
  	} else {
  		fmt.Println(run.CreatedAt.Format(time.RFC3339), run.Error.Type)
  	}
  }
  if err := runs.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var run : client.beta().deploymentRuns().list(
          DeploymentRunListParams.builder()
              .deploymentId(deployment.id())
              .build()).autoPager()) {
      // A união Error ainda não expõe acessores comuns .type()/.message();
      // .toString() inclui ambos.
      IO.println(run.createdAt() + " "
          + run.sessionId().orElseGet(() -> run.error().orElseThrow().toString()));
  }
  ```

  ```php PHP
  foreach ($client->beta->deploymentRuns->list(
      deploymentID: $deployment->id,
  )->pagingEachItem() as $run) {
      $outcome = $run->sessionID ?? $run->error->type;
      echo "{$run->createdAt->format(DATE_ATOM)} {$outcome}\n";
  }
  ```

  ```ruby Ruby
  client.beta.deployment_runs.list(
    deployment_id: deployment.id
  ).auto_paging_each do
    puts "#{it.created_at} #{it.session_id || it.error.type}"
  end
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID&has_error=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

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

  ```python Python
  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)
  ```

  ```typescript TypeScript
  for await (const run of client.beta.deploymentRuns.list({
    deployment_id: deployment.id,
    has_error: true
  })) {
    console.log(run.created_at, run.error?.type, run.error?.message);
  }
  ```

  ```csharp C#
  var failedRuns = await client.Beta.DeploymentRuns.List(
      new() { DeploymentID = deployment.ID, HasError = true }
  );
  await foreach (var failedRun in failedRuns.Paginate())
  {
      var error = failedRun.Error!;
      var errorType = error.Json.GetProperty("type").GetString();
      Console.WriteLine($"{failedRun.CreatedAt} {errorType} {error.Message}");
  }
  ```

  ```go Go
  failedRuns := client.Beta.DeploymentRuns.ListAutoPaging(ctx, anthropic.BetaDeploymentRunListParams{
  	DeploymentID: anthropic.String(deployment.ID),
  	HasError:     anthropic.Bool(true),
  })
  for failedRuns.Next() {
  	failedRun := failedRuns.Current()
  	fmt.Println(failedRun.CreatedAt.Format(time.RFC3339), failedRun.Error.Type, failedRun.Error.Message)
  }
  if err := failedRuns.Err(); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  for (var run : client.beta().deploymentRuns().list(
          DeploymentRunListParams.builder()
              .deploymentId(deployment.id())
              .hasError(true)
              .build()).autoPager()) {
      IO.println(run.createdAt() + " " + run.error().orElseThrow());
  }
  ```

  ```php PHP
  foreach ($client->beta->deploymentRuns->list(
      deploymentID: $deployment->id,
      hasError: true,
  )->pagingEachItem() as $run) {
      echo "{$run->createdAt->format(DATE_ATOM)} {$run->error->type} {$run->error->message}\n";
  }
  ```

  ```ruby Ruby
  client.beta.deployment_runs.list(
    deployment_id: deployment.id,
    has_error: true
  ).auto_paging_each do
    puts "#{it.created_at} #{it.error.type} #{it.error.message}"
  end
  ```
</CodeGroup>

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](https://platform.claude.com/docs/pt-BR/api/beta/deployment_runs/list) para ver todos os parâmetros de filtro e o esquema de resposta.

```json
{
  "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}`](https://platform.claude.com/docs/pt-BR/api/beta/deployment_runs/retrieve). Um [evento de webhook `deployment_run`](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks#supported-event-types) 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](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks#supported-event-types), 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.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/pause?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.pause(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.pause(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Pause(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Pause(ctx, deployment.ID, anthropic.BetaDeploymentPauseParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().pause(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->pause($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.pause(deployment.id)
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/unpause?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.unpause(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.unpause(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Unpause(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Unpause(ctx, deployment.ID, anthropic.BetaDeploymentUnpauseParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().unpause(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->unpause($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.unpause(deployment.id)
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/archive?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  client.beta.deployments.archive(deployment.id)
  ```

  ```typescript TypeScript
  await client.beta.deployments.archive(deployment.id);
  ```

  ```csharp C#
  await client.Beta.Deployments.Archive(deployment.ID);
  ```

  ```go Go
  if _, err := client.Beta.Deployments.Archive(ctx, deployment.ID, anthropic.BetaDeploymentArchiveParams{}); err != nil {
  	panic(err)
  }
  ```

  ```java Java
  client.beta().deployments().archive(deployment.id());
  ```

  ```php PHP
  $client->beta->deployments->archive($deployment->id);
  ```

  ```ruby Ruby
  client.beta.deployments.archive(deployment.id)
  ```
</CodeGroup>

### 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`](https://platform.claude.com/docs/pt-BR/api/beta/deployments/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.

<CodeGroup>
  ```bash cURL
  curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run?beta=true" \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "anthropic-beta: managed-agents-2026-04-01"
  ```

  ```bash CLI
  ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"
  ```

  ```python Python
  run = client.beta.deployments.run(deployment.id)
  ```

  ```typescript TypeScript
  const run = await client.beta.deployments.run(deployment.id);
  ```

  ```csharp C#
  var manualRun = await client.Beta.Deployments.Run(deployment.ID);
  ```

  ```go Go
  manualRun, err := client.Beta.Deployments.Run(ctx, deployment.ID, anthropic.BetaDeploymentRunParams{})
  if err != nil {
  	panic(err)
  }
  ```

  ```java Java
  var run = client.beta().deployments().run(deployment.id());
  ```

  ```php PHP
  $run = $client->beta->deployments->run($deployment->id);
  ```

  ```ruby Ruby
  run = client.beta.deployments.run(deployment.id)
  ```
</CodeGroup>