Claude Platform Docs
Managed Agents高度なオーケストレーション

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

Claude APIでデプロイメントを作成および管理します。定期的なcronスケジュールでエージェントを実行し、その実行履歴を確認します。

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

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

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

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

  • デプロイメントにはエージェント設定と環境設定が必要であり、オプションでファイル、GitHub、メモリストア、ボールトを受け付けます。セルフホスト環境を対象とするデプロイメントはメモリストアをアタッチできます。fileおよびgithub_repositoryリソースにはクラウド環境が必要です。Claude Consoleのデプロイメントフォームでは現在、セルフホスト環境向けのメモリストアは提供されていません。代わりにAPIまたはSDKを通じてアタッチしてください。
  • デプロイメントには、各セッションの作業を開始する初期イベント（user.messageまたはuser.define_outcome）が少なくとも1つ必要です。
  • 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時に実行されます。

各実行に予算を設定する

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

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

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

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 @- <<'EOF'
{
  "budget": {
    "type": "limit",
    "max_list_cost": {"amount": "2000", "currency": "USD"}
  }
}
EOF

デプロイメント実行

デプロイメントはさまざまな理由でトリガーに失敗することがあります。たとえば、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"

Was this page helpful?