这个 agent 是怎么搭的

0组件总览

这一节是“零件清单”，给想看技术栈的人看。第一次看可以直接跳到第 1 节。

1全图：节点与边

图在 build_graph() 里用 StateGraph(QAState) 声明，只有 5 个节点。 箭头上的字不是形容词，是代码里真实的判断条件。

怎么读：从 START 出发，每个箭头上的字是一个判断，按答案走对应的线。 方块里的大字是“它在干什么”，后面灰色小字是程序里的函数名（方便对着代码看）。

五个方块，用大白话说

为什么只有一个节点在干活

如果把“查工具”也画成节点，图会变成 agent → tools → agent → tools → agent。 问题在于轮数是运行时才决定的：模型可能查 1 次、2 次，也可能一次都不查。画出来的时候 不知道要循环几轮，只能固定几个节点——等于把流程写死。

所以这里的分工是：图负责“这次走哪条路”，循环负责“这条路怎么走完”。

2两个 agent

图上标着 agent 的方块有两个：绿色的「回答」和蓝色的「闲聊」。 它们不是同一个模型的两种提示词，而是两个独立模块、两套提示词、两个预算。

为什么不在一个 agent 里做

在工具 agent 里加一句“如果是寒暄就正常聊天”也能跑，但代价很实在： 那一套系统提示词加上三个工具的 JSON Schema，一次就多几千 token； 而且模型看到工具会忍不住去查——问一句“你好”，它可能真的去检索“你好”。

拆开之后，闲聊只用一段两百字的提示词、600 token 上限、最近 4 条历史， 把话接住、把话题拉回财税，别的什么都不做。

两者共用什么

3信息怎么流动

同一个节点做两件事：往下传数据（状态），同时播给观众看（事件）。 两条通道互不干扰，所以“答得对”和“看得见”能同时成立。

工单上记什么

事件有哪些

4回答节点（agent）内部：怎么循环

核心只有一件事：边流式输出边决策。决策和生成是同一次模型调用——模型要么吐正文， 要么吐工具请求，不是“先判断再生成”两次请求。

一次模型调用花在哪：首字 / 总用时 / 重试

每次调用模型都会发一条 trace(phase=llm)，带三个数： 首字延迟（多久吐出第一个字）、总用时、重试次数。 这三项分得清，才判断得出“慢”是模型排队、网络重试，还是我们自己在空转。

超时的口径也在这里定：读超时 180s 是“两个数据块之间最多等多久”，不是整次调用的上限； 整次调用另有 300s 硬上限。只有一个字都没吐时才会重试（最多 2 次）， 一旦开始吐字就不再重试——否则用户会看到回答被从头重复一遍。

真实例子：沙箱 0.07s 就算完了，但收尾那次模型调用一共花了 176s—— 工具没花时间，时间全在等模型出字。没有这条 trace，界面上就只剩“一直转圈”。 另外，阶段提示会在第一段正文出现时从「分析问题、选择工具…」切成「正在写答案…」， 不要让它一直停在“选工具”。

预算（写死的上限，不是路由）

简化后的循环（这段是代码，可以跳过）

# app/agents/react.py（简化）
messages = [system_prompt, *history, user_question]

for round in range(max_rounds):
    calls, produced = [], False
    async for kind, text in llm.stream_events(messages, tools=schemas):
        if kind == "thinking":  yield "thinking", text
        if kind == "content":   produced = True; yield "delta", text
        if kind == "tool_calls": calls = json.loads(text)

    if not calls: break                    # 这一轮就是最终回答

    for call in calls[:remaining]:
        yield "approval"          # 等用户点“允许”
        result = await registry.run(name, args)
        evidence = pool.extend(result.citations)   # 统一编号
        messages.append({"role": "tool", "content": pool.render(evidence)})

if 没有正文:   # 轮次用尽/只调了工具
    yield from final_answer(messages)   # 不带 tools，强制收尾

四个容易踩的实现细节

5三个工具

三个工具同一层暴露给模型，没有“必须先查知识库”的顺序。选哪个、查几次，由模型按材料性质决定。 模型看不到工具时，也就不会调——没配置的依赖会直接从列表里消失。

模型看到的 schema（真实内容，可以跳过）

