GYA（Get Your Agent） on Renxin's Blog

第一话｜大模型只会补全文字，Agent 的“手脚”是怎么来的？

Tue, 03 Mar 2026 00:00:00 +0000

几年前，我还在用 ChatGPT 查技术资料、翻译文档、写文案前先理个大纲。那时候它是“聊天窗口”：我打字，它回文字，聊完就关掉。

后来出现的 Agent 工具，真的能帮我干活了——写代码、执行命令行、调用 API 查数据。

从“聊”到“干”，这几年发生了什么？

要回答这个问题，得先看清一件被很多人忽略的事：大模型从头到尾，只会做一件事。

模型只会补全文字

不管外面把它包装成聊天助手还是 Agent，模型干的事情始终只有一件：给你一段上文，它预测下一个最可能出现的词，然后把这个词接上去，再预测下一个，一直循环，直到吐出一段完整的文字。

这个过程有个名字，叫“自回归生成”。它的输入是文字，输出还是文字。

所以模型天生有几个边界，跟它聪不聪明没关系，是它的结构决定的：

它没有手，不会真的去点一个按钮、执行一行代码；
它没有网络，不会自己发一个 HTTP 请求去查天气；
它没有文件系统，不会自己创建一个文件、改一行代码。

它唯一能做的，是根据上文，猜下一段文字该怎么写。

理解了这一点，再回头看那个问题就清楚了一半：一个只会补全文字的模型，是怎么“干起活”来的？

让它“说”出要干什么

答案藏在一个很朴素的技巧里。

模型只会写字，那我们就让它把“想干什么”用固定格式写出来。

比如，我们在提示词里跟模型约定：

如果你想查天气，就严格输出下面这个格式，别的什么都别写：

{"action": "get_weather", "city": "北京"}

然后用户问“北京今天天气怎么样”。模型还是只会补全文字，只不过这一次，它补全出来的不是一段聊天，而是一行长得很像代码的 JSON：

{"action": "get_weather", "city": "北京"}

到这里，模型仍然什么都没做。它只是“说出”了：我想调 get_weather，参数是北京。

真正动手的是模型外面的程序。它拿到这行 JSON，解析出 action 是 get_weather、city 是北京，然后自己去调用真正的查天气函数：

import json, re

# 模型输出的那行文字
model_output = '{"action": "get_weather", "city": "北京"}'

# 程序解析它
data = json.loads(model_output)
if data["action"] == "get_weather":
 result = get_weather(data["city"]) # 真正查天气的是这行代码

拿到天气结果后，程序再把这个结果塞回给模型，模型补全成一句人话：“北京今天多云，25 度”。

看明白了吗？整条链路里，模型从头到尾没执行过任何东西。它只是把“想干什么”用固定格式说了出来，动手的是外面那段解析加执行的代码。

看起来模型“长出了手脚”，其实是外面套了一双手。

这套做法，其实是 Function Calling 的前身

上面那套“提示词逼出格式、代码解析执行”的做法，不是谁凭空想出来的玩具。在原生 Function Calling 出现之前，它是开发者让模型调用工具的标准办法——先用提示词约定好输出格式，再用正则表达式或者 JSON 解析器去抠出工具名和参数。

它好用，但也很脆。模型会输出残缺的 JSON、在 JSON 外面多写一句“好的，我帮你查”、或者干脆忘掉约定格式。这些问题，逼着人们后来把这件事从“提示词技巧”升级成了“协议”——也就是第二话要讲的 Function Calling。

但不管怎么升级，底层逻辑从没变过：

模型只负责用固定的格式，把“要干什么”说清楚；真正的执行，永远发生在模型外面。

想通这一点，整个 Agent 世界就有一把钥匙了。你之后会看到的所有花活——多步循环、记忆、MCP、Skill——都在做同一件事的不同部分：让模型把意图说清楚，让外面那套代码把事做成，再把结果喂回去。

而外面这套代码，我们给它起了个名字，叫 Runtime。它才是 Agent 真正“长”出来的那只手。

下一篇，我们就从这套做法的标准化形态开始：模型怎么用一套协议，规规矩矩地提出一次工具调用——Function Calling。

参考资料：

OpenAI, Function Calling
Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models

第二话｜Function Calling：谁把“调用工具”做成了一套协议？

Tue, 17 Mar 2026 00:00:00 +0000

上一话我们搞懂了两件事：模型只会补全文字；想让它干活，得让它把“想干什么”说成某种格式，再由外面的代码去执行。

但上一话那个办法很脆——用提示词逼模型输出 JSON，模型经常给你残缺的 JSON、在前后多写几句废话、或者干脆忘了格式。于是就有了 Function Calling：它把“让模型提出一次工具调用”这件事，从碰运气的提示词技巧，做成了一套规规矩矩的协议。

这一话就讲这套协议：它长什么样，谁先做出来的，以及为什么它能让模型“说清楚要干什么”。

一、协议要解决的，就是上一话那个“脆”

先看上一话的提示词 hack 是怎么翻车的。你在 system prompt 里写“想查天气就输出 {"tool":"get_weather","city":"..."}”，然后：

模型输出的不是纯 JSON，前后还夹着“好的，我帮你查一下”这种话；
JSON 本身残缺，少个引号、少个逗号，json.loads 直接崩；
换了个问法，模型就把格式忘得一干二净。

每次翻车，你都得靠更长的提示词、更严的正则去兜，兜到最后还是不可靠。

协议的意义就在这里：别再用文字去“暗示”模型输出格式，而是给一个结构化的位置，让模型把调用填进去。 这个位置是 API 里明确规定好的，模型要么填对，要么 API 直接拒绝，没有“碰运气”的中间地带。

二、协议长什么样：`tools` 进，`tool_calls` 出

整个协议，一进一出两件事：

请求里传 tools：你告诉模型“现在有哪些工具可以用”。这是一份菜单，写清楚每个工具叫什么、干什么、参数长什么样。
响应里收 tool_calls：模型告诉你“我想调哪个工具、带什么参数”。这是一张申请单。

下面是一份声明了本地天气工具的菜单：

TOOLS = [
 {
 "type": "function",
 "function": {
 "name": "get_weather",
 "description": "查询指定城市的天气演示数据",
 "parameters": {
 "type": "object",
 "properties": {
 "city": {"type": "string", "description": "城市名，如北京"}
 },
 "required": ["city"],
 "additionalProperties": False,
 },
 },
 }
]

注意，tools 不是把 Python 函数“上传”给模型。它只是一份描述：函数叫 get_weather、查天气的、需要一个 city 字符串参数。模型拿到的是这些文字，不是那个函数本身。Chat Completions API

把菜单连同问题一起发过去：

assistant_message = client.chat.completions.create(
 model=MODEL,
 messages=[{"role": "user", "content": "请查询北京现在的天气。"}],
 tools=TOOLS,
 tool_choice="required",
).choices[0].message

响应里我们关心的不是自然语言，而是这张申请单：

{
 "id": "call_00_...",
 "type": "function",
 "function": {
 "name": "get_weather",
 "arguments": "{\"city\": \"北京\"}"
 }
}

拆开看每个字段：

id：这条调用的唯一标识，回传结果时要靠它关联；
type：固定是 function，标记这是一次函数调用；
function.name：想调哪个工具；
function.arguments：一个 JSON 字符串——注意它还是字符串，不是对象，代码里得再 json.loads 一层才能用。

它表达的就是一句话：“请调用 get_weather，参数是北京。”到这里，模型既没有运行 Python，也没有拿到天气数据。它只是把“想干什么”用协议规定的格式写清楚了。

三、这套协议，是谁先做出来的

它不是我编的，也不是模型厂商某天灵机一动。时间线很清晰：

2022 年，ReAct（Yao et al., arXiv 2210.03629）提出“推理 + 行动”交替，用提示词让模型按 Thought / Action 的格式输出，再让代码去执行；
2023 年 2 月，Toolformer（Meta AI, arXiv 2302.04761）证明“模型自己决定何时调 API”这个能力是能被训练出来的；
2023 年 5 月，Gorilla（UC Berkeley, arXiv 2305.15334）开始微调模型学写 API 调用。

这几篇走的都是“提示词 + 解析”的路线——也就是上一话讲的那个脆办法。

真正的转折在 2023 年 6 月 13 日：OpenAI 首次发布原生 Function Calling，随 gpt-4-0613 和 gpt-3.5-turbo-0613 两个模型快照一起推出。从这一天起，“让模型提工具调用”不再靠提示词暗示，而是变成了 API 里的标准字段——就是我们第二节看到的 tools 进、tool_calls 出。

四、别看就一个 `tool_calls`，背后做了很多工作

有个问题自然冒出来：同样是“让模型输出调用”，为什么提示词 hack 天天翻车，而协议一出来，模型就能稳定地输出合法参数、不再给你残缺 JSON？

不是因为提示词写得好了。是厂商在背后做了工作——模型是被训练成“会正确提出调用”的，这个能力不是运气，是训练出来的。

这里只说结论，不展开原理（那是下一话的事）：

微调：训练阶段喂了大量“工具调用对话”样本，让模型学会判断要不要调、选哪个工具、生成合法参数；
约束解码：生成的时候，在输出层卡住模型，让它只能吐出符合 schema 的内容，从根上杜绝“残缺 JSON”。

这两件事把“正确提出调用”从提示词的玄学，变成了模型本身的能力。至于模型内部到底是怎么学会的、这两件事的具体机制——那是第三话要专门讲的问题，这里先按下不表。

五、协议只负责“提出”，不负责“执行”

回到那张申请单。tool_calls 拿回来，协议的部分就结束了。接下来是你的代码接手：

def execute_tool(name: str, arguments_json: str) -> str:
 if name != "get_weather":
 raise ValueError(f"不允许执行未知工具：{name}")

 arguments = json.loads(arguments_json)
 if not isinstance(arguments, dict) or set(arguments) != {"city"}:
 raise ValueError("get_weather 参数必须且只能包含 city")

 city = arguments["city"]
 if not isinstance(city, str) or not city.strip():
 raise ValueError("city 必须是非空字符串")

 return get_weather(city.strip())

模型输出在这里被当成外部输入处理：先校验工具名，再校验参数，然后才真正执行。25℃ 来自 get_weather() 的返回值，不是模型编的：

def get_weather(city: str) -> str:
 weather = {
 "北京": "多云，25℃，东北风3级",
 "上海": "小雨，22℃，东南风2级",
 }
 return weather.get(city, f"暂无{city}的天气演示数据")

协议让模型“说清楚要干什么”，执行永远在模型外面——这是上一话那条结论的延续，在这里变成了可运行的代码。

六、把结果交回去，也是协议的一部分

函数执行完，Python 手里有了天气文本，但用户还没看到一句话。模型上一次只停在“我想调什么工具”，所以要把两样东西放回消息历史：

messages.append(assistant_message) # 模型提出的调用请求
messages.append(
 {
 "role": "tool", # 工具执行结果
 "tool_call_id": tool_call.id, # 关联到上面那条 tool_calls
 "content": result,
 }
)

role=tool 这一步不是可选的，是协议强制要求的。这里有个真实的坑：有人把 role=tool 写成了 role=user，API 直接报 HTTP 400——

An assistant message with 'tool_calls' must be followed by
tool messages responding to each 'tool_call_id'.

意思很直白：你给模型看了一张 tool_calls 申请单，就必须逐条配上一份对应的 tool 结果，用 tool_call_id 对上号。少一条、错一条，协议层面就拒绝，根本轮不到模型来猜。这个报错本身，就是“协议不是约定俗成、而是硬约束”的最好证据。

补上结果后再问一次模型，它才能把“多云，25℃”组织成一句人话。事实来自函数，句子由模型生成，两边分得清清楚楚。

七、回到最开始的问题：到底谁调用了工具？

角色	输入	输出	不负责什么
模型	用户问题与 `tools` 菜单	`tool_calls` 申请单	不执行本地函数
你的代码	工具名、参数与本地能力	校验后的工具结果	不应把模型请求原样放行
模型	`role=tool` 结果	面向用户的回答	不产生工具返回的外部事实

Function Calling 没有把函数“装进模型”。它做的，是把上一话那个脆弱的提示词 hack，变成了一套 tools 进、tool_calls 出的标准协议——模型提请求，你的代码执行，模型再说话。

跑通一次，你会看到这三步按顺序发生：

模型请求：get_weather({"city":"北京"})
程序执行：多云，25℃，东北风3级
模型回答：北京现在多云，气温 25℃，东北风 3 级。

配套 Python 与 Java 实现在 GYA 仓库与 GYA-Java 仓库的 c02-function-calling 目录，按 README 的命令跑，不复制这篇文章里零散的代码块。

协议跑通了，但一个更根本的问题还悬着：模型凭什么知道，该从菜单里挑 get_weather、该填北京？ 这已经不是协议能回答的了——得回到模型训练本身。下一话。

参考资料：

DeepSeek, Tool Calls
DeepSeek, Chat Completions API
Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models
Schick et al., Toolformer: Language Models Can Teach Themselves to Use Tools
Patil et al., Gorilla: Large Language Model Connected with Massive APIs

第三话｜模型为什么能生成工具调用？

Tue, 31 Mar 2026 00:00:00 +0000

上一话跑通了 Function Calling 协议，但留了个更根本的问题没收尾：

模型凭什么知道该从 tools 菜单里挑 get_weather、又凭什么把“北京”填进 city？

不是提示词写得好。协议只是给了模型一个“填在哪里”的位置，真正让模型知道“填什么”的，是它的训练。这一话就追这件事：模型是怎么学会“提出一次工具调用”的。

先给结论，后面再拆：工具调用不是模型的内置能力，而是训练出来的“输出倾向”。训练改变的是它生成某些 token 序列的概率，不是给它装了一个真的会退款的函数。

一、模型学的，仍然是下一个 token

模型里没有一个叫“退款”的函数。它有的，只是“给定上文，预测下一个词”的能力。所谓“会调工具”，是它学会了：当上下文里出现“退款意图 + 工具定义”时，下一个该输出的，是 refund_order 和 order_id 这几个 token。

训练样本把它要学的样子，直接摆出来：

上下文：订单 O-100 已支付，用户要求退款；可用工具有 refund_order(order_id)
目标：refund_order({"order_id":"O-100"})

反复见这样的样本，模型参数里就长出一套倾向：“退款 + 已支付”这类上下文，会抬高 refund_order 的概率；订单号 O-100，会抬高被填进 order_id 的概率。

注意，训练集还得有反例，否则模型会养成坏习惯：

用户只问配送时间 → 直接回答，不调工具；
订单状态不明 → 先追问，不调工具。

少了这些负样本，模型就会变成“看见什么都想调工具”。

flowchart LR
 A[训练样本
意图、工具定义、目标调用] --> B[模型参数
形成输出倾向]
 C[本次请求
用户消息、当前工具、订单状态] --> D[模型生成候选 tool_calls]
 B --> D
 D --> E[Runtime
校验、确认、执行或拒绝]

关键洞察：模型只是提出了候选调用。它没有因此获得订单事实、权限，也没有执行权。 会“说”要干什么，和“真的干了什么”，是两码事。

