Managed Agentsの実行中セッションでファイルを追加・一覧・ダウンロードする

セッション実行中にファイルを出し入れする2つの操作

Managed Agentsのセッションは、作成時に渡したファイルだけで完結する必要はありません。session resources APIを使えば実行中のセッションにファイルを追加・削除でき、Files APIを使えばエージェントが/mnt/session/outputs/に書き出した成果物を一覧・ダウンロードできます。セッション作成時にまとめてファイルを渡す方法はManaged Agentsにファイルをアップロード・マウントするで扱っているので、本稿は実行中セッションへの操作に絞ります。

前提条件も作成時と同じで、リクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です。追加したいファイルは事前にFiles APIへアップロードし、file_idを取得しておきます。

# curl: レスポンスの id が file_id
file=$(curl --fail-with-body -sS "${auth[@]}" "${base_url}/files" -F file=@data.csv)
FILE_ID=$(jq -er '.id' <<<"${file}")
 
# ant CLI: id だけを取り出す
FILE_ID=$(ant files upload --file data.csv --transform id --raw-output)

渡せるファイルの種類に決まった一覧はありません。ソースコード、CSVやJSONなどのデータ、テキストやMarkdownのほか、zipやtar.gzのアーカイブも渡せます。アーカイブはエージェントがbashで展開します。バイナリは、エージェントが適切なツールで処理します。

追加したファイルはサンドボックスのどこに置かれるか

実行中に追加したファイルも、作成時のマウントと同じ規則でサンドボックスに置かれます。ガイドの追加例はmount_pathを指定しない短い形ですが、APIリファレンスではmount_pathを省略可能な引数として載せています。

置かれるファイルは読み取り専用のコピーで、エージェントは元のアップロードを書き換えられません。修正版が必要なら、エージェントはサンドボックス内の別のパスに書き出します。コピーには新しいfile_idが振られ、そのコピーはFiles APIのストレージ上限に数えられません。1つのセッションに載せられるファイルは最大500個です。

mount_pathは/で始まる絶対パスで書きます。途中のディレクトリは自動で作られるので、作成時に/src/main.pyを指定すれば/mnt/session/uploads/src/main.pyに置かれます。入力は/mnt/session/uploads/、成果物は/mnt/session/outputs/と、向きでディレクトリが分かれています。エージェントが書き出した成果物をuploads側に探しても見つかりません。

mount_pathを省いて追加したファイルは、エージェントへの依頼文に/mnt/session/uploads/<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..."

作成時に渡し忘れたファイルや、途中で判明した追加データを、セッションを作り直さずに渡せます。返ってきたresource_idは削除時に必要なので、セッションIDと並べて保存しておきます。保存し忘れても、一覧からidを取れます。

ステップ2 — セッションのリソース一覧を確認する

セッションにマウントされているリソースは、GET sessions/{session_id}/resourcesで一覧できます。ファイル以外のリソースも同じ配列に入るため、取得後にtypeで絞り込みます。

curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/sessions/${session_id}/resources" \
  | jq -r '.data[] | "\(.id) \(.type)"'

Python SDKの例ではresources.listで受けた配列をentry.idとentry.typeで読み、TypeScriptの例はtype !== "memory_store"で除外してからファイルを扱っています。型を見ずに全件をファイルとして処理する実装は避けます。削除の前にも、対象がファイルのリソースかを確かめます。

ステップ3 — 不要になったファイルを削除する

resource_idを指定してDELETE sessions/{session_id}/resources/{resource_id}を呼ぶと、そのファイルをセッションから外せます。

curl --fail-with-body -sS "${auth[@]}" -X DELETE \
  "${base_url}/sessions/${session_id}/resources/${resource_id}" >/dev/null

セッションに置かれていたのは元ファイルのコピーで、file_idも別に振られています。元のアップロードを消す場合は、Files APIの削除(DELETE /v1/files/{id})を呼びます。

長時間セッションに追加データを渡す流れ

追加から回収までの流れは4段階です。

セッションを1本立てたまま外部からデータを継ぎ足せる点が、作成時にすべてを揃える構成との違いです。

ステップ4 — エージェントの出力ファイルを一覧・ダウンロードする

エージェントが/mnt/session/outputs/配下に書き込んだファイルは、Files APIから取得できます。scope_idにセッションIDを指定して絞り込むにはmanaged-agents-2026-04-01ベータヘッダーが必要で、SDKではbeta名前空間のfiles.listを使います。client.beta.filesは、Python SDK 1.2.0・TypeScript SDK 0.122.0以降でfiles-api-2025-04-14ヘッダーを送らなくなり、client.filesと同じ形を返します。ベータ機能向けのbetas引数だけは残っていて、scope_idのフィルタリングはそこにManaged Agentsのヘッダーを渡して使います。

