从“调用大模型”到“管理有状态运行时”

在大多数入门教程与快速原型中，一个 Agent 的实现似乎只需要十几行代码：写一个 while True 循环，调用 LLM，解析返回的 JSON，执行本地函数，把输出拼回 Prompt，然后继续下一轮。

这种“玩具抽象”给很多人带来了一种错觉：Agent 框架不过是在大模型 API 之上做了一层浅薄的 Prompt 模板与工具分发封装。

但当我们将视线投向生产环境中的真实 Agent 时，会发现系统面临的根本挑战完全变了：

• 不可逆的外部世界 ：Agent 不只是在生成文本，它在发邮件、改数据库、操作容器、调用转账接口。模型生成的内容可以重试，但现实世界中的副作用无法简单“撤销”。
• 不确定的时间跨度 ：一个复杂的任务可能需要人类审批介入，或者等待异步任务完成。执行进程必须在任意时刻挂起，状态落库，数小时甚至数天后由另一台物理机无缝恢复。
• 脆弱的状态一致性 ：网络中断、服务端限流、超时重试、并发冲突……一旦重试不当，就会导致工具被重复调用、或者历史消息在上下文窗口中出现不可逆的雪崩式重复。

生产级的 Agent 框架不是什么 LLM 客户端包装器；它本质上是一个为不确定性模型提供确定性边界的微型操作系统内核（Runtime Kernel）。

它向左接收来自 LLM 的概率性决策，向右连接会产生真实副作用的工具和外部系统；同时还要与会话存储、人类审批和运行状态打交道。它真正要解决的不是一组并列的“形式”，而是四个层次不同的工程问题：

1. 执行模型 ：怎样把连续运行的黑盒循环拆成可检查、可中断的状态迁移；
2. 一致性边界 ：怎样区分可以丢弃的模型输出与必须保留的现实副作用；
3. 协作协议 ：怎样在人类、服务端会话、远程工具和不同进程之间交接控制权；
4. 工程约束 ：怎样用确定性测试和 API 契约约束一个以概率模型为核心的系统。

图中的中心不是 LLM，而是运行时。LLM 只负责提出下一步；运行时决定这一步是否允许执行、执行后记录什么、何时需要暂停，以及失败后能否安全重试。

---

执行模型：从黑盒循环到离散状态机

初学者构建 Agent 时，最习惯的心智模型是“““黑盒控制流““”：一个阻塞的线程从头跑到尾，变量存在函数栈帧里。一旦服务器重启或线程中断，整个执行现场彻底湮灭。

生产运行时的第一大抽象，是将不可控的黑盒循环，拍平成严格可检查、可中断、可持久化的离散单步状态机。

这里需要区分两种“继续”：

• NextStepRunAgain ：当前 Agent 不变，把工具结果加入上下文，再调用同一个 Agent 的模型。
• NextStepHandoff(target_agent) ：先把 current_agent 替换为该 handoff 指向的目标 Agent，保存交接产生的项目并触发 Agent 更新事件，然后由目标 Agent 发起下一轮模型调用。常用的 handoff(agent=...) 接口会固定返回注册时传入的 Agent；源码中的 new_agent 只是“本次 handoff 解析出的接手者”这一局部变量名，并不意味着现场创建新对象。

handoff 后确实还会发生一次 model turn，但它属于接手后的目标 Agent，不是回到原 Agent。NextStepHandoff 也不是最终返回值，而是主循环中的一次“切换执行主体并继续运行”的控制指令。

Handoff 改变执行者，compaction 改变历史表示

这里还需要排除另一个容易产生的误解：handoff 本身不等于上下文压缩。两者作用在不同维度上。

机制	主要改变	默认是否改变另一个维度
NextStepHandoff(target_agent)	当前执行者：Agent A → 目标 Agent B	默认把此前对话继续交给 B，不自动压缩历史
nest_handoff_history / input_filter	B 在交接后看到的历史表示	不决定目标 Agent 是谁
OpenAIResponsesCompactionSession	Session 中长期保存的对话历史	不切换当前 Agent
Agent.as_tool()	临时执行一次子 Agent，并把结果返回调用者	主 Agent 仍掌握控制权

