Level 1LLM 协议与 Agent Loop免费

Message Schema：system / user / assistant / tool

围绕消息、工具调用、流式输出、重试和状态，搭建最小可靠 Agent Loop。

讲解

Message Schema：system / user / assistant / tool

「Message Schema：system / user / assistant / tool」可以理解为：把 message schema、tool call、streaming、retry、abort 和完成态之间的协议状态机写成可执行、可观察、可恢复、可验收的 Harness 单元。它的直接产物不是一段 prompt，而是可回放 turn trace 与最小 Agent Loop。这一讲的目标，是把概念落到边界、架构图、工程对象、代码对比和验收证据。

一句话定义本讲是什么

边界协议状态

它不负责替模型“想得更聪明”，也不把所有逻辑塞进 chat wrapper。它负责划清协议状态，让 message -> model -> tool -> state -> done、多步 loop 与事件流和 tool result、retry reason、abort reason、done proof 都能被追踪。

反例把完成误认为 assistant 最后一条文本

如果实现会导致「把完成误认为 assistant 最后一条文本」，说明边界没有建立起来，需要回到输入合同、policy 或 runtime 重新切分。

验收可回放 turn trace 与最小 Agent Loop

完成标准是交付可回放 turn trace 与最小 Agent Loop，留下 tool result、retry reason、abort reason、done proof，并能用每一步都有 event、state 和恢复策略复盘。

可以这样理解它不负责替模型“想得更聪明”，也不把所有逻辑塞进 chat wrapper。它负责划清协议状态，让 message -> model -> tool -> state -> done、多步 loop 与事件流和 tool result、retry reason、abort reason、done proof 都能被追踪。程序员在这一讲要完成的转变是：从“我会调用模型或工具”转到“我能设计多步 loop 与事件流，并用每一步都有 event、state 和恢复策略判断它是否真的完成”。

Agent Loop 架构图

Rendering Mermaid...

Mermaid 源码

flowchart LR
  input["输入合同"] --> boundary["协议状态"]
  boundary --> route["message -> model -> tool -> state -> done"]
  route --> runtime["多步 loop 与事件流"]
  runtime --> policy{"策略/权限"}
  policy -->|allow| tool["模型与工具"]
  policy -->|block| blocked["把完成误认为 assistant 最后一条文本"]
  tool --> state["状态与事件"]
  runtime --> state
  state --> evidence["tool result、retry reason、abort reason、done proof"]
  evidence --> artifact["可回放 turn trace 与最小 Agent Loop"]
  artifact --> eval["验收"]

  classDef inputNode fill:#eef4ff,stroke:#4664ff,color:#0b1220;
  classDef runtimeNode fill:#ecfdf5,stroke:#10b981,color:#0b1220;
  classDef gate fill:#fff7ed,stroke:#f59e0b,color:#0b1220;
  classDef stop fill:#fee2e2,stroke:#ef4444,color:#0b1220;

  class input,boundary,route inputNode;
  class runtime,tool,state,evidence,artifact,eval runtimeNode;
  class policy gate;
  class blocked stop;

Hermes / Pi / Fiitx 关系

框架	可借鉴的设计	本讲怎么用
Hermes	入口、AIAgent、工具分发、Session Storage、Gateway/Cron	判断 message -> model -> tool -> state -> done 是否具备长期运行和交付边界
Pi Agent Core	AgentSession、事件流、resource loader、compaction、save point	实现多步 loop 与事件流和可恢复 turn lifecycle
Fiitx	Workbench、进度流、审批 UI、模型路由、历史回放	把 tool result、retry reason、abort reason、done proof 做成用户可见的控制面
Eval	done criteria、trace、failure case、regression	证明可回放 turn trace 与最小 Agent Loop 满足验收标准

代码对比从 LLM 调用到 Harness 运行

普通 LLM 调用只返回回答。Harness 运行必须把目标、边界、工具、策略和验收写成参数。

// 普通 LLM 写法：只拿到一段回答，缺少边界、状态和验收
const answer = await model.generate({
  prompt: "实现：Message Schema：system / user / assistant / tool"
});

// Agent Harness 写法：把目标、工具、策略、状态和验收写进运行合同
const result = await harness.runLlmAgentLoop1AgentLoop({
  lesson: "1.1 Message Schema：system / user / assistant / tool",
  goal: "实现：Message Schema：system / user / assistant / tool",
  boundary: "协议状态",
  runtime: "多步 loop 与事件流",
  route: "message -> model -> tool -> state -> done",
  tools: runtime.tools.forBoundary("协议状态"),
  policy: {
    watch: "把完成误认为 assistant 最后一条文本",
    requireEvidence: true
  },
  eval: [
    "trace_complete",
    "artifact_exists",
    "policy_checked",
    "llm_agent_loop_1_Agent_Loop_accepted"
  ]
});

assert(result.artifact === "可回放 turn trace 与最小 Agent Loop");
assert(result.evidence.includes("tool result、retry reason、abort reason、done proof"));

关键点

1
定义：「Message Schema：system / user / assistant / tool」可以理解为：把 message schema、tool call、streaming、retry、abort 和完成态之间的协议状态机写成可执行、可观察、可恢复、可验收的 Harness 单元。它的直接产物不是一段 prompt，而是可回放 turn trace 与最小 Agent Loop。
2
边界：它不负责替模型“想得更聪明”，也不把所有逻辑塞进 chat wrapper。它负责划清协议状态，让 message -> model -> tool -> state -> done、多步 loop 与事件流和 tool result、retry reason、abort reason、done proof 都能被追踪。
3
代码：普通调用只拿 answer，Harness 调用必须返回 artifact、evidence 和 trace。
4
验收：交付可回放 turn trace 与最小 Agent Loop，留下 tool result、retry reason、abort reason、done proof，并防住「把完成误认为 assistant 最后一条文本」。