把 Agents API 或 Codex 描述成“一个会自己干活的员工”，很容易让产品方向一开始就走偏。员工拥有相对稳定的身份、长期关系和组织授权；Agent 运行通常只是一个被调度的过程。它读到一部分上下文，调用若干工具，在某个环境里修改文件或提交结果，然后结束、暂停、压缩，或者被另一个运行接管。真正决定可靠性的不是一句更聪明的提示词，而是 harness（编排与控制层）和 environment（执行环境）之间的边界有没有被设计清楚。
这里的 harness，不仅是 SDK 外面包的一层循环。它负责把目标变成可执行的任务，把上下文装载进来，把工具暴露给模型，保存状态，处理中断，安排并行工作，汇总结果，并在最后执行验收。environment 则是 Agent 能看到和改变的世界：代码仓库、文件系统、网络、凭据、数据库、浏览器、容器以及操作系统权限。模型负责提出下一步行动，但 harness 决定它能提出什么、environment 决定这个行动会造成什么。产品责任因此不应落在“模型会不会像人一样工作”上，而应落在“控制层是否把每一个行动放进可解释、可回收的环境”上。
这个划分会改变工程团队的工作清单。过去做聊天产品，核心是请求、响应、上下文窗口和延迟；做长运行 Agent，核心变成状态机、权限图、工具契约、资源预算、恢复点、证据链和退出条件。模型换代可能提升局部成功率，但如果 harness 把过时的上下文继续塞进去，把危险工具和只读工具混在一起，或者让多个子代理无协调地写同一个目录，系统仍然会在生产环境里失控。
先把一次运行看成可恢复的工作流
一个合格的 Agent run 不应只是“发送 prompt，等待 final”。它至少要有 queued、running、waiting-for-approval、paused、compacting、failed、completed 等可观察状态。每次工具调用都要记录输入摘要、工具版本、权限范围、开始与结束时间、输出位置和验证结果。这样做不是为了给界面增加状态标签，而是为了让用户知道运行究竟停在了哪里：模型没有理解需求，工具不可用，环境权限不足，还是验收没有通过。
harness 还应把任务拆成可重放的步骤。比如一次“修复支付回调并补测试”的运行，可以先建立任务说明和约束，再读取相关模块，执行调查工具，生成计划，申请写权限，修改代码，运行定向测试，最后执行更宽的回归门槛。每个阶段都应该有明确的输入和输出。失败时可以从最近的安全检查点恢复，而不是把整个对话重新发送一遍。恢复点也不等于把所有历史消息原样保存；它更像一份带证据的工作账本。
上下文压缩不是摘要功能，而是记忆治理
长运行任务迟早会遇到上下文上限。上下文 compaction 的责任不是“把旧消息缩短”，而是决定哪些事实可以进入下一阶段，哪些细节必须丢弃，哪些结论必须保留原始证据。一个坏的压缩器会把“测试失败”压成“测试已处理”，把临时假设写成事实，或者遗漏用户后来修改过的约束。Agent 随后会非常自信地沿着错误记忆继续执行。
更可靠的设计是把运行记忆分层。第一层是不可变的任务契约，包括目标、禁止事项、权限和生产验收标准；第二层是当前状态，例如已经修改的文件、未解决的风险、待批准动作和剩余预算；第三层是可重新获取的材料，例如搜索结果、日志原文和工具输出；第四层才是对话性的解释。压缩时优先保留前两层，第三层留下引用、哈希或对象地址，第四层可以大幅缩短。任何“已完成”的判断，都应该能指向命令输出、测试报告或人工批准，而不是只存在于模型生成的摘要里。
工程上还要测试压缩本身。让一个运行在接近窗口上限时暂停，压缩后继续执行，再比较它是否仍然知道当前分支、修改范围、失败测试、用户禁令和回滚路径。验收不能只看压缩后文本读起来是否流畅，而要看关键不变量是否保留。对于付款、删除、迁移这类高风险任务，宁可触发人工复核，也不要让不完整的摘要成为授权依据。
工具加载决定能力边界
工具搜索和按需加载解决了一个实际矛盾：工具越多，模型越容易遇到冗余、冲突和错误选择；工具太少，Agent 又无法完成真实任务。harness 不应在每次请求里暴露整个工具目录。它应先根据任务和环境筛选候选工具，再把名称、参数、权限、副作用、超时和返回格式加载给模型。工具的描述不是营销文案，而是安全契约：明确它能读什么、写什么、会不会联网、是否幂等、失败后能否重试。
工具加载也会改变后端设计。每个工具应该有稳定的版本、结构化错误和可观测的调用记录；凭据应该由环境注入而不是出现在 prompt；只读搜索和写入工具应该在授权层分离。程序化工具调用可以减少模型在长文本中搬运数据的浪费，但这不意味着可以跳过策略检查。harness 仍然要在调用前检查资源范围，在调用后验证返回值，并对超过预算、改变外部状态或触及敏感数据的动作暂停。
并行子代理不是多开几个聊天窗口
并行 subagents 适合把相互独立的工作拆开，例如一个子代理检查现有实现，一个分析测试覆盖，一个阅读官方接口约束，主代理再根据结果形成改动方案。它不适合让几个子代理同时随意修改同一份生产代码。并行带来的收益来自独立观察和缩短等待，不来自无条件增加模型数量。
harness 需要为子代理定义任务边界、输入快照、输出格式和合并规则。只读调查可以共享仓库快照；写入任务应使用独立工作树、临时分支或隔离目录。主代理不能只接收一句“已完成”，而要收到结构化证据：发现了什么、看了哪些文件、运行了哪些命令、哪些判断仍是假设。合并前由一个协调步骤检查文件冲突、测试互相矛盾、依赖变化和权限升级。子代理失败时，系统还要区分“该子任务不可用”和“整个运行不可用”，不能因为一个搜索代理超时就丢掉已有的安全结果。
沙箱选择就是产品承诺
沙箱不是部署细节，而是用户购买的风险边界。只读本地工作区适合代码解释、依赖扫描和文档生成；可写但无网络的容器适合编译、测试和格式化；需要访问测试服务的隔离环境适合集成验证；能够触碰真实凭据、生产数据库或外部 SaaS 的环境则应当是极少数、可审计、带审批的例外。把所有任务都放在“功能最完整”的环境里，看似减少配置，实际上把最小权限原则放弃了。
环境选择应由任务分类驱动，而不是由模型自行决定。harness 可以先判断任务是否只读、是否需要网络、是否会写文件、是否会改变外部状态，再选择环境配置。沙箱需要有资源上限、网络出口策略、凭据短期租约、文件挂载清单和销毁规则。尤其要区分“模型可以看到的内容”和“进程可以访问的内容”：环境里存在的秘密不应因为某个工具能读取目录就自动进入上下文。日志也要避免把 token、个人数据或完整客户记录原样保存。
三个场景：同一个 Agent，不同的责任分配
场景一：修复一个开源仓库的回归。用户提交 issue，Agent 需要定位问题、改代码、补测试。默认环境应是隔离工作树、无生产凭据、网络关闭或仅允许依赖缓存。harness 先加载仓库规则和测试命令，允许只读调查；模型提出计划后才获得当前分支的写权限。测试通过并不等于可以合并，最终仍要输出 diff、测试日志和未覆盖风险，交给维护者审阅。这里的工程责任是保证变更可回滚、证据可复现，而不是让模型自动获得提交权限。
场景二：企业知识库问答与报告生成。任务主要是检索、筛选和引用，不应让 Agent 默认拥有全盘文件访问。harness 为每次运行生成租约范围，只加载与问题相关的检索工具，并要求答案中的关键结论关联文档来源和访问时间。若用户要求把报告写回知识库，写入应是单独的批准动作。上下文压缩必须保留权限范围和引用，不得把上一次运行看到的机密文档带进下一次会话。这里的产品承诺是可追溯和不越权，而不是“回答得像一个知道一切的同事”。
场景三：线上故障辅助处置。Agent 可以读取指标、日志和变更记录，并并行安排多个只读调查子代理；它可以提出回滚或扩容建议，但真实变更要经过明确的审批和预演。沙箱应连接观测系统而非直接连接任意生产 shell，所有命令都要经过允许列表和参数校验。遇到 compaction 时，当前告警、影响范围、已验证假设和禁止动作必须保留。这里的成功标准不是自动修复次数，而是缩短判断时间、减少误操作，并让值班工程师能接管。
把“能跑”改写成生产验收
生产验收应围绕 harness 与 environment 的交界处建立，而不是只测一个模型回答分数。第一，可靠性：运行被打断、工具超时、网络暂时失败、模型重试或上下文压缩后，能否从检查点恢复，且不会重复执行不可逆动作。第二，权限：每个工具是否遵守任务范围，秘密是否最小暴露，越权读写和跨租约访问是否被拒绝并留下记录。第三，证据：最终结果能否关联到具体工具调用、文件 diff、测试输出、审批记录和环境版本。
第四，并发：多个子代理是否使用隔离快照，冲突是否被发现，协调器是否能处理部分失败，成本和延迟是否有上限。第五，环境：沙箱是否真的限制了网络、文件挂载、进程和资源，销毁后是否没有残留凭据或临时数据。第六，用户体验：用户能否暂停、取消、批准、拒绝和接管；系统是否清楚区分模型建议、已执行动作和已验证结论。没有这些能力，所谓长运行只是把一个不可解释的黑盒运行得更久。
可以把验收写成一组必须通过的反例测试：在工具返回伪造的成功字段时，Agent 是否仍会检查真实状态；压缩摘要漏掉禁止事项时，harness 是否拒绝高风险动作；两个子代理修改同一文件时，系统是否阻止静默覆盖；网络被切断后，运行是否进入可恢复状态；一个子代理返回恶意指令时，协调器是否把它当数据而不是新权限；用户撤销授权后，旧租约是否立即失效。反例比一条漂亮的 happy path 更能说明产品是否准备上线。
团队应该怎样分工
模型团队可以优化推理和工具选择，但不应独自定义生产权限。平台团队负责状态、队列、重试、压缩、审计和成本控制；环境团队负责沙箱镜像、网络、凭据、挂载和销毁；应用团队负责任务契约、领域工具和验收器；安全与合规团队负责数据分类、审批策略和留痕要求。出了问题，要能回答是模型建议错了、harness 传错了上下文、工具契约不完整，还是 environment 给了过大的能力。
这也是 Agents API 产品设计最重要的取舍：不要把 Agent 包装成一个拥有无限自主权的数字员工，再用一层 UI 掩盖风险。应该把它做成一个有明确输入、有限能力、可暂停状态、可验证输出和可替换环境的运行时。模型越强，越需要清晰的控制面；工具越丰富，越需要严格的装载策略；任务越长，越需要可恢复的记忆；子代理越多，越需要协调与隔离。真正成熟的 Agent 产品，不是让人类退出系统，而是让人类只在最值得判断的边界上介入。