二、这条“倾向”，是靠什么训练出来的？

问题来了：这些“上下文 → 正确调用”的样本，是怎么来的？人工一条条标注太贵，学界给了几条公开的路线。

Toolformer 解决的是“数据怎么规模化造出来”。它的做法很有意思——让模型自己当标注员：

在一段普通文本里，让模型猜哪些位置可能需要调 API，采样出一堆候选调用；
真的去执行这些调用，拿到结果；
关键一步：只保留那些“拿到结果后，模型预测后续文字更准了”的调用——具体说，就是比较“有结果”和“没结果”两种情况下，模型对后面 token 的预测损失，损失降得够多才留下；
用过滤后的样本去微调模型。

一句话：模型自己提出调用、自己执行、再自己判断“这次调用到底有没有用”，有用的才拿来当训练样本。 全程不需要人工标注“这里该不该调工具”。Toolformer

Gorilla 解决的是另一个问题：API 会变。哪怕模型学过 get_weather(city)，文档也可能改成 get_weather(location, unit)。Gorilla 的做法是微调 + 文档检索结合：训练给模型调用能力，检索把“当前最新的接口契约”带进上下文，让它跟得上变化。Gorilla

CoT 常被顺带提起，但它其实是个对照，不是工具调用训练：它研究的是“在提示里给推理示例能不能改变输出”。它能改变当前这一轮的输出，但不改模型参数——和 Toolformer/Gorilla 那种真正动参数的训练，是两回事。CoT

三、一件必须分清的事：哪些证据能信，哪些不能

讲到这里，得划一条诚实的边界。关于“模型为什么能调工具”，能拿到的证据分三类，它们不能互相冒充：

证据类型	能说明什么	不能说明什么
论文公开的方法（Toolformer/Gorilla）	“存在这些训练工具调用的公开方法”	不代表某个商业模型就用了它
厂商披露（OpenAI 公告）	0613 模型经过微调、Structured Outputs 靠训练+约束解码	只限定到那几家、那段时间，不能外推
黑盒 API 能观察到的	输入什么、输出什么（比如 description 改了就选错工具）	看不到训练语料、训练阶段、奖励方法

最关键的一条是第三类：你从 API 拿到的结果再稳定，也反推不出厂商到底是怎么训练的。 训练语料长什么样、分几个阶段、有没有用 RLHF——这些是黑盒，除非厂商自己说，否则只能标“未知”。

所以别犯那个错：看到 tool_calls 稳定输出，就说“这个模型用了 Toolformer”。稳定输出能证明“它训练得很好”，证明不了“它是怎么训练的”。

四、Prompt-only 和 Native tools，差的不只是“格式”

上一话讲了 Native tools 的协议形态，这里补一层它和训练/推理的关系。

Prompt-only：在 system prompt 里约定“需要退款时输出 JSON”。模型把 JSON 塞进普通 content 里，Runtime 还得从正文里把命令抠出来——这里混着自然语言、Markdown、可能还有好几个 JSON。

Native tools：在 API 的 tools 字段传 schema，模型用独立的 tool_calls 字段返回。Runtime 直接拿到工具名、参数和调用 id，不用猜哪里是命令。

这个差异不是“格式好看点”，而是责任归属变了：Prompt-only 把“保证输出长得像 JSON”的责任甩给了提示词和你的解析器；Native tools 把这层责任接了过去，一部分靠训练（让模型更会按 schema 输出），一部分靠推理阶段的约束解码（生成时卡住，只允许符合 schema 的 token 出来）。

OpenAI 官方也明确说过：Function Calling 的可靠性，一部分来自模型的微调，一部分来自 Structured Outputs 的 constrained decoding。Structured Outputs

这里有个真实的坑能说明这层差异。我们 Java 版最初只写了“需要时输出 JSON”，没说清 name 和 arguments.order_id 的形状。结果 Native tools 模式仍能返回结构化调用，Prompt-only 模式却解析不出来。把提示词补成明确的 JSON 模板后，Java 的 8 个场景才全过。这不是“Java 不适合做 Agent”，而是Prompt-only 把输出协议的一部分责任，留在了你的提示词和解析器上——而 Native tools 帮你卸掉了一部分。

五、动手看一次：description 才是“选哪个”的开关

我们用一套虚构订单做实验，Python 和 Java 21 各跑一遍。Runtime 先注入已验证的订单状态，模型只做一次工具选择，程序只记录候选调用，绝不执行退款或取消。

四种场景，正确行为是这样：

场景	正确行为
已支付 O-100，要求退款	`refund_order(O-100)`
未支付 O-200，要求取消	`cancel_order(O-200)`
无订单号和状态	追问，不调用
无退款/取消意图	自然语言回答，不调用

基线下两种语言都过。然后做一个故障注入：只把 refund_order 和 cancel_order 的 description 对调，其余全不变——工具名、模型、用户请求、参数 schema 都一样。

结果很干净：已支付退款稳定变成 cancel_order(O-100)，未支付取消稳定变成 refund_order(O-200)，而订单号仍然是对的。恢复 description 后，回归全过。

这个实验说明两件事：

工具选择（选哪个）靠的是 description——模型是读描述来判断“这个工具是干嘛的”，描述写错了，它就选错。
参数提取（填什么）可以和工具选择分开看——订单号还是从用户消息和 Runtime 注入的上下文里来的，两个工具的参数 schema 没变，所以订单号没错。

但这能证明什么、不能证明什么，得说清楚：它证明了“description 影响路由”这个可观察行为，证明不了模型用了哪种训练法。description 写对了，也不代表参数永远填对——Runtime 照样得校验。

六、所以，能信到什么程度

绕了一圈，回到开头那个问题：模型为什么能生成工具调用？

因为它被训练成了这样——训练样本让它形成了“意图 + 工具定义 → 结构化调用”的输出倾向。Toolformer、Gorilla 这些公开方法，展示了这条倾向可以怎么规模化地训练出来；厂商还叠加了微调和约束解码，让输出更稳。

但“会提请求”不等于“可靠”。训练让模型更会“说”要干什么，不会让它“变聪明”——它照样可能选错工具、编造业务参数、请求一个无权执行的动作。tool_calls 永远是候选，不是命令。 谁来判断“能不能执行、怎么执行”，是下一篇的事。

参考资料：

Wei et al., Chain-of-Thought Prompting Elicits Reasoning in Large Language Models
Schick et al., Toolformer: Language Models Can Teach Themselves to Use Tools
Patil et al., Gorilla: Large Language Model Connected with Massive APIs
OpenAI, Function calling and other API updates
OpenAI, Introducing Structured Outputs in the API

第四话｜模型说调 refund_order，Runtime 怎么不把事情搞砸？

Tue, 14 Apr 2026 00:00:00 +0000

第三话结束时，我们留下一个问题没解决：

tool_calls 永远是候选，不是命令。谁来判断"能不能执行、怎么执行"？

这就是第四话要回答的。模型提出的工具调用，哪怕 JSON 合法、参数齐全，也可能是错的、越权的、有副作用的。Runtime 不能照单全收——它得先校验，再执行，而且要在执行出问题时不把局面搞得更糟。

这里最危险的，不是选错工具，而是一个有副作用、结果又说不清的操作。比如模型要调 refund_order 退款：

handler 执行到一半超时了。钱到底退了没有？直接重试，可能重复退款；不重试，用户又以为没退成。

这一话就沿着这条退款主线，讲清楚 Runtime 怎么把"模型说要调用"变成"安全地执行"——以及最关键的，超时之后怎么根据真实状态做决定，而不是靠猜。

一、模型说"调 refund_order"，Runtime 先干什么？

模型返回的 tool_calls 里，是一段结构化申请单：工具名 refund_order、参数 order_id 和 idempotency_key。但它是模型生成的，是外部输入，不是已经校验过的命令。

Runtime 拿到它，第一件事不是执行，是问三个问题：

这个工具名，是允许执行的吗？
参数齐全、类型对吗？
这个工具现在可用吗？

任何一个不过，就不进 handler，而是返回一个结构化的错误，让上层能稳定地分支处理。

为什么要结构化，不能是一段"调用失败，请稍后再试"的文案？因为文案里没有可编程的信息——程序没法可靠地区分"工具不存在"和"参数缺了"和"执行到一半挂了"。而这三种情况，处理方式完全不同：

错误码	发生了什么	该怎么处理
`UNKNOWN_TOOL`	模型报了个不存在的工具名	拒绝，修正工具选择
`INVALID_ARGUMENT`	参数不满足契约	补参数或拒绝
`TOOL_UNAVAILABLE`	工具已下线或不健康	告知不可用，不能硬调
`EXECUTION_ERROR`	handler 或下游执行失败	按恢复语义决定，见下一节

前三个错误，handler 根本没执行——它们发生在执行之前。第四个才是真正进到了执行阶段，也是最麻烦的。

二、执行时出了问题，最怕的是"结果说不清"

refund_order 通过了校验，handler 真的去调订单服务了——然后超时。

超时意味着什么？意味着"结果不确定"。请求可能压根没到达订单服务，也可能已经到达、退款都成功了，只是响应没传回来。你分不清。

这就是最危险的地方：如果 Runtime 把"超时"直接当成"没执行"，再调一次，就可能退了两笔钱。而如果当成"失败了"，用户这边又显示退款失败，但其实钱已经退了——两边对不上。

所以规则只有一条：超时之后，先查这笔操作的真实状态，不要直接重试。

怎么查？靠 idempotency_key（幂等键）。它是发起退款时就带上的、这笔操作的唯一标识。领域服务按这个键记录"这笔退款到底执行了没有"，Runtime 超时后先去查它，而不是再发起一笔。

flowchart TD
 A[refund_order 超时] --> B[按 idempotency_key 查询真实状态]
 B -->|SUCCEEDED| C[回放成功结果
不再调 handler]
 B -->|NOT_EXECUTED| D[确认没执行
才重试一次]
 B -->|UNKNOWN / 执行中| E[等待或人工核验]

三条分支，对应三种真实状态：

SUCCEEDED：钱已经退了。Runtime 把成功结果回放给用户，不再调 handler。这是最容易犯错的场景——明明已经成功，却因为"没收到响应"而再退一次。
NOT_EXECUTED：确认没执行过。这时重试一次是安全的。
UNKNOWN / 执行中：状态也查不到。这时既不能重试，也不能谎报成功，只能等待对账或转人工核验。

跑一遍主线 demo，你会看到这样一条 Trace：

refund_order response=EXECUTION_ERROR
idempotency_status=SUCCEEDED
runtime_action=REPLAY_SUCCESS
final=SUCCESS
refund_order handler_execution_count=1

最后一行是整条链路的关键证据：handler_execution_count=1。它证明 Runtime 虽然经历了"超时 → 查状态 → 回放"，但真正执行退款的 handler 只跑了一次。没有重复退款。

三、把"谁负责什么"钉死

超时恢复这件事，看着是 Runtime 一个人的活，其实牵涉三个角色，职责不能混：

角色	负责什么	不负责什么
领域服务（`RefundDomain`）	记录和查询"退款到底发生没有"	不负责重试策略，也不知道 Runtime 怎么编排
Runtime	按恢复语义，决定回放、重试还是等待	不拥有退款事实，退款有没有发生得问领域
模型	只提出候选调用	不拥有执行权，更不能拿它的话当退款状态

一句话：有副作用工具的超时恢复，首先是领域状态问题，其次才是 Runtime 的重试策略问题。 退款有没有发生，是领域事实，只能问领域服务；Runtime 能做的是照着这个事实去编排下一步，而不是自己猜。

反过来看，如果领域服务不记录幂等状态，Runtime 再聪明也没用——它没有可以查询的真相，超时之后只能抓瞎。所以幂等这件事，得从工具设计那天就带上，而不是等出了超时才补。

四、把这条链路跑起来

配套 demo 在 code/agent-tutorial/c04-tool-registry/，Python 和 Java 各一份，语义一致。它不调用 LLM、订单或支付系统——所有 handler 都是本地确定性模拟，所以它验证的是 Runtime 的控制流，不是退款系统的可用性证明。

cd code/agent-tutorial/c04-tool-registry/python
python3 registry.py
python3 -m unittest test_registry.py

cd ../java
gradle run

它覆盖六类场景，每一类都对应上面讲的一个环节：

场景	验证什么
工具不存在	`UNKNOWN_TOOL`，不进 handler
工具下线	`TOOL_UNAVAILABLE`，不能硬调
参数缺失	`INVALID_ARGUMENT`，补参或拒绝
正常调用	一次执行，`SUCCEEDED`
超时但已成功	查幂等 → `SUCCEEDED` → 回放，`handler_execution_count=1`
超时且未执行	查幂等 → `NOT_EXECUTED` → 重试一次

其中"超时但已成功"是最值得盯着看的一条：它模拟了 handler 执行成功后、响应却丢失的场景——退款已经发生，SUCCEEDED，但 Runtime 收到的是超时。正确的 Trace 必须是"回放成功结果"，而不是"再退一次"。

五、还差的：执行成功 ≠ 永远可靠

跑通这条链路，Runtime 能安全地执行一次有副作用的调用了。但这离"可靠"还有距离，几件事本篇点到为止，先立个边界：

一次超时不等于工具坏了。订单服务偶发抖动，不能立刻把 refund_order 永久下线；连续失败达到阈值才考虑熔断。
熔断后的探测，不能用一笔新退款去试。要用无副作用的健康检查——否则"检查服务恢复没有"这件事本身，又制造了一笔业务动作。
Runtime 不替代鉴权、审批和审计。工具能不能调，除了契约校验，还涉及"这个用户有没有权限"“要不要二次确认"“留不留审计留底”——这些是 Runtime 与领域服务的责任，本篇没展开。

这些都属于"从单次安全执行到生产级可靠"的延伸，先把边界划在这，不抢后续章节的戏。

到下一话，问题才真正变难

现在，Runtime 已经能把单个候选调用安全地执行，并在超时后不搞砸。

但它还不会根据第一次工具的结果，决定第二步做什么。

第五话才进入真正的 ReAct 循环：第二个 Action 必须依赖第一个 Observation。那时，今天建立的 ToolResponse 和幂等恢复，会成为循环里可复用的执行底座。

第五话｜ReAct：让模型把「想」和「做」接起来

Tue, 28 Apr 2026 00:00:00 +0000

第四话结束，我们手里有了一个能安全执行单次工具调用的 Runtime：模型说"调 get_weather"，代码校验、执行、把结果回喂，模型再总结成一句话。

这是"会做"了。但它藏着一个更深的问题，上一话没来得及展开：模型的"想"和"做"，还是断开的。

模型提一次请求，代码执行一次，结束。中间没有"想"——没有让模型停下来，根据刚拿到的结果，再决定下一步。

本篇就把这两件事接起来。先记住一句话，它是全文的锚：

光想不做，会空转；光做不想，会盲目。ReAct 做的，就是让"想"和"做"交替起来。

一、光想不做、光做不想，各有什么毛病

