Claude Media
Managed Agentsのスケジュールデプロイをcronで定期実行する
Agent SDKチュートリアル

Managed Agentsのスケジュールデプロイをcronで定期実行する

Managed AgentsのDeployments APIでcronによる定期実行を組む手順を、タイムゾーン処理・実行1回ごとの予算・失敗時の挙動まで実装コード付きで解説します。

読了目安 約15分

スケジュールデプロイとは何をする機能か

Managed Agentsのスケジュールデプロイ(scheduled deployment)は、エージェントを人手を介さずcronの周期で起動する仕組みです。Deployments APIで作成・管理し、「毎週金曜の夜にコンプライアンスチェックを走らせる」のような定型タスクを、セッションを毎回手動で作らずに継続運用できます。

定型タスクを人手で回し続けると、実行忘れや担当者の休みで抜けが出るのが常です。スケジュールデプロイはこの「毎回誰かが手を動かしてセッションを作る」工程そのものを消し、cron式が指す時刻にプラットフォーム側が自動でセッションを起動します。監視・レポート生成・定期的なコード品質チェックのように、内容は毎回ほぼ同じで起動のタイミングだけが重要なタスクに向いています。

deploymentの作成にはエージェント設定と環境設定が必須で、ファイル・GitHub・メモリーストア・vaultは任意で追加できます。メモリーストアはセルフホスト環境向けdeploymentでも使えますが、file リソースと github_repository リソースはクラウド環境専用です。Claude Consoleのデプロイ作成フォームは現時点でセルフホスト環境向けのメモリーストア設定に対応していないため、必要な場合はAPIかSDKから直接付与します。

cronでdeploymentを作成する手順

deploymentの作成では、セッション作成と同じ設定に加えて schedule と、各実行を起動する初期イベント(user.message または user.define_outcome)を渡します。schedule はcron式とタイムゾーンの組で、粒度は分単位が上限です。

DEPLOYMENT_ID=$(
  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 @- <<EOF | 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"
  }
}
EOF
)

作成に成功すると、レスポンスの schedule.upcoming_runs_at に次回以降の発火予定時刻が入るので、意図した周期になっているかをここで確認できます。実行時刻には間隔の最大15%(下限5秒・上限9分)のジッターが加わり、多数のdeploymentが同時刻に集中しないよう分散されます。1組織あたりの上限は1,000件で、超える場合はAnthropicサポートへの申請が必要です。

cron式とタイムゾーンの扱い

expression はPOSIX標準のcron書式(分・時・日・月・曜日)で、Claude Console上で生成・検証できます。timezone はIANAタイムゾーン識別子("America/Los_Angeles" など)です。

判断を誤りやすいのが夏時間(DST)の扱いです。cronスケジュールは壁時計時刻でのリテラルマッチを行うため、"0 20 * * *" は夏時間か標準時かにかかわらず現地時間の午後8時に発火します。この設計には副作用があり、春の時計進み(spring forward)で存在しない時刻(多くの地域で午前2時台)は発火せず、逆に秋の時計戻り(fall back)で2回出現する時刻は2回発火します。取りこぼしや二重実行が許容できないタスクは、現地時間の午前1〜3時を避けてスケジュールするか、タイムゾーンをUTC指定にして回避します。

実行1回ごとの予算(budget)を設定する

deploymentはセッション予算と同じ budget オブジェクトを作成・更新時に渡せます。ここで指定した上限は、deploymentが起動するセッションごとに個別コピーされるため、累積の上限ではなく実行1回あたりの上限として働きます。"2000"(20ドル)を設定したdeploymentは、実行のたびに最大約20ドルまで使える計算です。

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

deploymentが起動したセッションは、通常の予算付きセッションと同じ挙動をします。自身のlist costが上限に達すれば budget_reached で停止します。deploymentの予算を変更しても、すでに走っているセッションの上限は変わりません(その場で変えたい場合はセッション自体を更新します)。セッション予算と違い、deploymentの予算は "budget": null を渡せば一度解除し、あとから設定し直せます。

deployment実行(run)の追跡とライフサイクル管理

deploymentは環境がアーカイブ済みだったりセッション作成がレート制限に達していたりすると発火に失敗することがあります。各試行はdeployment runというレコードとして残るため、セッションのライフサイクルとは独立に成功・失敗を追跡できます。成功した実行には対応する session_id が入り、以降のセッションの進行はイベントストリームかWebhookで追えます。

