Managed Agentsのセッションを初期イベントでシードする — 会話履歴を引き継いで開始する

Managed Agentsのセッションは、通常「作成する」「イベントを送って起動する」の2ステップです。initial_eventsを使うと、この2ステップを1回のリクエストに畳み込み、セッションを最初からrunning状態で作れます。会話の続きから始めたい、あるいは起動条件をまとめて渡したいケースで使う機能です。

初期イベント(initial_events)は何を解決するか

initial_eventsは、セッション作成リクエストに含められる任意のイベント配列です。受け付けるのはuser.messageとuser.define_outcomeの2種類のみで、最大50件まで渡せます。空でない配列を渡すと、エージェントのループがそのリクエストの中で始まり、セッションはrunning状態で作られます。追加のイベント送信は不要です。initial_eventsなしで作ったセッションはidleで待機し、空配列は省略と同じ扱いです。

前提として押さえておきたいのは、initial_eventsがイベント送信の完全な代替ではないという点です。user.tool_confirmation・user.tool_result・user.custom_tool_resultのようにエージェントのターンへの応答として送るイベントは、まだターンが存在しないため受け付けられません。user.interruptも止めるべきターンが無いので同様に拒否されます。この制約が効いてくるのは、「セッションを作った直後にツール確認を返したい」ような設計です。この用途では2ステップに戻し、作成後に通常のイベント送信エンドポイントを使います。

ステップ1: user.messageで会話を1件シードする

最小構成はuser.messageを1件だけ渡す形です。テキストのほかに画像・ドキュメントのコンテンツブロックも含められます。

curl -fsSL https://api.anthropic.com/v1/sessions \
  -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 '{
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "initial_events": [
      {"type": "user.message",
       "content": [{"type": "text", "text": "作業ディレクトリのファイル一覧を見せてください"}]}
    ]
  }'

user.messageは複数件を時系列順に並べて渡すこともできます。公式の例は1件のみで、過去の会話を再現する用途は公式ドキュメントに記載がありません。以下は、その応用として3件を並べた書き方の例です。

"initial_events": [
  {"type": "user.message",
   "content": [{"type": "text", "text": "請求書PDFを解析してCSVにまとめてください"}]},
  {"type": "user.message",
   "content": [{"type": "text", "text": "承知しました。列は日付・取引先・金額でよいですか?"}]},
  {"type": "user.message",
   "content": [{"type": "text", "text": "はい、それでお願いします。ファイルは/data配下にあります"}]}
]

3件ともtypeは同じuser.messageです。エージェントの発話を表すイベント種別は受け付け対象にないため、過去の返答もuser.messageとして渡す形になります。各イベントには通常のイベント送信と同じ検証がかかり、並べた順に永続化されます。

ステップ2: define_outcomeで到達目標を同時に指定する

initial_eventsにはuser.define_outcomeも1件だけ含められます。会話の起点と一緒に「何を満たせば完了とみなすか」のルーブリックを渡せるため、セッション開始時点から評価基準込みで走らせたい用途に向きます。ただし細かい制約があり、条件を外れると作成リクエストごと拒否されます。

user.define_outcomeにはdescription(何を作るかの短い説明)とrubric(採点基準)、任意でmax_iterations(既定3、最大20)を指定します。rubricはインラインテキストのほか、Files APIでアップロード済みのファイルIDでも渡せます。ルーブリックは採点基準ごとに独立して評価されるため、「データが良い感じ」のような曖昧な基準ではなく、「価格列に数値が入っている」のように機械的に判定できる粒度で書くのが安定します。user.messageと組み合わせれば、会話の最初の依頼文と完了条件を同じリクエストで両方渡せます。

"initial_events": [
  {"type": "user.message",
   "content": [{"type": "text", "text": "四半期の売上データからDCFモデルを作ってください"}]},
  {"type": "user.define_outcome",
   "description": "Costcoの四半期データを使ったDCFモデルの作成",
   "rubric": {"type": "text", "content": "# DCFモデル採点基準\n\n## 売上予測\n- 過去5会計年度の実績データを使用している\n- 5年以上先まで予測している\n\n## 出力品質\n- すべての数値が1つの.xlsxファイルにまとまっている"},
   "max_iterations": 5}
]

検証はオール・オア・ナッシングです。50件のうち1件でも検証に失敗すれば、セッションは作られず配列全体が拒否されます。部分的に成立したセッションが残ることはありません。

ステップ3: エージェント設定をセッション単位で上書きする

agentフィールドには、エージェントIDの文字列・バージョン固定オブジェクト・オーバーライドオブジェクトの3形態を渡せます。

設定そのものを変えたいときはオーバーライド、バージョンを固定したいだけならバージョン固定を選びます。

オーバーライドが効くのは作成の瞬間だけです。何が作成時に固定され、何が後から変わるかは次の表のとおりです。

