把一个能连续运行、会调用工具、可以拆分任务的 Agent 放进生产系统，真正困难的部分通常不是发出第一条请求，而是让它在第十分钟、第二次失败、权限不足和上下文变长之后，仍然可控。OpenAI 的 Agents API 值得关注的地方，正是它把一部分原本需要应用团队自己维护的执行基础设施，包装成了面向 API 的托管 harness。
但“托管 harness”不等于“自动员工”。它可以管理一段长任务的会话、编排和恢复，也可以让 Agent 在沙盒里操作文件、执行代码或连接工具；它不能替你决定一个工具是否有资格改生产数据库，不能替你定义什么叫完成，更不能替你承担错误调用带来的业务责任。评估 Agents API，应该先评估 harness 的边界，再评估模型会不会写出一段漂亮的回答。
围绕这次发布的中文介绍，混合了公告信息、文档能力和未被当前官方文档充分确认的宣传性说法。分层很重要，因为一旦把“有人这样介绍过”写成“平台已经保证”，后面的架构决策就会建立在错误前提上。
官方文档当前明确描述的能力包括：Agents API 让应用通过 OpenAI 管理的 API 使用 Codex harness；官方概览强调，平台负责会话、编排、上下文压缩与恢复，而应用仍需提供工具并选择执行环境。文档也把沙盒中的代码执行、文件编辑、MCP 连接和产物生成作为工作方式来介绍。这些可以作为架构讨论的事实起点，但不代表每个工作负载都天然具备相同权限或可靠性。
源文章还把工具按需发现、程序化工具调用、子代理并行和不同沙盒提供方式放在一起介绍。这些方向与长任务 Agent 的工程设计相符，也可以用来形成验证清单；可是具体接口、可用范围、并发上限和合作方名单会随文档变化，不能因为文章里出现了一个数字或代码片段，就把它当成稳定契约。
同样需要明确：源文章提到过的模型名称、客户指标、公测状态、价格和“已经被大规模验证”等结论，在没有对应官方文档、公告或定价页证据前，不应写进采购评估、预算模型或上线承诺。生产设计只依赖可验证的接口和行为，不依赖标题里的确定语气。
可以把 Agent 系统拆成四层。最底层是模型推理；上一层是工具协议和执行器；再上一层是 harness，负责把输入、工具结果、子任务和状态组织成持续运行的过程；最外层才是你的业务应用、用户权限、审批和数据系统。传统聊天 API 往往只给你第一层加一点工具调用，长任务系统则必须自己补齐后面几层。
Agents API 的价值，在于把部分中间层交给服务端维护。会话不再只是客户端内存里的消息数组，长任务也不必完全依赖一个永远不变的上下文窗口。上下文接近限制时，系统可以做 compaction，把早期过程压缩成继续工作所需的状态；出现中断时，文档所说的 recovery 思路也意味着执行过程不必每次从零开始。对开发团队而言，这能减少大量胶水代码。
然而，压缩不是记忆的同义词。压缩结果可能保留结论，却丢掉一个关键的反例、一次工具报错或一项尚未完成的约束。因此，业务系统不能只依赖模型上下文保存事实。订单号、审批状态、迁移版本、测试结果、外部系统的幂等键，都应该写进自己的状态存储，并把可恢复的阶段做成明确的状态机。
一套可落地的最小架构，可以分成五个组件：任务入口、Agent 编排层、工具网关、隔离执行环境和审计系统。任务入口只负责鉴权、限流、创建任务和返回 task_id，不要让浏览器直接获得任意工具权限。编排层调用 Agents API，维护业务状态、超时和重试策略，并把每次运行关联到用户、租户和版本。
工具网关是最容易被低估的一层。不要把内部 SDK 原样暴露为一个名叫“执行任意操作”的工具，而要把动作拆成窄接口，例如 query_invoice、create_draft、run_test、request_deploy。每个工具都应校验调用者、租户、资源范围、参数格式和幂等键。工具返回给 Agent 的内容也要设上大小上限，日志和大文件应放在受控存储中，只返回摘要与引用。
隔离执行环境负责承载代码、文件和依赖。沙盒不是权限系统的替代品：容器、虚拟机或第三方执行环境都必须明确网络出口、文件挂载、凭据注入、CPU、内存、磁盘、进程数和生命周期。默认应当是临时、最小权限、无生产凭据。需要访问内部服务时，优先通过带审计的窄代理，而不是把整张 VPC 或一枚高权限令牌塞给 Agent。
审计系统至少记录输入任务版本、模型和工具配置、每次工具调用、参数摘要、审批决定、执行环境、结束原因、资源消耗与最终产物。不要把所有原始内容无差别写入日志；对个人信息、密钥和业务机密做脱敏或分级存储，同时保留足以重放决策的结构化记录。
长任务最常见的误解，是把“能持续工作”理解成“应该让它一直自主工作”。生产系统需要为每个任务规定预算：最长墙钟时间、最大步骤数、最大工具调用次数、最大并发子代理数、输入输出字节数和费用上限。任何一个预算耗尽，都应进入可解释的暂停或失败状态，而不是继续重试。
建议把任务状态设计成 queued、running、waiting_for_approval、paused、succeeded、failed、cancelled 等有限状态，并把状态迁移写在数据库里。进程崩溃后，恢复逻辑只重新执行没有确认完成的阶段；对外部副作用必须使用幂等键。这样，harness 的 recovery 负责恢复执行上下文，你的系统负责保证业务动作不会因为恢复而重复扣款、重复发货或重复部署。
上下文压缩也需要自己的测试。准备一组会持续产生工具输出的任务，检查压缩前后是否仍保留验收条件、失败原因、未完成事项和关键标识。不要只测最终答案是否通顺，要检查 Agent 是否还能引用正确文件、继续同一事务、识别已经执行过的动作。对于不可压缩的事实，直接放到外部状态中，并在每个阶段重新读取。
工具调用不是能力列表，而是权限面。搜索工具通常是低副作用动作，读取内部客户数据已经需要更严格边界，发送邮件、修改配置、删除资源和发布代码则属于高副作用动作。把它们都放在同一个 Agent、同一个凭据和同一个批准策略下，等于把最低风险任务升级成最高风险系统。
工具定义应包含用途、输入约束、可访问资源、可能的副作用和失败语义。返回值也要告诉 Agent 哪些字段是事实、哪些是估计、哪些需要人工确认。对于批量操作，优先提供 dry_run 和 preview；对于不可逆操作，要求显式确认；对于可逆操作，保留 undo 或补偿事务。工具错误不能只返回“失败”，还要区分参数错误、权限错误、临时故障和业务拒绝。
// 伪代码：具体字段以当前官方文档为准\nconst task = await createAgentTask({ goal, tenantId, policyVersion });\nconst plan = await runAgent(task, { tools: ["read", "test", "draft"] });\nif (plan.requestsSideEffect) {\n await savePlanForApproval(task.id, plan.summary);\n return { status: "waiting_for_approval", taskId: task.id };\n}\nconst result = await executeApprovedSteps(task.id, plan.steps, { idempotencyKey: task.id });\nreturn verifyAndRecord(task.id, result);
下面的示例只是控制逻辑伪代码，不是某个具体 Agents API SDK 的可复制调用；实际字段和接口必须以当前官方文档为准。它把“先计划、再审批、后执行”的边界固定下来：
子代理适合把互不依赖的研究、代码审查或资料整理拆开，每个子任务拥有更窄的上下文，最后由主 Agent 汇总。它也会带来更多提示词、工具调用、结果合并和失败分支。并行数增加，延迟不一定线性下降，成本、限流和结果冲突却很可能一起上升。
真正使用 subagents 前，先定义拆分规则：哪些任务可以并行，哪些任务必须共享最新状态，谁有权写文件，谁只能读，主 Agent 如何判断两个子结果矛盾。代码修改不宜让多个子代理直接编辑同一工作区；更安全的做法是让它们产出建议、补丁或审查报告，由单一执行器合并并运行测试。
汇总阶段要防止“多数投票式正确”。三个子代理读到同一个错误数据源，不会因为结论一致就变成事实。为每个子结果保留来源、时间、工具调用和置信边界；涉及安全、财务和合规的结论，应由规则或人工审核，而不是由主 Agent 根据语言流畅度挑选。
沙盒边界至少要处理三种不信任。第一种是不信任代码：脚本、依赖安装和命令都应该在隔离环境内运行，限制网络、资源和文件范围。第二种是不信任输入：网页、工单、仓库 README 和外部 MCP 返回的文本都可能包含提示注入，工具返回的内容应被当作数据，不能获得改变系统规则的权限。第三种是不信任结果：Agent 说测试通过、文件已修改、漏洞已修复，都必须由独立工具验证。
托管沙盒、自选合作方环境和自托管执行器之间没有绝对的“最好”。选择时要问：数据能否离开指定区域，谁管理基础镜像，能否接入现有身份系统，网络出口是否可审计，故障时能否拿回文件，日志保留多久，是否能满足合规要求。源文章列出的环境和供应商只能作为线索，最终以当前官方文档和合同能力为准。
普通 API 监控常看请求成功率和延迟，长任务 Agent 还需要观察步骤级指标：平均工具调用数、每一步耗时、重试次数、上下文压缩次数、等待审批时长、子代理扇出数、沙盒资源峰值、取消率和达到预算上限的比例。按任务类型、租户、工具和版本切分后，才能知道问题来自模型、编排、工具还是环境。
为每次运行生成 trace_id，并让它贯穿会话、子代理、工具网关和沙盒。关键事件采用结构化格式，至少包括事件时间、任务状态、工具名称、结果类别、策略版本和幂等键。对于长任务，保留阶段性 checkpoint 和最终产物引用；不要只保留最后一条回答，否则无法解释中途到底发生了什么。
质量指标也要从“回答像不像人”换成业务验收：测试通过率、人工返工率、错误副作用率、计划被拒绝率、恢复后重复执行率、证据完整率。上线前建立一批固定任务，用同样的工具和数据回放，比较新版本的成功率、成本和风险。没有基准集，平台升级后的“变聪明”就无法被验证。
Agent 的成本不是一次模型调用的价格。一个任务可能经历多轮上下文、若干工具结果、子代理、重试、沙盒运行和人工等待。应该按任务计算总成本：模型输入输出、工具调用、执行环境、日志存储、外部服务以及失败重跑。把这些成本关联到业务结果，才能判断它是节省了人工，还是只是把人工工作换成了不可预测的云账单。
预算控制可分三道闸：任务创建时给出硬上限，运行中在每个阶段检查已用量，超过阈值就暂停；租户层限制并发和每日额度；异常增长触发熔断和告警。不要用无限重试掩盖工具不稳定，也不要让子代理数量由模型自由增长。对于低价值任务，先用只读工具、短上下文和小预算验证收益，再逐步开放。
源文章中的价格描述、公测状态和客户节省比例，不能直接作为预算依据。上线前应从当前官方定价、账户控制台和实际试跑账单获取数据，并把模型、工具和环境价格写入可替换的成本配置。价格会变，任务的验收标准和预算上限不应该跟着宣传文案漂移。
审批设计得不好，会在两个极端之间摇摆：要么每个读取动作都要求人确认，导致系统没人愿意用；要么所有副作用都自动执行，直到事故发生。更合理的做法是按风险分级。只读和可重复的动作可以自动化；写入草稿、创建临时资源需要策略检查；生产发布、删除数据、发送外部消息和改变权限必须显式审批。
审批请求要展示计划而不是一句“是否继续”：目标资源、变更前后差异、工具和参数、影响范围、预计成本、回滚方式、证据链接和有效期。批准应绑定任务版本与幂等键，计划发生变化就失效。人工批准也不是盲签，审批人应该能看到 Agent 的依据和验证结果。
上线前可以分四阶段。第一阶段是只读试验：只开放搜索、读取和测试工具，记录真实任务的成功标准，观察上下文压缩、工具失败和任务取消。第二阶段是沙盒写入：允许它在临时分支、临时数据库或一次性工作区中产生文件和补丁，强制资源配额并验证恢复不会重复执行。
第三阶段是受控副作用：只开放少量经过审计的写入工具，配合 dry-run、人工审批、幂等键和回滚，为每个工具演练超时、重复请求、权限变化、脏数据和下游不可用。第四阶段才是小流量生产：限制租户、并发和预算，设置自动熔断，每天复盘任务轨迹和业务指标，确认退出机制能够执行。
常见失败模式包括：接口返回 200 但只完成部分业务记录；网络超时导致恢复重试而重复扣款；上下文压缩丢掉“不能接触客户数据”的约束；子代理把未经验证的猜测写入共享文件；沙盒限制了代码但高权限 MCP 工具仍能把数据发到外部；监控只报任务失败而无法区分模型、工具、环境和审批问题。解决这些问题，依靠的是业务确认、幂等键、外部状态、工作区隔离、网关策略和结构化轨迹，而不是提高重试次数。
Agents API 适合减少长任务 Agent 的基础设施负担，尤其适合不想从零实现会话管理、上下文压缩、工具编排和恢复逻辑的团队。它不适合被当作安全策略、业务工作流和验收体系的替代品。越接近生产副作用，越应该把 Agent 降级为“提出计划和执行低风险步骤的组件”，而不是授予它模糊的全能权限。
判断是否上线，不要问“它像不像一个员工”，而要问六个更具体的问题：它的每一步能否追踪？失败后能否恢复且不重复副作用？工具权限能否收窄？沙盒和数据边界是否清楚？成本是否有硬上限？高风险动作是否有可审计的审批和回滚？这六个问题没有答案时，换一个模型名称、增加几个子代理或引用一组漂亮的客户数字，都不会让系统更接近生产。
真正成熟的 Agent 不是永远自主，而是在明确的边界里持续推进；不是把所有决策交给模型，而是让模型的判断经过工具、规则、证据和人的共同约束。把 harness 当作执行底座来评估，才是把一次发布消息转化为可靠工程方案的起点。延伸阅读：Agents API 官方文档与 OpenAI 官方公告。接口字段、模型可用性、沙盒选择、价格和发布阶段应以当前官方页面为准。