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

スケジュールされたデプロイメント（scheduled deployment）により、エージェントが自律的にセッションを開始でき、予測可能な周期でタスクを完了できるようになります。

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

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

• デプロイメントにはエージェント設定と環境設定が必要で、オプションでファイル、GitHub、メモリストア、ボールトを受け付けます。
• デプロイメントには、セッションの作業を開始する初期の user.message イベントも必要です。
• 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"
    ]
  }
}

次回の実行タイムスタンプは、設定された正確なスケジュールに基づいています。ただし、負荷を分散するために、デプロイメントには最大10秒のジッターが適用される場合があります。

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

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 が含まれます。セッションのライフサイクルを追跡するには、イベントストリームまたはwebhooksを通じてセッションイベントを追跡してください。

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

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

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

デプロイメントライフサイクルの管理

**一時停止（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" を持つ失敗した実行を記録し、エージェントを更新して再開できるようにデプロイメントは自動的に一時停止されます。

手動実行のトリガー

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

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