OpenAI 负责运行智能体的执行框架。您的应用向执行框架提交任务并接收结果。智能体需要计算资源或文件时,请为其添加环境。
架构组成
- 执行框架: 由 OpenAI 托管的 Codex 实例,负责循环调用模型和工具,并维护智能体的会话。
- 环境: 智能体在这里运行命令、执行代码和处理文件。环境可以是远程沙盒、您的笔记本电脑、Docker 容器或 AWS Lambda 函数。
- 应用服务器: 由您编写的代码,负责将智能体接入您的产品。它提交任务、接收事件并处理函数工具调用。如果您提供环境,这些代码还负责管理环境的生命周期。
先根据任务需要选择组件。执行框架无需环境也能工作,您的应用可以通过事件流或 Webhook 接收进度更新。
在不配置环境的情况下开始使用
如果智能体负责回答问题或通过工具访问外部服务,它可能无需自己的计算资源或文件。将 environment.type 设为 none。以下片段展示了环境配置。创建会话时还需指定智能体并提供初始输入:
{
"environment": {
"type": "none"
}
}
您的应用向会话发送输入。执行框架调用模型、使用已配置的工具并返回结果。OpenAI 会维护该会话,以便后续继续执行任务。
执行框架可以直接调用远程 MCP 工具。对于函数工具,您的代码会接收每次调用、执行相应函数并返回结果。
未配置环境时,智能体无法使用内置的 Bash 和 apply-patch 工具、工作空间中的文件或执行器提供的 MCP 服务。

图中的虚拟运行时是可选的。它通过您应用中的函数工具提供文件和 shell 命令。
添加由 OpenAI 托管的环境
当智能体需要运行脚本、编辑文件或生成产物时,请将 environment.type 设为 openai_hosted。OpenAI 会为该会话创建并管理沙盒。
您负责配置智能体所需的软件包、文件和网络访问权限。执行框架直接在沙盒中运行命令。您的应用继续提交任务、接收事件,并处理函数工具调用。

图中的虚线箭头仅适用于您自行管理环境的情况,详见下文。
有关配置选项,请参阅由 OpenAI 托管的环境。
连接您自己的环境
当智能体需要使用您的基础设施、专用网络或定制软件时,请使用 environment.type: "self_hosted"。
您的代码负责启动环境并将执行器连接到会话。执行器根据执行框架的请求运行命令和工具。您的应用负责管理连接和环境的生命周期,无需逐条转发命令。
您负责编配计算资源、重新建立连接、关闭环境,并保存需要保留的文件。这些工作可以由您的应用服务器或 Webhook 处理程序完成。

停止计算资源前,请协调好新任务的接收与处理,并确认没有尚待执行的操作。
接收进度更新和结果
无论如何配置环境,您都可以单独或同时使用以下两种方式:
- 流式传输: 在智能体执行任务时接收详细事件,例如携带输出内容的事件。您可以在产品中显示这些输出。
- Webhook: 无需保持事件流开启,即可接收会话状态变更通知。您的处理程序可以获取结果、运行函数工具或管理自托管环境。
函数工具需要由处理程序接收调用并返回结果。如果处理程序不可用,智能体可能会一直等待结果。事件处理程序或生命周期处理程序发生故障,也可能导致进度更新或环境管理中断。