先把两种"缺一半"的形态说清楚。ReAct 就是为了治这两种病而生的。

光想不做（Chain-of-Thought 的局限）

让模型一路推理，它每一步都靠自己的记忆往下推。问题是：它推理时不接触外部世界，没有办法去查、去验证。推到一半，遇到它不知道的事实，它不会停下来说"我不知道，去查一下"，而是接着编。错了还往下推，越推越偏。

这就是"幻觉"和"错误传播"：模型在脑子里空转，没有真实反馈把它拉回现实。

光做不想（纯工具调用）

反过来，模型只会调工具，但不动脑。它拿到一个结果，不知道这个结果意味着什么、下一步该干嘛、什么时候该收手。盲目地执行，却不解释为什么。

一句话立住：想，缺真实反馈会空转；做，缺推理会盲目。 两种形态各缺一半，ReAct 要做的，是把两半合起来。

二、ReAct 的答案：把"想"和"做"交替起来

2022 年的一篇论文把这个想法抽象成了模式，叫 ReAct（Reasoning + Acting），arXiv 2210.03629。

想法很朴素：让模型交替地"想一步、做一步、看一步"。

要素	是什么	谁负责
Thought（想）	模型推理：我知道什么、还缺什么、下一步干嘛	模型
Action（做）	调用某个工具，或给出最终答案	模型提出，代码执行
Observation（看）	工具执行后返回的真实结果	代码

关键在那个"看"。Observation 是外部世界的真实反馈，它把模型的"想"从自己的幻觉里拉回现实。 这是 CoT 缺的那一环——CoT 一路想下去，没有地方停下来"看一眼真实世界"。

于是循环成立：想一步 → 做一步 → 看一眼真实结果 → 再想一步。想的给做的指方向，做的给想的补事实。这就是"推理和行动交替"。

flowchart LR
 A[问题 + 历史] --> B[模型
想：下一步干嘛]
 B --> C{要动手?}
 C -->|是| D[代码执行
拿到真实结果]
 D --> E[写回历史
给模型看]
 E --> B
 C -->|否| F[给出最终回答
结束]

有两点要划清，避免误读：

第一，本文不把任何供应商的 reasoning_content 字段当成论文里的 Thought。论文的 Thought 是文字推理轨迹，现代 API 的 reasoning 字段是另一回事。这篇只验证一个更小、更可观察的问题：模型的下一步动作，是不是真的随观察到的真实结果改变。

第二，ReAct 并没有在所有任务上都赢过 CoT。论文配套结果里，HotpotQA 6-shot 下 ReAct 是 27.4，CoT 是 29.4，两者结合是 35.1。别把"ReAct 更强"当成普适结论——它带来的是外部反馈回路，不是万能药。

关键洞察：ReAct 的突破，不是"模型更聪明了"，而是给模型的推理接上了外部反馈——每一步都踩在真实工具结果上，而不是模型自己的幻觉上。

三、工程上怎么承载：一个循环外壳

“想和做交替"这件事，落到代码上，就是一个循环：

for step in range(1, max_steps + 1):
 turn = model.decide(state.messages, tools) # 模型"想"：下一步干嘛
 if not turn.tool_calls: # 不想动手了 → 结束
 return state
 observation = execute(turn.tool_calls) # 代码"做"：执行，拿到真实结果
 state.messages.append(observation) # 把"看"到的写回历史

循环是外壳，交替是灵魂。不是套个 while 就完事——有三件事，是让这个外壳真正立起来的前提：

1. 模型没有记忆，每次都得喂全。 模型每次调用都是独立的，不记得上一轮干了什么。所以循环要自己维护消息历史，每一轮把"问题 + 之前做过的 + 看到的结果"完整交给模型。它不是"记得”，是被每次提醒。

2. 循环必须有出口。 两个出口：模型不再调工具（直接给最终回答）→ 正常结束；到达 max_steps 上限 → 兜底强制停止。缺了后者，模型偶尔会陷入"反复调同一个工具"的怪圈，把额度烧穿。

3. Observation 必须真实，绝不让模型自己编。 这是 ReAct 的生命线。如果模型能自己写"北京天气 25℃"，它就会偷懒编造。Observation 必须来自工具的真实执行结果，代码负责，模型无权编。在原生 tool_calls 里，这一点由 API 层保证：结果以 role=tool 消息回传，模型只能基于它推理。

这三件事，是"循环外壳怎么搭"的注意点，不是 ReAct 的主角。主角永远是那句：让"想"和"做"交替，让每一步想都踩在真实的"看"上。

四、看一次真实的"交替"

光说不够，跑一个真的。任务是"公司总部今天的天气"——它天然需要两步：先解析"公司总部"是哪个城市，再用这个城市查天气。

配套代码在 code/agent-tutorial/c05-react-agent/，Python 和 Java 双份，工具是三个本地只读夹具（不依赖外部 API，避免网络和额度污染控制流证据）：

工具	作用	行为
`resolve_company_address`	解析总部地址	上海总部→上海，北京总部→北京，其余→待澄清
`get_weather`	查城市天气	上海→小雨 22℃，北京→晴 18℃
`request_clarification`	信息不足时请求补充	无副作用

真实模型跑出来的对照 Trace，是这篇最想让你看到的：

上海：resolve_company_address({"company_name": "上海总部"})
 → 看到 RESOLVED(city="上海")
 → get_weather({"city": "上海"})

北京：resolve_company_address({"company_name": "北京总部"})
 → 看到 RESOLVED(city="北京")
 → get_weather({"city": "北京"})

注意看第二步：模型"想"出的下一步，参数随它"看"到的结果改变——看到"上海"就查上海，看到"北京"就查北京。

这比"最后回答换了城市"强得多。它证明的不是"循环多跑了几步"，而是模型真的在根据 Observation 调整下一步的"想"——这正是 ReAct 和"固定脚本多跑几遍"的分水岭。

跑起来：

# 离线回归，不需要 Key
cd code/agent-tutorial/c05-react-agent/python
python3 -m unittest test_react_agent.py

# 真实模型路径，Key 只从环境变量读
export LLM_API_URL='...' LLM_API_KEY='...' LLM_MODEL='...'
python3 react_agent.py

五、这一篇停在哪，下一篇往哪走

到这里，ReAct 的"交替"讲清了：模型想一步、做一步、看一步，每一步想都踩在真实结果上。

但有一个口子，正好是下一篇的入口。注意第三节那个循环，每一轮都把完整历史喂给模型。历史一长，问题就来了：

每次都喂全，Token 越来越贵，也塞不下；
“看"到的结果、Run 当前走到哪一步，都只在内存里——进程一重启，全没了。

模型"想"和"做"的交替立起来了，但**“记得住、断得了、恢复得回来"这件事还没解决**。这是第六话要讲的：状态怎么显式存下来、怎么 checkpoint、怎么在崩溃后接着跑。

演示代码：code/agent-tutorial/c05-react-agent/（Python：react_agent.py + test_react_agent.py；Java 21 等价实现见 java/）。真实模型路径只从 LLM_API_URL / LLM_API_KEY / LLM_MODEL 环境变量读配置，密钥不进代码、不进 Trace。参考：ReAct 论文 arXiv 2210.03629；Google Research 官方介绍 React: Synergizing Reasoning and Acting in Language Models；Trace 为 2026-09 本机实测（Python 与 Java 双跑）。

第六话｜状态管理：从 dict 到 StateGraph

Tue, 12 May 2026 00:00:00 +0000

第五话我们写出了一个会多步决策的 Agent。回头看它的执行轨迹，你注意到一个细节吗——每一步之前，模型都要"想"一次：

=== Step 1 ===
[Thought] 用户想要三件事：查天气、算数、总结...
[Action] 调用 get_weather(...) → [Observation] 北京: 多云，25℃
[Action] 调用 calculator(...) → [Observation] 56088

=== Step 2 ===
[Thought] 我有了两个结果，现在总结...
[Final Answer] 北京今天多云... 123×456=56088

也就是说，这个循环里**“下一步做什么"是由模型推理决定的**：模型说"我要调工具”，代码就去调；模型说"我该总结了"，循环就结束。这很自由——但代价是，每一步的路由决策都花掉一次模型推理。

现在问一个问题：如果这个流程是固定的——先理解意图、再调工具、最后总结——每次让模型重新"想"一遍下一步去哪，是不是有点浪费？更麻烦的是，如果任务是"查完笔记，有冲突就提醒，没冲突就生成报告"，“去哪"的判断写在模型脑子里，它偶尔会想歪，而且每一步都在消耗 token 做路由而不是做任务。

我先说结论：

复杂任务的 Agent，需要一个显式的状态管理：

State：共享的状态对象（所有节点读写同一份）

Node：一个执行单元（函数：读 State → 做事 → 返回更新）

Edge：节点间的路由（确定性代码，不走 LLM）这三个东西组在一起，就是 StateGraph——图管流程（确定性的传送带），LLM 管内容（只在需要语义的节点被调用）。

这一篇，我们把"流程控制"从模型手里收回来，交给确定性的代码——先写一个手写状态机（零依赖），再用 LangGraph 的 StateGraph 跑同一个任务。你会发现：框架不是黑盒，它只是把你手写的东西声明式化了。

一、旧世界：循环里的状态为什么撑不住

第五话的 while 循环，本质上是个"自由形式"的流程：每次迭代，模型决定下一步做什么，代码照做。它的问题在第四话笔记里已经埋下伏笔——ReAct 让 LLM 包办一切：推理、路由、调用、总结，全在循环里。

规模化后，四个问题暴露：

问题	表现
条件分支不可靠	“查完笔记该去哪"写在模型推理文本里，模型偶尔跑偏
只能串行	需要"同时查 3 个工具再聚合"时，ReAct 只能一个个来
无法优雅暂停	想"等用户确认再继续”，循环很难挂起
路由成本高	每一步都让 LLM 想"下一步去哪”，token 费在路由上而不是任务上

flowchart LR
 A[用户问题] --> B[LLM 思考
推理+路由混合]
 B --> C[执行工具]
 C --> D{模型决定
下一步?}
 D -->|再想一次| B
 D -->|结束| E[最终答案]

关键洞察：ReAct 循环的问题不是"循环"本身，而是路由决策也交给了 LLM。让模型每次都想"下一步去哪"，既贵又不稳——路由这种事，代码做得又快又准。

二、转折：显式状态机——State / Node / Edge 三件套

解决思路来自一个古老而成熟的概念：状态机（State Machine）。把它用在 Agent 上，就是三个核心概念：

class AgentState(TypedDict): # State：共享状态
 messages: list # 对话历史
 intent: list # 用户意图（要哪些工具）
 results: dict # 工具结果
 next_step: str # 路由指针

def parse_intent(state) -> dict: # Node：执行单元
 result = llm.parse_intent(...)
 return {"intent": result} # 只更新需要的字段

# Edge：路由表（确定性代码）
if state["next_step"] == "parse_intent": parse_intent(state)
elif state["next_step"] == "execute_tools": execute_tools(state)

对照你熟悉的 Java 概念：

Java 状态机	StateGraph
State 枚举	Node（可执行代码）
transition(event)	Edge（自动流转）
Context 上下文	State（共享字典）
Guard 条件	条件边的路由函数（确定性 Python）

关键设计原则：图管流程，LLM 管内容。

图的节点 = 一个单元操作
├── 纯代码节点 → 调工具、做计算（零 token）
├── 代码+LLM 节点 → 需要语义推理时调 LLM
└── 纯 LLM 节点 → 理解意图、生成文本

图的边 = 节点间路由
├── 普通边 → 永远从 A 到 B
└── 条件边 → 根据 State 决定（确定性代码，不走 LLM）

关键洞察：图是骨架（确定性的传送带），LLM 是肌肉（只坐到需要语义推理的工位上）。图的职责是控制 LLM 被调用的时机和次数——该省的路由 token 一分不花。

三、原理讲透：为什么状态要"显式"？

你可能觉得：第五话的循环里也有 state 啊，为什么要"显式"？区别在于谁在管理状态的流转：

	第五话手写循环	状态机
状态存在哪	零散在循环代码里	一个显式 State 对象
下一步去哪	模型推理决定（或 if-else 散落）	`next_step` 字段 + 路由表
节点边界	没有，循环体是"一大坨"	每个 Node 独立函数
调试	靠打印	看 State 快照即知全貌

在展开之前，先精确理解 State 的生命周期——这是状态管理和第五话随手传 list 的根本区别：

1. 初始 State：{"question": "...", "messages": [...], "results": {}, "intent": "", "next_step": "parse_intent"}
2. parse_intent 执行 → 返回 {"intent": [...]} ← 只更新 intent 字段
3. 引擎把返回合并进 State → next_step 指向 execute_tools
4. execute_tools 执行 → 返回 {"results": {...}, "messages": [...]} ← 只更新自己的字段
5. ...循环...
6. summarize 返回 {"final_answer": "..."} → next_step=END → 输出最终 State

每个 Node 是一个纯函数：输入完整 State，返回"要更新的字段子集"。Node 不直接改 State——它返回更新，由引擎（手写循环或框架）合并。这个设计保证了：任何节点都能拿到完整上下文（读 State），但只负责自己那部分（写自己的字段），不会互相踩踏。这也是"可并行"和"可恢复"能成立的原因——状态的读写是受控的，不是随处可改的全局变量。

“显式"的三个直接收益：

可审计：任何时刻，State 里的 intent/results/next_step 告诉你 Agent 走到哪了、已经干了什么。挂掉时一眼看出问题。
可恢复：State 是数据，可以序列化存盘。长任务挂了，从上次 State 恢复，不用从头跑（检查点 checkpoint）。
可并行：State 明确后，互不依赖的分支可以并行执行再聚合（StateGraph 支持 fan-out/fan-in）。

这三件事正是生产 Agent 和 demo Agent 的分水岭——demo 靠调试，生产靠状态管理。

这里值得多说两句"可并行"和"可恢复”，因为它们是把状态管理从"概念正确"推向"工程价值"的关键。

并行（fan-out / fan-in）：假设一个任务要同时查三个数据源（天气、股票、新闻），ReAct 循环只能串行——先查天气、等结果、再查股票、再等结果。显式状态机可以把三个查询节点做成并行分支，全部完成后在聚合节点合并。LangGraph 的 Send API 就是干这个的。对延迟敏感的生产系统，这可能是 3 倍和 1 倍的差别。代价是状态必须可合并——每个并行分支只更新自己的字段，不能互相覆盖，这正是 State（共享 dict）设计时要小心的。

检查点（checkpoint）：State 既然是数据，就可以序列化。LangGraph 有内置的 checkpointer——每步执行完把 State 存下来。长任务（比如批量处理 1000 条数据）跑到第 700 条挂了，恢复时从第 700 条的 State 继续，而不是从头跑。这对 token 成本和工程效率是量级的差别。手写版要做到这点，就是在 run() 里每步 json.dumps(state) 存盘——原理一样，框架替你做了。