deploymentのライフサイクルは3操作で管理します。pauseは今後の予定実行だけを止め、すでに走っているセッションはそのまま継続します。run エンドポイントによる手動実行はpause中でも可能です。unpauseは次の予定発火から再開し、止まっていた間の実行は遡って補完されません。archiveはpauseと違って終端の操作で、スケジュールが終了しdeployment自体を変更できなくなります。

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"

失敗時の挙動

セッション作成のレート制限に引っかかった場合、session_rate_limited_error の実行として即座に記録され、リトライはされません。次の予定発火を待つだけです。セッション内部で起きるAPI呼び出しのレート制限は、セッション自身が処理します。

エージェントがアーカイブされている場合、deploymentは自動的にアーカイブされ、実行レコードは残りません。エージェントが削除されている場合は、次の発火時にその不在が検出されて自動アーカイブされます。一方、エージェントが参照するサブエージェントがアーカイブされている場合や、環境・vaultがアーカイブ済みの場合は挙動が異なります。これらは失敗した実行(agent_archived_error など)として記録され、deploymentは自動的にpauseされます。この違いは重要で、前者(エージェント本体の消失)は復旧不能なので自動archive、後者(依存リソースの一時的な問題)は修正すれば再開できるので自動pauseという設計です。deploymentの paused_reason.error.type を見れば、どちらのエラーで止まったかが分かります。

よくあるつまずき

  • cron式の粒度を秒単位で指定しようとする。Managed Agentsのスケジュールは分単位が上限で、それより細かい粒度は表現できません。数分おきの高頻度実行が必要なタスクには向きません。
  • ジッターを実行時刻のズレとして誤解する。upcoming_runs_at に出る時刻は設定どおりの厳密な値で、実際の発火にだけ最大9分のジッターが加わります。監視側で「ちょうどその時刻に来なかったから失敗」と早合点しないようにします。
  • pauseとarchiveを混同する。pauseは予定実行だけを止める可逆操作で、走行中のセッションには影響しません。archiveは終端操作で、そこから設定を変えることはできません。一時停止したいだけならarchiveではなくpauseを使います。
  • deploymentの予算をセッションの予算と同じ感覚で設計する。deploymentの予算は実行のたびにコピーされる非累積の上限です。月間の総支出を抑えたい場合は、deploymentの予算だけでは足りず、実行頻度そのものをcron式で調整する必要があります。

手動実行でスケジュールを本番投入前にテストする

run エンドポイントを呼ぶと、スケジュールを待たずにその場でセッションが1つ作成され、trigger_context.type: "manual" を持つdeployment runが記録されます。cron式やタイムゾーンの検証だけでなく、初期イベントの内容やエージェント設定が意図通りかを、本番のスケジュールに乗せる前に確認する用途で使えます。

Claude Codeのcron機能との違い

「cronで定期実行」と聞くと、Claude Code自身が持つcron式によるRoutineを思い浮かべる人もいます。両者は別の製品・別のAPIです。Claude CodeのRoutineはCLIセッションの延長として動き、cron式には7日で失効する仕様やジッターの扱いなど独自の制約があります。対してManaged AgentsのDeployments APIは、Anthropicのプラットフォーム側がセッションのライフサイクル・失敗時の自動pause/archive・実行1回ごとの予算までを管理する、サーバーサイド完結の仕組みです。CLIを常駐させずにAPI経由で本番の定期実行基盤を組みたい場合はDeployments API、Claude Codeの対話セッションの延長で定型作業を自動化したい場合はRoutineという使い分けになります。

まとめ

スケジュールデプロイは、エージェント・環境・初期イベントに加えてcron式とタイムゾーンを渡すだけで定期実行を組める仕組みです。壁時計時刻でマッチする設計なのでDSTの発火漏れ・二重発火に注意し、予算はセッションではなくdeploymentに設定して実行1回あたりの上限として使います。失敗時はエージェント本体の消失なら自動archive、依存リソースの問題なら自動pauseと挙動が分かれるため、paused_reason を見れば運用側が何をすべきかが判断できます。本番投入前には run エンドポイントでの手動実行を挟み、スケジュールに乗せてから気づく設定ミスを防ぎます。

この記事を共有:XはてブLinkedIn

関連する記事

Agent SDK をもっと見る →