如需查看完整的文档索引,请参阅 llms.txt。在文档页面的 URL 末尾加上 .md 即可查看该页面的 Markdown 版本。
主导航
主题

文件与产物

从环境中获取文件并保存已发布的输出。

文件与已发布的产物

文件存储在智能体的环境中。产物是从 OpenAI 托管环境发布的文件副本。环境过期后,您仍可下载该副本。

环境 文件获取方式
self_hosted 使用您的提供商的文件 API 或已挂载的文件系统。
openai_hosted 使用会话的 Artifacts API 获取 /workspace/outputs 下的文件。
none 没有环境文件系统。请从会话条目中读取输出。

上传文件

如果使用 OpenAI 托管环境,请在创建会话时通过 environment.files 提供输入文件。每个文件的目标路径都应位于 /workspace 下。

使用 type: "file_id" 时,请提供通过 Files API 获取的 file_id。使用 type: "inline" 时,请提供经过 base64 编码的 data。两种方式都必须指定 path。

要在环境连接后添加文件,请使用环境 Files API。

处理上传错误

在创建会话或附加文件时,文件检查可能会返回 HTTP 429,错误代码为 files_api_rate_limit_exceeded。有关响应内容和恢复步骤,请参阅 Files API 速率限制。

如果收到 HTTP 400,请根据 error.param 和 error.message 确定需要更正的输入。 例如,如果目标路径位于 /workspace 之外,您会收到以下响应:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

参数路径与请求结构一致。下表中的 i 是文件索引,第一个文件的索引为 0:

请求 error.param 示例
向环境中添加一个文件 path、data 或 file_id
创建会话或预热环境 environment.files[i].data
创建或更新环境模板 files[i].data

请使用有效的 base64 数据和文件 ID,并选择 /workspace 下的绝对路径。请查看文件限制。如果目标路径经过符号链接、已存在或包含过长的路径分量,API 会返回 HTTP 400。

如果将文件写入环境时发生意外错误,API 会返回 HTTP 500。重试前,请检查目标文件是否已创建,然后按照重试指南操作。

获取文件

从您自己的环境获取文件

让智能体将输出写入指定路径。本轮结束后,通过您的提供商或基础设施获取文件。在环境过期或您删除环境之前,将文件保存到应用的存储空间中。

自托管环境中的文件不会通过 Artifacts API 发布,包括 /workspace/outputs 下的文件。有关各提供商的文件访问方式,请参阅沙盒提供商。

从 OpenAI 托管环境获取文件

让智能体将文件保存到 /workspace/outputs 下,例如 /workspace/outputs/report.pdf。本轮结束时,OpenAI 会将输出发布为不可修改的产物。

将您的 API 客户端、会话 ID、已完成轮次的 ID、产物路径和本地目标路径传给以下函数。该函数会列出产物,并下载同时匹配指定轮次和路径的文件:

查找并下载产物
# Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

有关请求和响应字段,请参阅列出产物、获取元数据和下载内容的 API 参考文档。

下载多个文件

该 API 每次请求只能下载一个产物,不提供批量下载端点。要下载多个文件,请先列出产物,再逐个请求文件的 content。如果希望一次下载全部结果,请让智能体将结果打包成 ZIP 文件,保存到 /workspace/outputs 下,然后将该压缩包作为一个产物下载。

文件保留期限

环境过期后,已发布的产物仍会保留。删除会话前,请下载您需要保留的所有内容。

您无法通过此 API 上传或编辑产物。要发布新版本,请让智能体更新文件并完成新一轮操作。使用轮次 ID 和路径区分版本。

如果不再需要已发布的副本,请删除产物。删除产物后,环境中的文件会原样保留。

文件限制

文件操作 限制
创建会话时提供文件 每次请求最多 50 个文件。
内联上传 每个文件最多 5 MiB,按 base64 编码前的大小计算。
在一次创建请求中内联上传文件 总计最多 10 MiB,按 base64 编码前的大小计算。
从 Files API 复制文件 每个文件最多 50 MiB。
发布产物 每个文件最多 200 MiB。
一起发布多个输出 总计最多 500 MiB。