スケジュールされたデプロイメント

「scheduled deployment」（スケジュールされたデプロイメント）を使用すると、エージェントが自律的にセッションを開始できるようになり、予測可能な周期でタスクを完了させることができます。デプロイメントは、Claude APIの一部であるDeployments APIを使用して作成・管理します。

リリースの背景や、チームがスケジュールで実行している内容の例については、ブログのClaude Managed Agentsにおけるスケジュールされたデプロイメントとボールトを参照してください。

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

デプロイメントを作成する際は、scheduleに加えて、実行に必要なセッション設定を渡します。

• デプロイメントにはエージェント設定と環境設定が必要で、オプションでファイル、GitHub、メモリストア、ボールトを指定できます。セルフホスト環境を対象とするデプロイメントではメモリストアをアタッチできますが、fileおよびgithub_repositoryリソースにはクラウド環境が必要です。Claude Consoleのデプロイメントフォームでは現在、セルフホスト環境向けのメモリストアは提供されていないため、代わりにAPIまたはSDKを通じてアタッチしてください。
• デプロイメントには、各セッションの作業を開始する初期イベント（user.messageまたはuser.define_outcome）も少なくとも1つ必要です。ant apply用のデプロイメントファイルでは、フロントマターの下にあるテキストがそのuser.messageになります。
• scheduleでは、cronのexpressionとtimezoneを定義します。サポートされる最大の粒度は分単位です。

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.

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

{
  "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リファレンスを参照してください。

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

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

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

デプロイメントを作成または更新する際に、オプションのbudgetオブジェクトを渡します。これはセッション予算と同じ形式です。デプロイメントは開始する各セッションに上限をコピーするため、予算は実行全体の累積上限として機能するのではなく、各実行を個別に制限します。たとえば、上限が"2000"のデプロイメントは、実行ごとに約20ドルまで使用できます。

デプロイメントによって開始されたセッションは、他の予算付きセッションとまったく同じように動作します。つまり、自身の定価ベースのコストが上限に達すると、budget_reachedで一時停止します。デプロイメントの予算の変更は、その後に開始される実行に適用されます。すでに実行中のセッションは開始時の上限を維持しますが、これはセッション自体を通じて変更できます。セッション予算とは異なり、デプロイメントの予算はbudget=Noneで削除し、後で再度設定することができます。

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

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.

デプロイメントの実行

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

成功したデプロイメントはアクティブなセッションを生成し、成功したデプロイメント実行には関連するsession_idが含まれます。セッションのライフサイクルを追跡するには、イベントストリームまたはwebhookを通じてセッションイベントを追跡してください。デプロイメントのライフサイクルの変更と各スケジュール実行の結果もwebhookイベントとして配信されます。これらはサポートされているイベントタイプのDeployment eventsタブとDeployment run eventsタブに記載されています。

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

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

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

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)

失敗した実行には、セッション作成が拒否された理由を示すtypeを持つerrorが含まれます（例：environment_archived_error、agent_archived_error、session_rate_limited_error）。すべてのフィルターパラメータとレスポンススキーマについては、List Deployment Runsリファレンスを参照してください。

{
  "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}を呼び出します。deployment_run webhookイベントは、実行IDをdata.idとして保持しています。

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

ライフサイクルの変更ごとにwebhookイベントが発行されるため、ポーリングせずにデプロイメントの一時停止、一時停止解除、アーカイブに対応できます。Deployment eventsタブを参照してください。

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

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

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

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

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

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

失敗時の動作

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

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

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

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

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