{
  "name": "kb_search",
  "description": "检索财税知识库，返回法规原文片段。回答财税问题前应优先调用它；可以换关键词多次检索。",
  "parameters": {
    "type": "object",
    "properties": {
      "query":  { "type": "string", "description": "检索词：税种、政策名称、业务事项，尽量短" },
      "reason": { "type": "string", "description": "为什么需要检索，一句话，会展示给用户确认" }
    },
    "required": ["query", "reason"]
  }
}

reason 不是给模型看的，是给人看的：输入框上方确认条显示的就是这句话， 所以 schema 里明确写了“会展示给用户确认”。

kb_search 内部流水线

1. 原句检索 → 按 RETRIEVAL_MIN_SCORE=0.30 过滤（score is None 视为通过）
2. 最高分 < 0.50 或 0 命中 → 本地关键词压缩（去疑问词/口语词，不调模型）再查一次，两路按 chunk_id 合并取高分
3. 问题里有多个主题（税种/社保/公积金/发票）且已有命中没覆盖 → 对缺失主题补查一次
4. 取前 RETRIEVAL_TOP_K=6 条，按 CHUNK_MAX_CHARS=2000 / CONTEXT_MAX_CHARS=12000 装块
5. 父块 3.5k～4k 字符，答案常在 2000 字后 → 用查询词字符 bigram 给段落打分，挑最相关段落
6. 结果交给证据池统一编号

code_exec 的边界

bwrap --unshare-all：断网、只读挂载系统与 .venv、不挂载项目源码和 .env； timeout + prlimit + RSS 看门狗（不用 prlimit --as 当内存上限， 会把 numpy 卡死在启动阶段）。产物归属是进程内映射，重启后一律 404。

6两个模型怎么分工

为什么不用大模型做这些判断：一个布尔判断也要等一次 15 秒的推理，而且会让“天气”这种问题也跑完整轮。

阈值：tax < 0.10 才算明确无关；寒暄类 ≥ 0.8 且 tax < 0.2 才交给闲聊 agent（不是预设文案，详见下一节）；calc ≥ 0.6 只是给 agent 注入一句 “本题必须用 code_exec”的提示，不是硬门禁。

fail-open：超时（3s）、额度用尽、网络不通、返回格式异常，一律当作“没有判断”，继续走 agent——决策模型只是加速手段，不能成为故障点。

一个实测细节：MiMo 在绑定 tools 时默认用英文推理（0 个汉字）。系统提示词里明确“目标用户是中文用户、思考过程优先用中文”后， 复测两条问题都是 27～30 个汉字、0 个英文。

7证据与编号

知识库、网页进的是同一个编号池（app/services/evidence.py）： 工具返回时分配 index，按 chunk_id 或 url 去重； 同一篇文档已经有原文片段时，它的自动摘要不再入池。

# 回灌给模型的 tool 消息（真实格式）
【知识库检索结果】
[1] 《中华人民共和国增值税法_20260101.txt》（第 3 页）（知识库原文）
小规模纳税人发生应税交易，销售额未达到起征点的，免征增值税……

【互联网搜索结果】
[3] 《国家税务总局政策法规库》（网页）
链接：https://fgk.chinatax.gov.cn/…

# 前端引用卡片按 kind 显示角标：原文 / 摘要 / 网页

编号在“证据进入上下文的那一刻”分配，所以编号顺序 = 模型读到材料的顺序。 沙箱结果不进编号池：它是计算，不是资料，提示词要求模型说“来自沙箱计算”。

8一次真实问答：两条轨道并排看

下面是一条真实记录（问：增值税起征点是多少，总耗时 46.1s）。 左边是状态在变什么，右边是同一时刻观众看到了什么——两列同一行是同一时刻。

注意 19.0s 那一行：模型自己决定再联网，理由写在事件里。这不是代码里的规则， 是它读到“由国务院规定”之后，判断知识库还差一个当年的数字。

想看别的记录：打开任意一条回答下方的「执行记录」，或直接访问 /debug。

9失败与边界

10自己验证

这个页面讲的东西都可以在运行中的系统里对上：

• /debug：某条回答的完整时间线、工具入参出参、证据池、原始 meta
• 回答气泡上方的「执行过程」：同一个 meta.steps 的折叠版，刷新后仍在
• 日志事件名：clef.decided、agent.tools、tool.run、chat.completed
• 测试：.venv/bin/python -m pytest -q（98 个，全部离线，不访问网络）
• 流程图：.venv/bin/python scripts/graph_diagram.py → docs/agent-graph.mmd