Managed Agentsのセッション操作 — 取得・更新・アーカイブ・削除の使い分け

Managed Agentsのセッションは、作って終わりではありません。稼働中に設定を変え、予算を調整し、終わったら履歴を残すか消すかを選ぶ運用が必要です。取得・更新・アーカイブ・削除の4操作は、セッションが取りうる4つのステータスと結びついています。

セッションのステータスで、何ができるかが決まる

セッションはidle / running / rescheduling / terminatedの4状態を遷移します。操作の制約の多くは、この状態に紐づいています。

見落としやすいのは、タスクを完了したセッションはterminatedではなくidleに戻る点です。terminatedは回復不能なエラーか「明示的にアーカイブした」場合にしかなりません。ステータスをポーリングして「セッションが終わったか」を判定する実装では、この区別を取り違えると誤動作します。

前提条件として、Managed Agents APIへのリクエストにはmanaged-agents-2026-04-01のベータヘッダーが必要です(メモリストア関連のエンドポイントだけagent-memory-2026-07-22)。SDKを使えば自動で付与されるため、意識するのはcURLで直接叩く場合だけです。

以降の4操作は、セッション作成時のレスポンスに含まれるid(例では$SESSION_ID)を軸にします。

状態を読むには取得と一覧のどちらを使うか

1件の現在状態を読むならGET /v1/sessions/{id}、条件に合う複数件をまとめて読むならGET /v1/sessionsです。一覧はlimitでページサイズを、agent_idで対象エージェントを絞り込めます。

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq '{id, status, list_cost: .usage.list_cost}'

レスポンスで読む主なフィールドは、id、status、実行中のエージェント設定を持つagent、作成時に付けたbudget、消費額を持つusageです。usage.list_costはそこまでの消費額で、予算を決め直すときの基準になります(後述)。

一覧にはnext_pageとprev_pageの2つのカーソルが付きます。next_pageがnullなら最終ページ、prev_pageがnullなら先頭ページです。カーソルは作成日時の並び順(orderのasc / desc。既定はdescで新しい順)を内部に持つ不透明な値で、次の2つは400エラーになります。

• 取得したカーソルを、別のorderで使い回す
• created_atフィルタを変えて、カーソルの位置を範囲外にする

limitや残りのフィルタはページ間で変えても構いません。ページネーション中に動かさないのはorderとcreated_atの2つです。

カーソルを手で受け渡す必要がない場面も多くあります。CLIのant beta:sessions listは既定で自動的にページ送りして、セッションだけを出力します。ページ情報が欲しいときは--format rawを付け、次のように--transformでカーソルだけを抜き出せます。

ant beta:sessions list --agent-id "$AGENT_ID" --limit 1 \
  --format raw --transform '{prev_page,next_page}'

SDK側の自動ページ送りは言語ごとに呼び名が違います。

SDKごとの癖もあります。Rubyではnext_pageが「次ページを取りに行くヘルパー」の名前なので、カーソルの値はnext_page_(末尾にアンダースコア)で読みます。C#のListが返すページはカーソルを公開しないため、prev_page / next_pageを読みたいときはWithRawResponse.Listで受けてSessionListPageResponseに変換します。

実行中に設定を変えるにはどうするか

セッション作成後に変えられるのは、agent.toolsとagent.mcp_serversだけです。パーミッションポリシーや、Web検索・Web取得の許可・拒否ドメインといったツール単位の設定もここに含まれます。更新はそのセッションだけに効くセッションローカルな変更で、新しいエージェントバージョンは作られず、元のエージェントにも反映されません。更新したallowed_domains / blocked_domainsは、セッションの残りの間有効です。

変えられないものは次のとおりです。

• model / system / skillsは作成後に変更不可。別の値で動かしたいなら、作成時のエージェント設定オーバーライドを使う
• エージェントのinference_geoピンも実行中は変更不可。エージェントを保存し直すか、作成時のmodelオーバーライドで単発指定する
• systemはセッションの寿命全体で固定。ただし対応モデルでは、system.messageイベントでシステムレベルの指示を追記できる(既存のsystemを書き換える手段ではない)
• 作成時のオーバーライドでtoolsを空にすると、skillsが有効なままでは400で拒否される。skillsがreadツールを必要とするため。skillsを先に空にする