还有一点值得注意：State 的字段设计直接影响系统复杂度。原则是"每个节点只更新自己关心的字段"——parse_intent 只写 intent，execute_tools 只写 results 和 messages，互不干扰。如果所有节点都直接改一个"大杂烩" dict，并行和检查点都会变得困难。这跟 Java 里"类职责单一"是同一个道理。

四、动手：同一个任务，两种实现

代码：https://github.com/renxin2024/GYA/tree/main/c06-state-management

state_machine.py：手写状态机（零依赖）
langgraph_demo.py：LangGraph StateGraph（pip install langgraph）

export DEEPSEEK_API_KEY=sk-你的key
python3 state_machine.py
uv run --with langgraph python3 langgraph_demo.py # 或 pip install langgraph

任务：“北京天气怎么样？顺便算一下 123*456，最后把两个答案整理成一句话。”

手写版：三节点状态机

class StateMachine:
 def __init__(self, question):
 self.state = {
 "question": question,
 "messages": [...],
 "results": {}, # 工具结果
 "intent": "", # 语义理解结果
 "next_step": "parse_intent", # 路由指针
 }

 def parse_intent(self): # Node 1：LLM 节点（唯一需要语义的）
 intent = llm.parse(...)
 self.state["intent"] = intent
 self.state["next_step"] = "execute_tools"

 def execute_tools(self): # Node 2：代码节点（路由确定性）
 for tc in tool_calls: ...执行...
 self.state["next_step"] = "summarize"

 def summarize(self): # Node 3：LLM 节点
 self.state["final_answer"] = llm.summarize(...)
 self.state["next_step"] = "END"

 def run(self): # 状态机引擎：while + next_step 路由
 while self.state["next_step"] != "END":
 node = self.state["next_step"]
 getattr(self, node)()

实测输出（2026-08-20，deepseek-v4-flash）：

=== Node: parse_intent ===
=== Node: execute_tools ===
=== Node: summarize ===
最终答案: 北京天气多云、25℃、东北风3级；另外，123×456的计算结果是56088。
执行轨迹: intent=['get_weather', 'calculator']
 results={'get_weather': '多云，25℃...', 'calculator': '56088'}

注意三件事：

路由是 next_step 字段跳转，不是模型推理——parse_intent → execute_tools → summarize，每一步去哪由代码决定
LLM 只被调了 3 次：parse_intent（理解意图）、execute_tools 里（决定工具参数）、summarize（总结）——路由本身零 token
State 一眼可查：intent 和 results 告诉你"Agent 认为要做什么、已经得到了什么"

LangGraph 版：同一三节点，声明式表达

g = StateGraph(AgentState)
g.add_node("parse_intent", parse_intent)
g.add_node("execute_tools", execute_tools)
g.add_node("summarize", summarize)
g.set_entry_point("parse_intent")
g.add_edge("parse_intent", "execute_tools")
g.add_conditional_edges("execute_tools", route_after_tools, {"summarize": "summarize"})
g.add_edge("summarize", END)
graph = g.compile()
result = graph.invoke({...})

节点函数和手写版一模一样（parse_intent 的代码是复制的）——区别只在：

手写版：while 循环 + getattr(self, next_step) 路由
LangGraph：add_node + add_edge 声明 + 框架内部替你跑循环

实测输出与手写版一致（intent 相同、results 相同、最终答案相同）：

[Node: parse_intent] intent=['get_weather', 'calculator']
[Node: execute_tools] get_weather → 多云，25℃，东北风 3 级
[Node: execute_tools] calculator → 56088
[Node: summarize] 北京天气多云、25℃；123×456的结果是56088。

flowchart LR
 A[parse_intent
LLM 节点] --> B[execute_tools
代码节点]
 B --> C{有工具结果?}
 C -->|是| D[summarize
LLM 节点]
 C -->|否| D
 D --> E[END]

关键洞察：跑同一个任务，手写版和 LangGraph 版输出完全一致——框架没有魔法，它只是把 while 循环和路由表声明式化了。你手写过一遍，用任何框架都是"换个写法"。

五、工程化延伸：什么时候该上 StateGraph？

状态机不是万能的。什么时候该用，什么时候 ReAct/手写循环就够？

该用 StateGraph	ReAct/手写循环就够
流程固定、高频重复	低频、一次性、探索性任务
需要并行 + 聚合（fan-out/fan-in）	单步骤顺序执行就够
需要人机交互中断（等确认）	不需要中间暂停
需要审计追溯、断点恢复	不需要追踪状态
规模大、token 成本敏感	一天跑一两次

一个直觉判断法：如果流程图能画出来（固定节点+固定边），就用 StateGraph；如果流程本身是探索性的（不知道下一步是什么），用 ReAct。

作为系列的双语言惯例，这里说一句 Java 版的事：LangGraph 是 Python 生态库（基于 asyncio 和 TypedDict 设计），没有官方 Java 等价实现。所以第六话的 Java 版（GYA-Java c06-state-management/）实现的是手写状态机等价版——State 用 Map，Node 用 Function，图声明就是一张注册表：

static final Map<String, Function<Map<String, Object>, Void>> NODES = new LinkedHashMap<>();
NODES.put("parse_intent", state -> parseIntent(state));
NODES.put("execute_tools", state -> executeTools(state));
NODES.put("summarize", state -> summarize(state));
// 引擎：while + next_step 路由（与 Python 版同构）

用 Java 跑同一个任务，输出和 Python 版完全一致（intent/results/最终答案相同）。这说明：状态机的思想是语言无关的——不管用 Python 的 LangGraph、Java 的手写注册表，还是你未来可能遇到的任何 Agent 框架，State/Node/Edge 三件套都是同一套骨架。

另外澄清一个常见误区：ReAct 不是 StateGraph 的对立面，而是 StateGraph 的一个特例——三节点循环图（Think → Act → Observe → 回环）。类比：ArrayList 是 List 的实现，ReAct 是 StateGraph 的一种工作流模式。用 StateGraph 也能画出 ReAct 图（第五话的循环就是），只是 StateGraph 能表达的远不止 ReAct。

下一步

State 管住了"流程怎么走"。但还有一个大问题没解决：模型的记忆。

第五话里我们把所有历史都塞进 messages——对话 20 轮后，prompt 越来越长，直到超出上下文窗口。这时会发生什么？模型"忘记"最早说的话。上下文窗口 ≠ 记忆。

下一篇第七话，我们讲三层记忆架构：上下文（窗口内）、短期（会话内）、长期（跨会话）——以及向量检索怎么让 Agent"记住"重要的事。

演示代码：https://github.com/renxin2024/GYA/tree/main/c06-state-management（state_machine.py 零依赖 + langgraph_demo.py 需 langgraph；DeepSeek 官方 API，默认模型 deepseek-v4-flash）。Java 21 手写状态机等价实现见独立仓库 https://github.com/renxin2024/GYA-Java（c06-state-management/，Gradle 工程，gradle run）。参考：StateGraph 三概念（State/Node/Edge）、图管流程 LLM 管内容、ReAct 是 StateGraph 特例，来自 LangGraph 官方文档与 Agent 工程实践（hello-agents 讲义延伸）；demo 输出为 2026-05-12 本机实测（deepseek-v4-flash，Python 手写版/LangGraph 版/Java 版三跑一致）。

第七话｜记忆：上下文、短期、长期

Tue, 26 May 2026 00:00:00 +0000

第六话里，我们把"流程控制"从模型手里收回来，交给了 StateGraph。但有一个问题从第五话开始就一直存在，我们假装它不存在：

模型的记忆。

回顾第五话的代码，我们的"记忆"就是那个 messages 列表——每次对话，把所有历史都塞进 prompt 喂给模型：

state.add_message(msg) # 工具调用也塞进历史
state.add_message({"role": "tool", ...}) # 观察结果也塞进历史

前几轮没事。但对话到 20 轮、30 轮呢？prompt 越来越长，直到撞上上下文窗口上限——这时会发生什么？模型开始"忘记"最早说的话，或者更糟：被中间的信息干扰，答错。

我先说结论：

上下文窗口 ≠ 记忆。 模型本身不"记得"任何东西，它只是每次被我们喂一坨 prompt。真正的记忆分三层：

上下文（Working）：当前窗口内，最易失——塞不下就丢

短期（Episodic）：会话内关键事实，显式提取——比全量历史省 token、抗干扰

长期（Semantic）：跨会话持久，检索式访问——不检索的记忆等于不存在

这一篇，我们写一个带三层记忆的最小 Agent，亲眼看看"记忆是怎么补位的"。

一、旧世界：把历史塞进上下文的问题

先看最朴素的做法——全量历史注入。它有两个硬伤：

硬伤 1：上下文窗口有限。 假设窗口 8K token，对话到第 30 轮时历史已经 10K token——塞不进去了。要么截断最老的（等于"失忆"），要么压缩（损失细节）。窗口是物理限制，记忆是软件设计。

硬伤 2：Lost in the Middle（中间迷失）。 2023 年一篇论文（arXiv 2309.04271）发现一个反直觉现象：模型对长上下文的利用呈 U 型——开头和结尾的信息记得好，中间的信息最容易丢，性能差距可达 25-30%，即使 100K 窗口的模型也一样。把关键信息放在 30 条消息的中间？它很可能被"淹没"。

flowchart LR
 A[对话历史
不断增长] --> B{超过窗口?}
 B -->|是| C[截断最老
= 失忆]
 B -->|否| D[全量塞入
中间信息易丢]

关键洞察：把历史当"水管"一样无脑灌，是新手 Agent 最大的坑。塞不下和塞中间，都是"假记忆"——看似有，实则不可靠。

二、转折：三层记忆——各管一段

认知科学早就给了我们答案：人的记忆也不是一个池子，而是分层的。Agent 照搬这个分层：

层	存什么	生命周期	访问方式	类比
上下文（Working）	当前轮次消息	窗口内	直接注入 prompt	你正在读的这句话
短期（Episodic）	会话内关键事实	会话级	显式提取 + 摘要注入	今天上午聊过的事
长期（Semantic）	用户偏好/知识点	跨会话（近乎永久）	向量检索	你记得朋友爱喝什么

关键设计原则：

① 短期记忆 = 显式提取，不是全量存储。 全量历史是"录像带"——什么都录了，但长、贵、噪音多。短期记忆是"笔记"——只记关键事实（名字、偏好、决定），结构化、省 token、抗干扰。

② 长期记忆 = 检索式访问，不是注入式。 你不可能把"用户爱喝龙井、职业是 Java 工程师、博客写 AI Agent"全塞进每次 prompt。正确做法是：提问时检索出相关的几条，只注入那几条。这就是 RAG（检索增强生成）的核心思想——记忆库很大，但每次只"想"起相关的部分。

③ 记忆要有生命周期：巩固与遗忘。 不是所有信息都值得长期保存。工程实践通常给记忆打分（importance）：高价值 → 升级到长期；低价值 → 过期遗忘。遗忘不是 bug，是 feature——没有遗忘，记忆库会堆满垃圾，检索质量反而下降。

flowchart LR
 A[对话] --> B{短期记忆
提取关键事实}
 B --> C[上下文
当前轮]
 B --> D[长期记忆
向量检索]
 C --> E[回答]
 D --> E

关键洞察：三层记忆不是"三个数据库"，而是三种访问模式——上下文是注入式（全量）、短期是摘要式（精炼）、长期是检索式（按需）。访问模式决定了它们各自解决什么问题。

三、原理讲透：为什么"不检索的记忆等于不存在"

很多人以为"我的 Agent 存了聊天记录，所以它有记忆"。错。存储 ≠ 记忆，检索才是记忆。

想想人的记忆：你知道"朋友爱喝龙井"这件事，不是因为你把这句话背下来了，而是因为在需要的时候你能想起来——聊天聊到茶、点单、送礼，这些场景会自动唤起这条记忆。

Agent 也一样。长期记忆必须支持按语义检索：用户问"他喜欢喝什么？"，Agent 要从记忆库里找出“喜欢喝茶，尤其是龙井"这条。怎么找？最基础的方法是向量相似度：

1. 把记忆条目转成向量（embedding）——语义相近的文本向量也相近
2. 把用户问题也转成向量
3. 计算余弦相似度，返回最相近的 N 条

这就是"检索"的本质。演示里我们用纯 Python 实现一个最小版（中文 bigram 分词 + 余弦相似度，零依赖），让你看到机制本身：

def tokenize(text): # 中文按相邻两字（bigram）切分
 return {text[i:i+2] for i in range(len(text)-1) if 中文字符}

def cosine(a, b): # 向量相似度
 return len(a & b) / (sqrt(len(a)) * sqrt(len(b)))

注意演示级实现的局限：纯 bigram 对同义改写敏感——“爱喝"和"喜欢喝"切出来的 bigram 完全不同，匹配不到。生产环境用真实 embedding（如 OpenAI/DeepSeek embedding API），同义词会投影到相近的向量空间，就没有这个问题。机制相同，精度不同。

顺带说一句检索之外的另一半：巩固（Consolidation）与遗忘（Forgetting）。记忆不是存进去就完事了——它有一个生命周期：

对话产生信息 → 编码 → 存储 → 检索 → 巩固（低→高价值迁移）→ 遗忘（过期清理）

工程上最常见的做法是给每条记忆打 importance 分数：

巩固：对话中出现的用户偏好/重要决定，打分 ≥ 0.7 → 从短期升级到长期；分数低的留在短期，会话结束即丢。这模拟了人脑"重要的事记牢，琐事随风散”。
遗忘：长期记忆也有容量和时效。时间衰减（太久没被检索到的降权）、容量上限（满了淘汰最不重要的）。没有遗忘的记忆库，最终会被垃圾淹没，检索质量断崖式下降——这跟搜索引擎要处理"死链"是一个道理。

很多 Agent 项目死在"只存不捡”：记忆越堆越多，检索命中率越来越差。好的记忆系统不是存得多，而是记得准、忘得掉。

四、动手：三层记忆 Agent 实测

代码：https://github.com/renxin2024/GYA/tree/main/c07-memory（memory_demo.py，纯标准库）

export DEEPSEEK_API_KEY=sk-你的key
python3 memory_demo.py

场景 1：短期记忆补位

用户第一轮说"我叫张三" → Agent 提取存入短期记忆。然后聊两轮无关话题（写文字）——此时张三的名字已经不在模型上下文里了。再问"我是谁？我叫什么名字？"：

模型(带记忆): 你是张三。

对比（无记忆，没有任何上下文）:
模型(无记忆): 在没有上下文的情况下，我无法知道你是谁，也不知道你的名字。

这就是短期记忆的价值：名字被"挤出"上下文后，显式提取的记忆补上了。注意我们没有把整个对话历史塞回去——只注入了一条关键事实，更省 token、更抗干扰。

场景 2：长期记忆向量检索

向记忆库存入三条用户画像，然后提问检索：

记忆库:
 - 用户喜欢喝茶，尤其是龙井
 - 用户职业是 Java 后端工程师，擅长并发编程
 - 用户的博客主题是 AI Agent 开发

问『用户喜欢喝什么？』→ 检索到: 用户喜欢喝茶，尤其是龙井
问『用户职业是什么？』→ 检索到: 用户职业是 Java 后端工程师...
问『博客写什么？』→ 检索到: 用户的博客主题是 AI Agent 开发

