面向 AI 助手：本页的 Markdown 版本位于 https://ark.volcengine.com/region:cn-beijing/docs/upload-and-mount-files.md，全部文档索引见 https://ark.volcengine.com/llms.txt。

上传与挂载文件

本文介绍如何在方舟 Managed Agents 中上传和挂载输入文件、在 Session 运行时管理文件资源，以及查询 Agent 生成的产物。

Managed Agents 支持挂载通过 文件输入(Files API) 或 TOS 对象存储 上传的文件，再将文件作为 Session 资源挂载到沙箱环境目录中。Agent 可以读取这些输入文件，并将最终产物写入 /mnt/session/outputs/。

上传文件#

你可以使用 Files API 或 TOS 上传需要被 Agent 读取的文件。

  • 使用 Files API：

    先将本地文件上传到 Files API。上传成功后，平台会返回 file_id，后续创建 Session 或向运行中的 Session 追加文件资源时都需要使用该 ID。

```Bash
file=$(
  curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/files" \
    -H "Authorization: Bearer $ARK_API_KEY" \
    -F 'purpose=agent' \
    -F 'file=@path/of/your/file'
)

FILE_ID=$(jq -er '.id' <<<"$file")

echo "File ID: $FILE_ID"
```

  • 使用 TOS 上传：

    以下示例使用 TOS Python SDK 上传本地文件，更多使用方式，请参考 TOS 官方文档。

    python
    import os
import tos

ak = os.getenv("TOS_ACCESS_KEY")
sk = os.getenv("TOS_SECRET_KEY")

endpoint = "tos-cn-beijing.volces.com"
region = "cn-beijing"

bucket_name = "<BUCKET_NAME>"
object_key = "<OBJECT_KEY>"   # The path of the uploaded file. For example: agent-files/skill.md
file_name = "/path/of/your/file"  # Local file path

try:
    client = tos.TosClientV2(ak, sk, endpoint, region)

    result = client.put_object_from_file(
        bucket_name,
        object_key,
        file_name,
    )

    print("upload success")
    print("request_id:", result.request_id)
    print("etag:", result.etag)

except tos.exceptions.TosClientError as e:
    print("client error:", e.message)
    print("cause:", e.cause)

except tos.exceptions.TosServerError as e:
    print("server error code:", e.code)
    print("request_id:", e.request_id)
    print("message:", e.message)
    print("status_code:", e.status_code)
    print("request_url:", e.request_url)

except Exception as e:
    print("unknown error:", str(e))

在创建 Session 时挂载文件#

创建 Session 时，在 resources 数组中声明需要挂载的文件。

  • 通过 Files ID 挂载：

每个文件资源至少需要包含 type 和 file_id。
mount_path 可选。建议设置 mount_path，让 Agent 可以从稳定、可读的路径访问文件。如果不显式指定路径，请确保上传文件名足够清晰，便于 Agent 识别文件用途。

bash
session=$(
  curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions" \
    -H "Authorization: Bearer $ARK_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "resources": [
    {
      "type": "file",
      "file_id": "$FILE_ID",
      "mount_path": "target/mounting/path/of/the/file"
    }
  ]
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

挂载后，平台会为该 Session 内的文件实例生成新的 file_id。这些 Session 内副本不计入用户的文件存储额度。

  • 从 TOS 挂载：
bash
session=$(
  curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions" \
    -H "Authorization: Bearer $ARK_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
  "agent": "$AGENT_ID",
  "environment_id": "$ENVIRONMENT_ID",
  "resources": [
    {
      "type": "tos",
      "tos_bucket": "<BUCKET_NAME>",
      "tos_key": "path/of/the/tos/directory/"
    }
  ]
}
EOF
)

SESSION_ID=$(jq -er '.id' <<<"$session")

echo "Session ID: $SESSION_ID"

挂载多个文件#

如果一次任务需要多个输入文件，可以在 resources 中添加多个条目。单个 Session 最多支持挂载 100 个文件。

以 Files ID 为例：