# セッションに紐づくファイルの一覧
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

出力は、エージェントが書き終えた直後ではなく少し遅れて一覧に載ります。セッションがアイドルになってから数秒かかることもあります。期待したファイルが無いときは、少し待ってから一覧を取り直します。一覧に現れた時点で、そのファイルのアップロードは完了しています。

ドキュメントのPython例は、一覧の各ファイルについてidとfilenameを表示し、先頭の1件をclient.files.downloadでoutput.txtに保存しています。複数の成果物がある場合は、filenameで目的のファイルを選んでからダウンロードします。

出力ファイルを待つときのポーリング設計

出力の完成時刻をアプリケーション側で予測するのは難しいので、待ち方を決めておきます。セッションのステータスがアイドルに変わったのを検知し、少し待ってからscope_id指定の一覧を取り直す形が扱いやすい設計です。一度の一覧で「出力がない」と判断せず、短い待機を挟んだ再試行を入れると、反映遅れによる誤検知を防げます。

何度取り直しても出ないときは、書き出し先を見直します。Files APIの一覧に載るのは/mnt/session/outputs/に書かれたファイルです。エージェントの書き出し先が別のディレクトリになっていないかを見ます。

ant CLIで同じ操作を行う

curlの代わりにant CLIでも、同じ操作を呼べます。ドキュメントに載っているサブコマンドは次のとおりです。

# 追加・一覧・削除
ant beta:sessions:resources add \
  --session-id "$SESSION_ID" --type file --file-id "$FILE_ID"
ant beta:sessions:resources list --session-id "$SESSION_ID"
ant beta:sessions:resources delete \
  --session-id "$SESSION_ID" --resource-id "$RESOURCE_ID"
 
# セッションの出力を一覧・ダウンロード
ant beta:files list --scope-id "$SESSION_ID" --beta managed-agents-2026-04-01
ant files download --file-id "$FILE_ID" --output output.txt

出力側の一覧だけbeta:filesと--betaが付き、ダウンロードは通常のfiles downloadになっています。

file_idの扱いで気をつけること

Files APIのファイルは、アップロードしたワークスペース全体からアクセスできます。ユーザー・会話・セッションごとに区切られているわけではありません。同じワークスペースのAPIキーなら、どのファイルも参照できます。

デフォルトのワークスペースには、サービスアカウントと、組織の役割がAPIアクセスを許す全ユーザーが入れます。互いに見せたくないファイルは、専用のワークスペースに置き、そのワークスペースのキーだけで扱います。

エンドユーザーから受け取った値をそのままfile_idに使うと、別の利用者がアップロードした内容を読める経路になります。file_idはサーバー側の参照子として扱い、利用者とファイルの対応はアプリケーションで管理してください。ファイルはワークスペース全体からアクセスできるため、scope_idで一覧を絞っても、利用者ごとの境界にはなりません。対策の詳細はClaude Files APIのfile_idセキュリティリスクと対策にあります。

実行中セッションで使うAPIの使い分け

scope_idで絞り込む一覧だけが、beta名前空間とベータヘッダーを必要とします。

よくあるつまずき

• 出力ファイルが一覧に出てこない: 書き込み完了から反映まで、遅れることがあります。すぐ一覧を叩いて「無い」と決めず、取り直します。
• scope_idで絞り込むと失敗する: scope_idのフィルタリングにはベータヘッダーが要ります。通常のfiles.listではなくbeta名前空間の呼び出しを使います。
• リソースを削除しても元のファイルは消えるのか: セッションにあったのはコピーで、別のfile_idが振られています。元のアップロードを消すには、Files APIの削除を呼びます。
• resources.listにファイル以外が混ざる: 一覧にはGitHubリポジトリやメモリーストアも入ります。typeで絞ってから処理します。
• 実行中に足したファイルが探せない: 追加時にmount_pathを付けるか、依頼文でパスを伝えます。

まとめ

作成時に揃えきれない追加データや、途中で出てくる成果物を扱うなら、セッションを作り直さずに済む実行中の出し入れが選択肢になります。その場合は、出力の一覧への反映が遅れる前提で、取り直しを含めて組みます。

作成時にまとめて渡す手順はManaged Agentsにファイルをアップロード・マウントする、セッション・ハーネス・サンドボックスの分離設計はManaged Agentsの設計思想にあります。