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

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

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

initial_eventsは、セッション作成リクエストに含められる任意のイベント配列です。受け付けるのはuser.messageとuser.define_outcomeの2種類のみで、最大50件まで渡せます。空でない配列を渡すと、セッションはそのリクエスト1回だけで状態になり、追加のイベント送信は不要です。

前提として押さえておきたいのは、initial_eventsがイベント送信の完全な代替ではないという点です。user.tool_confirmationやuser.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回のリクエストで再現できます。

"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で、送り手が利用者かエージェントかを区別するフィールドはありません。既存セッションのやり取りを移行する場合は、元の発話順を保ったまま並べるだけで、直前までの文脈を保持した状態で新しいセッションが起動します。

ステップ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形態を渡せます。

バージョン固定オブジェクトはtypeをagentにし、idとversionを指定する形です。

"agent": {"type": "agent", "id": "AGENT_ID", "version": 1}

こちらはエージェントの設定を一切変えず、「どのバージョンで走らせるか」だけを固定します。新しいバージョンを段階的にロールアウトしたいとき、特定セッションだけ旧バージョンに留めておく用途に向きます。

これに対してオーバーライドオブジェクトは、エージェント自体をバージョニングせずに、そのセッションだけモデルやツールを変える形です。typeをagent_with_overridesにし、model / system / tools / mcp_servers / skillsのうち変えたいフィールドだけを指定します。使い分けの基準は単純で、バージョンを固定したいだけならバージョン固定オブジェクト、設定そのものを変えたいならオーバーライドです。両者は排他ではなく、オーバーライドオブジェクトのidとversionの組み合わせでも「どのバージョンをベースにオーバーライドを適用するか」を固定できます。versionを省略すればエージェントの最新バージョンがベースになります。

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

見落としやすいのが、modelオーバーライドはeffort(推論の力の入れ具合)を引き継がない点です。modelをオーバーライドしたセッションは、そのモデルのデフォルトeffortで走ります。特定のeffortで動かしたいなら、エージェント側にeffortを設定し、セッションではmodelをオーバーライドしないのが正解です。

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

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-sonnet-5"}, "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でアイドル状態になります。

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

amountは米セント単位の整数を文字列で渡します("2500"で25.00ドル)。数値ではなく文字列にしているのは、浮動小数点の丸め誤差を混入させないためです。上限判定はモデルリクエストの合間に行われるため、上限を跨いだリクエスト自体は最後まで実行され、最終的な消費額が上限をわずかに超えることがあります。initial_eventsで会話をシードしつつbudgetも同時に設定すれば、「起動直後から予算の天井付きで走らせる」という組み合わせが1回のリクエストで完結します。

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

• user.tool_confirmationやuser.interruptをinitial_eventsに入れて拒否される: 対象のターンがまだ存在しないため不可。セッション作成後に通常のイベント送信で扱う
• toolsをオーバーライドで空にしようとして400になる: 有効なskillsがreadツールに依存しているため、skillsを先にクリアしないとtoolsを空にできない
• mcp_serversをクリアできない: tools側にそのmcp_serversを参照するmcp_toolsetが残っていると拒否される。同じリクエストでtools側の参照も外す
• modelオーバーライド後にeffortが変わってしまう: オーバーライドはmodelオブジェクトを丸ごと差し替えるため、エージェント側のeffort設定は引き継がれない
• シードした内容が見えないと勘違いする: 作成レスポンスにはエコーされないため、確認はevents一覧の取得で行う

まとめ

• initial_eventsはuser.messageとuser.define_outcomeだけを受け付け、非空の配列を渡すとセッションはリクエスト1回でrunningになる
• 検証はオール・オア・ナッシングで、1件でも失敗すればセッション自体が作られない
• agent_with_overridesを使えば、モデル・システムプロンプト・ツール・MCPサーバー・skillsをセッション単位で上書きでき、inference_geoのピンもここで制御する
• modelオーバーライドはeffortを引き継がないため、effort固定が必要ならエージェント側で設定する

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