自前cronの何がしんどいのか

AIに定期的な仕事をさせる方法として、まず思いつくのは「サーバーを1台用意して、cronでClaude Codeを叩く」構成です。実際に動きますし、以前の記事でもその手順を扱いました。ただ、運用に乗せると以下が地味に効いてきます。

• サーバーの面倒を見続ける必要がある。OSアップデート、ディスク、プロセスの死活監視。AIの仕事とは無関係な作業が増えます
• 失敗が静かに起きる。cronは失敗してもログに残るだけで、ジョブ自体が起動しなかったのか、起動して途中で落ちたのかを切り分けるには自分でログ設計が必要です
• 実行環境がサーバーと一体になっている。AIに危険なコマンドを打たせたくないのに、実行場所は本番サーバーそのもの、という構成になりがちです

Scheduled Deploymentsは、この3点をまとめてAnthropic側に寄せる仕組みです。cron式を登録しておくと、Anthropicのインフラが定刻にエージェントのセッションを起動し、そのセッションはAnthropic側の隔離されたサンドボックスで動きます。自前サーバーは一切要りません。

自前cronとの比較

判断の分かれ目は「社内リソースに直接触る必要があるか」と「サブスク枠で回したいか」です。社内のファイルサーバーを直接読む必要があるなら自前サーバー、それが不要でAPI課金でよいならScheduled Deploymentsのほうが圧倒的に運用が軽くなります。自前サーバー構成の実装は別記事にまとめています。

実装：3つのオブジェクトを順番に作る

登場するオブジェクトは3つです。上から順に作ります。

ステップ1：エージェントと環境を用意する

from anthropic import Anthropic

client = Anthropic()   # ANTHROPIC_API_KEY を環境変数から読む

agent = client.beta.agents.create(
    name="Daily Report Agent",
    model="claude-opus-5",
    system="あなたは日次レポートの作成担当です。結論を先頭に置き、数値には集計元を併記してください。",
    tools=[{"type": "agent_toolset_20260401"}],
)

environment = client.beta.environments.create(
    name="report-env",
    config={"type": "cloud", "networking": {"type": "unrestricted"}},
)

print(agent.id, environment.id)

agent_toolset_20260401 は、bash・ファイル読み書き・Web検索などの標準ツール一式を有効化する指定です。エージェントと環境の id は保存しておいて使い回します。毎回作り直すのはアンチパターンです（不要なオブジェクトが溜まるうえ、バージョン管理の意味がなくなります）。

ステップ2：デプロイメントを作る

ここでスケジュールを設定します。initial_events には毎回の実行開始時に送られるメッセージを書きます。これが実質的な「定期実行させたい指示」です。

deployment = client.beta.deployments.create(
    name="毎朝の売上レポート",
    agent=agent.id,
    environment_id=environment.id,
    initial_events=[
        {
            "type": "user.message",
            "content": [{"type": "text", "text": "昨日の売上データを集計し、前週同曜日との比較レポートを作成してください。"}],
        },
    ],
    schedule={
        "type": "cron",
        "expression": "0 9 * * 1-5",     # 平日9時
        "timezone": "Asia/Tokyo",
    },
)

print(deployment.schedule.upcoming_runs_at)

initial_events に指定できるのは user.message と user.define_outcome のいずれかで、最低1つは必須です。ファイル・GitHubリポジトリ・メモリストア・認証情報（Vault）も、通常のセッションと同じようにデプロイメントに紐付けられます。たとえばメモリストアを接続しておけば、毎回の実行結果から得た知見を次回に引き継がせることもできます。

cron式で必ずハマる3つの落とし穴

落とし穴1：実行時刻は最大9分ずれる

これは知らないと必ず混乱します。upcoming_runs_at は設定どおりの時刻を返しますが、実際の実行には負荷分散のためのジッター（ゆらぎ）が入ります。

• ジッター幅：実行間隔の最大15%
• 下限5秒、上限9分

つまり1時間ごとの実行なら、最大9分遅れる可能性があります。「9時ちょうどにレポートが届く」前提で後続処理の締め切りを組むと破綻します。後工程の期限は余裕を持って設計してください。

落とし穴2：サマータイムで実行が消える／2回走る

cronは壁掛け時計どおりの時刻マッチングで動きます。America/New_York で 0 20 * * * を指定すれば、EST期間でもEDT期間でも現地20時に実行されます。ここまでは直感どおりです。

問題は切り替え日です。

公式の推奨は「現地時間の1〜3時を避けてスケジュールする」か「UTCを使う」です。日本（Asia/Tokyo）はサマータイムがないためこの問題は起きませんが、海外拠点向けのタイムゾーンを指定する場合は要注意です。二重実行が致命的な処理（請求・通知・外部への書き込み）では、処理側に冪等性を持たせておくのが安全です。

落とし穴3：分単位より細かくはできない