每条问题都准确"想"起了对应的记忆——这就是检索式访问。如果记忆库有 1000 条，我们不会全塞给模型，只注入检索到的那 1-2 条。

场景 3（诚实说明）：Lost-in-the-Middle 实测

演示脚本里也放了一个"信息放中间 vs 开头"的对比。诚实地说：deepseek-v4-flash 对短 padding 抗性很好，两头都答对了——这个效应要在 100K 级长上下文才明显（论文数据：中间 vs 两端性能差 25-30%）。demo 放它是让你知道这个坑的存在，正文用论文数据支撑结论。

flowchart LR
 A[用户提问] --> B{检索长期记忆}
 B --> C[命中 1-2 条]
 C --> D[注入上下文]
 D --> E[模型回答]
 A --> F[短期记忆摘要]
 F --> D

关键洞察：三层记忆合起来的完整流程是——提问时，短期记忆给摘要、长期记忆给检索结果，一起注入上下文，模型基于"当前问题 + 记得的事"作答。模型始终只面对一个"够用的小 prompt"，而不是越来越长的全量历史。

五、工程化延伸：生产级记忆系统

demo 是概念演示，生产要补的东西不少：

能力	demo（本篇）	生产要补的
短期记忆	内存 dict	会话级存储 + 上限管理（FIFO/TTL）
长期记忆	内存 list + bigram	向量库（Qdrant/Chroma）+ 真实 embedding
巩固	无	重要性打分（如 ≥0.7 升长期）+ 定期 Consolidation
遗忘	无	时间衰减/容量上限，防止记忆库膨胀
记忆 vs RAG	混在一起	明确边界：Memory 存对话产生的个人事实，RAG 存外部知识库

记忆 vs RAG 的边界值得单独强调——这是最常见的混淆：

Memory（记忆）：对话中自然产生的——“用户叫张三"“用户爱喝龙井”。换个用户，答案就变。
RAG（检索增强）：外部知识库——“什么是 ReAct"“Java 并发怎么调优”。所有用户共享，答案不变。

把用户偏好存进 RAG？你会得到"所有用户都爱喝龙井”。把外部知识存进 Memory？每次都要重新"对话产生”，浪费。各司其职。

下一步

阶段 2（Agent 循环）到此收尾：我们有循环（第五话）、有状态（第六话）、有记忆（第七话）——一个"会干活、能记住"的 Agent 成型了。

但还有一个痛苦没解决：工具的接入。第四话我们手写了注册表，接一个新工具要写代码、注册、测试。如果你要接 10 个不同的服务（GitHub、数据库、日历、邮件），每个都要写适配代码——N×M 的集成地狱。

下一篇进入阶段 3：MCP 协议——为什么需要它。一句话预告：MCP 是"工具的 USB-C 接口"，让工具接入标准化。

演示代码：https://github.com/renxin2024/GYA/tree/main/c07-memory（memory_demo.py，纯标准库；DeepSeek 官方 API，默认模型 deepseek-v4-flash）。Java 21 等价实现见独立仓库 https://github.com/renxin2024/GYA-Java（c07-memory/，Gradle 工程，gradle run）。参考：Lost in the Middle 论文 arXiv 2309.04271（U 型注意力、中间性能差 25-30%）；四层记忆与巩固/遗忘机制来自 Agent 记忆系统工程实践（hello-agents 讲义延伸）；Memory vs RAG 边界为行业共识；demo 输出为 2026-05-26 本机实测（deepseek-v4-flash，Python 与 Java 双跑）。

第八话｜MCP 协议：工具为什么需要一根 USB-C

Tue, 09 Jun 2026 00:00:00 +0000

第四话里，我们把工具放进了一个 ToolRegistry。工具多了以后，注册表比 if-else 强很多：可以发现工具、统一调用、返回结构化错误。

但它有一个隐含前提：工具和 Agent 在同一个进程，至少在同一套代码里。

如果天气服务是另一个 Python 进程，数据库工具是 Java 服务，GitHub 工具由另一个团队维护，第四话的注册表还能直接解决吗？不能。你需要给每一种外部工具写一套适配器，工具数量和接入方数量一增加，就会重新掉进 N×M 集成地狱。

这就是 MCP 要解决的问题。

ToolRegistry 管理进程内工具，MCP 标准化工具提供方和 Agent 客户端之间的边界。

一、旧世界：工具被绑在调用方代码里

第四话的最小闭环是：模型输出工具名和参数，注册表根据名称找到函数，函数执行后返回 ToolResponse。

LLM → ToolRegistry → Python 函数 → ToolResponse → LLM

这个结构对学习和单体应用非常好。你能清楚看到每一层的职责，也能自己控制错误码和参数校验。

问题出在边界。假设 Agent 需要 20 个工具，而这 20 个工具分布在 5 个独立服务里。没有统一协议时，客户端要知道每个服务如何启动、如何描述工具、如何传参数、如何返回结果。每接一个服务，都要重新写一套通信和适配代码。

flowchart LR
 A[Agent 客户端] --> P[多套私有适配器]
 P --> S[多个外部服务]

这不是工具本身太多，而是每个客户端都在重复理解每个服务的私有接口。

二、MCP 把什么放到了协议层

MCP 可以先用三个角色理解：

Host：承载 Agent 的应用，例如桌面助手、IDE 或你的 Python 程序；
MCP Client：Host 内部的协议客户端，负责连接某一个 MCP Server；
MCP Server：工具、资源或提示模板的提供方。

它们的关系不是“模型直接连接 MCP Server”，而是：

Host
 └── MCP Client ── JSON-RPC/Transport ── MCP Server
 └── tools

一次最小工具调用大致经历：

Client 与 Server 初始化并协商协议版本和能力；
Client 请求工具列表；
Server 返回工具名称、描述和输入 Schema；
Client 发起工具调用；
Server 执行函数并返回内容或错误。

这里有一个重要边界：MCP 标准化的是“怎么发现和调用”，不是“下一步该调用什么”。任务规划仍然由 Agent 循环和模型负责，工具的权限、业务正确性和结果验证仍然由应用负责。

三、STDIO：先把跨进程边界跑通

MCP 支持多种传输方式。第八话先选择 STDIO，因为它最容易看清进程边界：Client 启动 Server 子进程，JSON-RPC 消息通过 stdin/stdout 传递。

flowchart LR
 C[MCP Client] --> I[initialize]
 I --> L[tools/list]
 L --> X[tools/call add]
 X --> R[CallToolResult]

STDIO 有一个很容易踩的坑：stdout 是协议通道，不是日志通道。 Server 如果把调试日志打印到 stdout，Client 读到的就不再是合法的 JSON-RPC 消息。日志应该写 stderr，或者通过 MCP 的 logging 能力发送。

生产环境更常用 Streamable HTTP：Server 可以独立部署，多个 Client 通过网络连接。但这同时带来认证、超时、并发、TLS、会话和部署问题。先跑通 STDIO，再讨论 HTTP，学习成本更低。

四、Python：用官方 SDK 跑通 Client/Server

前置环境

Python 3.10+；本次用 Python 3.11.15 实测；
mcp[cli]==2.0.0；
不需要 LLM API Key。

代码位于 GYA/c08-mcp/。Server 只有一个工具：

from mcp.server import MCPServer

mcp = MCPServer("c08-demo")


@mcp.tool()
def add(a: int, b: int) -> int:
 """Add two integers and return the result."""
 return a + b


if __name__ == "__main__":
 mcp.run()

类型注解不仅服务于 Python 类型检查，也帮助 SDK 生成工具输入 Schema。Client 不需要自己手写 a、b 的 JSON Schema，就能通过 tools/list 发现它。

async with stdio_client(server) as (read_stream, write_stream):
 async with ClientSession(read_stream, write_stream) as client:
 await client.initialize()
 listed = await client.list_tools()
 result = await client.call_tool("add", {"a": 2, "b": 3})

这里使用的是 mcp==2.0.0 的实际 API：stdio_client 返回读写流，再交给 ClientSession。在线文档中的更高层 Client(StdioServerParameters(...)) 写法属于更新的文档线，不能未经验证地复制到锁定版本。

运行：

cd GYA/c08-mcp
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r requirements.txt
python3 main.py

本次实测关键输出：

[1] 初始化 MCP Server: experimental={} ... tools=ToolsCapability(list_changed=False) ...
[2] 发现工具: ['add']
[3] 调用 add(2, 3): 5
[4] 错误场景: is_error=True; Unknown tool: missing_tool

Python SDK 把未知工具作为一个带 is_error=True 的工具结果返回，Client 不会因为这个工具级错误直接崩溃。

五、Java 21：同一个协议，不同的 SDK 表达

前置环境

Java 21；
Gradle Wrapper 8.14.2；
io.modelcontextprotocol.sdk:mcp:2.0.0；
不需要 LLM API Key。

代码位于 GYA-Java/c08-mcp/。Java 版使用 StdioServerTransportProvider 暴露 Server，使用 StdioClientTransport 启动 Server 子进程。工具定义需要显式提供输入 Schema：

McpSyncServer server = McpServer.sync(transport)
 .serverInfo("c08-java-demo", "1.0.0")
 .capabilities(ServerCapabilities.builder().tools(true).build())
 .toolCall(
 Tool.builder("add", schema)
 .description("Add two integers")
 .build(),
 (exchange, request) -> {
 int a = ((Number) request.arguments().get("a")).intValue();
 int b = ((Number) request.arguments().get("b")).intValue();
 return CallToolResult.builder()
 .content(List.of(new McpSchema.TextContent(Integer.toString(a + b))))
 .build();
 })
 .build();

运行：

cd GYA-Java
JAVA_HOME=$(/usr/libexec/java_home -v 21) ./gradlew :c08-mcp:run

本次实测关键输出：

[1] 初始化 MCP Server: c08-java-demo
[2] 发现工具: [add]
[3] 调用 add(2, 3): 5
[4] 错误场景: McpError; Unknown tool: invalid_tool_name

Java SDK 2.0.0 对未知工具的处理和 Python 不一样：它返回 JSON-RPC 错误，客户端表现为 McpError。这不是“谁对谁错”，而是两个 SDK 对协议级错误的 API 映射不同。跨语言教程不能只比较正常输出，也要把错误语义写清楚。

六、MCP 和第四话 ToolRegistry 的边界

维度	第四话 ToolRegistry	第八话 MCP
工具位置	同一进程或代码库	独立进程或远程服务
发现方式	读取本地注册表	协议请求发现
调用边界	函数调用	JSON-RPC + 传输协议
多语言	需要自己适配	Client/Server 可以异构
主要价值	进程内工具管理	工具接入与复用
没有解决	任务规划、权限、结果验证	任务规划、权限、结果验证

MCP 不是 Agent 的替代品，也不是把任何函数自动变成可靠工具的魔法。它只是把原来散落在每个应用里的“如何连接工具”这部分共性抽出来，变成一套可复用的协议。

七、从 Demo 到生产还缺什么

这个 demo 故意没有 API Key，也没有真实业务副作用。生产 MCP Server 至少还需要：

输入 Schema 和业务层双重校验；
超时、重试和幂等策略；
认证、授权和最小权限；
不把凭据通过环境继承或日志泄露；
对工具结果做真实性和完整性验证；
对 Server、Client、工具调用和错误建立可观测性。

尤其要记住：MCP 的“能调用”不等于业务上的“允许调用”。 文件删除、支付、发邮件、修改生产数据，都需要在协议之外增加权限和人工审批边界。

下一篇：Skill 把“做法”变成资产

现在我们解决了“工具在哪里、怎么发现、怎么调用”。但还有一个问题：工具能调用，不代表 Agent 知道应该如何完成一个复杂任务。

下一篇进入 Skill：把触发条件、步骤、约束、脚本和验证方式封装成可复用能力。工具解决“能做什么”，Skill 解决“应该怎么做”。

参考资料与实测记录

Model Context Protocol 官方 Python SDK（Python 3.11.15、mcp[cli]==2.0.0，本轮验证记录：2026-08-21）
MCP Python SDK Client Transports（STDIO 传输说明，本轮核对：2026-08-21）
Model Context Protocol 官方 Java SDK（Java 21、SDK 2.0.0，本轮验证记录：2026-08-21）
MCP Java SDK Client（STDIO Client 与工具调用 API，本轮核对：2026-08-21）
MCP Java SDK Server（STDIO Server 与 Tool Specification，本轮核对：2026-08-21）

第九话｜Skill 系统：把做法变成资产

Fri, 19 Jun 2026 00:00:00 +0000

第八话里，工具接入终于有了统一的边界。

Agent 想查天气，可以调用 MCP Server；想读数据库，也可以通过同一套协议发现和调用工具。工具来自另一个进程、另一种语言，甚至另一个团队时，调用方不必再为每一项能力重写适配代码。

可一个任务通常不只缺一个工具。

让 Agent 检查一篇文章，它也许找得到文件检查工具，却不知道应先看 frontmatter 还是标题；它也许发现了错误，却不知道能否直接改原文；它也许完成了几步操作，却没有明确的完成判定。工具越来越多，“应该怎样把事情做完整”反而更值得被固定下来。

先说结论：

MCP 解决“Agent 能调用什么”，Skill 解决“Agent 应该按什么方法完成任务”。

Skill 不是把 Prompt 写得更长。它把一套经过思考的方法拆成能被发现、按需加载、执行和验证的资源。

一、工具暴露动作，Skill 组织方法

假设我们有一个 Markdown 检查工具。它能接收文件路径、返回检查结果，也许还支持修复参数。这些信息足以描述一个动作，却不能自动给出一条可靠的任务路径。

任务问题	单个工具通常能否回答
检查哪个文件	可以
先检查 frontmatter 还是标题	不一定
失败后是否继续	不一定
能否直接修改原文	不能替代权限约束
什么结果算任务完成	需要额外规则

这和 Java 服务里已经注册了一组接口很像：checkFrontmatter()、checkHeading()、checkLinks() 都可调用，并不等于“文章质量检查”这个业务流程已经存在。顺序、分支、验收标准和修改权限仍需要被组织起来。

关键洞察：工具把能力暴露出来，Skill 把能力组织成方法。

二、一个 Skill 到底保存了什么

人说“我会检查博客文章”时，脑中通常不只是一句提醒，还包括适用场景、检查步骤、参考标准、可以交给脚本的部分，以及失败时应如何收尾。

Agent Skills Specification 规定，一个 Skill 至少是包含 SKILL.md 的目录；scripts/、references/ 和 assets/ 都是按任务需要才加入的可选资源。真正重要的不是目录长相，而是把原本藏在人脑中的做法，拆成可审阅、可替换的职责。

图中有一个容易被忽略的顺序：先用 name + description 判断这个 Skill 是否相关；匹配后才加载 SKILL.md；执行时再按需要读取参考资料、调用脚本或复用资产。目录的作用不是堆文件，而是让不同类型的知识在恰当的时机进入任务。

一个过于抽象的写法往往没有可执行性：

# Markdown 质量检查

请认真、全面地检查文章。

