托管智能体管理智能体上下文

添加文件

上传文件并将其挂载到您的沙盒中以供读取和处理。

您可以通过 Files API 上传文件并将其挂载到会话的沙盒中，从而为您的智能体提供文件。

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

上传文件

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

file = client.beta.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

在会话中挂载文件

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

mount_path 是可选的，但请确保上传的文件具有描述性的名称，以便智能体能够识别它。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/workspace/data.csv",
        },
    ],
)

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

多个文件

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

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

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

管理运行中会话的文件

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

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

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

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

列出和下载会话文件

使用 Files API 列出限定于某个会话的文件并下载它们。

# 列出与会话关联的文件
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for f in files:
    print(f.id, f.filename)

# 下载文件
content = client.beta.files.download(files.data[0].id)
content.write_to_file("output.txt")

支持的文件类型

智能体可以处理任何文件类型，包括：

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

文件路径

挂载到沙盒中的文件是只读副本。智能体可以读取它们，但无法修改原始上传的文件。如需处理修改后的版本，智能体会将内容写入沙盒内的新路径。

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

Was this page helpful?

托管智能体管理智能体上下文

添加文件

上传文件并将其挂载到您的沙盒中以供读取和处理。

您可以通过 Files API 上传文件并将其挂载到会话的沙盒中，从而为您的智能体提供文件。

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

上传文件

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

file = client.beta.files.upload(file=Path("data.csv"))
print(f"File ID: {file.id}")

在会话中挂载文件

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

mount_path 是可选的，但请确保上传的文件具有描述性的名称，以便智能体能够识别它。

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": file.id,
            "mount_path": "/workspace/data.csv",
        },
    ],
)

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

多个文件

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

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

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

管理运行中会话的文件

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

resource = client.beta.sessions.resources.add(
    session.id,
    type="file",
    file_id=file.id,
)
print(resource.id)  # "sesrsc_01ABC..."

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

listed = client.beta.sessions.resources.list(session.id)
for entry in listed.data:
    print(entry.id, entry.type)

client.beta.sessions.resources.delete(resource.id, session_id=session.id)

列出和下载会话文件

使用 Files API 列出限定于某个会话的文件并下载它们。

# 列出与会话关联的文件
files = client.beta.files.list(
    scope_id="sesn_abc123",
    betas=["managed-agents-2026-04-01"],
)
for f in files:
    print(f.id, f.filename)

# 下载文件
content = client.beta.files.download(files.data[0].id)
content.write_to_file("output.txt")

支持的文件类型

智能体可以处理任何文件类型，包括：

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

文件路径

挂载到沙盒中的文件是只读副本。智能体可以读取它们，但无法修改原始上传的文件。如需处理修改后的版本，智能体会将内容写入沙盒内的新路径。

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

Was this page helpful?

上传文件

在会话中挂载文件

多个文件

管理运行中会话的文件

列出和下载会话文件

支持的文件类型

文件路径

上传文件

在会话中挂载文件

多个文件

管理运行中会话的文件

列出和下载会话文件

支持的文件类型

文件路径

上传文件

在会话中挂载文件

多个文件

管理运行中会话的文件

列出和下载会话文件

支持的文件类型

文件路径

上传文件

在会话中挂载文件

多个文件

管理运行中会话的文件

列出和下载会话文件

支持的文件类型

文件路径