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

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

Managed Agentsのエージェントにデータセットや設定ファイルを読ませるには、Files APIでファイルをアップロードし、セッション作成時に配列でマウントします。エージェント本体のコードにファイル読み込み処理を書く必要はなく、サンドボックス内のパスとして見えるようになるだけです。実行中セッションへの追加・一覧・ダウンロードは操作が別になるため、実行中セッションでのファイル操作で扱います。本稿はセッション起動時の渡し方に絞ります。

前提条件

Managed Agents APIのリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です(メモリーストア関連のエンドポイントだけはagent-memory-2026-07-22)。SDKを使う場合はこのヘッダーが自動で付与されます。加えて、マウントするファイルは先にFiles APIへアップロードしてfile_idを取得しておく必要があります。

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

まず対象ファイルをFiles APIにアップロードし、file_idを控えます。

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

このアップロードはManaged Agents専用の処理ではなく通常のFiles APIです。アップロードしたファイルはワークスペース単位でアクセス可能になり、特定のセッションや会話にスコープされません。この点はfile_idを利用者ごとに払い出すような実装では要注意です。ファイルサイズの上限は1ファイル500MB、組織全体の合計保存容量は1TBで、容量やファイルの有効期限の管理はClaude 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ディレクトリを起点とし、親ディレクトリは自動で作成されます。パスは/から始まる絶対パスで指定してください。

マウント時には元のfile_idを参照する新しい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セッションにマウントできるファイル数の上限は最大500件です。データセットとコード、設定ファイルを1つのセッションに混在させるような使い方でも、この上限までは1回のリクエストで完結します。

マウントできるファイル形式

エージェントはソースコード(.py・.js・.ts・.go・.rsなど)、データファイル(.csv・.json・.xml・.yaml)、ドキュメント(.txt・.md)を問わず扱えます。.zipや.tar.gzのようなアーカイブはエージェントがbashで展開して読み込めますし、バイナリファイルも適切なツールがあれば処理対象になります。形式によってマウント方法を変える必要はなく、resources配列の指定はどのファイル種別でも共通です。ソースコードと設定ファイルを同じセッションに混在させる構成でも、mount_pathを分けておけば読み込み時に迷うことはありません。

ファイルの有効期限とワークスペース分離を意識する

マウント元のファイルはFiles API本体の仕様に従うため、Managed Agents特有ではない制約もあわせて押さえておく必要があります。アップロード時にexpires_in_seconds(1時間から90日の範囲)を指定すると、そのファイルは指定時刻に自動で失効します。失効後もメタデータは30日間は読み取れますが、内容はダウンロードできなくなるため、複数セッションで繰り返し参照するファイルには有効期限を設定しないか、十分に長い期間を確保してください。

もう1つ重要なのは、アップロードしたファイルがワークスペース単位でアクセス可能になり、特定のエンドユーザーやセッションに閉じないという点です。複数のテナントを扱うプロダクトでビルドする場合は、テナントごとに別のワークスペースを用意し、そのワークスペースに限定したAPIキーでファイルをアップロード・マウントする設計が、データを混在させない唯一の境界になります。

アップロード用ディレクトリと出力用ディレクトリを混同しない

マウントしたファイルが置かれる/mnt/session/uploads/と、エージェントが成果物を書き出す/mnt/session/outputs/は別のディレクトリです。前者は読み取り専用で、後者に書いたファイルだけがFiles API経由で取得できるようになります。エージェントへの指示で「入力はuploads配下、出力はoutputs配下に書く」と明示しておくと、加工結果を取りこぼす事故を防ぎやすくなります。マウント時に指定するmount_pathは/data.csvのように絶対パス表記で指定し、実体はセッションのuploadsディレクトリ配下に置かれます。/src/main.pyのようにサブディレクトリを含めても親ディレクトリは自動で作成されます。

存在しないfile_idをマウントしようとするとどうなるか

resources配列に指定したfile_idが存在しない、あるいは別のワークスペースに属している場合、ワークスペース単位のアクセス境界に反するため、セッション作成のリクエストは失敗するとみられます(具体的なエラー文言・ステータスコードは一次ソースに明記がありません)。マウント対象のファイルは事前にFiles APIへのアップロードが完了している必要があり、アップロードとセッション作成を並行して走らせるパイプラインでは、アップロードのレスポンスでfile_idを受け取ってからセッション作成に進む順序を守る必要があります。アーカイブを展開する用途で.zipをマウントした場合も、展開はエージェントがサンドボックス内でbashコマンドを実行して行うものであり、マウントした時点で自動的に展開されるわけではない点も合わせて押さえておきます。

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

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

よくあるつまずき

• mount_pathを省略してファイルが見つからない: 省略時は/mnt/session/uploads/<file_id>という分かりにくいパスになります。エージェントのプロンプトでファイルの場所を明示するか、mount_pathを必ず指定してください。
• アップロードしたファイルを編集しようとして失敗する: マウントされたファイルは読み取り専用のコピーです。編集結果は別パスに書き出す前提で設計します。
• file_idをエンドユーザーから直接受け取ってしまう: Files APIのファイルはワークスペース単位のアクセスになるため、ユーザー入力のfile_idをそのまま信用すると、別の利用者がアップロードしたファイルを参照できてしまいます。file_idはサーバー側で管理し、利用者とファイルの対応関係はアプリケーション側で持つ設計にします。
• 500ファイルの上限に近づいていることに気づかない: データパイプラインを自動化していると、1セッションに大量のファイルを積み上げがちです。上限に達すると以降のマウントが失敗するため、不要なファイルは削除するか、セッションを分割します。
• mount_pathを相対パスで書いてしまう: 公式仕様ではmount_pathは/から始まる絶対パスを前提としています。data.csvのように先頭のスラッシュを落とした指定は仕様外の書き方になるため、常に/data.csvのように絶対パスで指定します。

まとめ

Managed Agentsへのファイル提供は、Files APIでのアップロードとセッション作成時のresources指定という2ステップで完結します。mount_pathは省略可能ですが明示するのが安全で、マウントされたファイルは読み取り専用のコピーとして扱われる点、最大500ファイルという上限がある点を押さえておけば、データ処理タスクをエージェントに任せる設計はシンプルになります。ファイルの有効期限やワークスペース単位のアクセス範囲といったFiles API本体の制約も、複数セッションやマルチテナントの構成を組むときには無視できません。セッション実行中に新しいファイルを渡したい場合や、エージェントの出力を取り出したい場合は、実行中セッションでのファイル操作を参照してください。基盤となるセッション・ハーネス・サンドボックスの分離設計はManaged Agentsの設計思想で解説しています。