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

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

Managed Agentsのセッションはどんな状態を持つか

セッションはidle / running / rescheduling / terminatedの4状態を遷移します。多くの操作制約はこの状態に紐づいているため、最初に押さえておくのが安全です。

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

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

以降で扱う取得・更新・アーカイブ・削除の4操作は、いずれもこの$SESSION_ID(セッション作成時のレスポンスに含まれるid)を軸にした個別セッション向けの操作です。一覧取得だけは対象を1件に絞らず、条件に合う複数のセッションをまとめて返します。

セッションを取得・一覧するには何を渡すか

セッション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 '.status'

一覧取得のレスポンスにはnext_page / prev_pageという2つのカーソルが入ります。next_pageがnullなら最終ページ、prev_pageがnullなら先頭ページです。カーソルはorder(作成日時の昇順・降順)を内部に持つ不透明な値なので、取得したカーソルを別のorderで使い回すと400エラーになります。同じく、ページをまたぐ途中でcreated_atフィルタを変えてカーソルの位置が範囲外になった場合も400エラーです。limitとagent_id以外のフィルタはページ間で変えても構いませんが、ページネーション中はorderとcreated_atの組み合わせを固定しておくのが無難です。

GET(単体・一覧とも)のレスポンスで読める主なフィールドは次のとおりです。

一覧レスポンスにはこれに加えてnext_page / prev_pageのカーソルが付きます。監視用のスクリプトを書くなら、jq '.status'で状態だけを抜き出すか、jq '{id, status, list_cost: .usage.list_cost}'のように必要なフィールドだけを組み合わせて取り出すと扱いやすくなります。

カーソルを手で受け渡すのが面倒なら、CLIのant beta:sessions listはデフォルトで結果を自動的にページ送りし、セッションだけを出力します(生のページ情報が欲しいときは--format raw)。Pythonなど各SDKにも、next_pageを自動で追いかけて全ページを反復するヘルパー(auto_paging_eachなど)が用意されているため、監視バッチを組むときは手動のカーソル管理より先にこちらを検討する価値があります。

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

セッション作成後でも、agent.toolsとagent.mcp_serversはセッション実行中に更新できます。パーミッションポリシーや、Web検索・Web取得の許可・拒否ドメインリストのようなツール単位の設定もここに含まれます。更新は新しいエージェントバージョンを作るわけではなく、そのセッションだけに効くセッションローカルな変更で、元になったエージェントの設定には反映されません。ただし次の3点は更新できません。

• model / system / skillsはセッション作成後に変更不可(変えたい場合はセッション作成時のエージェント設定オーバーライドを使う)
• エージェントのinference_geoピンもセッション実行中は変更不可。設定するにはエージェント自体を保存し直すか、セッション作成時のmodelオーバーライドで単発指定する
• systemはセッションの寿命全体で固定。対応モデルでは、実行中にsystem.messageイベントを送ってシステムレベルの指示を追記することはできる(既存のsystemを書き換える手段ではない)
• tools / mcp_serversの更新は差分マージではなく全置換。既存のエントリを残したいなら、先にGETで現在の配列を取得し、それを編集してからPOSTし直す必要がある
• toolsをnullまたは[]にして空にする更新は基本的に通るが、有効なskillsが1つでも残っていると400エラーになる。skillsは内部でreadツールに依存するため

もう1つの制約が、更新にはidle状態が必須という点です。running中のセッションを更新したい場合は、単独のuser.interruptイベントを送ってidleになるのを待ってから更新します。

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

予算(budget)の更新も同じPOST /v1/sessions/{id}で行い、max_list_costを差し替えるかbudgetをnullにして外すかの2通りです。どちらも上限到達で一時停止していたセッションを自動的に再開させます。新しい上限は古いmax_list_costではなく、上記のusage.list_cost(実際の消費額は上限をわずかに超えて止まっているため)を基準に、余裕を持たせて決める必要があります。予算の削除は一方通行で、外した予算を戻したり、予算なしで作ったセッションに後から追加したりはできません。上限到達時のイベント順序や、一時停止中に受理されるイベントの区別といった詳細な挙動は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"