オーバーライドの挙動は3パターンに整理できます。

見落としやすいのが、modelオーバーライドはeffort(推論の力の入れ具合)を引き継がない点です。effortなしで上書きしたセッションは、そのモデルの既定のeffortで走ります。特定のeffortで動かすなら、オーバーライドのmodelオブジェクトの中にeffortを書きます。モデルが対応しない水準を指定すると400になります。

modelオーバーライドはinference_geoのピンも一緒に置き換えます。オーバーライドにinference_geoを含めればそのセッションのモデルリクエストを指定の地域に固定でき、含めなければエージェントのピンが外れてワークスペースのdefault_inference_geoに従います。指定した値は、作成時にワークスペースのallowed_inference_geosと照合されます。

curl -fsSL https://api.anthropic.com/v1/sessions \
  -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 '{
    "agent": {"type": "agent_with_overrides", "id": "'"$AGENT_ID"'",
              "model": {"id": "claude-opus-5-5", "effort": "high"}, "system": null},
    "environment_id": "'"$ENVIRONMENT_ID"'"
  }'

オーバーライドはそのセッション限りの適用で、エージェントのリソース自体や他のセッションには影響しません。作成レスポンスのagentオブジェクトにはオーバーライド適用後の設定が入り、idとversionは元のエージェントを指したままです。

MCP認証が必要なツールをシードと同時に使うには

initial_eventsで会話を始めるセッションが、認証の要るMCPツール(社内のIssueトラッカーやSaaSのAPIなど)を使う場合、セッション作成時にvault_idsを渡してOAuth認証情報を参照させます。トークンのリフレッシュはAnthropic側が肩代わりするため、呼び出し側がトークンの有効期限を管理する必要はありません。

curl -fsSL https://api.anthropic.com/v1/sessions \
  -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 '{
    "agent": "'"$AGENT_ID"'",
    "environment_id": "'"$ENVIRONMENT_ID"'",
    "vault_ids": ["'"$VAULT_ID"'"],
    "initial_events": [
      {"type": "user.message",
       "content": [{"type": "text", "text": "Linearの未対応チケットを確認してください"}]}
    ]
  }'

vault_idsとinitial_eventsは同じ作成リクエストに入れられます。シードした会話の最初のターンから、認証済みのMCPツールを呼べる状態で起動できます。「シードした会話の最初のターンから外部サービスを触らせたい」のに動かない場合は、vault_idsをセッション作成リクエストに含め忘れていないかをまず確認してください。

なお、initial_eventsやagentと同じ作成リクエストに、任意でbudgetオブジェクトを含めることもできます。typeをlimitにしmax_list_costに上限額を渡すと、そのセッションの消費コストに上限を設定した状態でシードできます。budgetは作成時にしか付与できず、作成後に追加することはできません。上限に達したセッションは終了せず、停止理由budget_reachedでアイドル状態になり、履歴とサンドボックスはそのまま残ります。通貨は現時点でUSDのみです。

"budget": {
  "type": "limit",
  "max_list_cost": {"amount": "2500", "currency": "USD"}
}

amountは米セント単位の整数を文字列で渡します("2500"で25.00ドル)。数値ではなく文字列にしているのは、浮動小数点の丸め誤差を混入させないためです。上限判定はモデルリクエストの合間に行われます。上限を跨いだリクエストは最後まで実行されるので、最終的な消費額が上限をわずかに超えることがあります。止まったセッションは上限を上げるか予算を外すと再開します。新しい上限は、それまでの消費額より大きい値でなければ受け付けられません。initial_eventsとbudgetを同じリクエストに入れれば、起動直後から予算の天井付きで走らせられます。

initial_eventsを使うときにつまずきやすい点

• toolsをオーバーライドで空にしようとして400になる: 有効なskillsがreadツールに依存しているため、skillsも同じリクエストでクリアしないとtoolsを空にできない
• mcp_serversをクリアできない: tools側にそのmcp_serversを参照するmcp_toolsetが残っていると拒否される。同じリクエストでtools側の参照も外す
• 作成後にbudgetを足そうとして400になる: 予算を付けられるのは作成時だけ。上限を設けたいセッションは作成リクエストに入れておく

まとめ

予算を使うセッションは、上限を作成リクエストに入れておく必要があります。作成後に変えられるのは上限額と削除だけで、付け直しはできないためです。ツール確認のように途中で返す応答は、作成後のイベント送信に回します。

作成後のセッションをどう読み・更新し・終わらせるかはManaged Agentsのセッション操作リファレンスにまとめています。Managed Agents全体のアーキテクチャ設計はAgent SDKのManaged Agentsの設計思想、MCPサーバー接続の基礎はMCPとはを参照してください。複数セッションでタスクリストを共有したい場合はClaude CodeのCLAUDE_CODE_TASK_LIST_IDが使えます。