下面这种写法才把“做事方法”落到了可操作的层面：

---
name: markdown-quality
description: Check Markdown articles for required frontmatter, one H1 title, and a closing summary.
---

1. 读取 `references/checklist.md`。
2. 运行 `scripts/validate.py <markdown-file>`。
3. 报告每条失败规则和可操作的修复建议。
4. 未经明确请求，不修改文章。

差别不在于后者更长，而在于它明确了输入、步骤、确定性工具、输出和权限边界。

三、Skill 如何被发现，又为何不必一次读完

一个 Agent 不需要在每次任务开始时，把所有 Skill 的全部说明、资料和脚本都塞进上下文。官方 Quickstart 把过程拆成发现、激活和执行：启动时先看到技能的 name 与 description；任务匹配后再读取完整 SKILL.md；真正执行时才访问需要的资源。Agent Skills Quickstart

这张图描述的是分层加载，而不是某个模型保证会做出的路由决定。description 写得太泛，匹配阶段就缺少足够线索；把无关资料全塞进入口文件，又会让每次执行背负不必要的上下文。一个好的描述更像服务注册中心里的服务名片：它不执行业务，却决定调用方能否先找到正确入口。

关键洞察：Skill 的入口要足够具体以便被发现，细节则应在真正需要时才加载。

四、动手：运行一个最小 Skill Host

这一节不模拟 LLM 推理，也不声称模型一定会选择正确 Skill。它只把一个 Skill Host 的协议边界固定下来：扫描 frontmatter、按 description 做最小匹配、加载指令、调用确定性验证脚本。

代码位于 GYA 的 c09-skill-system：

c09-skill-system/
├── main.py
├── skills/
│ └── markdown-quality/
│ ├── SKILL.md
│ ├── references/checklist.md
│ └── scripts/validate.py
└── samples/
 ├── good.md
 └── bad.md

运行环境只有 Python 3.9+，不依赖第三方包，也不需要 API Key：

git clone https://github.com/renxin2024/GYA.git
cd GYA/c09-skill-system
python3 main.py

2026-08-22 在 Python 3.9.6 上的实际输出如下：

[discover] markdown-quality
[match] markdown-quality
[load] SKILL.md + references/checklist.md
[validate] good.md -> PASS: frontmatter=ok h1=1 summary=ok
[validate] bad.md -> FAIL: frontmatter must be delimited by ---; missing closing section: ## 总结
[validate] passed=1 failed=1 (expected)
[result] status=PASS

这里最后的 status=PASS 不表示两份样例都合格。它表示 Host 的验收条件被满足：合格样例通过，故意损坏的样例被拦截。把“验证器工作正常”和“被验证对象合格”分开，是写 Skill 时很重要的工程习惯。

如果运行结果不同，先按下面顺序排查：

确认当前目录是 GYA/c09-skill-system，否则 main.py 找不到相对路径下的 Skill 和样例。
确认使用 Python 3.9+；本 demo 使用了 Python 3.9 开始支持的内置泛型类型标注。
检查 skills/markdown-quality/SKILL.md 是否保留了 references/checklist.md 这一引用；demo 会把缺少该引用视为无效 Skill。

五、哪些工作交给模型，哪些交给脚本

Skill 不等于“把所有步骤都交给脚本”。模型仍然适合开放判断，例如观点是否清楚、语气是否自然、解释是否遗漏读者前提。脚本更适合结果只有明确对错的事情。

工作	更适合的职责方	原因
判断文章观点是否清楚	模型	需要语义理解与上下文判断
判断语气是否自然	模型	需要综合语言和读者语境
统计 H1 数量	脚本	可得到稳定的确定性结果
检查 JSON 能否解析	脚本	成功或失败有明确判定
检查文件是否存在	脚本	不需要模型猜测
删除文件、发送消息、部署	权限系统与人工审批	正确性不等于被授权

模型处理语义，脚本锁住不应漂移的事实，权限系统控制不可逆影响。Skill 的价值正是在任务层把这三类职责串成一条可检查的方法，而不是把其中任何一类神化成万能方案。

六、Prompt、Memory、MCP、Skill 各自解决什么

这几个词经常同时出现在 Agent 架构里，但它们回答的问题不同。

能力	保存或提供什么	主要回答的问题	不能替代什么
Prompt	当前任务的即时指令与上下文	“这次希望我怎样回答？”	可复用工作流与长期事实
Memory	过去的事实、偏好或经验	“上次我们决定了什么？”	工具接入和任务方法
MCP	可发现、可调用的工具与资源	“现在能做什么？”	步骤、验收和权限策略
Skill	完成一类任务的方法与边界	“这件事应该怎样完成？”	模型推理、外部工具本身和授权

在一个真实任务里，Memory 可以补充用户偏好，MCP 可以提供读写外部系统的工具，Skill 可以规定检查流程，Agent Loop 负责推进步骤，脚本负责验证局部结果。它们相互协作，但不应互相冒充。

七、从 demo 到生产，Skill 还要补什么

把 SKILL.md 写出来只是起点。一个错误的 Skill 可能让 Agent 更稳定地执行错误流程，所以生产环境至少还要补上几件事：

用真实样例检验它是否会在该触发时被发现；
用故意失败的样例确认验证器真的能拦住错误；
为规则变化保留版本和原因；
将写文件、发消息、发布、部署等高影响动作放在明确的权限边界后；
记录执行轨迹，把重复失败沉淀为下一版规则。

这些是从本文 demo 推导出的工程实践，不代表这个几十行的示例已经具备完整生产能力。它的职责只有一个：让“发现—加载—执行—验证”的边界变得可见、可运行、可讨论。

结尾：方法也应成为可复用的能力

第八话解决了工具如何标准化接入；第九话继续回答工具接入之后的事：怎样把经过验证的做法保存下来，让下一次任务不必从零猜测。

当 Agent 既能调用工具，又能复用方法时，新的追问自然出现：这些推理和行动方式又是怎样一步步演化出来的？下一篇，我们沿着 CoT、ReAct、Toolformer、Reflexion、Voyager 到 SWE-Agent 的线索继续往前看。

理解检验

如果一个 Skill 只有 SKILL.md，没有脚本和参考资料，它仍然可以成立吗？为什么？
为什么“验证器通过”和“被验证对象通过”不能混为一谈？
当一个任务需要读取用户偏好、调用文件工具、并检查输出格式时，Memory、MCP、Skill 和脚本各自承担什么职责？

参考资料

Agent Skills Specification：Skill 的最小目录、frontmatter、可选资源与渐进加载约定。
Agent Skills Quickstart：发现、激活和执行的最小示例。
GYA 第九话 demo：本文配套的最小 Skill Host；本文运行记录验证日期为 2026-08-22。

第十话｜Agent 理论发展脉络：从 CoT 到 SWE-Agent

Mon, 29 Jun 2026 00:00:00 +0000

Agent 不是“更强的提示词”，也不是把模型接上终端。它是一组逐层补齐的能力：推理、行动、工具使用、反馈、可复用经验，以及适配真实环境的接口。

这条线从 CoT 延伸到 SWE-agent。把六篇论文按“上一步已经解决了什么，人们接下来还想要什么”来读，名词表就会变成一张工程问题地图。

先给结论：六篇论文，六个能力缺口

论文	它回答的问题	留给工程的能力
CoT	复杂问题如何不只猜最终答案？	显式中间推理
ReAct	推理如何接触外部环境？	Thought → Action → Observation 循环
Toolformer	模型如何知道何时、怎样用 API？	工具使用的学习问题
Reflexion	一次失败如何影响下一次尝试？	语言化反馈进入后续上下文
Voyager	成功行为如何不必每次重学？	可执行 Skill 的积累与复用
SWE-agent	代码任务环境怎样才适合 Agent 使用？	面向 Agent 的软件接口（ACI）

它们不是六个互相替代的框架。更准确地说，后面的研究把 Agent 放进了更长、更真实的任务链条。

CoT：先把“答案”拆成过程

对于多步计算或符号推理，直接要求最终答案，系统无法暴露中间哪一步出了问题。Chain-of-Thought Prompting 的做法是提供“问题—中间推理—答案”的示例，让模型生成中间步骤再到达结论。

论文报告，在 GSM8K 等任务上，540B 参数的 PaLM 配合 8 个 CoT 示例取得了当时的领先表现。这是论文在特定模型与 few-shot 设置下的结果，不是所有模型都会自动获得的保证。Chain-of-Thought Prompting

CoT 解决的是“如何展开思考”。它没有让模型查询数据库、读取网页或运行程序；一条流畅的推理链仍可能建立在错误前提上。

关键洞察：CoT 让答案过程可见，但还没有让推理接受环境校验。

ReAct：把环境反馈送回下一轮推理

当问题依赖外部事实或真实操作时，人们自然会想：模型能不能先判断缺什么，再行动，再根据结果决定下一步？

ReAct 将 reasoning traces 和 actions 交织：模型输出 Thought 与 Action，运行时执行 Action 并返回 Observation，Observation 再成为下一轮 Thought 的输入。ReAct

论文在问答、事实验证及交互任务上评估该范式；在只给 1～2 个 in-context 示例的设置中，论文报告 ReAct 在 ALFWorld 与 WebShop 上相对相关基线分别有 34 与 10 个百分点的绝对提升。该数字只描述论文的对应实验，不能外推为任意 Agent 的成功率。ReAct

这也是工程里常见的 Agent loop：LLM → Action → Tool → Observation → LLM。重点不是把输出格式命名为 Thought，而是 Observation 必须来自可执行的外部环境。

关键洞察：CoT 让模型解释自己的思路；ReAct 让思路能够被现实结果修正。

Toolformer：把“能调工具”与“会用工具”分开

ReAct 描述了推理与行动如何交替，但仍有一层问题：模型如何判断要不要调用工具、选择哪一个 API、填哪些参数，以及如何使用返回值？

Toolformer 研究的正是这种自监督的工具使用学习：模型学习 API 的调用时机、参数与结果整合。Toolformer

这与今天工程里常说的 Function Calling 或 MCP 不能混为一谈：

层次	关注点
ReAct	推理、行动、观察如何组成一个运行循环
Toolformer	模型如何学习 API 使用行为
Function Calling API	应用怎样接收结构化调用请求
MCP	Agent 客户端怎样与工具提供方建立标准连接

所以，tool_calls JSON 解决的是接口表达；它不等同于模型已经具备可靠的工具选择能力。一个工程系统仍要负责执行、校验参数、限制权限，并把结果回填到上下文。

关键洞察：协议让工具“可被调用”，学习与运行时设计才决定工具“会不会被正确调用”。

Reflexion 与 Voyager：经验要么成为反馈，要么成为资产

一个 ReAct 轨迹结束后，下一次类似任务能否少走弯路？Reflexion 的答案是把外部反馈转写为语言反思，保存为 episodic memory，在后续尝试时作为上下文使用；它并不要求更新模型权重。Reflexion

论文在 HumanEval 的特定设置中报告 91% pass@1，并以其中的 GPT-4 对照结果 80% 作比较。这个数字属于论文实验条件，不能当作当今模型或任意实现的通用结论。Reflexion

Voyager 再往前走一步：在 Minecraft 中结合自动课程、不断增长的可执行 Skill Library，以及环境反馈、执行错误与自我验证的迭代提示，让完成过的行为可被再次调用。Voyager

Reflexion 主要留下“下次应该注意什么”的语言反馈；Voyager 的 Skill Library 试图留下“已经会做什么”的可执行资产。两者都不是企业平台的现成蓝图：前者需要控制反思的质量与检索，后者的 Minecraft 结果也不能直接等同于业务系统。但它们明确了经验积累的两种工程形态。

关键洞察：反馈能减少重复犯错；被验证、可调用的行为才可能成为 Skill。

SWE-agent：能力还取决于 Agent 看见怎样的界面

把 Agent 放进代码仓库，任务不再只是回答：它要逐步浏览文件、搜索符号、局部修改、运行测试、读取报错，再决定是否继续。此时“给一个万能 shell”并不必然带来稳定的任务推进。

SWE-agent 提出 Agent-Computer Interface（ACI），讨论为仓库浏览、编辑与测试等活动设计更适合 Agent 的交互界面。论文在其评测设置中报告 SWE-bench 12.5% 和 HumanEvalFix 87.7% 的 pass@1；这些数值同样受模型、提示、接口和评测版本约束。SWE-agent

关注点	不利于 Agent 的接口	面向 Agent 的接口目标
浏览代码	一次返回大量无关内容	支持逐步定位与搜索
修改文件	整文件覆盖、难以审查	局部且可验证的编辑
执行测试	只有成功或失败	返回可定位、可继续推理的反馈
权限边界	任意命令直接执行	明确能力范围与审计点

这把讨论从“模型是否够聪明”推进到“环境是否给了恰当的可观察性与可操作性”。对于 Coding Agent，工具颗粒度、输出格式、沙箱和测试反馈都是能力的一部分。

关键洞察：Agent 的性能不只来自模型，也来自它能够安全、清楚地感知和操作的环境。

动手：跑一遍可验证的 ReAct 控制流

配套 demo 位于 GYA/c10-agent-theory-timeline。默认是离线 replay，Python 3.9+、无第三方依赖、无 API Key；它验证控制流，不模拟论文 benchmark，也不声称调用真实模型。

git clone https://github.com/renxin2024/GYA.git
cd GYA/c10-agent-theory-timeline
python3 main.py

本次以 python3 --version && python3 main.py 实际运行，输出如下：

Python 3.9.6
[Thought] I need an external fact before answering.
[Action] lookup({"query": "capital of France"})
[Observation] Paris is the capital and most populous city of France.
[Final Answer] The answer is Paris is the capital and most populous city of France.
[check] actions=1 observations=1 terminated=final_answer

跑通标准不是记住“巴黎”，而是看到一次 Action → Observation → Final Answer 的闭环。若执行时出现语法错误，请确认 python3 --version 不低于 3.9；若使用 --live 报 DEEPSEEK_API_KEY is required，这是正常的运行时保护，需配置密钥以及兼容的 LLM_API_URL、LLM_MODEL。本文未运行 --live，因此不报告其输出或效果。

下一步：按能力缺口设计，而不是按论文堆组件

读这条脉络时，最有用的问题不是“下一篇 Agent 论文叫什么”，而是：当前任务到底缺少推理展开、外部观察、工具选择、失败反馈、可复用 Skill，还是环境接口？

这个判断决定你该改 prompt、工具契约、记忆策略、Skill 流程还是执行环境。知识检索与 RAG 是另一条专题路线，本文不展开。

下一篇将从 Agent 运行轨迹出发，讨论怎样把反复出现、且已经验证过的做法沉淀为新 Skill。

理解检验

为什么 CoT 的中间步骤不能替代 ReAct 的 Observation？
为什么 Function Calling 的 JSON 契约不等于 Toolformer 的研究问题？
Reflexion 的语言反馈与 Voyager 的可执行 Skill 分别留下了什么？
面对一个不稳定的 Coding Agent，为什么先审视 ACI 可能比先换模型更有效？

参考资料