当前框架里确实存在真正的 compaction：OpenAIResponsesCompactionSession 会在满足阈值或被手动触发时调用 Responses API 的 responses.compact，再以压缩结果替换底层 Session 历史。默认触发条件是候选项目达到 10 条；替换过程还包含失败回滚、取消恢复和并发写入保护。

handoff 有一项相关但不同的能力：可选的 nest_handoff_history。它只在交接边界整理下一个 Agent 看到的历史——把适合整理的调用轨迹放入带 <CONVERSATION HISTORY> 标记的 assistant 历史段，同时保留需要无损转交的消息。默认 mapper 主要做结构化整理、嵌套和去重，并没有调用模型生成语义摘要。因此，更准确的称呼是是是交接历史重写是是，而不是与 responses.compact 等价的全局 compaction。换言之：

handoff    回答“接下来由谁负责？”
compaction 回答“接下来带多少、以什么形式带历史？”

它们可以分别使用，也可以组合使用。将两者拆开，正是这个框架没有把“专家路由”和“上下文工程”混成同一个魔法操作的地方。在这一抽象下：

1. Agent 与执行彻底解耦 ：Agent 是以配置为主的数据类（Instructions、Tools、Handoffs）。它不持有某次运行的调用栈与会话历史，因此同一份定义可以被复用或派生。
2. 状态的离散归约 ：每一轮交互被严格归约为四种确定性的 NextStep。无论是复杂的多工具并发、长链条交接，还是安全拦截，最终都要在单步裁决器（turn_resolution）中收敛为单一的枚举分支。
3. 现场即数据 ：执行现场不再只存在于内存调用栈，而是被整理为结构化的 RunState。在 Agent 定义、工具身份和 SDK 版本保持兼容的前提下，调用方可以把快照持久化，并在之后的进程中恢复运行。

---

一致性边界：不可逆世界中的副作用如何记账

大模型最显著的特点是“输出概率性”，而软件系统最基本的要求是“执行确定性”。当这两者在工具调用（Tool Calls）相遇时，就产生了一个尖锐的工程矛盾：副作用的不可逆性。

如果一个 Agent 调用了 transfer_funds(amount=1000)，随后大模型在生成结语时触发了安全策略（Output Guardrail），被系统判定为违规并拦截，系统应该怎么做？

• 做法 A（朴素回滚） ：把这一轮的所有内容全部丢弃。结果：转账动作在外部系统已经发生，但 Agent 的历史记忆里却没有任何记录，下一轮 Agent 会认为转账从未发生，从而而而再次发起转账而而！
• 做法 B（粗暴保存） ：把违规的输出和转账记录全存下来。结果：违规文本污染了会话历史，甚至作为下一次推理的上下文造成越狱。

这就是生产运行时必须建立的“““非对称事务边界““”：

• 护栏的时序约束 ：阻塞型输入护栏必须在沙箱环境初始化（如挂载云盘、拉取代码库）之前严格运行，防止不安全请求触发底层环境的物理状态变更；
• 输出拦截与副作用落库的分离 ：输出内容被熔断拦截时，系统必须启动专门的游标溯源机制，精准保留已落地的工具执行记录，剔除被污染的响应文本；
• 审批前后的双重校验 ：在人工审批前做一次参数预检（避免将明显合规错误的脏数据抛给人类审核），在审批通过、真正执行工具的前一毫秒再次复检（防止在漫长的人工等待期间，底层资源或时间窗口已失效）。

护栏在生产 Agent 框架里，绝对不是简单的字符串正则或者内容分类器，而是是是横跨在模型推理与现实副作用之间的事务控制边界是是。

---

协作协议：分布式语境下的控制权与所有权

