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

沙盒生命周期

启动、重新连接和停止智能体的环境。

智能体的环境停止后,会话仍可继续存在。您的应用负责管理 self_hosted 环境使用的计算资源和文件。

启动环境

创建会话后,您的应用可以使用提供商的 SDK 或 API 启动计算资源,然后使用该会话的环境 ID 和一个环境密钥连接执行器。

请参阅 OpenAI Cookbook 中由应用管理沙盒的示例。

应用发送输入、接收事件,并控制提供商的计算资源。沙盒执行器主动连接到 Agents API,然后通过该连接交换命令和结果。

每个会话的环境应由一个组件负责管理。请保存会话与提供商计算资源之间的映射关系,并确保重复或并发请求不会创建重复的环境。

通过 webhook 启动计算资源

您也可以等到处理输入需要连接环境时再启动计算资源。API 会先发出 agent.session.action_required 事件,其中包含 required_action.type: "environment_connection",然后等待执行器连接。您的 webhook 处理程序负责启动或重新连接环境。

请参阅 OpenAI Cookbook 中通过 webhook 管理沙盒的示例。

应用向 Agents API 发送输入并接收事件。webhook 控制器验证连接请求,检查当前会话,然后启动或重新连接提供商的沙盒。沙盒执行器主动建立出站连接,并通过该连接交换命令和结果。

按照 webhook 设置说明注册处理程序,以接收 agent.session.action_required 和 agent.session.failed 事件。请将处理程序的签名密钥和会话读取凭据与执行器的环境密钥分开管理。如果多个提供商的处理程序共用一个项目,请将事件路由到负责相应会话的处理程序。

处理程序和后台工作进程分别负责以下步骤:

  1. 验证并加入队列。 处理程序验证 webhook 签名。仅当 data.required_action.type 为 environment_connection 时,才将连接请求加入队列。会话失败事件也要加入队列。只有成功入队后,才能返回表示成功的 HTTP 响应。
  2. 检查当前状态。 后台工作进程获取会话信息。忽略已删除的会话和已解决的操作请求。如果自托管会话仍需要连接,请使用 session.environment.id 和 session.environment.remote_url 启动或重新连接其执行器。如果会话仍处于失败状态,请释放其计算资源。

在会话事件流中,同一请求以 agent.session.requires_action 事件的形式出现。如果所需操作为 function_call,则需要提供函数调用结果,无需启动环境。等到收到轮次创建事件或 agent.session.in_progress 事件时,再启动离线执行器就已经太晚了。

部署处理程序后,请创建自托管会话并发送输入。请确保工作目录与处理程序中的配置一致,并满足处理程序中配置的所有智能体筛选条件。如果执行器在截止时间前建立连接,原先提交的输入将继续得到处理。

保持环境可用或停止环境

您可以让计算资源在轮次之间持续运行,以便复用,也可以在一个轮次结束后留出一段宽限期,再停止计算资源。请根据新到的任务协调停机。一旦收到连接请求或任务开始执行,就取消尚未执行的停机操作。停止计算资源前,请再次检查状态。

仅凭空闲事件无法判断是否可以安全停机。连接请求解除后,等待中的输入可能尚未开始新一轮执行,此时就可能收到空闲事件。如果您的应用无法根据新到的任务协调停机,请保持环境运行。

断开后重新连接

连接事件用于报告状态。您可以通过 agent.session.environment.connected 和 agent.session.environment.disconnected 观察连接状态。建立连接时,API 也可能发出 agent.session.environment.pending 或 agent.session.environment.failed。这些事件不会请求计算资源。请在所需操作为 environment_connection 时启动计算资源,并单独检查提供商的运行状况。

如果连接在轮次中途断开,即使该轮次最终完成,工具调用也可能失败。请检查工具结果和智能体的最终回复。断开连接不会自动通过 webhook 请求重新连接,也不会重新启动已被终止的命令。后续输入可以触发重新连接请求。

处理输入时,API 最多等待 5 分钟以建立连接。请根据这段等待时间设置客户端和代理的超时时间。如果等待超时,本次提交就会失败。初始输入可能在提交后异步失败,使会话停留在 failed 状态。

进程崩溃后,API 无法保证恢复待处理的输入。重试前,请检查请求或会话的处理结果。原请求仍在等待时,请勿重复提交。超时后才建立的连接不会重新执行已超时的输入。

复用环境 ID 无法在新的计算资源上恢复原有文件。请使用提供商的存储服务或快照保存这些文件。

清理资源

停止接收新输入。执行清理时,请与已在进行的启动操作做好协调,以免清理后仍有计算资源在运行。

请删除会话,并单独停止提供商的计算资源。删除会话不会停止其环境,也不会触发会话删除 webhook。