Managed Agentsの実行中セッションでファイルを追加・一覧・ダウンロードする
実行中のManaged Agentsセッションにファイルを追加・削除し、エージェントが書き出した出力を一覧・ダウンロードする手順を解説します。
セッション実行中にファイルを出し入れする2つの操作
Managed Agentsのセッションは、作成時に渡したファイルだけで完結する必要はありません。session resources APIを使えば実行中のセッションにファイルを追加・削除でき、Files APIを使えばエージェントが/mnt/session/outputs/に書き出した成果物を一覧・ダウンロードできます。セッション作成時にまとめてファイルを渡す方法はManaged Agentsにファイルをアップロード・マウントするで扱っているので、本稿は実行中セッションへの操作に絞ります。
前提条件も作成時と同じで、リクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です。追加したいファイルは事前にFiles APIへアップロードし、file_idを取得しておきます。
ステップ1 — 実行中セッションにファイルを追加する
セッション作成後に追加でファイルを渡したい場合は、sessions/{session_id}/resourcesエンドポイントにfile_idを渡します。追加したリソースにはid(sesrsc_プレフィックス)が返るので、削除するときに使います。
resource=$(
jq -n --arg file_id "${file_id}" '{type: "file", file_id: $file_id}' \
| curl --fail-with-body -sS "${auth[@]}" \
"${base_url}/sessions/${session_id}/resources" --json @-
)
resource_id=$(jq -er '.id' <<<"${resource}")
printf '%s\n' "${resource_id}" # "sesrsc_01ABC..."公式のリクエスト例ではtypeとfile_idのみを指定しており、mount_pathは登場しません。セッション作成時のマウントと違って配置先を細かく制御したい場合は、まず動作を確認したうえで運用してください。作成時に見落としていたファイルや、セッションの途中で判明した追加のデータを、セッションを作り直さずにこの経路で渡せる点が実行中セッションへの追加の利点です。返ってきたresource_idは削除時に必ず必要になるため、セッションIDと紐づけてアプリケーション側で保存しておきます。保存し忘れてもresources.listから探し直せますが、大量のセッションを並行運用していると特定に手間がかかるため、追加した時点で控えておくのが確実です。
ステップ2 — セッションのリソース一覧を確認する
セッションにマウントされているリソースはresources.listで一覧できます。ファイル以外にGitHubリポジトリやメモリーストアもリソースとして同じ一覧に含まれるため、一覧取得後にtypeで絞り込みます。定期的に一覧を取得して差分を追う運用にしておくと、想定外のリソースが増えていないかも同時に監視できます。
curl --fail-with-body -sS "${auth[@]}" \
"${base_url}/sessions/${session_id}/resources" \
| jq -r '.data[] | "\(.id) \(.type)"'ステップ3 — 不要になったファイルを削除する
resource_idを指定してresources.deleteを呼び出すと、そのファイルはセッションから切り離されます。元のFiles API上のファイル自体はそのまま削除されずに残るため、別のセッションでもあらためて再利用できます。
curl --fail-with-body -sS "${auth[@]}" -X DELETE \
"${base_url}/sessions/${session_id}/resources/${resource_id}" >/dev/null典型的な運用フロー
長時間動くエージェントに追加データを渡す典型的な流れは、①セッションの実行中にユーザーが新しい入力ファイルをアップロードする、②アプリケーションがそのファイルをresources.addでセッションに追加する、③エージェントが処理を終えて/mnt/session/outputs/に結果を書き出す、④アプリケーションがポーリングで出力を検知してダウンロードする、という4段階です。セッションを1本立てたまま外部からデータを継ぎ足していける点が、作成時にすべてのファイルを揃える必要がある構成との大きな違いです。
resourcesに混在する3種類のリソース
resources.listが返す一覧には、ファイル以外にgithub_repository(GitHubリポジトリの接続)やmemory_store(エージェントの記憶ストア)も同じ配列に並びます。TypeScriptの例ではtype !== "memory_store"で除外してからファイルだけを扱い、Javaの例ではentry.isFile()とentry.isGitHubRepository()で型を判別してから処理を分けています。一覧を機械的に処理する実装では、typeフィールドを見ずに全件をファイルとして扱うと、GitHubリポジトリのメタデータをファイルのIDと誤って渡してしまうような事故につながります。削除するときも同様に、対象が本当にファイルのリソースかを確認してからresources.deleteを呼ぶ設計にします。
ステップ4 — エージェントの出力ファイルを一覧・ダウンロードする
エージェントが/mnt/session/outputs/配下に書き込んだファイルは、Files APIから取得できます。scope_idにセッションIDを指定して絞り込む場合は、managed-agents-2026-04-01ベータヘッダーが必要になるため、beta名前空間のFiles APIを使います。
# セッションに紐づくファイルの一覧
curl -fsSL "https://api.anthropic.com/v1/files?scope_id=sesn_abc123" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01"
# ファイルのダウンロード
curl -fsSL "https://api.anthropic.com/v1/files/$FILE_ID/content" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-o output.txtエージェントが出力を書き終えてから一覧に反映されるまでには、セッションがアイドル状態になった後で数秒ほどのタイムラグがあります。期待したファイルが一覧に出てこない場合は、少し待ってから再度一覧を取得してください。一覧に現れた時点で、そのファイルのアップロードは完了しています。
出力ファイルを待つときのポーリング設計
長時間実行するエージェントほど、出力の完成タイミングをアプリケーション側で正確に予測するのは難しくなります。実務では、セッションのステータスがアイドルに変わったことを検知したあと、数秒間隔でscope_id指定の一覧を数回だけ再取得する設計が扱いやすくなります。一覧に現れないまま長時間経過する場合は、エージェントが想定していたパス(/mnt/session/outputs/)以外に書き出してしまっている可能性が高いため、セッションのイベントログやハーネスの実行ログを確認します。即座に1回だけ一覧を叩いて「出力がない」と判断するのではなく、短い待機を挟んだ再試行を組み込んでおくと、タイムラグに起因する誤検知を防げます。
file_idの扱いで気をつけること
セッション出力のダウンロードはfile_idを使ってFiles APIから直接取得する経路です。file_idはワークスペース単位でアクセス可能な参照子であり、利用者ごとにアクセス範囲が区切られているわけではありません。エンドユーザーからの入力をそのままfile_idとして扱う実装は、他の利用者の出力を読める経路になり得ます。この種のリスクと対策はClaude Files APIのfile_idセキュリティリスクと対策にまとめています。セッションのダウンロードAPIを組み込むときは、file_idとセッションの所有者の対応をアプリケーション側で管理してください。scope_idで一覧を絞り込めるからといって、それだけでアクセス制御が完結するわけではない点にも注意が必要です。
実行中セッションで使うAPIの使い分け
| やりたいこと | 使うAPI | 返ってくるもの |
|---|---|---|
| セッションに新しいファイルを追加する | 使うAPIsessions/{id}/resources(POST) | 返ってくるものsesrsc_で始まるリソースID |
| セッションのリソース一覧を確認する | 使うAPIsessions/{id}/resources(GET) | 返ってくるものファイル・GitHubリポジトリ・メモリーストアの一覧 |
| 不要なファイルをセッションから切り離す | 使うAPIsessions/{id}/resources/{resource_id}(DELETE) | 返ってくるもの204(本体はFiles APIに残る) |
| エージェントの出力を取得する | 使うAPIFiles API files?scope_id=...(GET)+ダウンロード | 返ってくるもの出力ファイルの一覧と実体 |
前半2つはセッションのリソース管理、後半2つはFiles API本体の操作です。エンドポイントの階層が異なるぶん、認証ヘッダーの要否も異なります。セッションのリソース操作は通常のManaged Agents API呼び出しと同じmanaged-agents-2026-04-01ベータヘッダーで完結しますが、scope_idで絞り込むFiles APIの一覧取得だけは、通常のFiles APIエンドポイントではなくbeta名前空間を経由する必要がある点が異なります。
よくあるつまずき
- 出力ファイルが一覧に出てこない: エージェントの書き込みが完了してから反映まで数秒のタイムラグがあります。即座に一覧を叩いて「ファイルがない」と判断しないようにします。
scope_idで絞り込んだのに403やヘッダーエラーになる:scope_idでのフィルタリングにはmanaged-agents-2026-04-01ベータヘッダーが必須です。通常のFiles APIクライアントではなくbeta名前空間を使う必要があります。- リソースを削除したのにFiles API上のファイルも消えたと誤解する:
resources.deleteはセッションとの紐付けを切るだけで、Files API上のファイル本体は残ります。ストレージ容量を減らしたい場合は、Files API側の削除もあらためて別途必要です。 resources.listにメモリーストアやGitHubリポジトリが混ざって扱いに困る: 一覧にはファイル以外のリソース種別も含まれます。typeフィールドでfileだけに絞り込んでから処理します。- セッション作成時の
resourcesと実行中のresources.addを同じ仕様だと思い込む: 作成時のリクエストにはmount_pathを指定できますが、公式のリクエスト例では実行中セッションへの追加にmount_pathは登場しません。配置先の制御まで必要な場面では、実際の挙動を確認してから設計に組み込みます。
まとめ
実行中のManaged Agentsセッションは、sessions/{session_id}/resourcesでのファイル追加・削除と、Files APIでの出力の一覧・ダウンロードという2系統の操作で運用できます。出力の反映には数秒のタイムラグがあること、resources.deleteはセッションとの紐付けを切るだけであること、file_idはワークスペース単位のアクセスになることの3点を押さえておけば、長時間実行するエージェントに追加データを渡したり、成果物を回収したりする運用が組みやすくなります。resources.listにはファイル以外のリソースも混在するため、typeフィールドで絞り込んでから処理する習慣をつけておくと、GitHubリポジトリやメモリーストアの情報をファイルと取り違える事故も避けられます。セッション作成時にまとめてファイルを渡す手順との違いを意識しておくだけで、実行中セッションの運用でつまずく箇所は大きく減らせます。作成時にまとめてファイルを渡す手順はManaged Agentsにファイルをアップロード・マウントする、セッション・ハーネス・サンドボックスの分離設計はManaged Agentsの設計思想を参照してください。