Skip to main content
Agent コンテキストの管理

ファイルの添付とダウンロード

Agent にコンテキストを与えるファイルをアップロードし、Agent が生成したファイルをダウンロードします。

ファイル API を使うと、Session にコンテキスト — コードリポジトリ、構成、参考ドキュメントなど — を提供できます。Agent はこれらのファイルを読み取ってタスクを理解します。

基本フロー

1

ファイルをアップロード

POST /api/v1/cloud/files — テキストベースの内容をアップロードします。
2

Session にマウント

POST /api/v1/cloud/sessions/{session_id}/resources — アップロード済みファイルを Session にアタッチします。
3

Agent が利用

Session 中に Agent がファイル内容を読み取り、タスクを完了します。

ファイルをアップロードする

POST https://api.qoder.com/api/v1/cloud/files
Content-Type: multipart/form-data

パラメータ

フィールド型必須説明
filebinaryはいファイル内容
namestringいいえカスタムファイル名
/content が利用可能かどうかは、ファイルオブジェクトの downloadable フィールドで判断してください。
  • 単一ファイル
  • 複数ファイル
curl -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./src/main.py"

curl アップロード例

curl -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./src/main.py"
レスポンス:
{
  "id": "file_019e6a18dc0978e9a2104c9b269748ac",
  "type": "file",
  "filename": "main.py",
  "size_bytes": 4096,
  "downloadable": false,
  "mime_type": "text/plain",
  "scope": null,
  "created_at": "2026-05-01T10:00:00Z"
}
複数ファイルのアップロード:
# 1 つずつアップロード
curl -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./config.yaml"

curl -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./requirements.txt"

{
  "id": "file_019e6a18dc0978e9a2104c9b269748ac",
  "type": "file",
  "filename": "main.py",
  "size_bytes": 4096,
  "downloadable": false,
  "mime_type": "text/plain",
  "scope": null,
  "created_at": "2026-05-01T10:00:00Z"
}

Session にマウントする

アップロード後、Resources API でファイルを特定の Session にマウントします。 
POST https://api.qoder.com/api/v1/cloud/sessions/{session_id}/resources
リクエストボディ — 単一のファイルリソースを送信: 
{
  "type": "file",
  "file_id": "file_abc123",
  "mount_path": "/data/input.txt"
}
  • 単一ファイル
  • 複数ファイル
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resources": [
      {"type": "file", "file_id": "file_abc123"}
    ]
  }'

ファイルを管理する

ファイルメタデータを取得

curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_abc123/resources \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "file",
    "file_id": "file_abc123",
    "mount_path": "/data/input.txt"
  }'
Session 作成後に複数のファイルをアタッチするには、ファイルごとにこのエンドポイントを 1 回ずつ呼び出します。 Session スコープのファイルでは scope_id でのフィルタリングがサポートされます。

ファイルをダウンロード

"downloadable": true のファイルはダウンロードできます。 
curl https://api.qoder.com/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -o output.txt
ダウンロード不可のファイルでは、/content へのリクエストは 403 Forbidden を返します。

エンドツーエンドの例

# 1. ソースファイルをアップロード
FILE_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./app.py" | jq -r '.id')

echo "Uploaded: $FILE_ID"

# 2. Session を作成
SESSION_ID=$(curl -s -X POST https://api.qoder.com/api/v1/cloud/sessions \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent": "agent_abc123", "environment_id": "env_abc123"}' | jq -r '.id')

# 3. ファイルを Session にマウント
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"type\": \"file\", \"file_id\": \"$FILE_ID\"}"

# 4. タスクを送信 — Agent はマウント済みファイルを参照できる
curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/$SESSION_ID/events" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"type": "user.message", "content": [{"type": "text", "text": "Review app.py and fix the bugs."}]}
    ]
  }'

よくある質問

Q: アップロードしたファイルはどれくらい保持されますか? A: ファイルは DELETE /api/v1/cloud/files/{file_id} で明示的に削除するまで保持されます。アクティブな Session からまだ参照されているファイルは削除できません。先に該当する Session を削除するかデタッチしてください。 Q: Session 作成時にファイルを添付できますか? A: はい。Session 作成時に resources フィールドでファイルリソースを渡します。Sessions — 作成時にリソースをアタッチ を参照してください。 Q: なぜ一部のファイルはダウンロードできないのですか? A: セキュリティ上、一部のファイルは Agent の内部利用のみとしています。結果をエクスポートするには、ファイルオブジェクトが "downloadable": true を返すファイルを使用してください。 Q: どのファイル形式がサポートされますか? A: アップロード API はテキストベースのファイルを受け付けます。コード、構成、プレーンテキストの参考ドキュメントが最も適しています。

次のステップ

Session の開始

Session 作成時にファイルを添付する。

永続メモリの構築

Session 間で Agent の知識を永続化する。

Files API

完全な Files API。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス
ファイルの添付とダウンロード - Qoder