managed_agents/ 的 notebook 比 Agent SDK 多出大量资源名：agent、environment、session、resource、memory store、vault、thread、event 和 outcome。把它理解成一套更方便的 Agent API，会看不出这些对象为何需要单独存在。

它们共同解决一个问题：Agent 执行会跨越多个模型请求、工具进程、人工审批和服务重启，谁保存这段工作的权威状态？Managed Agents 的回答是由控制面保存。模型可以停，事件流可以断，执行沙箱也可以换；session 的状态、待处理动作、版本和历史事件仍然存在。

Environment、Agent 和 Session 被拆成三种资源

最基础的 failing-tests 示例先创建 Agent，再创建 Environment，上传代码文件，最后创建 Session 并挂载文件。三者的生命周期不同：

• Agent 保存模型、prompt、工具和多 Agent 配置；
• Environment 规定代码在哪里执行、网络如何开放；
• Session 保存某次任务的消息、文件状态、工具事件和运行状态。

这个拆分使同一个 Agent 可以在多个隔离环境和会话中运行，环境也可以在不改 prompt 的情况下从云端沙箱换成自托管 worker。文件不必复制进 prompt，而是作为 resource 挂载到 session 文件系统；生成的报告也作为 artifact 取回。

这和普通 tool use 的差异不在模型会不会调用 read、bash，而在工具执行已有独立生命周期。session 进入 running、idle 或 terminated，应用围绕状态变化做恢复、审批和回收，不必靠某个一直在线的 Python 循环记住“现在执行到哪了”。

流式输出不是事件记录

Managed Agents 同时提供预览 delta 和持久事件。前端示例收到 event_start、event_delta 时拼出正在生成的文本；完整的 agent.message 落入事件日志后（服务端在消息完成时正式提交的记录），再撤掉预览。

这两条通道不能混为一谈。delta 为界面提供低延迟，但不会持久化，断线期间可能错过；buffered event 才是权威记录。前端重连时先重新获取事件日志，再接上 SSE 尾流，按事件 ID 去重，并以日志顺序为准。

这个细节适用于所有流式 Agent 产品：屏幕上出现过的字不等于系统已经保存了它。若把 preview 当作历史，断线、重试和错误请求会留下重复文本或半句话。显示状态可以暂时不一致，账本只能有一个。

Human-in-the-loop 是暂停协议

CMA_gate_human_in_the_loop.ipynb 的费用审批 Agent 调用 decide() 或 escalate() 时，工具不会在沙箱内直接执行。session 发出 agent.custom_tool_use，随后进入 idle，停止原因为 requires_action。应用记录决策或等待人工审核，再发送对应的 user.custom_tool_result，session 从原位置继续。

Agent 调用 escalate
→ session: idle / requires_action
→ 应用展示审批、等待人工输入
→ 写回 custom_tool_result
→ session 恢复执行

如果执行 decide，外部服务器直接执行工具。相对于直接给工具设定审批hook，escalate 适用于 大多数低风险案例自动处理，只把模糊案例交给人。

人工思考几分钟甚至几天时，不需要维持一条 HTTP 连接。开发阶段可以在本地 stream 中即时处理；生产阶段监听 session.status_idled webhook，验证签名、查找待处理事件，审核完成后再写回结果。

这比“让模型先问用户”更可靠。暂停状态和待回复的 tool-use event ID 都由平台保存，业务系统可以审计谁批准了什么。并行工具调用还暴露了工程细节：待处理 ID 可能分批出现，处理器必须记录已经回复的 event ID，避免重复提交同一结果。

custom tool 也是控制面与私有系统之间的边界。沙箱访问不到内网数据库时，Agent 发出请求，由应用在自己的权限域内执行。这样密钥和审批规则无需进入沙箱。

多 Agent 的主要收益是隔离原始材料

CMA_coordinate_specialist_team.ipynb 给 coordinator 配置三个 specialist，每个角色拥有不同工具。价格 Agent 只能读规则文件，无法上网抄竞争对手价格；检索 Agent 读取大量案例，原文留在自己的 thread，coordinator 只收到提炼后的结果。

CMA_plan_big_execute_small.ipynb 进一步把这种隔离用于成本控制：昂贵模型只负责拆题和综合，便宜 worker 并行读取网页。示例运行中，两种方案读取量接近，但分工方案约便宜 2.5 倍、快 3 倍，84%—98% 的输入 token 按 worker 价格计费。这不是“多 Agent 天然更便宜”的结论，只适用于少量判断加大量可并行阅读的任务；探索性搜索若依赖强模型不断调整方向，差距会缩小。