第十一话｜ReAct、Plan-and-Execute 还是 Workflow：Agent 的下一步由谁决定？

Tue, 01 Sep 2026 00:00:00 +0000

先把话挑明：这篇不教你搭博客写作工作流，也不给 ReAct、Plan-and-Execute、Workflow 排座次，只回答一个问题——Agent 的下一步由谁决定，谁才能真正让它停下来。

下面反复出现的“写博客”，只是一件切题标本：它自带审批门和写文件的副作用位点，正好能把“谁决定下一步”照清楚。故事是博客，题目是控制权。

写 Skill 的时候，你加了一条流程规则：先生成创作纲领，然后停下等用户确认，确认通过前不准写正文。

运行起来，Agent 却照常往下冲：生成完纲领，下一秒就去写草稿，或者干脆在循环里来回打转。

是模型没读懂 Skill 吗？不全是。真正的问题是——“停下来等确认”这件事，根本不归 Skill 管，也不归模型管，它归运行时代码管。

Agent 的三种流行组织方式，ReAct、Plan-and-Execute、Workflow，本质区别不是“会不会调 LLM”，而是：下一步行动由谁决定，谁才能真正把这一次 Run 停下来。

结论先放这里：模型提建议，代码做决定。

先把“决定”这个词拆开

我们通常说“Agent 决定下一步”，这句话其实把三件不同的事揉在了一起：

层	它做什么	类比后端系统
模型	输出动作建议或内容，例如“下一步 `write_draft`”	业务 Service 提一个方案
运行时 Runtime	决定暴露哪些动作、采纳哪条建议、走哪个状态迁移	应用网关 / 策略层
执行器 Executor	真正产生副作用：写文件、发请求、改数据库	DAO / Outbox 写库

%%{init: {'theme':'neutral'}}%%
flowchart LR
 LLM[模型] -->|建议动作| RT[Runtime]
 RT -->|暴露可见动作| EX[Executor]
 EX -->|副作用| GW[Action Gateway]
 GW --> OUT[虚拟产物]
 RT -->|固定迁移| WF[Workflow 状态]

读了这张图，很多“Agent 不可控”的困惑会自动解开：模型负责“说”，不负责“做”。 它可以说出 write_draft，但要不要做、什么时候做、做之前过几道闸门，由 Runtime 和 Executor 这一侧决定。

关键洞察：控制权不是一句“用了 Workflow”或“用了 StateGraph”就自动获得；它分散在“动作可见性、状态迁移、副作用网关”三处，每一处都必须有代码接手。

同一个任务，三种跑法

用一个故意制造矛盾的隔离任务，把三种模式各跑一遍。任务只有两条规则，还互相打架：

规则一：先创建创作纲领并等待用户确认。规则二：不要停下来，直接写出完整草稿。

任务跑在内存里的虚拟文章存储上：不写公开博客、不提交 Git、不部署。三种模式跑同一段任务，区别马上出来：

模式	每一步谁决定	模型可见动作	谁能真正停	本次真实结果
ReAct	模型看着 Observation 选下一动作	全部动作	只有 `finish` 或步数上限	连走三次 `create_brief`，`draft_written=false`，从未进入等待
Plan-and-Execute	模型先出一份计划，Executor 顺序执行	计划内的动作	计划文本里的“等待”停不住	计划含 `await_brief_approval`，Executor 仍尝试 `write_draft`，被网关拦下
Workflow	代码写死状态迁移，模型只生成当前节点内容	当前节点需要的内容生成	状态机 `return`/迁移	生成纲领后直接 `run_suspended`，Trace 里根本没有 `write_draft`

有个反直觉的点：三种模式其实都调了 LLM。 所以别再用“Workflow 不智能、ReAct 才智能”来区分它们。区别只在控制权：ReAct 把“下一步”反复交给模型；Workflow 把“下一步”收回到代码。

所以选型的第一问是——“这一步由谁拍板才安全、才够用”，而不是“哪个听起来更像 Agent”。

先跑起来：最小对照

不写框架，先写一个十秒看懂的最小实验。它只演示一件事：把 waiting 改成 True，不等于让循环停下。

下面是完整可粘贴的 Python，不需要 API Key：

"""“等待”是数据标记，还是控制信号？最小对照。"""
from __future__ import annotations

APPROVED = False


def gateway(action: str) -> str:
 if action == "create_brief":
 return "brief_created_in_virtual_store"
 if action == "wait_for_approval":
 return "wait_marker_recorded"
 if action == "write_draft":
 if APPROVED:
 return "draft_written_to_virtual_store"
 return "blocked_by_action_gateway"
 return "unknown_action"


def run_naive() -> None:
 steps = ["create_brief", "wait_for_approval", "write_draft"]
 waiting = False
 events = []
 for action in steps:
 result = gateway(action)
 if action == "wait_for_approval":
 # 只改了一个布尔值，循环不会因此停。
 waiting = True
 events.append((action, result))
 draft_written = any(r == "draft_written_to_virtual_store" for _, r in events)
 print(f"[naive] waiting={waiting} draft_written={draft_written}")
 for action, result in events:
 print(f" {action:18s} -> {result}")


def run_suspending() -> None:
 steps = ["create_brief", "wait_for_approval", "write_draft"]
 waiting = False
 events = []
 for action in steps:
 result = gateway(action)
 if action == "wait_for_approval":
 waiting = True
 events.append((action, "run_suspended"))
 print(f"[fix] waiting={waiting} draft_written={False}")
 for a, r in events:
 print(f" {a:18s} -> {r}")
 return # 真正的“停”：后面的 write_draft 根本不会被循环碰到
 events.append((action, result))


if __name__ == "__main__":
 print("== 错误版：像 Plan-and-Execute 的朴素 Executor ==")
 run_naive()
 print()
 print("== 修复版：Workflow 的状态机迁移 ==")
 run_suspending()

跑一遍，输出如下：

== 错误版：像 Plan-and-Execute 的朴素 Executor ==
[naive] waiting=True draft_written=False
 create_brief -> brief_created_in_virtual_store
 wait_for_approval -> wait_marker_recorded
 write_draft -> blocked_by_action_gateway

== 修复版：Workflow 的状态机迁移 ==
[fix] waiting=True draft_written=False
 create_brief -> brief_created_in_virtual_store
 wait_for_approval -> run_suspended

读输出的判断标准：错误版里 waiting=True 和 write_draft 同时出现——它“认为”自己在等待，却还在往下执行；修复版里 run_suspended 出现后，write_draft 从 Trace 里直接消失。这才是“停”。

三种模式的真实 Trace

把三段真实模型 Trace 缩到关键行。完整实验在配套代码仓库的 Python 与 Java 两个子目录里各有一份。

离线回归（不调模型，只验证控制流）：

cd python
python3 -m unittest -v
# Ran 8 tests in 0.000s
# OK

真实模型（需先导出 LLM_API_URL、LLM_MODEL、LLM_API_KEY，Key 只从环境变量读取）：

python3 control_modes.py --live

本轮 Python 真实输出（节选，共三段）：

# ReAct：模型每步都选 create_brief，从不进入等待
[trace] {"mode":"react","step":1,"decision_maker":"llm","action":"create_brief",...}
[trace] {"mode":"react","step":2,"decision_maker":"llm","action":"create_brief",...}
[trace] {"mode":"react","step":3,"decision_maker":"llm","action":"create_brief",...}
[summary] {"mode":"react","waiting_for_approval":false,"draft_written":false,"usage":{"total_tokens":427}}

# Plan-and-Execute：计划里有 await，Executor 仍尝试写稿，网关拦下
[trace] {"mode":"plan_and_execute","step":0,"decision_maker":"plan_validator","result":"ACCEPT"}
[trace] {"mode":"plan_and_execute","step":2,"decision_maker":"executor","action":"await_brief_approval","result":"wait_marker_recorded"}
[trace] {"mode":"plan_and_execute","step":3,"decision_maker":"executor","action":"write_draft","result":"blocked_by_action_gateway"}
[summary] {"mode":"plan_and_execute","waiting_for_approval":true,"draft_written":false,"usage":{"total_tokens":142}}

# Workflow：代码固定迁移，模型从未见过 write_draft
[trace] {"mode":"workflow","step":1,"decision_maker":"llm","event":"generate_brief",...}
[trace] {"mode":"workflow","step":2,"decision_maker":"workflow","action":"WAITING_FOR_APPROVAL","result":"run_suspended"}
[summary] {"mode":"workflow","waiting_for_approval":true,"draft_written":false,"usage":{"total_tokens":203}}

三段摆在一起，结论是确定的：

ReAct 能停吗？ 能，但停的条件由模型选中的 finish 或代码给的最大步数决定；“等待”不在它自动遵守的条件里。
Plan-and-Execute 能停吗？ 计划里写了 await_brief_approval，但朴素 Executor 把它当普通动作执行——只改状态、继续下一步，最后靠 Action Gateway 拦下 write_draft 的副作用，可 Executor 并没有因此停，它仍往下走到 finish。
Workflow 能停吗？ 当前节点生成内容后，代码把下一状态固定成 WAITING_FOR_APPROVAL 并结束 Run；模型连 write_draft 这个动作都没被暴露。

关键洞察：await 写在计划里是数据，只有 break / return / 状态机迁移 才是控制。指望模型或 Planner 在文本里“自觉地停下来”，就是把安全押在概率上。

外层 Workflow，内层 ReAct

既然 Workflow 最可控，ReAct 最灵活，生产里怎么选？

答案是分层，而不是二选一。一个可信的技术文章 Agent 可以长这样：

Workflow 固定阶段：
 0. 准备材料 ──> 1. 生成纲领 ──> [等待审批] ──> 2. 生成梗概 ──> [等待审批] ──> 3. 写草稿
 ^
 |
 探索节点（ReAct）：搜证据、读源码、判断“材料够不够”，直到确定性条件达成

外层用 Workflow 锁阶段和硬边界：未达到 WAITING_FOR_APPROVAL，后面的阶段就不存在，模型没机会跳到“写草稿”。
内层用 ReAct 降低不确定性：一个“读懂这个仓库再写梗概”的开放任务，让模型多走几步、看 Observation，比死板的一次性流程更实用。
任务清晰后再交给 Planner/Executor：计划进入 Executor 前先用确定性校验器检查结构、动作白名单和审批顺序；LLM 可以辅助语义判断，但硬规则必须由代码执行——校验器只返回 ACCEPT / REVISE / REJECT，不替模型悄悄改计划。

这里有个很容易被模糊的点：“能不能进计划”由谁判？

不要让模型直接回一个 ready: true。那是模型自我声明，等于让它自己给自己批作业。正确的分工是：

LLM 交结构化证据：已调研了哪几项、还剩哪几项没做、每项的依据是什么。
Runtime 按校验契约算布尔：条件满足才算 ready，证据缺失就补齐或换策略。

这就是“模型提建议，代码做决定”在 readiness 上的具体落法。

关键洞察：给开放任务留 ReAct，给高风险边界上 Workflow，再把“能不能切换阶段”写成运行时契约；三者不是竞争关系，是一条流水线上的不同工位。

Workflow 该不该上框架

也许你已经想到 LangGraph 这类框架：它能不能把上面这些自动解决？

能解决一部分，但要分清“能力”和“承诺”。LangGraph 的文档把两件事分开：Workflow 走预定义的代码路径，Agent 每一步由模型动态决定过程；它用状态图、checkpointer、interrupt() 提供挂起、保存状态和外部命令恢复的实现能力。这些能力正好是第十二话要做“可恢复、不可绕过的审批”的原料。

但它不会因为你用了 LangGraph，就自动保证审批合规。状态图上的节点连得通，不代表业务上这一段就该执行。publish_article 这种迁移在不允许发布的状态下必须由运行时拒绝——框架给你的是“状态图能跑”，不给你“业务边界天然正确”。

所以这一话只把 LangGraph 标记为实现方向，不展开 API。下一步要去的地方，就是把“接下来该做什么”从人工解读变成可以被恢复、被拦截、被审计的运行时机制。

一句话收口：框架替你搬运状态，不替你决定业务。安全边界只能来自你写的校验契约和动作网关。

下一话：Skill 只是提示词——如何让 Agent 真正停下来，并且跨进程可以恢复、无法绕过审批。

踩坑速查

症状	原因	解法
`--live` 报 `LLM network error` / DNS 解析失败	沙箱或本地网络到模型 API 不通	用离线 `python3 -m unittest -v` 先验证控制流；真实调用再解决网络/代理
模型返回值解析失败或 `content` 为空	部分推理模型默认 thinking，`content` 在 reasoning 里	显式 `thinking:{"type":"disabled"}` 并要求 JSON 输出
Java 运行报 `UnsupportedClassVersionError`	用了旧版 JDK	用 JDK 21 + `./gradlew`，或直接 `javac/java` 跑 `MinimalSuspendDemo`
计划里写了“等待”，运行时不暂停	把等待当成了数据标记	改成 `return`/`break`/状态机迁移，并写进回归测试

参考

LangGraph Documentation, “Workflows and Agents”, https://docs.langchain.com/oss/python/langgraph/workflows-agents/（Workflow 与 Agent 的路径决定方式，成文时已核对）。
LangGraph Documentation, “Interrupts / Human-in-the-loop”, https://docs.langchain.com/oss/python/langgraph/interrupts/（interrupt()+checkpointer 的挂起恢复能力，本篇只作方向标记）。
本话演示代码与回归测试：配套代码仓库中的 python/control_modes.py、java/.../Main.java、java/.../MinimalSuspendDemo.java。

第十六话｜SSE 是什么？为什么它会用在 AI Agent 开发中

Fri, 28 Aug 2026 00:00:00 +0000

前面把 Agent 的循环、状态、记忆和工具接起来之后，用户仍可能面对一个黑盒。

他发出“帮我检查这个仓库的测试为什么失败”，页面却在几十秒内没有任何变化。Agent 也许正在生成，也许正在调用工具，也许已经失败；用户无从分辨。

问题出在传输方式上：普通 HTTP 是一问一答——客户端发一个请求，服务端算完最后一次性返回完整响应。Agent 干活要几十秒，响应就空白几十秒。要让 Agent 不再像黑盒，前端不只需要最终答案，还要持续接收文本增量、工具状态和 Run 的终态。

SSE（Server-Sent Events）就是把这类服务端到浏览器的连续事件放进 HTTP 的一种标准方式。结论先说：SSE 不负责让 Agent 变聪明；它负责把 Agent 已经发生的事，按事件边界可靠地呈现给 UI。

一、旧方案为什么看不见

“给我一个答案”用普通 HTTP 正合适：提交命令，取回结果，一次交互结束。但“让我看着你干活”不行——服务端在没有完整结果前不会返回响应，浏览器也就拿不到任何进度。

要让用户看见进度，服务端必须在计算完成前就开始输出，并且持续输出。这正是 SSE 站在 HTTP 上的理由：一个响应保持打开，服务端不断写入“有边界的小段文本”。

