Managed Agentsにファイルをアップロード・マウントする

Managed Agentsのセッションにファイルを渡す方法

Managed Agentsのエージェントにデータセットや設定ファイルを読ませるには、Files APIでファイルをアップロードし、セッション作成時に配列でマウントします。エージェント側のコードにファイル読み込み処理を書く必要はありません。サンドボックス内のパスとして見えるようになるだけです。

実行中のセッションへの追加・一覧・ダウンロードは操作が別になるため、実行中セッションでのファイル操作で扱っています。ここではセッション起動時の渡し方を順に見ます。

前提条件

Managed Agents APIのリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要で、SDKを使うと自動で付きます。メモリーストア関連のエンドポイントだけは別のヘッダーagent-memory-2026-07-22を使い、同じリクエストに両方を並べると400になります。マウントするファイルは、先にアップロードしてfile_idを手元に置いておきます。

ステップ1 — Files APIでファイルをアップロードする

対象ファイルをFiles APIにアップロードし、file_idを控えます。ファイル名は日本語でも構いません。< > : " | ? * \ / と制御文字を含まず、1〜255文字に収まっていれば通ります。詳しくはFiles APIの日本語ファイル名対応にあります。

file=$(curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/files" \
  -F file=@data.csv)
file_id=$(jq -er '.id' <<<"${file}")
printf 'File ID: %s\n' "${file_id}"

ant CLIを使うなら、ant files upload --file data.csv --transform id --raw-outputでIDだけが返ります。ここまではManaged Agents専用の処理ではなく、通常のFiles APIそのものです。

ステップ2 — セッション作成時にresourcesでマウントする

セッション作成リクエストのresources配列に、type: "file"のエントリとしてfile_idとmount_pathを指定します。mount_pathは省略できますが、そのときの置き場所は/mnt/session/uploads/<file_id>です。中身の見当がつくパスを自分で付けたほうが、エージェントはファイルを見つけやすくなります。

session=$(
  jq -n \
    --arg agent_id "${agent_id}" \
    --arg environment_id "${environment_id}" \
    --arg file_id "${file_id}" \
    '{
      agent: $agent_id,
      environment_id: $environment_id,
      resources: [
        {
          type: "file",
          file_id: $file_id,
          mount_path: "/data.csv"
        }
      ]
    }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-
)
session_id=$(jq -er '.id' <<<"${session}")

mount_pathに/data.csvを指定すると、エージェントは/mnt/session/uploads/data.csvとして読めます。パスは常にセッションのuploadsディレクトリを起点にし、/から始まる絶対パスで書きます。/src/main.pyのようにサブディレクトリを含めても、親ディレクトリは自動で作られます。

ant CLIでは、ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENVIRONMENT_ID"にYAMLを標準入力で渡します。YAMLのresources:にtype: file・file_id・mount_pathを並べる形で、cURLと同じ内容になります。

マウント時には、元のファイルを参照する新しいfile_idがセッション用のインスタンスとして作られます。このコピーはFiles APIの保存容量にカウントされません。

複数ファイルをまとめてマウントする

resources配列にエントリを足せば、1回のセッション作成で複数ファイルを同時にマウントできます。

"resources": [
  { "type": "file", "file_id": "file_abc123", "mount_path": "/data.csv" },
  { "type": "file", "file_id": "file_def456", "mount_path": "/config.json" },
  { "type": "file", "file_id": "file_ghi789", "mount_path": "/src/main.py" }
]

データセット、コード、設定ファイルを1つのセッションに混在させても、mount_pathを分けておけば読み込み時に迷いません。形式ごとにマウント方法を変える必要もなく、resourcesの書き方はどの種別でも同じです。

容量と期限の扱いはClaude Files APIの容量上限とファイルライフサイクルに詳しくあります。

エージェントからはどう見えるか

ソースコード(.py・.js・.ts・.go・.rsなど)、データファイル(.csv・.json・.xml・.yaml)、ドキュメント(.txt・.md)のどれもマウントできます。.zipや.tar.gzはエージェントがbashで展開して読めます。バイナリも、適切なツールがあれば処理できます。

マウントされたファイルは読み取り専用のコピーで、アップロード元は書き換えられません。加工した版が必要なら、エージェントがサンドボックス内の別のパスへ書き出します。

入力は読み取り専用、成果物はoutputsに書く

入力のマウント先/mnt/session/uploads/と、成果物の書き出し先/mnt/session/outputs/は別のディレクトリです。