cron式は標準のPOSIX形式（分 時 日 月 曜日）で、最小粒度は分です。秒単位の制御はできません。また、1組織あたり最大1,000デプロイメントという上限があります。

cron式に自信がない場合は、Claude Console のデプロイメント画面で式を生成・検証できます。

実行履歴の追い方：失敗を「起動できたか」で切り分ける

ここがcron運用との一番大きな違いです。デプロイメント実行記録（deployment run）が、起動の成否を1件ずつ自動で記録します。

重要なのは、この記録が追っているのが「セッションを起動できたかどうか」だという点です。起動後にAIの作業が失敗したかどうかは、セッション側のイベントストリームやWebhookで追います。この2層構造を理解しておくと、障害調査が速くなります。

# すべての実行履歴
for run in client.beta.deployment_runs.list(deployment_id=deployment.id):
    print(run.created_at, run.session_id or run.error.type)

# 失敗したものだけ
for run in client.beta.deployment_runs.list(
    deployment_id=deployment.id,
    has_error=True,
):
    print(run.created_at, run.error.type, run.error.message)

成功した実行には session_id が入るので、そこからセッションの中身を追えます。失敗した実行には 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"
}

trigger_context.type で、スケジュール起動（schedule）か手動起動（manual）かが区別できます。agent.version も記録されるので、「いつからエージェント設定を変えて挙動が変わったか」を後から追えます。

なお、Webhookを設定しておけばポーリングせずに実行結果を受け取れます。ただしWebhookイベントが飛ぶのはスケジュール実行のみで、手動実行では飛びません。

いちばんハマるのは「勝手に止まる」挙動

失敗時の挙動は一様ではありません。ここを知らないと「気づいたら1週間動いていなかった」が起きます。

実務上は、失敗記録（has_error=True）を定期的に監視するか、Webhookで通知を受ける仕組みを最初に入れておくのが現実的です。デプロイメントが止まっていることに人間が気づかない、というのが最大のリスクです。

pause・unpause・archive の使い分け

client.beta.deployments.pause(deployment.id)
client.beta.deployments.unpause(deployment.id)
client.beta.deployments.archive(deployment.id)   # 取り消せない

原則として、止めたいときはまず pause です。archive は「このスケジュールはもう二度と使わない」と確信できるときだけにしてください。

本番前のテストは手動実行で

スケジュールを信じて1週間待つ必要はありません。run エンドポイントで即座に1回実行できます。

run = client.beta.deployments.run(deployment.id)
print(run.session_id)

これは trigger_context.type: "manual" として記録され、一時停止中でも実行できます。「pauseしたまま手動実行で挙動を確認し、問題なければunpauseする」という運用ができます。

Vertex AI・Bedrock経由のClaudeでは使えない

「うちはGoogle CloudのVertex AI（Agent Platform）でClaudeを使っている」「AWSのBedrock経由で契約している」というケースは多いはずです。結論から書くと、Managed Agentsはこれらのプラットフォームでは利用できません。Anthropicの公式ドキュメントに、サポート対象外として明記されています。

なぜ使えないのか

Managed Agentsが「モデルを呼び出すAPI」ではなく、エージェントの実行ループとサンドボックス環境そのものをAnthropicがホストするサービスだからです。Vertex AIやBedrockが提供しているのは推論（Messages API）であって、Anthropic側のコンテナやスケジューラではありません。

同じ理由で、これらのプラットフォームではFiles API・コード実行・Agent Skills・MCPコネクタ・Message Batchesなども対象外です。Vertex AI・Amazon Bedrock・Microsoft Foundryそれぞれの公式ドキュメントに、いずれも「サポートされない機能」の一覧としてClaude Managed Agentsが挙げられています。

Vertex AI・Bedrockのままで近いことを実現するには

定期実行そのものは、この記事の冒頭で比較した「自前サーバー＋cron」構成に戻ることになります。Vertex AIやBedrock経由でMessages APIを叩くスクリプトを書き、それをcronやCloud Scheduler、Amazon EventBridge Schedulerから起動する形です。

Claude Code自体はAmazon BedrockおよびVertex AI経由での利用に対応しているため、「Bedrock契約のままClaude Codeをcronで回す」という構成は成立します（プラットフォーム経由で使う際の設定は別記事で解説しています）。

失われるのは「使い捨てサンドボックス」「実行記録の自動保存」「エージェントループの提供」の3つで、これらは自前で用意することになります。逆に得られるのは、社内ネットワークへのアクセスと、プラットフォーム側のコンプライアンス境界の中で完結できることです。どちらが有利かは要件次第なので、記事冒頭の比較表と合わせて判断してください。

よくある質問

まとめ

今日やれる最初の一歩は、「いま人間が毎週やっている定型作業を1つ選ぶ」ことです。それを initial_events の1文に書き下せるなら、この仕組みに乗せられます。書き下せないなら、まだ手順が固まっていないということなので、先に手順を言語化するところからです。