tools / mcp_serversの更新は差分マージではなく全置換です。渡した配列が新しい値になるので、既存のエントリを残したいなら先にGETで配列を取得し、編集してからPOSTし直します。

更新にはidle状態が必須です。running中のセッションは、手順を次のとおり踏みます。

curl -sS --fail-with-body "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -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":{"tools":[{"type":"agent_toolset_20260401"}]}}'

この例はtoolsをagent_toolset_20260401の1要素だけに置き換えます。全置換なので、それまで入っていた他のツールやmcp_toolsetは残りません。

予算の上限はどう引き上げるか

予算(budget)の更新も同じPOST /v1/sessions/{id}です。やり方はmax_list_costを差し替えるか、budgetをnullにして外すかの2通りで、どちらも上限到達で一時停止していたセッションを自動で再開させます。新しい上限は現在より高くても低くても構いません。条件は、セッションの消費済みlist costを厳密に上回ることです。満たさないと400エラーで、メッセージはbudget.max_list_cost must be greater than the session's consumed list costです。

つまずきやすいのは、新しい上限を古いmax_list_costから決めてしまうことです。上限到達で止まったセッションの消費額は、上限をわずかに超えて止まります。

上限は1回のモデルリクエストの前に判定されます。上限を超えさせたリクエストは、判定の時点では上限の内側にいたため最後まで走り、超過はスレッドごとに最大でモデルリクエスト1回分です。新しい上限は、古いmax_list_costではなくusage.list_costを基準にし、1セント以上の余裕を足します。報告値は丸められており、判定に使う正確な消費額より小さく見えることがあるためです。

予算の削除は一方通行です。外した予算を戻すことも、予算なしで作ったセッションに後から付けることもできません。上限到達時のイベント順序や一時停止中に受理されるイベントは、Managed Agentsのセッション予算と予算到達後の再開にまとめています。

セッションを終わらせるにはアーカイブと削除のどちらを使うか

「もう使わない」と決めたセッションの終わらせ方は2つあり、残すものが違います。

# アーカイブ: 履歴を残したまま新規イベントを止める
curl -fsSL -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/archive" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"
 
# 削除: レコード・イベント・サンドボックスを永続的に削除
curl -fsSL -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01"

どちらもrunning中は実行できません。先にuser.interruptを単独で送り、idleになってから呼びます。

削除で影響を受けるのはセッション自身の分だけです。メモリストア・vault・skills・environments・agentsは独立したリソースで、セッションを消しても残ります。Files APIで事前にアップロードしたファイルも無傷です。一方、セッションが生成したファイルはセッションのファイルシステムごと消えるので、必要なものは削除前にダウンロードします。

最後のターンで書き出したファイルは、idleになってから数秒遅れてファイル一覧に出ることがあります。期待するファイルが一覧に出たのを見てから削除するのが安全です。

SDK・CLIでは、アーカイブがclient.beta.sessions.archive(session.id)(Python)/ ant beta:sessions archive --session-id "$SESSION_ID"(CLI)、削除がclient.beta.sessions.delete(session.id)/ ant beta:sessions delete --session-id "$SESSION_ID"です。

後始末を定期バッチで自動化するには

定期バッチで後始末を自動化するなら、一覧を取り、各セッションのstatusとcreated_atを見て、古いterminatedだけを対象にする組み立てが考えられます。必要なファイルをダウンロードしてから削除します。監査で履歴を残したいときは、削除せずアーカイブにとどめ、イベント履歴を別ストレージへ書き出してから消す2段階にもできます。ローカルのClaude Codeで同様の後始末をするなら、SessionEndフックが使えます。

まとめ

アーカイブか削除かは「履歴を後で読むか」で決まり、runningでなければ削除できるので、迷うなら先にアーカイブして、不要と分かってから削除する順序にもできます。

これらの操作を組み合わせてセッションを起動する流れは、Managed Agentsのセッションを初期イベントでシードするにあります。全体の設計思想はAgent SDKのManaged Agentsの設計思想、Agent SDK自体の基本はClaude Agent SDK入門、動作中のセッションを端末で追う方法はant beta:sessions connectの使い方で扱っています。