🎯 今日核心问题
- ReAct 循环写到第几行就该停?终止条件写错了会发生什么?
- 工具返回的东西要不要原样塞回模型?上下文在第几轮开始爆掉?
- 一条请求从进来到返回,哪些节点必须落库,才能让线上问题可复现?
📖 精读提纲
【一】循环的骨架只有六步
组装消息 → 调模型 → 解析输出 → 判断是「回答」还是「调工具」→ 执行工具 → 把 Observation 追加进消息,回到第二步。听起来简单,四个细节决定成败:
- 最大步数:一般 6–8 步。不给上限的循环在模型陷入重复调用时会烧掉几百块钱。
- 重复调用检测:连续两次相同工具 + 相同参数,直接打断并降级。这是最常见的行为退化。
- 超时预算:不是给单次请求超时,而是给整个 trace 一个 deadline,每步开始前检查
ctx.expired()。 - 终止必须显式:模型输出既不是工具调用也不是终答时,不要猜,重试一次后按失败处理。
【二】Observation 要「压缩后再入上下文」
第 5 轮之后上下文里可能堆了四份完整 JSON,每份 3KB,模型开始丢前面的关键信息。三个动作:
- 工具侧截断:列表类结果只回前 N 条 + 总数,明细按需二次查询。这不是偷懒,是正确设计——让模型知道「还有更多」,再次调用是正常路径。
- 字段投影:工具返回时只保留模型决策需要的字段,
createdAt、operatorId这类给前端用的字段不要进入上下文。 - 旧轮次摘要化:超过 N 轮后把早期 Observation 折叠成一行「已查订单 A123,状态:已签收」。
压测方法很简单:造一个 8 轮的场景,打印每轮的 prompt_tokens,你会看到不压缩时它线性增长,压缩后基本持平。
【三】落库:让线上问题可复现
至少两张表。agent_trace(traceId、userId、输入、最终答复、总步数、总耗时、状态)与 agent_step(traceId、stepNo、thought、toolName、参数 JSON、observation、耗时、错误码)。有了这两张表,用户投诉「它说查不到我的订单」时,你能五分钟内定位是哪一步、哪个工具、参数错在哪。
<strong>密钥和手机号必须打码后再落库</strong>,这一步在写第一行业务代码时就要做,事后补做等于全量数据清洗。
【四】错误必须分类返回,不能一把 500
按处理方式分四类:可重试(模型 429/超时 → 自动重试一次)、可降级(工具挂了 → 返回「暂时查不到,请稍后再试」并带 traceId)、需用户补充(参数缺失 → 反问用户)、需人工(越权、高危操作 → 转人工并落待办)。前端按 errorCode 分支渲染,这比返回一个「系统繁忙」有用得多。
💻 代码示例
最小可用的 ReAct 循环,包含步数上限、重复调用打断、deadline 检查:
@RequiredArgsConstructor
public class ReActLoop {
private final LlmClient llm;
private final ToolRegistry registry;
private final TraceStore traceStore;
private static final int MAX_STEPS = 7;
public AgentResult run(String question, ToolContext ctx) {
List<Message> messages = new ArrayList<>();
messages.add(Message.system(PromptBuilder.systemPrompt(registry.retryable())));
messages.add(Message.user(question));
String lastKey = null;
int repeat = 0;
for (int step = 1; step <= MAX_STEPS; step++) {
if (ctx.expired()) return AgentResult.degraded("处理超时,请稍后重试", ctx.traceId());
LlmResponse resp = llm.chat(messages);
if (resp.isFinal()) {
traceStore.finish(ctx.traceId(), resp.content(), step);
return AgentResult.ok(resp.content(), ctx.traceId());
}
ToolCall call = resp.toolCall();
String key = call.name() + Json.encode(call.args());
repeat = key.equals(lastKey) ? repeat + 1 : 0;
lastKey = key;
if (repeat >= 2) {
traceStore.finish(ctx.traceId(), "重复调用被拦截", step);
return AgentResult.degraded("未能完成查询,请补充更多信息", ctx.traceId());
}
ToolResult result = executeSafely(call, ctx);
messages.add(Message.assistantToolCall(call));
messages.add(Message.toolResult(call.id(), result.observation()));
traceStore.saveStep(ctx.traceId(), step, call, result);
}
return AgentResult.degraded("步数超限,已中止", ctx.traceId());
}
private ToolResult executeSafely(ToolCall call, ToolContext ctx) {
try {
return registry.get(call.name()).execute(call.args(), ctx);
} catch (IllegalArgumentException e) {
return ToolResult.fail("TOOL_NOT_FOUND");
} catch (Exception e) {
return ToolResult.fail("TOOL_ERROR");
}
}
}
Controller 只负责组装上下文与统一返回:
@RestController
@RequestMapping("/api/agent")
@RequiredArgsConstructor
public class AgentController {
private final ReActLoop loop;
@PostMapping("/chat")
public ApiResult<AgentResult> chat(@Valid @RequestBody ChatRequest req, Principal principal) {
ToolContext ctx = new ToolContext(
UUID.randomUUID().toString(),
principal.getName(),
Instant.now().plusSeconds(30));
return ApiResult.ok(loop.run(req.question(), ctx));
}
}
【五】上下文预算用显式数字
不要凭感觉设「保留几轮」,给一个预算:窗口的 60% 给对话历史、20% 给工具 schema 与系统提示、20% 留给输出。每轮组装前算 token(TokenCountEstimator 或中文按 字符数/1.6 粗估),超了按优先级丢:最早的非关键 Observation → 中间轮 thought → 更早的补充说明。系统提示与第一步用户问题永不丢。预算写进配置并打进每轮日志,P95 变长时先看是不是打满了。
【六】一次真实排查
现象:某天 steps.avg 从 2.7 涨到 4.1,成本涨四成,成功率不变。查 agent_step 按 stepNo 分组,发现 search_kb 被连调两次,参数只差一个空 page 字段。原因是上游知识库多返回了 hasMore: true,模型以为还有下一页。修复:只在真有下一页时才下发该字段。
结论:工具出参会直接改变模型行为,一个多余布尔字段换来 50% 额外调用。这是「工具必须独立成层」的第二个理由。
✏️ 今日动手
接上真实模型(或本地 Ollama 兜底),把 echo 工具换成「查订单」真工具,跑通三个场景:一次查询就答、需要两次工具调用、工具抛异常后降级。每个场景录一条 agent_trace 与若干 agent_step,把 traceId 打进日志。
🔖 明日预告
链路通了,但你还不知道它有多可靠。明天写测试:单元测试守工具,召回测试守检索,固定样例回归守住「今天没变差」。