---
title: Deployment pianificati
url: https://platform.claude.com/docs/it/managed-agents/scheduled-deployments
description: "Crea e gestisci i deployment con la Claude API: esegui un agente secondo una pianificazione cron ricorrente e ispeziona la cronologia delle sue esecuzioni."
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

Uno "scheduled deployment" (deployment pianificato) consente a un [agente](https://platform.claude.com/docs/it/managed-agents/agent-setup) di avviare [sessioni](https://platform.claude.com/docs/it/managed-agents/sessions) in modo autonomo, permettendo il completamento di attività con una cadenza prevedibile. Crei e gestisci i deployment con la Deployments API, parte della Claude API.

Per il contesto del lancio ed esempi di ciò che i team eseguono secondo pianificazioni, consulta [scheduled deployments and vaults in Claude Managed Agents](https://claude.com/blog/whats-new-in-claude-managed-agents) sul blog.

## Creare un deployment pianificato

Quando crei un deployment, passi le [configurazioni di sessione](https://platform.claude.com/docs/it/managed-agents/sessions) necessarie per l'esecuzione, oltre a uno `schedule` (csharp, go: `Schedule`).

* I deployment richiedono la [configurazione dell'agente](https://platform.claude.com/docs/it/managed-agents/agent-setup) e la [configurazione dell'ambiente](https://platform.claude.com/docs/it/managed-agents/environments), e accettano facoltativamente [file](https://platform.claude.com/docs/it/managed-agents/files), [GitHub](https://platform.claude.com/docs/it/managed-agents/github), [memory store](https://platform.claude.com/docs/it/managed-agents/memory) e [vault](https://platform.claude.com/docs/it/managed-agents/vaults). Un deployment che ha come destinazione un [ambiente self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory) può collegare memory store; le risorse `file` e `github_repository` richiedono un ambiente cloud. Il modulo di deployment della Claude Console attualmente non offre memory store per gli ambienti self-hosted; collegali invece tramite l'API o un SDK.
* I deployment richiedono inoltre almeno un evento iniziale, un `user.message` o un `user.define_outcome`, che avvia il lavoro di ogni sessione. In un file di deployment per `ant apply`, il testo sotto il frontmatter diventa quel `user.message`.
* Nello `schedule` (csharp, go: `Schedule`), definisci una `expression` (csharp, go: `Expression`) cron e un `timezone` (csharp, go: `Timezone`). La granularità massima supportata è al livello del minuto.

<Note>
  Su [Claude Platform on AWS](https://platform.claude.com/docs/it/build-with-claude/claude-platform-on-aws), ogni esecuzione crea la propria sessione come ruolo IAM nel tuo account AWS. Prima di creare il deployment, imposta `execution_identity` sull'agente a `{"type": "aws_role", "role_arn": "arn:aws:iam::123456789012:role/example-role"}`. La creazione di un deployment per un agente privo di questo campo restituisce un errore 400.

  * **Trust policy:** Consenti al service principal `aws-external-anthropic.amazonaws.com` di chiamare `sts:AssumeRole` e `sts:SetSourceIdentity`.
  * **Permessi del ruolo:** Consenti `aws-external-anthropic:CreateSession`, `sts:GetWebIdentityToken` e `sts:TagGetWebIdentityToken`.
  * **Permessi del chiamante:** Il principal IAM che imposta il ruolo sull'agente necessita di `iam:PassRole` su quel ruolo. Il ruolo deve trovarsi nello stesso account AWS. Nessuna [policy gestita](https://platform.claude.com/docs/it/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/it/cli-sdks-libraries/cli/apply) stampa l'ID del nuovo deployment e lo registra in `claude-lock.json`. Per visualizzare l'oggetto deployment, esegui `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>

La risposta include un oggetto deployment con un campo `schedule.upcoming_runs_at` popolato con i prossimi orari di attivazione, per confermare che la pianificazione sia stata impostata correttamente.

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

I timestamp delle prossime esecuzioni riflettono esattamente la pianificazione configurata. Tuttavia, per distribuire il carico, l'esecuzione effettiva applica un "jitter" (variazione casuale) fino al 15% dell'intervallo tra le esecuzioni, con un minimo di 5 secondi e un massimo di 9 minuti.

È supportato un massimo di **1.000 deployment pianificati** per organizzazione. Contatta il supporto Anthropic se ne hai bisogno di più.

Consulta il [riferimento Create Deployment](https://platform.claude.com/docs/it/api/beta/deployments/create) per i parametri completi e lo schema della risposta.

### Semantica di cron e fuso orario

* **Espressione:** cron POSIX standard (`minute hour day-of-month month day-of-week`). Puoi generare e convalidare queste espressioni cron nella [Claude Console](https://platform.claude.com/workspaces/default/deployments).
* **Fuso orario:** identificatore di fuso orario IANA (ad esempio, `"America/Los_Angeles"`).
* **Ora legale:** le pianificazioni cron usano una corrispondenza letterale con l'ora locale, quindi `"0 20 * * *"` in `America/New_York` si attiva alle 20:00 ora locale indipendentemente dal fatto che sia in vigore EST o EDT.

<Note>
  Gli orari locali che non esistono nel giorno del passaggio all'ora legale (come le 2 di notte) non vengono attivati. Gli orari locali che si verificano due volte nel giorno del ritorno all'ora solare si attivano due volte. Pianifica al di fuori della finestra locale 1–3 di notte, oppure usa UTC, quando esecuzioni mancate o duplicate non sono accettabili.
</Note>

### Impostare un budget per ogni esecuzione

Passa l'oggetto facoltativo `budget` (csharp, go: `Budget`) quando crei o aggiorni il deployment. Ha la stessa forma di un [budget di sessione](https://platform.claude.com/docs/it/managed-agents/budgets). Il deployment copia il limite su ogni sessione che avvia, quindi il budget limita ogni esecuzione separatamente anziché agire come tetto cumulativo tra le esecuzioni: un deployment con un limite di `"2000"` può spendere fino a circa $20 per ogni esecuzione.

Una sessione avviata dal deployment si comporta esattamente come qualsiasi altra sessione con budget: si mette in pausa con `budget_reached` quando il proprio costo di listino [raggiunge il limite](https://platform.claude.com/docs/it/managed-agents/budgets#when-a-session-reaches-its-budget). La modifica del budget del deployment si applica alle esecuzioni avviate successivamente; una sessione già in esecuzione mantiene il limite con cui è stata avviata, che puoi [modificare tramite la sessione stessa](https://platform.claude.com/docs/it/managed-agents/session-operations#updating-the-session-budget). A differenza di un budget di sessione, il budget di un deployment può essere rimosso con `"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 reimpostato in seguito.

L'esempio seguente imposta un budget su un deployment esistente:

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

## Esecuzioni dei deployment

I deployment possono non attivarsi per diversi motivi: ad esempio, se la risorsa `environment` è stata archiviata, o se la creazione delle sessioni è soggetta a limite di velocità. Ogni tentativo di eseguire un deployment genera un record di "deployment run" (esecuzione del deployment), che ti consente di tracciare successi e fallimenti indipendentemente dal ciclo di vita della sessione.

I deployment riusciti generano sessioni attive, e un'esecuzione del deployment riuscita contiene il `session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`) associato. Per seguire il ciclo di vita di una sessione, traccia gli eventi della sessione tramite lo [stream di eventi](https://platform.claude.com/docs/it/managed-agents/events-and-streaming) o i [webhook](https://platform.claude.com/docs/it/managed-agents/webhooks). Anche le modifiche al ciclo di vita del deployment e l'esito di ogni esecuzione pianificata vengono recapitati come eventi webhook, elencati nelle schede Deployment events e Deployment run events di [Tipi di eventi supportati](https://platform.claude.com/docs/it/managed-agents/webhooks#supported-event-types).

Elenca tutte le esecuzioni di un deployment come segue:

<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())
  {
      // L'unione Error espone .Message direttamente; il discriminatore viene letto
      // da .Json finché non verrà aggiunto un accessor .Type comune.
      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()) {
      // L'unione Error non espone ancora gli accessor comuni .type()/.message()
      // .toString() li include entrambi.
      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>

Puoi inoltre filtrare le esecuzioni del deployment con errori:

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

Un'esecuzione fallita include un `error` con un `type` che descrive il motivo per cui la creazione della sessione è stata rifiutata (ad esempio, `environment_archived_error`, `agent_archived_error` o `session_rate_limited_error`). Consulta il [riferimento List Deployment Runs](https://platform.claude.com/docs/it/api/beta/deployment_runs/list) per tutti i parametri di filtro e lo schema della risposta.

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

Per recuperare una singola esecuzione tramite ID, chiama [`GET /v1/deployment_runs/{deployment_run_id}`](https://platform.claude.com/docs/it/api/beta/deployment_runs/retrieve). Un [evento webhook `deployment_run`](https://platform.claude.com/docs/it/managed-agents/webhooks#supported-event-types) riporta l'ID dell'esecuzione come suo `data.id`.

## Gestire il ciclo di vita del deployment

Ogni modifica del ciclo di vita emette un [evento webhook](https://platform.claude.com/docs/it/managed-agents/webhooks#supported-event-types), così puoi reagire a un deployment messo in pausa, riattivato o archiviato senza polling; consulta la scheda Deployment events.

**Pausa** sospende le attivazioni pianificate da quel momento in poi; le sessioni in esecuzione avviate da un'esecuzione precedente del deployment continuano a essere eseguite. Le esecuzioni manuali tramite l'endpoint `run` sono comunque consentite durante la pausa. La messa in pausa imposta `paused_reason` su `{"type": "manual"}`; la riattivazione lo cancella.

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

**Riattiva** riprende la pianificazione dalla successiva occorrenza pianificata. Le attivazioni mancate non vengono recuperate.

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

**Archivia**, a differenza di **pausa**, è definitivo: la pianificazione termina e il deployment non può essere modificato.

<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 in caso di errore

Le risposte di limite di velocità sulla creazione delle sessioni vengono registrate immediatamente come esecuzione `session_rate_limited_error` senza nuovi tentativi; la pianificazione riprova alla successiva occorrenza pianificata. I limiti di velocità sulle chiamate API sottostanti all'interno di una sessione sono gestiti dalla sessione stessa.

Se l'agente di un deployment è stato archiviato, il deployment viene archiviato automaticamente nella stessa operazione. Se l'agente è stato eliminato, la successiva attivazione pianificata rileva l'agente mancante e archivia automaticamente il deployment. In entrambi i casi non viene registrata alcuna esecuzione del deployment. Se un subagente referenziato dall'agente è stato archiviato, l'attivazione successiva registra un'esecuzione fallita con `error.type: "agent_archived_error"` e il deployment viene messo automaticamente in pausa, così puoi aggiornare l'agente e riprendere. Altri errori irrecuperabili di creazione della sessione, come un ambiente o un vault archiviato, si comportano allo stesso modo: l'attivazione registra un'esecuzione fallita e il deployment viene messo automaticamente in pausa. Il `paused_reason.error.type` del deployment rispecchia l'`error.type` dell'esecuzione fallita.

## Avviare un'esecuzione manuale

Per eseguire un deployment al di fuori della sua pianificazione, chiama l'[endpoint `run`](https://platform.claude.com/docs/it/api/beta/deployments/run). Questo crea immediatamente una sessione e scrive un'esecuzione del deployment con `trigger_context.type: "manual"`. Ciò ti consente di testare un deployment prima di affidarti alla pianificazione.

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