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

Managed Agentsのスケジュールデプロイ(scheduled deployment)は、エージェントをcron式の周期でセッションとして自動起動する仕組みです。「毎週金曜の夜にコンプライアンスチェックを走らせる」のような定型タスクで、毎回誰かがセッションを作る工程をなくせます。Deployments APIで作成・管理します。

向いているのは、内容がほぼ毎回同じで、起動のタイミングだけが重要なタスクです。監視・定期レポート・コード品質チェックなどが当てはまります。

最初のdeploymentを作る

deploymentの作成には、エージェント設定と環境設定が必須です。ファイル・GitHub・メモリーストア・vaultは任意で付けられます。メモリーストアはセルフホスト環境向けでも使えますが、file と github_repository はクラウド環境専用です。

Claude Consoleのデプロイ作成フォームは、セルフホスト環境向けのメモリーストア設定に対応していません。その構成ではAPIかSDKで付与します。

起動時の入力として、初期イベント(user.message か user.define_outcome)を最低1つ渡します。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
)

設定をファイルで管理したいなら、ant CLIの ant apply が使えます。フロントマターにエージェントや環境のID、schedule を書き、本文が初期イベントの user.message になります。

---
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.

ant apply deployment.md で作成され、新しいdeploymentのIDは claude-lock.json に記録されます。中身は ant beta:deployments retrieve で確かめます。

作成後のレスポンスには、次回以降の発火予定が入ります。

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

金曜20時(ニューヨーク)が、UTCでは土曜0時として並んでいます。周期が意図どおりかは、この upcoming_runs_at で作成直後に確かめられます。

時刻がずれる・飛ぶ・二重に動くとき

発火時刻まわりで押さえる数字は3つです。

upcoming_runs_at の値は設定どおりの厳密な時刻です。実際の発火にだけ、多数のdeploymentが同時刻に集中しないようジッターが加わります。「予定の時刻ちょうどに来なかった」だけで失敗と判断しないでください。判断は後述する実行レコードで行います。

もう1つの落とし穴が夏時間(DST)です。cronは壁時計時刻でのリテラルマッチなので、"0 20 * * *" は夏時間でも標準時でも現地の午後8時に発火します。UTCに換算した時刻は季節で動きます。

取りこぼしも二重実行も許容できないタスクは、現地の午前1〜3時を避けるか、タイムゾーンをUTCにします。timezone はIANAタイムゾーン識別子で、cron式はClaude Consoleで生成・検証できます。

1回の実行でいくらまで使うかを決める

deploymentにはセッション予算と同じ形の budget を、作成時にも更新時にも渡せます。上限はdeploymentが起動するセッションごとにコピーされます。累積の上限ではなく、実行1回あたりの上限として働きます。"2000"(20ドル)なら、実行のたびに最大約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

起動されたセッションは、通常の予算付きセッションと同じ挙動です。自身のlist costが上限に達すると、stop_reason が budget_reached のアイドル状態で止まります。終了はせず、履歴とサンドボックスは残ります。再開の扱いは予算到達後の再開で詳しく扱っています。

deploymentの予算を変えても、すでに走っているセッションは起動時の上限のままです。その場で変えるにはセッション自体を更新します。セッション予算と違い、deploymentの予算は "budget": null で外し、あとから付け直せます。

月間の支出を抑えたい場合、deploymentの予算だけでは足りません。上限は1回ごとなので、月の最大額は上限に実行回数を掛けた値になります。実行頻度はcron式側で調整します。

実行が失敗したときの追跡と自動停止

発火は失敗することがあります。環境がアーカイブ済み、セッション作成がレート制限に達した、などです。各試行はdeployment runというレコードに残るので、セッションの状態とは別に成否を追えます。成功した実行には session_id が入り、以降の進行はイベントストリームかWebhookで追います。

curl --fail-with-body -sS "https://api.anthropic.com/v1/deployment_runs?beta=true&deployment_id=$DEPLOYMENT_ID&has_error=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

has_error=true を付けると失敗した実行だけに絞れます。失敗した実行には、セッション作成が拒否された理由が error.type として入ります。

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

失敗の種類によって、deploymentの扱いは3通りに分かれます。

pause中の原因は、deploymentの paused_reason.error.type を見れば分かります。値は失敗した実行の error.type と同じです。手動でpauseした場合の paused_reason は {"type": "manual"} になります。

ポーリングを避けたいなら、Webhookが使えます。deployment.paused や deployment.archived などの状態変化と、deployment_run.started / succeeded / failed が通知されます。レート制限のような回復可能な失敗は、deploymentをpauseしないため deployment.paused は飛びません。レート制限の全般はManaged Agentsのレート制限にまとめています。

pauseとarchiveを使い分ける

一時的に止めたいのか、永久にやめたいのかで操作が変わります。

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"

unpause と archive も同じ形で、パスの末尾を差し替えます。ant CLIなら ant beta:deployments pause --deployment-id "$DEPLOYMENT_ID" です。

実行一覧も同様で、ant beta:deployment-runs list --deployment-id "$DEPLOYMENT_ID" --has-error が失敗だけの絞り込みになります。特定の1件は GET /v1/deployment_runs/{deployment_run_id} で取れます。Webhookの deployment_run イベントでは、data.id がこの実行IDです。started と succeeded / failed は同じIDで届くので、1回の発火の開始と結果を突き合わせられます。

予定時刻に何も起きないときの確認順

スケジュールが動いていないように見えたら、次の順に切り分けます。

本番投入の前に手動で1回走らせる

run エンドポイントを呼ぶと、スケジュールを待たずにセッションが1つ作られ、trigger_context.type: "manual" のdeployment runが記録されます。cron式の検証だけでなく、初期イベントの文面やエージェント設定が意図どおりかを、本番の周期に乗せる前に確かめられます。

curl --fail-with-body -sS -X POST "https://api.anthropic.com/v1/deployments/$DEPLOYMENT_ID/run?beta=true" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

手動実行では、Webhookの deployment_run イベントは発行されません。通知を受ける側の動作確認は、予定発火でしか試せない点に注意が要ります。

Claude Codeの定期実行との選び分け

「cronで定期実行」には、Claude Code側にも似た機能があります。Claude Codeのドキュメントでは、定期実行の方法が3種類に分かれています。

/loop で作る繰り返しタスクは、作成から7日で失効します。最後に1回発火して自分で削除される仕様です。cron式の書き方とジッターはClaude Codeのcron式リファレンスにあります。

Managed AgentsのDeployments APIは、これらとは別系統のAPIです。セッションの起動から失敗時の自動pause・archive、実行1回ごとの予算までをプラットフォーム側が持ちます。

Claude Codeの設定や手元のファイルを使う定型作業なら、Claude Code側の仕組みが合います。独立したサービスとして、APIから作成・監視する定期実行基盤を組みたいなら、Deployments APIが候補です。

まとめ

取りこぼしや二重実行が許されないタスクかどうかで、timezoneの選び方が変わります。許されないなら、時計が動く日の挙動まで見て決めます。