CLIならant beta:files list --scope-id sesn_abc123 --beta managed-agents-2026-04-01で同じ一覧が取れます。

書き込み直後は一覧に出ないことがあります。セッションがidleになってから数秒遅れて現れる場合があるため、見当たらないときは少し待って一覧を取り直します。一覧に出た時点で、アップロードは完了しています。

プロンプトで場所を指定しておくと、加工結果を取りこぼしにくくなります。たとえば次のような書き方です。

/mnt/session/uploads/data.csv を読み、集計結果を /mnt/session/outputs/summary.md に書き出してください。

セッションを作る前にfile_idを確かめる

ファイルはアップロードしたワークスペースに属し、同じワークスペース内のリクエストから参照できます。存在しないfile_idは404になります。アップロードとセッション作成を並行して走らせるパイプラインでは、アップロードのレスポンスでfile_idを受け取ってから作成に進みます。

事前に存在を確かめるなら、一覧エンドポイントのids[]クエリが使えます。1回で最大100件のIDを渡せ、ワークスペースに無いIDはレスポンスのdataから黙って省かれます。返ってきたIDと依頼したIDを突き合わせれば、欠けたものが分かります。ids[]はpageやlimitとは併用できません。

curl -g --fail-with-body -sS "${auth[@]}" \
  "${base_url}/files?ids[]=${file_id_a}&ids[]=${file_id_b}"

ワークスペース・削除・有効期限で押さえる点

アップロードしたファイルは、特定のセッションや利用者ではなくワークスペース全体からアクセスできます。ワークスペースへのアクセス権を持つAPIキーなら、どのファイルも参照できます。

マルチテナントのアプリでは、テナントごとにワークスペースを分けるのが公式の案内です。1組織で作れるワークスペースは100までで、デフォルトワークスペースには組織内のサービスアカウントなどもアクセスできます。分けたいファイルは専用のワークスペースに置き、そのキーだけで扱います。

削除したファイルはAPIから間もなく見えなくなり、復元はできません。ただし、実行中のMessages APIの呼び出しやツール利用には残ることがあります。

組織でCompliance APIを有効にしていれば、アップロード(POST /v1/files)、内容のダウンロード、削除はActivity Feedに記録されます。一覧とメタデータの取得は記録対象外で、APIをオフにしていた間の操作は後から復元できません。

有効期限はexpires_in_secondsでアップロード時に一度だけ設定でき、後から変更できません。期限を過ぎるとダウンロードは404になりますが、メタデータは最大30日間読めます。複数のセッションで繰り返し使うファイルには、期限を付けないか、十分長く取ります。

起動時マウントと実行中の追加、どちらを使うか

セッション作成時にinitial_eventsでファイル由来のdocumentコンテンツブロックを渡す経路もあります。この場合は全体で100個を超えると400になり、リクエスト本体が32MBを超えると413です。resourcesによるマウントとは別の経路です。

実行中セッションへの追加・削除・一覧と、出力のダウンロード手順は実行中セッションでのファイル操作にあります。

よくあるつまずき

• mount_pathを省略してファイルが見つからない: 省略時のパスは/mnt/session/uploads/<file_id>です。mount_pathを指定するか、プロンプトで場所を伝えます。
• マウントしたファイルを編集しようとして失敗する: マウントされたファイルは読み取り専用です。編集結果は別パスに書き出す前提で設計します。
• file_idをエンドユーザーから直接受け取ってしまう: ファイルはワークスペース単位でアクセスできるため、入力されたfile_idをそのまま使うと、別の利用者のファイルを参照できてしまいます。file_idはサーバー側で管理し、利用者との対応はアプリ側で持ちます。
• mount_pathを相対パスで書く: パスは/から始まる絶対パスで指定します。data.csvではなく/data.csvと書きます。
• アップロードしたファイルを後から差し替えたい: ファイルは更新も改名もできません。内容を変えるときは新しくアップロードして、古いファイルを削除します。

まとめ

Managed Agentsへのファイル提供は、アップロードしてresourcesにfile_idを入れるだけです。成果物を受け取りたいときは、uploadsではなくoutputsに書かせる指示を添えます。

マルチテナントや長期運用なら、ワークスペースの分け方と有効期限を、最初のファイルを上げる前に決めておく選択肢があります。基盤になるセッション・ハーネス・サンドボックスの分離設計はManaged Agentsの設計思想で解説しています。