第 1 章 智能体循环与形态分界¶
智能体（agent）在工程上不是一个模型，而是一个循环：模型只负责"读入一段上下文、吐出一段 token"，把这段 token 变成对外部世界的动作、再把动作的结果变回 token 的那层代码，才是执行框架（agent harness）。本章划清这层运行时的边界，给出最小循环的五个阶段、三种形态的分界，以及终止与预算这两类容易被模型"自报完成"绕过去的外部约束。
1. 模型之外的那层运行时¶
语言模型的调用是无状态的：给定一段消息数组，返回下一段 token，服务端不替调用方保存对话。于是"记住上一轮"不是模型的能力，而是 harness 每轮把历史重新装进请求的结果。围绕这个事实，harness 至少要承担六件事：装配上下文、调用模型、解析输出、派发工具、回灌观测、执行权限与预算，并把每一步记进轨迹（trace）。
由此得到一条稳定的分界判据：控制流由谁决定。调用方决定全部步骤，是一次模型调用；代码把步骤写死成有向无环图（DAG），是工作流（workflow）；模型根据上一步的观测决定下一步，才是智能体。框架（framework）与 harness 的区别在另一维：框架提供积木（消息抽象、工具注册、回调），harness 是一个有主循环、有状态、有终止条件的运行时。用框架搭 harness 是常见做法，但二者不能互相替代。
| 形态 | 控制流 | 状态 | 典型适用面 |
|---|---|---|---|
| 单次调用 | 调用方 | 无 | 分类、抽取、单段改写 |
| 工作流 | 代码（DAG） | 外部存储 | 步骤固定、每步验收标准可写死 |
| 智能体 | 模型 | harness | 步骤依赖观测、路径无法预先枚举 |
2. 最小循环的五个阶段¶
一次循环由五个阶段加一个判定组成：装配（assemble）→ 调用（sample）→ 解析（parse）→ 派发（dispatch）→ 回灌（observe）→ 判定是否继续。五阶段之间没有隐藏状态，任何一步的输入都能从轨迹里复现，这是后续排障与评测的前提。
2.1 循环不变量¶
- 每轮请求自包含：历史、工具定义、系统提示都在请求里，不能依赖服务端记忆。
- 历史只追加，不就地改写：压缩是显式的、可记录的事件，不是悄悄删除中间几轮。
- 观测必须可归因：工具结果要带上触发它的调用标识，否则并行调用时无法配对。
- 动作先校验后执行：模型给出的参数是待检数据，不是可执行代码。
2.2 最小骨架¶
下面这段循环不依赖任何模型 SDK，model.complete 是可以替换的适配器。工具在派发前做参数校验，预算兜底独立于模型自报的完成状态。
from dataclasses import dataclass
@dataclass
class Msg:
role: str # user / assistant / tool
content: str
call_id: str | None = None # 工具结果回填时用于配对
def run(task, model, tools, max_steps=12):
history = [Msg("user", task)]
for _ in range(max_steps):
reply = model.complete(history, [t.schema for t in tools])
history.append(Msg("assistant", reply.text)) # 先落历史，保证可复现
if not reply.call:
return reply.text # 无动作请求 → 正常终止
tool = tools[reply.call.name] # 名称白名单，未知工具直接拒绝
args = tool.validate(reply.call.args) # 参数校验在派发之前
history.append(Msg("tool", tool.run(**args), reply.call.id))
return {"status": "budget_exhausted", "history": history} # 预算兜底
片段省略了流式、重试与权限门，它们分别在第 2、5 章展开。这里要看清的是骨架的闭合性：循环只依赖一个模型适配器与一张工具表，替换模型或增删工具都不改循环本身。
3. 三种形态与混合¶
单次调用适合输出可以一次成型、验收标准明确的任务；工作流适合步骤可枚举、每步都能单独验收的流程；智能体适合下一步取决于上一步观测、路径无法预先写死的任务。
判据不是"任务复不复杂"，而是步骤能否在运行前枚举。能枚举的步骤放进工作流，可获得可复现、可审计、可中断续跑；只有真正依赖观测的分支才交给模型。把固定流程写成智能体循环是常见反模式：每步都要采样，成本与方差都上升，换来的只是"看起来更智能"。
混合形态通常是工程上的落点：外层用工作流固定阶段与验收门，内层在某个阶段嵌入智能体循环处理不确定部分。这样失败时能定位到阶段，而不是只看到"整个任务失败了"。
4. 状态机与终止¶
把循环显式写成状态机，能让"卡住"与"失败"变成可观测的状态，而不是超时后才发现。最小状态集是：空闲（idle）、采样中（sampling）、等待工具（awaiting_tool）、等待用户（awaiting_user）、完成（done）、失败（failed）。状态迁移由事件驱动，事件同时写入轨迹。
终止条件分四类，缺一类就会留下一种挂死方式：
- 模型终态：不再请求工具且给出最终答复。
- 不可恢复错误：工具不存在、参数校验连续失败、权限被拒且无替代路径。
- 预算耗尽：步数、工具调用数、token、墙钟、成本任一触顶。
- 外部中断：用户取消、上游超时、看门狗触发。
判据："模型说完成"不是完成。完成状态必须由外部验收给出——工具返回的校验结果、任务判据、或用户确认。模型自报完成而外部未验收时，状态应停在未验收，而不是直接置为 done。
4.1 在途与暂停¶
机器人语境会放大"在途"问题：命令已下发、执行器仍在运动时，错误或中断不能立刻判为失败。守卫逻辑应先区分"命令在途"与"执行器被暂停"，等执行停稳再判定结果；否则会把正常的长动作误判成超时。这条判据在第 10 章的安全硬门里落地。
5. 预算¶
预算是 harness 对模型唯一的硬约束。可计量的至少有五项：步数、工具调用次数、输入与输出 token、墙钟时间、货币成本。预算不是"防止花太多钱"的附加项，而是终止条件的一部分——没有它，循环的终止就只剩模型自律。
两条工程判据：
- 按最坏情况单步成本预留：单步可能包含一次大工具结果回灌与一次长输出，平均成本不足以支撑预算设计。
- 耗尽时产出部分结果与原因码：抛出异常会丢掉已完成的工作；返回结构化状态（已完成步骤、未完成目标、触顶维度）才能让人接手。
5.1 预算与上下文的耦合¶
每轮请求都重发完整历史，单次任务的输入 token 随轮数近似线性增长，成本则近似按轮数乘上下文规模增长。压缩历史因此既是上下文动作，也是预算动作（第 3 章）。把这两件事分开设计，往往会在预算触顶时才发现压缩来不及。
6. 与分层感知路线的接口¶
具身场景有两条路线：视觉-语言-动作（vision-language-action，VLA）模型端到端出动作，或大模型做任务分解、调用现成的感知与技能工具。前者把感知、理解与动作接成一体，后者保留分层可验证性。本板块只做后者的执行侧：工具从哪来、调用怎样被约束、结果怎样回灌与验收，端到端策略本身归感知与操作侧笔记（camera-note 第 9 章「视觉-语言-动作概览」）。
机器人工具可以粗分三类：查询（读状态，无副作用）、技能（产生动作，有副作用）、验证（给判据，只读但决定后续分支）。三类工具的权限级别不同，混在同一张表里会让权限粒度失效（第 5 章）。接入执行的判据是输出能否被几何或规则层校验：能校验的先接，不能校验的先在仿真里跑（第 10 章）。
7. 最小 harness 的模块边界¶
一个可维护的骨架按职责切成六个模块：循环（loop）、上下文（context）、工具表（tools）、权限策略（policy）、轨迹（trace）、模型适配器（model adapter）。依赖边界刻意收窄到标准库加一个 HTTP 客户端，不引入编排框架——框架的行为会混进机制讨论，让"为什么这样设计"变成"这个框架碰巧这样做"。
两条替换性判据：循环不依赖具体模型（换适配器即可换厂商）；工具不依赖具体循环（同一张表能被工作流与智能体共用）。满足这两条，后续章节的机制才能逐章长出而不必重写骨架。
8. 要点¶
- 智能体 = 模型 + harness；模型无状态，记忆与权限都在 harness 一侧。
- 形态由控制流决定：代码决定走工作流，模型决定才是智能体；步骤能枚举就不要用循环。
- 循环的闭合性靠四个不变量：自包含请求、只追加历史、可归因观测、先校验后执行。
- 终止必须有外部兜底，"模型说完成"不等于完成；在途命令要先等停稳。
- 预算是终止条件的一部分，按最坏单步成本预留，耗尽时返回部分结果与原因码。