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

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

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



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

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

• デプロイメントにはエージェント設定と環境設定が必要で、オプションでファイル、GitHub、メモリストア、ボールトを受け付けます。
• デプロイメントには、各セッションの作業を開始する少なくとも1つの初期イベント（user.messageまたはuser.define_outcome）も必要です。
• scheduleでは、cronのexpressionとtimezoneを定義します。サポートされる最大の粒度は分単位です。

DEPLOYMENT_ID=$(ant beta:deployments create <<YAML | jq -er '.id'
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
YAML
)

レスポンスには、次回以降の実行予定時刻が設定された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スケジュールはリテラルな壁時計時刻のマッチングを使用するため、America/New_Yorkにおける"0 20 * * *"は、ESTとEDTのどちらが有効であるかに関係なく、現地時間の午後8時に発火します。



デプロイメントの実行

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

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

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

ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID"

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

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

失敗した実行には、セッション作成が拒否された理由を説明する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"}に設定され、一時停止を解除するとクリアされます。

ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID"

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

ant beta:deployments unpause --deployment-id "$DEPLOYMENT_ID"

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

ant beta:deployments archive --deployment-id "$DEPLOYMENT_ID"



失敗時の動作

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

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



手動実行のトリガー

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

ant beta:deployments run --deployment-id "$DEPLOYMENT_ID"