---
title: スケジュールされたデプロイメント
url: https://platform.claude.com/docs/ja/managed-agents/scheduled-deployments
description: Claude APIでデプロイメントを作成・管理します。定期的なcronスケジュールでエージェントを実行し、その実行履歴を確認できます。
featureMetadata:
  topic:
    title: Managed Agents
    url: https://platform.claude.com/docs/en/managed-agents/overview
  status: beta
  betaHeader: managed-agents-2026-04-01
---

「**scheduled deployment**」（スケジュールされたデプロイメント）を使用すると、[エージェント](https://platform.claude.com/docs/ja/managed-agents/agent-setup)が自律的に[セッション](https://platform.claude.com/docs/ja/managed-agents/sessions)を開始できるようになり、予測可能な周期でタスクを完了させることができます。デプロイメントは、Claude APIの一部であるDeployments APIを使用して作成・管理します。

リリースの背景や、チームがスケジュールで実行している内容の例については、ブログの[Claude Managed Agentsにおけるスケジュールされたデプロイメントとボールト](https://claude.com/blog/whats-new-in-claude-managed-agents)を参照してください。

## スケジュールされたデプロイメントを作成する

デプロイメントを作成する際は、`schedule` (csharp, go: `Schedule`)に加えて、実行に必要な[セッション設定](https://platform.claude.com/docs/ja/managed-agents/sessions)を渡します。

* デプロイメントには[エージェント設定](https://platform.claude.com/docs/ja/managed-agents/agent-setup)と[環境設定](https://platform.claude.com/docs/ja/managed-agents/environments)が必要で、オプションで[ファイル](https://platform.claude.com/docs/ja/managed-agents/files)、[GitHub](https://platform.claude.com/docs/ja/managed-agents/github)、[メモリストア](https://platform.claude.com/docs/ja/managed-agents/memory)、[ボールト](https://platform.claude.com/docs/ja/managed-agents/vaults)を指定できます。[セルフホスト環境](https://platform.claude.com/docs/ja/managed-agents/self-hosted-sandboxes-memory)を対象とするデプロイメントではメモリストアをアタッチできますが、`file`および`github_repository`リソースにはクラウド環境が必要です。Claude Consoleのデプロイメントフォームでは現在、セルフホスト環境向けのメモリストアは提供されていないため、代わりにAPIまたはSDKを通じてアタッチしてください。
* デプロイメントには、各セッションの作業を開始する初期イベント（`user.message`または`user.define_outcome`）も少なくとも1つ必要です。`ant apply`用のデプロイメントファイルでは、フロントマターの下にあるテキストがその`user.message`になります。
* `schedule` (csharp, go: `Schedule`)では、cronの`expression` (csharp, go: `Expression`)と`timezone` (csharp, go: `Timezone`)を定義します。サポートされる最大の粒度は分単位です。

<Note>
  [Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws)では、各実行はAWSアカウント内のIAMロールとしてセッションを作成します。デプロイメントを作成する前に、エージェントの`execution_identity`を`{"type": "aws_role", "role_arn": "arn:aws:iam::123456789012:role/example-role"}`に設定してください。このフィールドがないエージェントに対してデプロイメントを作成すると、400エラーが返されます。

  * **信頼ポリシー：** `aws-external-anthropic.amazonaws.com`サービスプリンシパルに`sts:AssumeRole`および`sts:SetSourceIdentity`の呼び出しを許可します。
  * **ロールの権限：** `aws-external-anthropic:CreateSession`、`sts:GetWebIdentityToken`、`sts:TagGetWebIdentityToken`を許可します。
  * **呼び出し元の権限：** エージェントにロールを設定するIAMプリンシパルには、そのロールに対する`iam:PassRole`が必要です。ロールは同じAWSアカウント内にある必要があります。`iam:PassRole`を付与する[マネージドポリシー](https://platform.claude.com/docs/ja/api/claude-platform-on-aws-iam-actions#managed-policies)はありません。
</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/ja/cli-sdks-libraries/cli/apply)は新しいデプロイメントのIDを出力し、それを`claude-lock.json`に記録します。デプロイメントオブジェクトを確認するには、`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>

レスポンスには、次回以降の実行予定時刻が設定された`schedule.upcoming_runs_at`を含むデプロイメントオブジェクトが含まれており、スケジュールが正しく設定されたことを確認できます。

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

今後の実行タイムスタンプは、設定されたスケジュールを正確に反映しています。ただし、負荷を分散するため、実際の実行には実行間隔の最大15%のジッター（最小5秒、最大9分）が適用されます。

組織あたり最大**1,000件のスケジュールされたデプロイメント**がサポートされています。それ以上が必要な場合は、Anthropicサポートにお問い合わせください。

パラメータとレスポンススキーマの詳細については、[Create Deploymentリファレンス](https://platform.claude.com/docs/ja/api/beta/deployments/create)を参照してください。

### cronとタイムゾーンのセマンティクス

* **Expression：** 標準のPOSIX cron（`minute hour day-of-month month day-of-week`）です。これらのcron式は[Claude Console](https://platform.claude.com/workspaces/default/deployments)で生成および検証できます。
* **Timezone：** IANAタイムゾーン識別子（例：`"America/Los_Angeles"`）です。
* **DST：** cronスケジュールは実時刻（wall-clock）との文字どおりの一致を使用するため、`America/New_York`における`"0 20 * * *"`は、ESTとEDTのどちらが適用されているかにかかわらず、現地時間の午後8時に実行されます。

<Note>
  夏時間開始日に存在しない実時刻（午前2時など）はトリガーされません。夏時間終了日に2回発生する実時刻では2回実行されます。実行の欠落や重複が許容できない場合は、現地時間の午前1時〜3時の時間帯を避けてスケジュールするか、UTCを使用してください。
</Note>

### 各実行に予算を設定する

デプロイメントを作成または更新する際に、オプションの`budget` (csharp, go: `Budget`)オブジェクトを渡します。これは[セッション予算](https://platform.claude.com/docs/ja/managed-agents/budgets)と同じ形式です。デプロイメントは開始する各セッションに上限をコピーするため、予算は実行全体の累積上限として機能するのではなく、各実行を個別に制限します。たとえば、上限が`"2000"`のデプロイメントは、実行ごとに約20ドルまで使用できます。

デプロイメントによって開始されたセッションは、他の予算付きセッションとまったく同じように動作します。つまり、自身の定価ベースのコストが[上限に達する](https://platform.claude.com/docs/ja/managed-agents/budgets#when-a-session-reaches-its-budget)と、`budget_reached`で一時停止します。デプロイメントの予算の変更は、その後に開始される実行に適用されます。すでに実行中のセッションは開始時の上限を維持しますが、これは[セッション自体を通じて変更](https://platform.claude.com/docs/ja/managed-agents/session-operations#updating-the-session-budget)できます。セッション予算とは異なり、デプロイメントの予算は`"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`)で削除し、後で再度設定することができます。

次の例では、既存のデプロイメントに予算を設定します。

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

## デプロイメントの実行

デプロイメントは、さまざまな理由でトリガーに失敗することがあります。たとえば、`environment`リソースがアーカイブされている場合や、セッション作成がレート制限されている場合などです。デプロイメントの実行を試みるたびに「**deployment run**」（デプロイメント実行）レコードが生成されるため、セッションのライフサイクルとは独立して成功と失敗を追跡できます。

成功したデプロイメントはアクティブなセッションを生成し、成功したデプロイメント実行には関連する`session_id` (java: `sessionId`; php: `sessionID`; csharp, go: `SessionID`)が含まれます。セッションのライフサイクルを追跡するには、[イベントストリーム](https://platform.claude.com/docs/ja/managed-agents/events-and-streaming)または[webhook](https://platform.claude.com/docs/ja/managed-agents/webhooks)を通じてセッションイベントを追跡してください。デプロイメントのライフサイクルの変更と各スケジュール実行の結果もwebhookイベントとして配信されます。これらは[サポートされているイベントタイプ](https://platform.claude.com/docs/ja/managed-agents/webhooks#supported-event-types)のDeployment eventsタブとDeployment run eventsタブに記載されています。

デプロイメントのすべてのデプロイメント実行を一覧表示するには、次のようにします。

<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())
  {
      // Error 共用体は .Message を直接公開します。共通の .Type アクセサが追加されるまで、
      // 識別子は .Json から読み取られます。
      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()) {
      // Error ユニオンはまだ共通の .type()/.message() アクセサを
      // 公開していません。.toString() は両方を含みます。
      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>

さらに、エラーのあるデプロイメント実行でフィルタリングすることもできます。

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

失敗した実行には、セッション作成が拒否された理由を示す`type`を持つ`error`が含まれます（例：`environment_archived_error`、`agent_archived_error`、`session_rate_limited_error`）。すべてのフィルターパラメータとレスポンススキーマについては、[List Deployment Runsリファレンス](https://platform.claude.com/docs/ja/api/beta/deployment_runs/list)を参照してください。

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

IDで単一の実行を取得するには、[`GET /v1/deployment_runs/{deployment_run_id}`](https://platform.claude.com/docs/ja/api/beta/deployment_runs/retrieve)を呼び出します。[`deployment_run` webhookイベント](https://platform.claude.com/docs/ja/managed-agents/webhooks#supported-event-types)は、実行IDを`data.id`として保持しています。

## デプロイメントのライフサイクルを管理する

ライフサイクルの変更ごとに[webhookイベント](https://platform.claude.com/docs/ja/managed-agents/webhooks#supported-event-types)が発行されるため、ポーリングせずにデプロイメントの一時停止、一時停止解除、アーカイブに対応できます。Deployment eventsタブを参照してください。

**一時停止（Pause）** は、以降のスケジュールされたトリガーを抑制します。以前のデプロイメント実行から開始された実行中のセッションは引き続き実行されます。一時停止中も、`run`エンドポイントによる手動実行は引き続き可能です。一時停止すると`paused_reason`が`{"type": "manual"}`に設定され、一時停止を解除するとクリアされます。

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

**一時停止解除（Unpause）** は、次にスケジュールされた時点からスケジュールを再開します。見逃されたトリガーは遡って実行されません。

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

**アーカイブ（Archive）** は、**一時停止** とは異なり最終的な操作です。スケジュールは終了し、デプロイメントは変更できなくなります。

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

### 失敗時の動作

セッション作成のレート制限レスポンスは、再試行されることなく直ちに`session_rate_limited_error`の実行として記録されます。スケジュールは次にスケジュールされた時点で再度試行します。セッション内の基盤となるAPI呼び出しに対するレート制限は、セッション自体によって処理されます。

デプロイメントのエージェントがアーカイブされている場合、デプロイメントは同じ操作で自動的にアーカイブされます。エージェントが削除されている場合は、次のスケジュールされたトリガーがエージェントの欠落を検出し、デプロイメントを自動的にアーカイブします。いずれの場合も、デプロイメント実行は記録されません。エージェントが参照するサブエージェントがアーカイブされている場合、次のトリガーは`error.type: "agent_archived_error"`を含む失敗した実行を記録し、デプロイメントは自動的に一時停止されるため、エージェントを更新して再開できます。アーカイブされた環境やボールトなど、その他の回復不能なセッション作成エラーも同様に動作します。トリガーは失敗した実行を記録し、デプロイメントは自動的に一時停止されます。デプロイメントの`paused_reason.error.type`は、失敗した実行の`error.type`を反映します。

## 手動実行をトリガーする

スケジュール外でデプロイメントを実行するには、[`run`エンドポイント](https://platform.claude.com/docs/ja/api/beta/deployments/run)を呼び出します。これによりセッションが直ちに作成され、`trigger_context.type: "manual"`を含むデプロイメント実行が書き込まれます。これにより、スケジュールを確定する前にデプロイメントをテストできます。

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