当任务变得复杂，单机单进程内存模型就会彻底失效。现代 Agent 必须能与服务端会话（OpenAI Conversations / Responses API）、远程 MCP 服务以及人类审核员协同工作。

此时，系统必须显式规定：历史由谁保存、下一步由谁决定、哪些动作能够自动重放，以及控制权在什么条件下交还给运行时。

在这个分布式拓扑中，运行时需要确立三重所有权机制：

1. 记忆所有权的互斥性

客户端本地 Session 与 OpenAI 服务端托管会话（conversation_id / previous_response_id）））在底层是两套互斥的权威源））。生产框架必须在运行时做强校验，严禁在同一 Run 中混用，并配备专门的增量追踪器（Tracker）。在遇到网络重试时，能够主动将已发送但未确认的增量数据执行回滚（Rewind），避免在服务端产生脏数据。

2. 两阶段挂起的人工在环（HITL）

人工审批不是阻塞等待的 UI 交互，而是一个个个解耦的两阶段协议个个。系统需要记录 response_accepted（服务端是否已经确认）与 llm_end_hooks_started（生命周期是否已推进）两个细粒度标志，确保在跨机器恢复时，系统能够精确识别断点，既不漏掉任何副作用，也不重复发起已计费的模型调用。

3. Replay-Safe 的重试协商

重试绝不是在 catch 块里写一个重试次数。如果模型上下文里包含写操作的程序化工具（ProgrammaticToolCallingTool），重试该请求就是是是极度危险的重放攻击风险是是。框架必须引入模型建议、Provider 权威与硬否决（Veto）机制，只有在证明请求“纯净且可幂等重放”时才允许自动重试。

---

工程约束：用代码契约驯服不确定性系统

Agent 开发中最令人头疼的是：底层的 LLM 具有天生的随机性，传统的软件工程测试与版本管理方法在此处几乎处处碰壁。

如果每次跑 CI 都要真实调用一遍远端模型，不仅昂贵、缓慢，而且会因为模型的微小输出抖动导致测试用例随机挂掉。

生产运行时的第四大抽象，是用高密度的确定性工具与严格的接口契约，把整个不确定性系统锁进可靠的工程笼子里。

1. 确定性多轮仿真（ScriptedModel） ：
   框架不依赖网络 Mock，而是建立了一套完整的“多轮剧本模型”。你可以精确指定第 1 轮返回什么 Tool Call、第 2 轮在收到特定参数后返回什么结果。如果 Agent 在执行中跳过了某个预定步骤，或者发起了未曾声明的调用，测试会立即抛出 UnexpectedModelCall 或 UnconsumedModelSteps。这让极其复杂的多 Agent 协作与状态恢复测试可以在毫秒级、零成本、零随机性的环境下进行单测。
2. 版本化 API 契约冻结（API Contract Snapshot） ：
   在 tests/fixtures/ 目录下，静静躺着一个高达 1.13 MB 的 released_api_contract.json 及其策略文件。它把整个 SDK 导出的每一个类、方法签名、参数默认值甚至是规范的 Canonical Import 路径全部固化为测试资产。任何一行不小心的代码修改只要改变了公共契约表面，CI 就会无情熔断。

---

贯穿全篇的核心图景

当执行模型、一致性边界、协作协议与工程约束彼此连接起来，就构成了生产级 Agent 运行时的完整剖面。

• 【人工审批与恢复协议】 ：剖析 5000 行 RunState 背后的两阶段挂起、状态落盘与跨进程断点唤醒；
• 【副作用与事务边界】 ：详解输出拦截后已执行工具的非对称保留算法，以及四层护栏的时序控制；
• 【四种记忆策略与所有权】 ：厘清客户端 Session 与服务端 Tracker 的增量同步与回滚，看清为什么它们绝对不能混用；
• 【失败重试与异常治理】 ：深入 retry.py 的 Veto 否决机制、异常组拓扑脱敏与可自愈的兼容开关；