核心结论 :这不是模型在骗你,是你的循环把「说了」当成了「做了」。病根是三处错位------终止信号错位 (拿「没有工具调用」当完成条件)、计划载体错位 (允许模型用散文讲计划,而不是用
tool_use表达)、成功定义错位 (success写在循环退出处,而不是写在验收处)。修法不是换更强的模型,而是四层防线:终止信号、计划载体、空转检测、结果验收。
目录
-
- 一句话结论:循环把「说了」当成了「做了」
-
- 三种「说而不做」的形态
-
- 三个错位:终止信号、计划载体、成功定义
-
- 四层防线总览
-
- 第一层:只认结构化终止信号
-
- 第二层:把计划压成 tool_use
-
- 第三层:空转检测与承诺登记表
-
- 第四层:验收器定义成功
-
- 一张对照表:症状 → 原因 → 解法
-
- 完整可运行代码:先复现 bug,再打补丁
-
- 边界:什么时候不该上这套防线
1. 一句话结论:循环把「说了」当成了「做了」(Said vs Done)
先还原现场 🎯。你给了 Agent 一个任务,它回了一段话:「我会先读取 config.py,把端口改成 8080,然后跑一遍测试。」程序看到这段文字,判定「模型已经给出答复」,退出循环,标记 success = True。
文件没动,测试没跑,端口还是 8000。日志上一片绿。
这个 bug 最迷惑人的地方是它不报错:所有异常路径都平安通过,唯一不对劲的是结果------而结果通常没人立刻检查。
打个比方 🎭:你让助理去银行转账,他回你一句「好的,我准备先去取号、然后填单、最后转账」。你听完这句,就在流程系统里点了「已完成」。他不是在骗你,他只是把话说了;是你的验收标准,把「他描述了流程」当成了「流程走完」。
所以修法分两半:一半是别让「说话」有机会冒充「做事」 ,另一半是别让「循环退出」有机会冒充「任务成功」。
2. 三种「说而不做」的形态(Three Shapes)
同一句「没调用工具」,背后有三种形态 ⚠️:
形态一:叙述式计划。 模型输出「我会先读取 X,然后修改 Y,最后运行 Z」,stop_reason 是 end_turn,一个 tool_use 块都没有。最常见,也最容易被当成正常答复。
形态二:未来时承诺。 「马上为你执行」「接下来我将调用 search 工具」------语气更肯定,内容一样是空的。它甚至点了工具名,看起来更像「已经在做了」。
形态三:空回复或被截断。 官方文档专门写了一条:Claude 有时返回只有 2--3 个 token、实际没有内容 的响应,stop_reason 仍是 end_turn,常见于刚收到工具结果之后;另一种是 max_tokens 截断,此时可能挂着一个不完整的 tool_use 块。两者都不能当完成处理(细节见 §5)。
三种形态的共同点是:程序看到的都是「一轮结束了,没有工具调用」 。如果你的终止条件是 if not tool_calls: break,三种形态会被压成同一个结局。
3. 三个错位:终止信号、计划载体、成功定义(Three Mismatches)
3.1 错位一:终止条件写的是「没动作」,不是「已完成」
这是最核心的一行代码 🔍:
python
if not tool_calls:
return text # 没工具调用 → 当最终答案
这行的隐含语义是「没有工具调用 = 任务完成 」。但在 Agent 里,正确的语义应该是「没有工具调用,且验收通过 = 任务完成」。
差距有多大?若单轮正确调用工具的概率是 p,连续 n 轮不出错的链路成功率是:
Pchain=pn
代入 p=0.95、 n=5: 0.955≈0.7738,单轮 95% 看着很高,五轮下来只剩 77.38% 。要守住 90% 的整体成功率,单轮得做到约 0.98( 0.985≈0.9039)。
这条账说明一个关键判断 🎯:靠换更强的模型治这个病,性价比极低 ------ p 从 0.95 提到 0.98 要换模型、改提示词、重跑评测;加一层终止判断只改十行代码,且对 p 依赖为零。
3.2 错位二:计划的载体选错了通道
模型表达「我打算做什么」有两条通道:文本通道 (说话)和 tool_use 通道 (动手)。默认它更习惯先说话,因为训练数据里「先讲思路再动手」的表达太常见。提示词没写死「计划必须用工具调用表达」,模型就会挑最省力的那条路。这不是模型的缺陷,是你没规定出口 🚪。
3.3 错位三:success 写在了循环退出口
翻一下自己的代码,success = True 这一行大概率出现在 break 附近。这叫控制流即结论:程序把「我没抛异常地退出了」当成「任务成了」。
而该定义成功的地方是结果验收:文件内容变了吗?命令退出码是 0 吗?测试通过了吗?
用医院打比方 🎭:医生写完手术方案,不等于手术做完了。方案是文本,手术是动作,出院小结才是验收。三者混为一谈,病历会很好看,病人却没被治好。
4. 四层防线总览(Four Layers)
四层防线各管一件事,从模型输出排到任务结果:
| 层 | 拦的是什么 | 关键动作 | 失效时的表现 |
|---|---|---|---|
| 第一层 终止信号 | 把「截断 / 拒答 / 空回复」当成完成 | 只按 stop_reason 路由,不看文本 |
半句话被当答案、空回复静默成功 |
| 第二层 计划载体 | 模型用散文讲计划 | 强制 tool_choice、提供 plan 工具、提示词写死二分法 |
反复「我马上执行」但一次不动 |
| 第三层 空转检测 | 「没动作也没完成」的死循环 | 识别计划文本、注入纠正、连续两次判失败 | 烧满轮数、烧满 token,最后超时 |
| 第四层 结果验收 | 循环退出冒充任务成功 | verifier 返回 success / failed / unknown |
日志全绿、文件没动 |
顺序不能换 🔒:先保证「不误判结束」,再保证「不空转」,最后才谈「判得对」。第一层还在把截断当完成,后面三层就没有机会执行。
5. 第一层:只认结构化终止信号(Stop Reason)
Anthropic 用 stop_reason,常见取值如下:
stop_reason |
含义 | 你的动作 |
|---|---|---|
end_turn |
模型自然结束这一轮 | 作为候选答案,交给第四层验收 |
tool_use |
模型在调工具,等你执行 | 执行工具 ,回传 tool_result |
max_tokens |
撞到输出上限,响应被截断 | 视为截断,提高上限重试,禁止当完成 |
stop_sequence |
命中你设置的停止序列 | 读 stop_sequence 判断是哪一条 |
pause_turn |
服务端工具循环达迭代上限 | 把内容原样回传继续 |
refusal |
模型拒绝回答 | 走降级或转人工,别标成功 |
OpenAI 侧对应 finish_reason:tool_calls 对 tool_use、stop 对 end_turn、length 对 max_tokens。
三条铁律 🔒:永远不要写 if text: break ,文本长度不是完成信号;tool_result 必须单独成条 ,带 tool_use 的那轮之后必须紧跟一条只含 tool_result 块的消息,塞额外文本会报错;截断必须能被识别 ,stop_reason 落在 max_tokens 上就提额重试。
还有一个易踩的坑 ⚠️:空回复也可能是 end_turn。此时递一条新的用户消息「请继续」,而不是原样重试------同样的空回复发回去只会再结束一次。
参考资料:
- Stop reasons and fallback -- Claude Platform Docs ⭐值得阅读
- How the agent loop works -- Claude API Docs
- Chat Completions finish_reason 枚举 -- Microsoft Learn
6. 第二层:把计划压成 tool_use(Force the Channel)
第一层解决「别误判结束」,第二层解决「别让它有空说话」。三个手段,侵入性从低到高:
① 提示词写死二分法。 一句话够用:「每一步要么调用工具,要么给出最终答案;不允许只描述计划。若想说明打算怎么做,请调用 plan 工具,而不是写一段话。」
② 提供一个 plan 工具。 最被低估的一招 🎯:把「我打算做什么」也变成工具调用,它就能被程序计数、被 schema 校验、被日志追踪 。文本里的计划是空气,tool_use 里的计划是对象:
json
"steps": {
"type": "array", "minItems": 1,
"items": {
"type": "object",
"properties": {
"tool": {"type": "string", "enum": ["read_file", "write_file", "run_tests"]},
"why": {"type": "string", "maxLength": 60}
},
"required": ["tool", "why"]
}
}
注意 enum 与 maxLength:把自由文本的空间压窄,模型的发挥空间就小了,跑偏概率跟着降。
③ 强制 tool_choice。 在图的第一轮(还什么都没做过时)直接指定必须调某个工具:
python
resp = client.messages.create(
model=MODEL,
max_tokens=2048,
tools=TOOLS,
tool_choice={"type": "tool", "name": "plan"}, # 第一轮只能调 plan
messages=messages,
)
OpenAI 侧对应 required 模式或直接指定 function.name。代价是牺牲一点灵活性,收益是把「要不要动手」从模型手里拿走。在 AI Agent 工具误调用怎么解决 里我讲过参数校验与高危操作二次确认------那是拦住错的调用 ,这里拦的是根本没有调用。
7. 第三层:空转检测与承诺登记表(Idle Detection)
前两层上完还会有漏网的:模型老老实实给了一段计划文本,stop_reason 也是 end_turn,schema 没拦住。这时需要第三层------判它是不是空转,再决定继续还是放弃。
7.1 空转判定:三个信号取或
python
PLAN_PAT = re.compile(r"(我会|我将|接下来|准备先|马上为你|这就去|先.{0,12}然后)")
def looks_like_plan(text): # 未来时/步骤词命中,或文本里点了工具名
return bool(PLAN_PAT.search(text)) or any(name in text for name in TOOLS)
三个信号是:未来时或步骤词命中 、文本里出现已注册的工具名 、本轮工具调用次数为 0。前两个命中一个,加上第三个成立,就可以判为空转。
提醒一句 ⚠️:正则只是启发式 ,别指望它 100% 准;它的价值是在明显该动手却没动手时,把方向盘抢回来一次。
7.2 处理方式:注入纠正,而不是退出
判定空转后,正确动作不是 break,而是追加一条纠正消息让循环再转一轮:
python
messages.append({"role": "assistant", "content": blocks})
messages.append({"role": "user", "content":
"你只描述了计划,没有实际调用任何工具。请现在就调用工具执行,不要复述步骤。"})
三条经验值 💡:纠正消息要具体 (点名「没有调用工具」,别说「请继续」);纠正次数要有上限 (建议连续 2 次判失败);一旦出现真实工具调用,计数器立即清零 ------否则一次小磕碰会污染整条链路的判定。反向的病也要防:模型停不下来时,max_turns(建议 8--12)是唯一刹车。
7.3 承诺登记表:让「我做了」必须附证据
比正则更可靠的机制是登记表(ledger,台账) :从文本里抓出「我要调用 X」,记成待兑现承诺;下一轮如果没出现 X 的调用,就判违约。
背后的原则一句话:任何完成声明,都必须在同一轮带上能证明它的工具调用证据 。不是「我验证过了」,而是「证据是第 3 次 run_tests 返回 2 passed」。业界把这条总结成------把 done 变成一个需要凭据的声明。
7.4 另一种失衡:工具上瘾
防空转做过头会撞上另一堵墙:模型永远在调工具,永远不收敛 。JetBrains 记录过一个案例------历史里连续 100 组「调用 → 结果」,模型学到的唯一格式就是「继续调用」。这也是 max_turns 不能省的原因。
参考资料:
- Your AI Agent Lies About Finishing Work -- DEV Community
- When Tool-Calling Becomes an Addiction -- JetBrains Blog
8. 第四层:验收器定义成功(Verifier Owns Success)
前三层管「过程有没有跑偏」,第四层管「结果到底成没成 」。这是唯一有资格写 success = True 的地方。
8.1 验收要写「可观测证据」
| 任务类型 | 合格的验收条件 | 不合格的验收条件 |
|---|---|---|
| 改配置文件 | 文件内容包含 PORT = 8080 |
「模型说改了」 |
| 跑测试 | 退出码为 0,且输出含 passed |
「模型说通过了」 |
| 调接口 | HTTP 200,响应体字段符合预期 | 「模型说成功了」 |
规律很清晰:验收条件必须能被一段不依赖模型的代码检查。要用模型去检查,那它就不是验收,是第二次生成。
8.2 三态输出,unknown 不能默认成 success
python
def verify():
c = FILESTORE["config.py"]
if "8080" in c and "8000" not in c:
return "success", "config.py 含 PORT = 8080"
if "8000" in c:
return "failed", "config.py 仍是 PORT = 8000"
return "unknown", "文件读不到,无法判定"
三态里最容易被忽略的是 unknown ⚠️。文件被删了、路径写错了、权限不足------这些都验不出「成没成」。此时默认 success 是最坏的选择,因为它把「不知道」包装成了「做到了」。验收器的默认值必须是 unknown。
8.3 验收失败要回灌,而不是标成功
返回 failed 之后,把证据 发回给模型进入修复轮:追加一条 {"role": "user", "content": f"验收未通过:{evidence}。请继续修复。"},而不是把 success 改回 True。证据要具体到能复现(「config.py 仍是 PORT = 8000」),比「再试一次」有效得多;修复次数同样设上限(建议 2 次),用完就老实返回 failed。
9. 一张对照表:症状 → 原因 → 解法(Symptom → Cause → Fix)
| 症状 | 原因 | 解法 |
|---|---|---|
| 模型输出一段计划,程序直接判定结束 | 终止条件写「没有工具调用」,不是「验收通过」 | 完成判定后移到 verifier,循环只负责「继续 / 停止」 |
| 日志显示成功,文件、数据库却没变化 | success 写在循环退出口,属于控制流即结论 |
用可观测证据定义成功,unknown 不得默认成 success |
| 模型反复说「马上执行」,一轮轮烧 token | 提示词允许散文表达计划,且没有空转计数 | 加 plan 工具 + 强制 tool_choice + 空转检测 |
| 响应被截断,半句话被当成最终答案 | max_tokens 与 end_turn 走了同一个分支 |
按 stop_reason 路由,截断就提额重试 |
| 模型永远在调工具,永远不结束 | 缺少轮数上限,历史里全是「调用 → 结果」 | 加 max_turns,并明确「何时该停」 |
10. 完整可运行代码:先复现 bug,再打补丁(Reproduce First)
下面这段代码零依赖、复制即可运行(Python 3.8+),不需要 API Key 与网络:假模型把「只说不做」稳定复现,再并排跑一个加固版做对比。
python
import re
ORIGINAL = "HOST = '0.0.0.0'\nPORT = 8000\n" # 初始配置:端口 8000
FILESTORE = {"config.py": ORIGINAL} # 内存文件表,代替真实磁盘
TASK = "把 config.py 的 PORT 从 8000 改成 8080,并跑一遍测试。"
def read_file(a): # 读文件
return FILESTORE.get(a["path"], "<missing>")
def write_file(a): # 写文件
FILESTORE[a["path"]] = a["content"]
return "written"
def run_tests(a): # 端口是 8080 才算通过
return "2 passed" if "8080" in FILESTORE["config.py"] else "1 failed: PORT is 8000"
TOOLS = {"read_file": read_file, "write_file": write_file, "run_tests": run_tests}
SCRIPT = [ # 模型固定的行为序列
("end_turn", [{"type": "text", "text": "我会先读取 config.py,把 PORT 改成 8080,然后跑一遍测试。"}]),
("tool_use", [{"type": "tool_use", "id": "t1", "name": "read_file", "input": {"path": "config.py"}}]),
("tool_use", [{"type": "tool_use", "id": "t2", "name": "write_file",
"input": {"path": "config.py", "content": "HOST = '0.0.0.0'\nPORT = 8080\n"}}]),
("tool_use", [{"type": "tool_use", "id": "t3", "name": "run_tests", "input": {}}]),
("end_turn", [{"type": "text", "text": "已完成:PORT 改为 8080,测试全部通过。"}]),
]
class FakeModel: # 按脚本吐响应,无需 API Key
def __init__(self):
self.n = 0
def create(self, messages, tools):
self.n += 1 # 第 n 次调用
if self.n <= len(SCRIPT): # 脚本内按序返回
reason, blocks = SCRIPT[self.n - 1]
return {"stop_reason": reason, "content": blocks}
return {"stop_reason": "end_turn", "content": []}
PLAN = re.compile(r"(我会|我将|接下来|马上为你|先.{0,12}然后)") # 计划文本的特征词
def looks_like_plan(text): # 空转判定
return bool(PLAN.search(text)) or any(n in text for n in TOOLS)
def verify(): # 验收:只认可观测证据
ok = "8080" in FILESTORE["config.py"] and "8000" not in FILESTORE["config.py"]
return ok, FILESTORE["config.py"].strip().replace("\n", " | ")
def run(guard): # guard=False 复现原始 bug
FILESTORE["config.py"] = ORIGINAL # 重置,保证可复现
model, msgs, made, idle = FakeModel(), [{"role": "user", "content": TASK}], 0, 0
for turn in range(1, 9):
r = model.create(msgs, TOOLS)
blocks, reason = r["content"], r["stop_reason"]
text = "".join(b.get("text", "") for b in blocks)
calls = [b for b in blocks if b["type"] == "tool_use"]
print(f" 第 {turn} 轮 stop_reason={reason} 工具调用={len(calls)}")
if not guard and not calls: # BUG:没调用就当完成
return {"success": True, "turns": turn, "tool_calls": made, "text": text}
if reason == "max_tokens": # 第一层:截断要重试
print(" → 判定为截断,提额重试")
continue
if calls: # 执行工具并回传结果
msgs.append({"role": "assistant", "content": blocks})
out = []
for c in calls:
out.append({"type": "tool_result", "tool_use_id": c["id"],
"content": TOOLS[c["name"]](c["input"])})
made += 1 # 真实动作计数
msgs.append({"role": "user", "content": out}) # 结果单独成条
idle = 0 # 有动作就清零空转
continue
if looks_like_plan(text): # 第三层:空转纠正
idle += 1
print(f" → 空转第 {idle} 次,注入纠正消息")
if idle >= 2: # 连续两次判失败
return {"success": False, "turns": turn, "tool_calls": made, "text": text}
msgs.append({"role": "assistant", "content": blocks})
msgs.append({"role": "user", "content": "你只说了计划,请现在调用工具执行。"})
continue
ok, ev = verify() # 第四层:验收说话
print(f" → 候选答案,验收{'通过' if ok else '未通过'}:{ev}")
return {"success": ok, "turns": turn, "tool_calls": made, "text": text}
return {"success": False, "turns": 8, "tool_calls": made, "text": "超过最大轮数"}
for name, g in (("朴素循环(有 bug)", False), ("加固循环(四层防线)", True)):
print(f"\n===== {name} =====")
r = run(g)
print(f"success={r['success']} turns={r['turns']} tool_calls={r['tool_calls']}")
print("config.py = " + FILESTORE["config.py"].strip().replace("\n", " | "))
p, n = 0.95, 5 # 单轮 95%,五轮链路
print(f"\n0.95^5 = {p ** n:.4f}")
实际输出:
ini
===== 朴素循环(有 bug) =====
第 1 轮 stop_reason=end_turn 工具调用=0
success=True turns=1 tool_calls=0
config.py = HOST = '0.0.0.0' | PORT = 8000
===== 加固循环(四层防线) =====
第 1 轮 stop_reason=end_turn 工具调用=0
→ 空转第 1 次,注入纠正消息
第 2 轮 stop_reason=tool_use 工具调用=1
第 3 轮 stop_reason=tool_use 工具调用=1
第 4 轮 stop_reason=tool_use 工具调用=1
第 5 轮 stop_reason=end_turn 工具调用=0
→ 候选答案,验收通过:HOST = '0.0.0.0' | PORT = 8080
success=True turns=5 tool_calls=3
config.py = HOST = '0.0.0.0' | PORT = 8080
0.95^5 = 0.7738
两段输出并排看,结论很清楚 🎯:
- 朴素版
success=True,但tool_calls=0、PORT = 8000:成功标记有了,动作没有,结果没变。修复第一步永远是先把这条证据链打进日志。 - 加固版
turns=5、tool_calls=3:多花 4 轮换来一次真实读取、一次真实写入、一次真实测试。判断成本要看「有效动作数」。 - 被拦下的那一轮日志是「空转第 1 次,注入纠正消息」,不是「直接当最终答案」:同一个响应,两条分支,差了整个任务。
11. 边界:什么时候不该上这套防线(When Not To)
四层防线不是免费的,用错地方会拖慢该快的路径 ⚠️。
纯问答场景不用上。 用户问「这段代码什么意思」,答案本来就是文本,没有可验收的副作用。硬套 verifier 只会把「一句话回答」变成「三轮工具调用」,纯属自找麻烦。
只读、幂等的分析任务可以只上第一层。 读代码、查日志、做汇总,错了重跑就行;第一层把「截断当完成」挡住,已能解决八成误判。
写操作、对外副作用、花钱的任务,四层全上。 改配置、发消息、下单、部署------这类任务「假成功」的代价远高于「多跑几轮」的成本。当 Agent 会自己发邮件、自己调支付接口时,第四层的验收器是唯一的刹车片。
最后一个判断标准,也是我在 GUI Agent 打转死循环怎么解决 里那套思路的延伸:打转是「忙而不动」,只说不做是「不动还报喜」 。前者烧钱,后者骗人。烧钱的能被监控发现,骗人的只有验收能发现。
参考资料:
- Stop reasons and fallback -- Claude Platform Docs
- GUI Agent 打转死循环怎么解决 -- 掘金
- Agent 任务规划怎么选:ReAct 与 Plan-and-Execute -- 掘金
判断收尾:只改一处就先改终止条件------把 if not tool_calls: break 换成交给验收器判,这一行能挡掉大部分假成功;有写操作的 Agent,四层都别省。
本专栏《AI Agent 工具》聚焦 Agent 的工具调用链路、循环控制、上下文管理与工程化落地,每篇都配一段可直接运行的代码,每周更新一篇。想按顺序读完,可在专栏页订阅。