添加文件 - Claude API Docs

您可以通过 Files API 上传文件并将其挂载到会话容器中，从而向代理提供文件。

所有 Managed Agents API 请求都需要 managed-agents-2026-04-01 beta 请求头。SDK 会自动设置该 beta 请求头。

上传文件

首先，使用 Files API 上传文件：

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

在会话中挂载文件

通过在创建会话时将文件添加到 resources 数组中，将已上传的文件挂载到容器中：

mount_path 是可选的，但请确保上传的文件具有描述性名称，以便代理知道它在查找什么。

将创建一个新的 file_id，用于引用会话中该文件的实例。这些副本不计入您的存储限制。

多个文件

通过向 resources 数组添加条目来挂载多个文件：

每个会话最多支持 100 个文件。

管理运行中会话的文件

您可以在会话创建后使用会话资源 API 添加或删除文件。每个资源在添加（或列出）时都会返回一个 id，您可以使用该 id 进行删除操作。

使用 resources.list 列出会话中的所有资源。要删除文件，请使用资源 ID 调用 resources.delete：

列出和下载会话文件

使用 Files API 列出与会话关联的文件并下载它们。

支持的文件类型

代理可以处理任何文件类型，包括：

源代码（.py、.js、.ts、.go、.rs 等）
数据文件（.csv、.json、.xml、.yaml）
文档（.txt、.md）
压缩包（.zip、.tar.gz）——代理可以使用 bash 解压这些文件
二进制文件——代理可以使用适当的工具处理这些文件

文件路径

挂载在容器中的文件是只读副本。代理可以读取它们，但无法修改原始上传的文件。若要处理修改后的版本，代理会在容器内的新路径中写入。

文件挂载在您指定的确切路径
父目录会自动创建
路径应为绝对路径（以 / 开头）

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: "/workspace/data.csv"
        }
      ]
    }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-
)
session_id=$(jq -er '.id' <<<"${session}")

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

resource=$(
  jq -n --arg file_id "${file_id}" '{type: "file", file_id: $file_id}' \
    | curl --fail-with-body -sS "${auth[@]}" \
        "${base_url}/sessions/${session_id}/resources" --json @-
)
resource_id=$(jq -er '.id' <<<"${resource}")
printf '%s\n' "${resource_id}"  # "sesrsc_01ABC..."

curl --fail-with-body -sS "${auth[@]}" \
  "${base_url}/sessions/${session_id}/resources" \
  | jq -r '.data[] | "\(.id) \(.type)"'

curl --fail-with-body -sS "${auth[@]}" -X DELETE \
  "${base_url}/sessions/${session_id}/resources/${resource_id}" >/dev/null

# 列出与会话关联的文件
curl -fsSL "https://api.anthropic.com/v1/files?scope_id=sess_abc123" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14"

# 下载文件
curl -fsSL "https://api.anthropic.com/v1/files/$FILE_ID/content" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: files-api-2025-04-14" \
  -o output.txt