OpenAI Agents SDK:让工具暂停,才谈得上人工批准

把工具暂停、服务端状态与目标端结果接起来,避免批准后重复执行,也让审核决定有据可查。

Buda Team
← 返回博客
OpenAI Agents SDK:让工具暂停,才谈得上人工批准

工具调用、状态保存和审批恢复各有职责;把它们接起来,业务团队才能知道谁批准了什么、重试是否会重复执行。

OpenAI Agents SDK 提供了构建 Agent 应用的运行机制:模型接收指令,选择工具,多轮执行,必要时把任务交给另一个 Agent,并保留追踪记录。对准备把 Agent 用进业务系统的团队,关键选择并不只是“用什么框架”,还包括哪些动作可以自动继续、哪些动作必须暂停,以及中断后由谁恢复。

官方入门文档将 Agents、工具、交接和 guardrails 作为核心组成,也提供 sessions、tracing、沙箱和人工介入机制。SDK 是可编程的运行基础;真正进入业务流程时,团队需要把这些能力接到自己的身份、权限、持久化和目标系统上。

先决定是否需要 SDK 管理执行循环

直接调用 Responses API,适合由应用自己控制模型循环、工具调度和状态的情况。Agents SDK 则适合希望运行时管理多轮执行、工具调用、交接或会话的应用。两条路径可以在同一个产品里共存,无需把所有请求一次性迁移。

这项选择首先取决于团队希望维护什么。只有短暂回答的功能,未必需要复杂编排;会跨多个步骤、使用真实文件或生成产物的任务,则更需要明确的运行状态与恢复机制。开发框架可以降低重复实现的成本,但任务的业务终点仍要由应用定义。

例如,“工具返回成功”和“业务记录已按预期更新”并非同一件事。前者是一次调用结果,后者需要目标系统的确认。把两者写成同一个完成标记,会让后续的重试和审核变得含混。

三种机制,各自回答不同问题

工具定义决定 Agent 可以调用什么;guardrails 用于检查输入、输出或相关约束;审批决定某次敏感动作是否获得允许。三者应分别配置。

三种机制,三种职责

官方人工介入指南允许工具声明需要审批。符合条件的调用会以 interruption 暴露,应用把运行转为 RunState,取得批准或拒绝后再恢复。这个机制可以覆盖交接后的工具,也可以覆盖嵌套 Agent 工具内部产生的审批。

只在提示词写“发送前询问”,并不等于工具调用在执行层被阻断。需要审批的动作,应在工具或运行策略中配置实际暂停条件,再由应用处理待审请求。与此同时,通过参数校验也不意味着业务负责人已经同意。

工具能力、检查和审批在执行中承担不同职责

审核界面展示请求,可信状态留在服务端

当任务暂停,审核者需要看见动作对象、工具参数、预期影响和相关依据。完整运行快照可能包含执行状态、待处理调用和敏感参数,适合留在应用控制的服务端存储中。

官方指南特别指出,RunState 的反序列化不会替应用验证提交者身份。收到一份格式正确的状态,不等于它来自有权批准的人。服务端应验证审核者身份,确认其有权处理当前运行,再把提交的决定与服务端保存的待审调用对应起来。

浏览器可以传回决定和请求标识,不能让浏览器替换工具参数或整份运行状态。显示工具名和参数时,也要当作待转义内容处理。这样,界面负责表达决定,运行时负责恢复执行,身份与权限仍由应用控制。

多个人同时打开同一请求时,还要避免重复消费。一个人已经批准并开始恢复后,另一个旧页面不应再次恢复同一份快照。需要的是存储层能确认归属和当前状态的原子转换,而不是仅把按钮变灰。

批准一次,不等于只执行一次

最容易漏掉的故障发生在外部动作已经完成、最新运行状态尚未保存的时候。进程此时中断,如果从较旧的已批准快照恢复,工具可能再次调用。

批准之后,仍有重复执行窗口

官方文档明确区分审批与 exactly-once 执行。对付款、发送消息或业务写入,应给逻辑动作一个稳定的幂等键,并让目标端按其契约防止重复效果。重试时复用同一个键和相同参数,同时注意目标端的保留期限。

如果目标系统没有可靠的幂等机制,恢复前先核对实际结果。普通查询未返回结果,不一定说明上次没有执行:结果可能延迟可见,旧请求也可能仍在运行。无法判定时应保留未知状态,交给有权的人处理,而不是自动重放。

这也决定了审核页面需要展示什么。除了“已批准”,还需要“是否已调用”“目标端是否确认”“结果是否确定”。把决定和执行结果分开,运营人员才知道下一步该补证还是重试。

长期批准要匹配权限边界

SDK 支持针对单次调用的决定,也支持在运行状态中保留后续同类工具的持续批准。持续批准可以减少重复交互,却需要理解匹配范围。

官方指南指出,本地 shell 和文件编辑工具的持续决定按工具类型和名称匹配,未必按拥有它的 Agent 隔离。在不同执行器权限不一致时,应优先使用逐次决定,并在新的权限环境中使用新的审批上下文。不能因为两个工具名称相同,就默认它们有相同的访问范围。

长期等待的审批还应记录 SDK 或 Agent 定义版本。恢复发生时,旧快照需要能够进入匹配的代码路径;否则,模型配置或工具定义变化可能让原请求失去原来的含义。

从开发机制走向团队交付

可以用 Buda 搭建围绕真实资料和成果审核的工作流程:先在 Agent 中准备文件、约束和输出要求,执行后检查实际产物,再授权下一步动作。工作空间和 Drive 与记忆承接资料和持续上下文。是否采用 SDK 自建应用,应由产品需要控制的运行机制与团队维护能力决定。

如果要自行开发审核服务,先做一条能完整走通的路径:待审工具调用进入服务端存储;有权限的人批准或拒绝;原运行恢复;目标系统回传结果;结果再写回同一任务。最后检查进程中断、重复提交和拒绝后的分支。一个漂亮的批准按钮,只是这条路径中的一环。

两个常见实现决策

tracing 能否替代业务审计?

追踪有助于调试执行路径。业务审计还需要身份、批准范围、动作参数、目标端结果和最终状态。把运行追踪与业务任务关联起来,保留两者各自的职责。

每次工具调用都要人批准吗?

按动作影响与既有授权划分。已授权的低风险读取可以自动继续,敏感写入或外部动作按工具策略暂停。重点是让规则在执行层生效,并能解释一次动作为什么获得允许。