文件与已发布的产物
文件存储在智能体的环境中。产物是从 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。 |