给编码助手发一句“修复这个报错”，演示时很容易看到它读文件、改代码、运行测试。把同样的能力放进产品里，开发者还要回答一些具体问题：用户关闭页面以后，任务在哪里；网络断开以后，是否应该重发；助手说修好了，下载到的补丁又属于哪一轮工作。
可以用一个小型工单修复服务来讨论 Agents API。用户提交错误说明，服务为它建立隔离工作区，助手尝试复现并修改，最后返回补丁与测试记录。这个范围足够小，也能暴露长任务接入时最常见的状态问题。本文依据 2026 年 9 月 23 日官方文档整理，流程设计为示例，没有声称运行过付费 API 或完成过真实工单。
先确定哪一部分由平台运行
Agents API 提供由 OpenAI 管理的 Codex harness，负责会话和执行编排等工作；应用配置工具，并选择执行环境。它与安装在自己应用里的 Agents SDK 是两条接入路线。已有成熟任务调度器、希望控制执行循环的团队，应同时比较 SDK；希望减少会话与执行基础设施维护的团队，可以从 Agents API 试起。运行方式比较
对工单服务而言，平台能够帮助助手持续工作，但工单编号、代码版本和验收结果仍归应用管理。例如工单 1042 针对提交 a1b2c3，用户后来补充了一个附件，应用必须知道这次补充属于原任务还是新的任务版本。不能只把工单全文拼成提示词，等最终回答回来后再寻找对应记录。
可以给每个业务任务保存工单编号、输入版本、目标代码提交、会话标识和产物记录。页面展示的“排队中”“运行中”“待查看结果”等状态，也由这些记录支持。这样用户刷新页面时，看到的是同一个任务，而不是重新创建一个助手。
会话与一轮工作要分开记录
官方文档中，session 可以持续保存配置和工作记录，turn 是其中一轮工作。向空闲会话发送消息会开始新一轮；在工作过程中发送消息，则用于引导当前工作。这种区别会直接影响产品交互。会话与轮次
假设助手正在排查登录错误，用户补充“Safari 也会出现”，这是对当前问题的补充。若用户又要求“顺便把支付页重写”，范围就发生了变化。应用可以提示把后一个需求单独建任务，或者明确增加新一轮，并保存更新后的验收条件。否则最终补丁混合两类改动，既难审查，也难判断原来的登录问题是否已解决。
数据库中的一个任务不一定永远只对应一轮，但每份测试记录和产物应当能追溯到具体轮次。比如第一次只复现了错误，第二次生成补丁，第三次根据反馈修改。列表页只显示最后状态，详情页仍应能查到前两次发生了什么。
为了让这种结构可用，先把任务输入整理清楚：复现步骤、预期行为、实际行为、运行版本和可修改范围。若没有复现资料，就让第一轮专门收集它。把缺失信息写成“已确认”，会让后面的测试针对一个想象出来的问题。
流式输出用于展示，完成判断要读结果
前端可以显示助手正在查看文件、运行命令和生成说明。不过连接收到最后一段文字，或会话进入 idle，都不足以证明修复成功。官方说明明确区分会话空闲与 turn 的完成、失败、取消；即使一轮完成，也可能包含失败的工具调用。事件与结果
工单服务可以采用两步验收。第一步检查本轮是否结束，并保存失败原因；第二步检查所需产物和测试证据。例如要求存在补丁文件、包含复现测试、运行了约定测试命令，并记录退出码。助手输出“测试环境缺少依赖”，应该展示为环境受阻，不能因为它同时写了一段修复建议就标为已解决。
更进一步，应当让独立的测试任务在指定代码版本上应用补丁并重跑关键用例。助手可以生成测试，但最终验收不宜只读取助手对自己的评价。尤其是修改了测试预期以后才变绿的情况，审查者需要看见测试本身的变化。
这里不必一开始就建立复杂评分体系。一组可复现工单已经很有用：包含一个确实能修的问题、一个资料不足的问题、一个依赖安装失败的问题和一个无须修改代码的问题。产品应能把这些结果清楚地区分开。
断线以后，先恢复视图
用户的浏览器断网，与远端助手停止执行，是两件事。若每次断线都重新提交原任务，可能重复安装依赖、重复改文件，甚至创建两个工单评论。前端应先通过已保存的会话标识找回工作状态。
当前官方恢复流程要求重新接入事件流并暂存新事件，同时读取会话和已保存 items，再按 item 标识合并。事件流不会把所有错过的中间事件重放一遍，不能把它当作永久日志队列。分页读取也不能只取第一页就宣布历史恢复完整。断线恢复说明
在应用侧，可以把显示中的临时文本与已完成条目分开保存。恢复时用最终条目替换临时内容，不要把两份文字直接拼接。这样用户不会看到同一段结论出现两遍，也不会把半截命令输出误认为完整测试报告。
业务动作还需要自己的去重规则。例如向工单系统回写评论时，保存目标工单、任务版本和已写入的评论标识；重试前先查询本地记录及目标结果。会话恢复解决的是继续工作，无法代替外部系统对重复写入的处理。
后台通知负责唤醒处理，不直接宣布成功
服务不一定需要始终保持流连接，可以接收 session webhook。处理端先按官方方式验证签名，再取回对应会话的当前状态。action_required 只告诉应用需要进一步处理，具体函数调用或环境连接信息需要继续读取。会话 Webhook
对于工单产品，通知处理器适合完成短小工作：记录收到的事件、提交一次状态同步任务，然后返回。补丁检查和测试可以放入应用自己的任务队列。这样通知入口的请求时长不会被一轮测试拖住，也方便对同步失败单独重试。
准备部署这个接收端和任务队列时，可以先使用独立的小型服务环境。Brnchost 的配置入口在下面；选型时按接收请求、日志保存和队列运行的实际需求核对资源。这里的服务器承担的是应用后端，具体 Agent 执行环境仍按 API 配置选择。
补丁文件必须属于这一次结果
在 OpenAI 托管环境中，可以把需要交付的文件写入 /workspace/outputs，完成轮次后以产物形式获取。自托管环境的文件则通过自己的文件系统或服务商接口取得，不能直接套用同一产物流程。文件与产物
下载时同时匹配轮次和路径。第二轮与第三轮都可能生成 fix.patch，只按文件名找“最新一个”容易取错。业务记录还可以保存文件摘要、对应基础提交和测试记录，让审查者知道补丁适用于哪个版本。
下载成功之后再进行清理。清理清单应分别列出会话、产物副本以及所用执行环境资源，按它们各自的生命周期处理；不要假定删除一个标识就释放了全部资源。保留在应用存储里的补丁和日志，也应有明确用途与保留周期。
第一版只交付一份能检查的修复结果
最小版本可以只支持一个仓库、一个隔离环境和一组固定测试，不自动合并代码。用户收到的结果应包括修改说明、补丁、测试命令与结果，以及仍未验证的部分。这样的输出足以判断它是否帮上忙。
试运行时记录每个任务从提交到可检查结果的时间、失败发生在哪个阶段，以及人工还需做多少修改。成本也按整件任务统计，包含模型、工具、环境和重跑，而非仅看一次请求。当前 SDK 入口和请求头等细节，以官方快速开始页面为准；示例跑通以后，再逐步增加工具和并发。快速开始
当用户打开工单 1042，能看到原来的报错、对应代码版本、这轮生成的补丁和真实测试结果，下一步如何处理就很清楚。把这条链路做完整，才有依据决定哪些修复可以进一步自动化。