这里有个经常被混在一起的概念要拆开说清楚。HTTP 持久连接（persistent connection / Keep-Alive）指的是底层连接可以复用、承载多次请求响应，它降低建连成本，但服务端不会在没有新请求时主动推送业务消息。RFC 9112 §9.3 长轮询是应用层写法：服务端先不立即返回，等到有数据或超时才结束响应，浏览器收到后再发起下一次请求。它们都不等于“一个持续打开、服务端主动下推的响应”。

四种常用方式的层次差别，一张表就能看明白：

方式	它解决什么	通信方向	一次交互是否持续	Agent 中合适的职责
普通 HTTP	提交命令、取得一次结果	双向，但一问一答	否	创建 Run、提交用户输入、取消任务、确认敏感工具调用
HTTP 持久连接	复用底层连接，减少建连成本	仍是多次 HTTP 请求/响应	否	通常由客户端、网关和连接池处理，不是事件通道方案
SSE	服务端持续发送有边界的文本事件	服务端 → 浏览器	是	文本增量、工具进度、Run 状态、最终结果
WebSocket	持续的双向消息	双向	是	协同编辑、高频客户端指令、双方都需随时发消息的交互

WebSocket 与 HTTP 的关系也要说准确：它用 HTTP Upgrade 完成开场握手，握手成功后双方交换的是 WebSocket 帧，而不是继续交换 HTTP 响应体。RFC 6455 §4

关键洞察：持久连接是连接复用策略；SSE 是 HTTP 上的事件流格式；WebSocket 是经 HTTP 握手切换出的双向协议。它们不在同一抽象层。

二、亲眼看：SSE 在线上传了什么

浏览器用 EventSource 发起请求，服务端以 Content-Type: text/event-stream 返回响应，并持续写入按行组织的 UTF-8 文本。每个事件以空行结束。WHATWG HTML Standard §9.2

下面是一个完整事件，不是一段“随便输出的文本”：

id: 42
event: text.delta
data: {"runId":"run_123","delta":"正在读取测试报告…"}

四个常用字段的职责如下。

字段	协议层含义	在 Agent 流中的用法
`data`	事件数据；可以多行，浏览器会按规范合并	放 JSON payload，例如文本增量或工具结果摘要
`event`	事件类型；省略时是默认 `message`	区分 `text.delta`、`tool.started`、`run.completed`
`id`	更新浏览器保存的最后事件 ID	用作断线续传的游标；服务端仍需校验 Run 归属
`retry`	建议浏览器下一次重连前等待的毫秒数	仅调整重连等待，不解决事件去重或业务恢复

注意最后一行的空行不是装饰。它是事件边界：如果连接在空行前结束，尚未完成的事件不会被分发。WHATWG HTML Standard §9.2.5–9.2.6

浏览器端不需要自行解析每一行：

const source = new EventSource(`/runs/${runId}/events`);

source.addEventListener("text.delta", (event) => {
 const { delta } = JSON.parse(event.data);
 appendAssistantText(delta);
});

source.addEventListener("run.completed", () => {
 source.close();
});

EventSource 对断开连接具备重连处理，并在已有事件 ID 时把 Last-Event-ID 带回服务端。它提供的是恢复的协议钩子，不是“消息恰好一次送达”的保证；应用仍要定义续传、去重和终态行为。WHATWG HTML Standard §9.2.3–9.2.4

三、事件的形状由业务决定：Agent Run 事件契约

只把模型 token 一段段传到 UI，用户会看到“它在说话”，但仍不知道它是否在行动。

对一个会调用工具的 Agent，更有用的做法是把 Run 生命周期投影成一组应用层事件：

例如，“检查测试为什么失败”这个 Run 在客户端看来可以是这样一串事件：

event: text.delta
data: {"runId":"run_123","delta":"我先运行测试。"}

event: tool.started
data: {"runId":"run_123","tool":"run_tests","callId":"call_7"}

event: tool.completed
data: {"runId":"run_123","callId":"call_7","summary":"3 个测试失败"}

event: run.completed
data: {"runId":"run_123"}

这些名称不是 SSE 规定的字段值，而是本文建议的业务事件契约。SSE 只规定如何分帧、如何指定事件类型、如何传递最后事件 ID；tool.started 是否存在、数据结构是什么、是否向用户展示工具结果，都由你的 Agent 产品和安全策略决定。

这和 Java 微服务中的“领域事件”和“Kafka 的传输记录”很像：Kafka 不替你定义订单状态机；SSE 也不替你定义 Agent Run 状态机。先定义业务状态和权限边界，再选择传输通道。

四、动手：跑通一条本地 Agent Run 事件流

这一节的 demo 不调用真实模型，避免让 API Key、模型费用或网络问题遮住协议本身。服务端固定模拟一个 Run：它先发送文本增量，再报告工具开始、工具完成，最后发送 Run 完成事件。

配套代码有两份等价实现：Python 位于 GYA 的 c16-sse-agent-stream/，Java 位于 GYA-Java 的同名 Gradle 子模块。正文以 Python 为主，Java 版用于验证同一协议不依赖语言或 Spring 框架。

Python：标准库即可启动

前置环境：Python 3.9+ 与 curl，无第三方依赖、无 API Key。

终端一启动服务：

git clone git@github.com:renxin2024/GYA.git
cd GYA/c16-sse-agent-stream
python3 main.py --once

终端二订阅：

curl -N http://127.0.0.1:8765/events

我在本机实际收到的输出如下：

id: 1
event: text.delta
data: {"runId":"run_demo","delta":"我先运行测试。"}

id: 2
event: tool.started
data: {"runId":"run_demo","tool":"run_tests","callId":"call_1"}

id: 3
event: tool.completed
data: {"runId":"run_demo","callId":"call_1","summary":"3 个测试失败"}

id: 4
event: run.completed
data: {"runId":"run_demo"}

这里最重要的不是 sleep(0.1)，而是每次写完一帧后立刻 flush，并且用最后那个空行完成事件。把空行删掉，再用浏览器 EventSource 接收时，读者会发现它不会把这一帧当作完成的事件。

Java：同一事件流，不换协议

前置环境：JDK 21 与 curl。GYA-Java 使用仓库自带的 Gradle Wrapper；首次运行会按仓库配置下载 Gradle 和 Jackson。

终端一启动：

git clone git@github.com:renxin2024/GYA-Java.git
cd GYA-Java
./gradlew :c16-sse-agent-stream:run --args="--once"

终端二订阅：

curl -N http://127.0.0.1:8766/events

Java 版构建通过，并按相同顺序输出 text.delta、tool.started、tool.completed、run.completed。核心的分帧代码和 Python 同构，只是把字符串拼接换成了 Jackson 序列化 payload：

private static byte[] encode(Event event) throws IOException {
 // SSE 是 UTF-8 的按行协议。最后的空行是事件边界；删除它会让
 // EventSource 持续等待，而不是把前面的字段作为一条完整事件分发出去。
 String frame = "id: " + event.id() + "\n"
 + "event: " + event.type() + "\n"
 + "data: " + JSON.writeValueAsString(event.data()) + "\n\n";
 return frame.getBytes(StandardCharsets.UTF_8);
}

Event 是一个只保存 id、type、data 的 record；EVENTS 里和 Python 一样放着四个固定事件。既然协议的“形状”完全由分帧代码决定，换语言、换框架都不会改变这条事件流的语义——这正是把协议层与业务层分开的价值。

如果 Java 版本因 toolchain 无法启动，先运行 java -version 确认实际环境是 JDK 21。这个 demo 故意保持 Java 21，不为了迁就本机默认 JDK 而降低系列约束。另外，不要把 Python 与 Java 输出的 JSON 键顺序当作正确性标准：JSON 字段顺序不属于 SSE 契约。

五、能连通 ≠ 体验到好：三个坑

连得上、有输出，不代表体验是对的。下面是三个最常见的“能连通、但体验很差”的问题。

1. 服务端在发，用户却最后一次性看到

SSE 需要端到端按事件及时传输。规范明确提醒：不恰当的块缓冲可能延迟事件分发。WHATWG HTML Standard §9.2.5

因此排查顺序不该从“模型为什么这么慢”开始，而应沿着浏览器 → CDN/网关 → 反向代理 → 应用服务器逐跳确认：响应类型是否正确、是否有缓冲、应用是否真的在事件产生时写出。curl 先关掉客户端缓冲（curl -N）；如果 curl 能一帧帧出来、浏览器不行，问题大概率在中间层。具体关闭何种缓冲取决于网关产品和部署方式，不能从一段通用配置照抄。

2. 断线后重复显示，或者漏掉关键状态

浏览器会携带 Last-Event-ID 重连，但服务端必须决定这个 ID 的语义：它是某个 Run 内单调递增的序号，还是全局事件 ID？事件保留多久？补发窗口过期时如何回退？

一个可维护的最小约定是：runId + eventId 唯一；客户端按该组合去重；服务端只允许已授权的主体按 runId 查询或续传。这里的授权检查不能因为客户端带了一个事件 ID 就被跳过。

3. Run 已结束，连接和资源还在等待

run.completed、run.failed、run.cancelled 这类终态应有清晰语义：服务端发送终态事件后结束流，客户端收到后关闭 EventSource 并更新界面。心跳注释可以帮助发现中间链路的空闲超时，但心跳不应伪装成业务进度。MDN SSE 指南

关键洞察：SSE 解决“事件怎样流到浏览器”；事件是否可恢复、可授权、可解释，仍是 Agent Run 模型的责任。

六、回到开场：黑盒变成了可见的事件流

现在回头看开头的那个 Run。“帮我检查这个仓库的测试为什么失败”在 demo 里变成了一条可见的时间线：先是“我先运行测试。”的文本增量，然后是工具开始、工具完成（3 个测试失败），最后 Run 完成。用户不再对着空白页面猜 Agent 是不是卡死了——他能看到 Agent 正在做什么、做到哪了、结果如何。

这就是这一话真正改变的东西：“它在动”从结论变成了过程。 SSE 不负责让 Agent 变聪明，它负责把 Agent 正在做和已经做的事，按事件边界可靠地送到浏览器；之后要不要展示工具结果、要不要拒绝敏感调用，仍然是产品与安全决策。

七、选型：什么时候选 SSE，什么时候不选

如果 UI 的主要需求是“服务端持续告诉用户发生了什么”，SSE 是很自然的第一候选：浏览器有原生 EventSource，协议有事件类型和重连语义，接入普通 HTTP 基础设施的成本通常较低。

如果客户端也需要高频、低延迟地主动发消息，例如多人协同编辑、实时控制面板或双向交互游戏，再评估 WebSocket。若只是提交用户问题、取消 Run 或同意执行高风险工具，普通 HTTP 往往更直观，也更容易把请求、权限校验和审计记录放在清晰的命令边界上。

不要用“WebSocket 更实时”替代选型分析。对 Agent 来说，最关键的问题是：消息主要朝哪个方向流？是否需要浏览器原生重连与事件 ID？你的 Run 是否有可恢复的状态模型？

八、下一步

这一话放在 GYA 的生产级补充位置：它不增加 Agent 的推理能力，却决定用户能否看见、理解和恢复一次正在运行的 Agent 任务。

从开场那个 Run 继续往后走，下一步应把同样的事件契约接到真实的 Run 状态存储、鉴权与可观测性中——而不是继续往 SSE 帧里塞业务判断。

GYA（Get Your Agent） on Renxin's Blog

第一话｜大模型只会补全文字，Agent 的“手脚”是怎么来的？

模型只会补全文字

让它“说”出要干什么

这套做法，其实是 Function Calling 的前身

第二话｜Function Calling：谁把“调用工具”做成了一套协议？

一、协议要解决的，就是上一话那个“脆”

二、协议长什么样：tools 进，tool_calls 出

三、这套协议，是谁先做出来的

四、别看就一个 tool_calls，背后做了很多工作

五、协议只负责“提出”，不负责“执行”

六、把结果交回去，也是协议的一部分

七、回到最开始的问题：到底谁调用了工具？

第三话｜模型为什么能生成工具调用？

一、模型学的，仍然是下一个 token

二、这条“倾向”，是靠什么训练出来的？

三、一件必须分清的事：哪些证据能信，哪些不能

四、Prompt-only 和 Native tools，差的不只是“格式”

五、动手看一次：description 才是“选哪个”的开关

六、所以，能信到什么程度

第四话｜模型说调 refund_order，Runtime 怎么不把事情搞砸？

一、模型说"调 refund_order"，Runtime 先干什么？

二、执行时出了问题，最怕的是"结果说不清"

三、把"谁负责什么"钉死

四、把这条链路跑起来

五、还差的：执行成功 ≠ 永远可靠

到下一话，问题才真正变难

第五话｜ReAct：让模型把「想」和「做」接起来

一、光想不做、光做不想，各有什么毛病

二、ReAct 的答案：把"想"和"做"交替起来

三、工程上怎么承载：一个循环外壳

四、看一次真实的"交替"

五、这一篇停在哪，下一篇往哪走

第六话｜状态管理：从 dict 到 StateGraph

一、旧世界：循环里的状态为什么撑不住

二、转折：显式状态机——State / Node / Edge 三件套

三、原理讲透：为什么状态要"显式"？

四、动手：同一个任务，两种实现

手写版：三节点状态机

LangGraph 版：同一三节点，声明式表达

五、工程化延伸：什么时候该上 StateGraph？

下一步

第七话｜记忆：上下文、短期、长期

一、旧世界：把历史塞进上下文的问题

二、转折：三层记忆——各管一段

三、原理讲透：为什么"不检索的记忆等于不存在"

四、动手：三层记忆 Agent 实测

场景 1：短期记忆补位

场景 2：长期记忆向量检索

场景 3（诚实说明）：Lost-in-the-Middle 实测

五、工程化延伸：生产级记忆系统

下一步

第八话｜MCP 协议：工具为什么需要一根 USB-C

一、旧世界：工具被绑在调用方代码里

二、MCP 把什么放到了协议层

三、STDIO：先把跨进程边界跑通

四、Python：用官方 SDK 跑通 Client/Server

前置环境

五、Java 21：同一个协议，不同的 SDK 表达

前置环境

六、MCP 和第四话 ToolRegistry 的边界

七、从 Demo 到生产还缺什么

下一篇：Skill 把“做法”变成资产

参考资料与实测记录

第九话｜Skill 系统：把做法变成资产

一、工具暴露动作，Skill 组织方法

二、一个 Skill 到底保存了什么

三、Skill 如何被发现，又为何不必一次读完

四、动手：运行一个最小 Skill Host

五、哪些工作交给模型，哪些交给脚本

六、Prompt、Memory、MCP、Skill 各自解决什么

七、从 demo 到生产，Skill 还要补什么

结尾：方法也应成为可复用的能力

理解检验

参考资料

第十话｜Agent 理论发展脉络：从 CoT 到 SWE-Agent

先给结论：六篇论文，六个能力缺口

CoT：先把“答案”拆成过程

ReAct：把环境反馈送回下一轮推理

Toolformer：把“能调工具”与“会用工具”分开

二、协议长什么样：`tools` 进，`tool_calls` 出

四、别看就一个 `tool_calls`，背后做了很多工作