json
"resources": [
  { "type": "file", "file_id": "<FILE_ID_1>" },
  { "type": "file", "file_id": "<FILE_ID_2>" },
  { "type": "file", "file_id": "<FILE_ID_3>" }
]

在 Session 运行时管理文件#

Session 创建后，可以通过 Session Resources API 继续添加文件，并查询当前已挂载的资源。

以下示例沿用前面创建 Session 后写入的 $SESSION_ID；添加 Files API 文件时也沿用上传步骤写入的 $FILE_ID。

添加文件资源#

bash
resource=$(
  curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions/$SESSION_ID/resources" \
    -H "Authorization: Bearer $ARK_API_KEY" \
    -H "Content-Type: application/json" \
    -d @- <<EOF
{
  "type": "file",
  "file_id": "$FILE_ID"
}
EOF
)

RESOURCE_ID=$(jq -er '.id' <<<"$resource")

echo "Resource ID: $RESOURCE_ID"

查询文件资源#

Bash
# List session resources
curl -sS --fail-with-body "https://ark.cn-beijing.volces.com/api/v3/sessions/$SESSION_ID/resources" \
  -H "Authorization: Bearer $ARK_API_KEY"

获取 Session 运行时产物#

Agent 将需要交付的文件写入 /mnt/session/outputs/ 后，平台会将这些文件注册为当前 Session 下 purpose=agent 的文件。需要在你的服务中展示或下载报告、图片、视频、文档或代码等产物时，通过 Files API 获取：

  1. 调用 GET /files?scope_id=<session_id>&purpose=agent，分页查询该 Session 的 Agent 产物。
  2. 从列表响应中获取文件 ID、文件名、文件大小、MIME 类型和 download_url。
  3. 使用 download_url 下载文件内容。

视觉增强 Agent 生成的图片和视频也遵循相同规则。生成工具会将最终产物写入 /mnt/session/outputs/ 并注册到 Files API，业务系统通过 Session ID 查询和下载产物。

Bash
# List files associated with a session.
curl -sS --fail-with-body \
  "https://ark.cn-beijing.volces.com/api/v3/files?scope_id=$SESSION_ID&purpose=agent" \
  -H "Authorization: Bearer $ARK_API_KEY"

列表响应中的 download_url 是服务端签发的预签名下载地址，具有时效性。

创建 Session 前，按产物的保留要求选择存储方式：

你的配置 产物位置 你需要做什么
不配置 config.tos 方舟公共 TOS 在平台 TTL 到期前下载所需文件。删除 Session 时，平台会清理默认存储中的关联产物。
在 Environment 或 Session 覆写中配置 config.tos 你的 TOS Bucket，完整对象路径为 {prefix}outputs/{env-id}/{session-id}/{file} 在 TOS 中管理对象生命周期。删除 Session 不会删除 Bucket 中的对象。

配置 Environment 产物存储及按 Session 临时覆写的方法，详情请参见 配置产物存储 和 覆写产物存储。

支持的文件类型#

Agent 可以处理多种文件类型。常见类型包括：

  • 源代码文件，例如 .py、.js、.ts、.go、.rs 等。
  • 数据文件，例如 .csv、.json、.xml、.yaml。
  • 文本文档，例如 .txt、.md。
  • 归档文件，例如 .zip、.tar.gz；Agent 可以在沙箱中使用 bash 解压后处理。
  • 二进制文件；是否能正确处理取决于沙箱内是否具备相应工具。

使用建议#

  • 挂载到沙箱中的文件是只读副本。Agent 可以读取这些文件，但不能直接修改原始上传文件。
  • 如果任务需要产出修改后的版本，应将结果写入沙箱中的新路径。
  • 需要回传的输出文件，应在任务说明中要求 Agent 写入 /mnt/session/outputs/。需要长期保存时，为 Environment 配置自己的 TOS Bucket，并在 TOS 中管理对象生命周期。
  • 如果运行中的 Session 不再需要某个大文件，及时移除对应资源，减少后续工具调用的上下文干扰。