这个实验还有一个值得保留的做法：它给单 Agent 对照组施加相同验证标准。若 solo Agent 少读来源，成本更低只是因为完成了较弱的任务。比较 Agent 架构时，必须固定覆盖率和证据要求，不能只比账单。

多 Agent 配置本身也有脆弱处。coordinator 的 roster 会固定子 Agent 版本，但它看不到子 Agent 的 prompt、描述和真实能力，只能依据自己的 system prompt 理解角色。如果 coordinator 认为某 worker 会搜索，而该 worker 实际没有搜索工具，平台不会自动发现两份定义冲突。角色说明与角色配置仍需共同测试。

Outcomes 把“完成”变成独立判断

普通 Agent 通常自己决定何时结束。CMA_verify_with_outcome_grader.ipynb 增加一个独立 grader：writer 每次提交研究简报后，grader 在新的上下文中读取 artifact，按 rubric 检查覆盖项和引用；失败原因返回 writer，writer 修改后再次送审，直到通过或达到迭代上限。

示例 rubric 没有只写“检查需求电费和公司财务”，而是要求需求电费必须出现美元每千瓦或运营成本占比，上市公司数据必须来自 10-K 或 10-Q，引用 URL 必须能够直接读取，原文引语必须逐字匹配。第一次草稿覆盖五项，第二次虽然换成 sec.gov，引用的仍是 8-K 中的新闻稿附件；第三次找到真实 10-K 后才通过。

grader 有独立上下文，因此不会沿用 writer 对来源的印象。但独立不等于客观。rubric 写得宽松，grader 会轻易通过；写成不可执行的步骤，grader可能根本无法验证；写得过严，则会反复修改直到耗尽迭代次数。Outcomes 把终止条件从 writer 的自我判断中分离出来，同时把质量上限交给 rubric 作者。

Prompt 版本化把发布动作从代码部署中拆出

Prompt versioning 示例创建 v1，跑标注集，再用 agents.update 生成不可变的 v2。v2 加入一条过宽的路由规则，导致 billing ticket 被分到 API 团队。回滚时不用重新部署应用，只需让新 session 再次固定到 version 1。

这里有一个容易忽略的风险：传裸 agent ID 会自动使用最新版本，任何能调用 update 的身份都可能让下一批 session 立即采用新 prompt。平台没有替你完成代码评审。更稳妥的方式是生产调用始终固定版本号，把“生产当前指向哪个版本”作为受审配置；创建新版本只是实验，修改生产 pin 才是发布。

Prompt 脱离代码后，回滚更快，但治理没有消失，只是从代码 diff 转移到版本、测试集和流量配置。没有固定评测集，版本号只能告诉你发生了变化，不能告诉你变好了。

自托管沙箱仍由托管控制面调度

self-hosted sandbox 示例把工具执行放到 Docker、Modal、Daytona、Vercel 或 Cloudflare。控制面发送 session.status_run_started，worker 领取 work item，在每个 session 的隔离环境中执行 bash、read、write 等工具，持续发送 heartbeat，并把 tool result 写回 session。

自托管的含义不是把整个系统搬回本地。session 和工作队列仍由平台管理，用户只接管执行面。environment key 同时用于领取任务、确认、heartbeat、读取事件和下载 skill；组织 API key 不进入 runner。若直接在主机上运行 worker，工具也会直接操作主机，所以文档明确建议把它放进容器或其他隔离边界。

工作队列和 lease 比具体云厂商更值得借鉴。webhook 只负责唤醒，worker 随后主动 drain 队列，可以补回早先漏掉的通知；heartbeat 表示任务仍被占用；进程退出时需要停止或释放 work item。只靠“收到 webhook 就执行一次”无法处理重复通知、通知丢失和执行进程崩溃。

托管运行时的重点是边界可恢复

Managed Agents 没有发明新的推理方式。它把 Agent 周围最容易散落在应用代码里的状态收成协议：

• artifact 和 session event 是可恢复的任务记录；
• idle / requires_action 是可持久的暂停点；
• thread 隔离子 Agent 的上下文和工具；
• Outcome 把验收交给独立 grader；
• agent version 让 prompt 可以测试、固定和回滚；
• environment 与 worker contract 分开控制面和执行面。

这些机制共同保证：中断后仍能判断任务处于什么状态、等待谁、使用哪个版本、哪些输出已经成为事实。模型输出具有概率性；围绕它的任务状态不能也依赖猜测。