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.cn/api/v1/cloud/files
Content-Type: multipart/form-data

参数

字段类型必填说明
filebinary是文件内容
namestring否自定义文件名
是否可通过 /content 下载以 File 对象的 downloadable 字段为准。

curl 上传示例

curl -X POST https://api.qoder.com.cn/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"
}
上传多个文件： 
# 逐个上传
curl -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./config.yaml"

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

挂载到 Session

上传后，通过 Resources API 将文件挂载到指定 Session： 
POST https://api.qoder.com.cn/api/v1/cloud/sessions/{session_id}/resources
请求体（发送单个 file resource）： 
{
  "type": "file",
  "file_id": "file_abc123",
  "mount_path": "/data/input.txt"
}

curl 挂载示例

curl -X POST https://api.qoder.com.cn/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 创建后挂载多个文件，请对每个文件各调用一次该接口。

下载文件

downloadable 为 true 的文件可下载： 
curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -o output.txt
不可下载文件请求 /content 端点将返回 403 Forbidden。

查看文件信息

curl https://api.qoder.com.cn/api/v1/cloud/files/file_abc123 \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

列出文件

curl "https://api.qoder.com.cn/api/v1/cloud/files?scope_id=sess_abc123" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
支持按 scope_id 过滤 Session 范围文件。

Session 产出物的交付与取回

Agent 在 Session 中生成的文件按以下步骤交付给客户端：
  1. Agent 使用 Write 将文件写入沙箱的 /data/ 目录
  2. Agent 调用 DeliverArtifacts 将文件交付为 File
  3. 事件流发送 agent.artifact_delivered，其中包含 file_id、original_filename、size 和 content_type
  4. 客户端通过 Files API 取回文件
# 列出 Session 的文件（scope_id 为 Session ID）
curl "https://api.qoder.com.cn/api/v1/cloud/files?scope_id=sess_abc123" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

# 获取临时下载 URL，再请求该 URL 下载内容
curl "https://api.qoder.com.cn/api/v1/cloud/files/file_abc123/content" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"
接口说明见列出文件和下载文件内容。
  • 只有 downloadable 为 true 的文件可以下载。
  • 文件可能在交付数秒后才出现在列表中。
  • Agent 也可能直接在回复中给出结果，客户端应同时处理这两种情况。
  • 需要按验收标准评估产出时，见 Outcome 验收判定。

完整工作流示例

# 1. 上传源代码文件
FILE_ID=$(curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/files \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -F "file=@./app.py" | jq -r '.id')

echo "上传完成: $FILE_ID"

# 2. 创建 Session
SESSION_ID=$(curl -s -X POST https://api.qoder.com.cn/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.cn/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.cn/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": "审查 app.py 并修复其中的 bug"}]}
    ]
  }'

常见问题

Q：上传的文件存储多久？ A：文件在你调用 DELETE /api/v1/cloud/files/{file_id} 显式删除前会持续保留。仍被活跃 Session 引用的文件无法删除，需先删除或取消挂载相关 Session。 Q：能否直接在创建 Session 时附带文件？ A：可以。创建 Session 时在 resources 字段中传入文件资源即可。详见 Sessions — 创建时挂载资源。 Q：为什么有些文件不可下载？ A：出于安全考虑，部分文件仅供 Agent 内部使用。如需导出结果，请使用 File 对象中 downloadable 为 true 的文件。 Q：支持哪些文件格式？ A：上传接口接受文本类文件。代码、配置和纯文本参考文档效果最佳。