削除で特に見落としやすいのが、セッションが生成したファイルはセッションのファイルシステムごと消える点です。Files APIで事前にアップロードしたファイルは影響を受けませんが、セッション実行中に生成された出力ファイルは、削除前にダウンロードしておかないと戻せません。最後のターンで書き出したファイルは、セッションがidleになってから数秒遅れてファイル一覧に反映されることもあるため、期待するファイルが一覧に出てから削除するのが安全です。

そして両操作に共通するのが、running中は実行できないという制約です。アーカイブ・削除のどちらも、runningセッションに対しては先にuser.interruptを送ってidleにする必要があります。

cURLの代わりに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"に対応します。エンドポイントの形が違うだけで、idleが前提という制約自体はどの言語でも変わりません。

更新・アーカイブ・削除でつまずきやすい点

• running中に更新・アーカイブ・削除を試みて失敗する: 3操作ともidleが前提。user.interruptを単独で送り、idle遷移を待ってから操作する
• tools更新で意図せず既存ツールが消える: 全置換の挙動を知らずに一部のツールだけを送ると、残りが消える。事前にGETして配列全体を組み立て直す
• skillsが有効なのにtoolsを空にしようとして400になる: skillsはreadツールに依存するため、skillsが非空の状態でtoolsをnullにはできない。skills側を先にクリアする
• 予算を後から追加しようとして拒否される: budgetは作成時にしか設定できない一方通行の仕組み。運用開始前にコスト上限の方針を決めておく
• 新しい上限を古いmax_list_cost基準で決めて拒否される: 一時停止中の消費額は上限をわずかに超えている。基準にすべきはusage.list_costで、そこに余裕を足した値を新しい上限にする
• ページネーションのカーソルを別orderで使い回してエラーになる: カーソルはorder込みで発行される。同じorderのまま次ページ・前ページを辿る
• ページ送りの途中でcreated_atフィルタを変えて400になる: フィルタを変えるとカーソルが指す位置が結果の範囲外になりうる。limitとagent_id以外は基本的にページ間で固定する
• アーカイブ・削除をGETのエンドポイントに投げてしまう: アーカイブは/v1/sessions/{id}/archiveへのPOST、削除は/v1/sessions/{id}へのDELETEと、それぞれ別のパス・メソッドを取る

実運用では、この4操作を組み合わせて「終わったセッションの後始末」を自動化するケースが多くなります。たとえば、一覧取得でterminatedかつcreated_atが一定期間より古いセッションを抽出し、必要なファイルだけダウンロードしてから削除する、といった定期バッチです。逆に、監査目的で履歴を残す必要がある場合は削除ではなくアーカイブを選び、terminatedになったセッションのイベント履歴を別ストレージへエクスポートしてから、必要なタイミングで削除するという2段階の運用も考えられます。どちらの設計でも、running中は操作できないという制約と、削除が不可逆であるという2点は共通して意識しておく必要があります。

まとめ

• セッションはidle / running / rescheduling / terminatedの4状態を遷移し、タスク完了はidle止まりでterminatedにはならない
• セッション実行中に変更できるのはtoolsとmcp_serversだけで、いずれも全置換。model / system / skillsはセッション作成時にしか設定できない
• 更新・アーカイブ・削除はすべてidleが前提で、running中はuser.interruptを挟む必要がある
• アーカイブは履歴を残したまま停止、削除はレコードとファイルシステムごと消える不可逆操作
• 予算の追加はセッション作成時限定、削除は一方通行という非対称なルールを把握しておく

これらの操作を組み合わせてセッションを起動する具体的な流れは、Managed Agentsのセッションを初期イベントでシードするで扱っています。Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想、Agent SDK自体の基本はClaude Agent SDK入門を参照してください。