手写最小 ReAct 循环——退出条件才是真正的考点

import hashlib, json

def run_agent(user_input, tools, dispatch,
              max_steps=12, max_tokens_budget=120_000, repeat_window=3):
    messages = [system(AGENT_PROMPT), user(user_input)]
    used_tokens = 0
    recent = []                                   # 最近的动作指纹，用于无进展检测

    for step in range(max_steps):                 # 闸 1：步数上限
        if used_tokens > max_tokens_budget:       # 闸 2：预算上限
            return finish("成本超预算，已转人工", messages)

        resp = llm.chat(messages, tools=tools)
        used_tokens += resp.usage.total_tokens
        messages.append(resp)

        if not resp.tool_calls:                   # 正常出口：模型给出最终答案
            return resp.content

        for call in resp.tool_calls:
            fp = hashlib.md5(                     # 闸 3：动作指纹
                f"{call.name}:{json.dumps(call.arguments, sort_keys=True)}".encode()
            ).hexdigest()
            if recent.count(fp) >= repeat_window:  # 连续重复同一动作 → 强制干预
                messages.append(tool_result(
                    call.id,
                    "你已用完全相同的参数调用过该工具多次且结果相同。"
                    "不要再重复：请改变策略，或直接向用户说明当前信息不足以及缺什么。"
                ))
                continue
            recent = (recent + [fp])[-8:]

            try:
                result = dispatch(call)            # 真正执行
            except FatalToolError as e:            # 闸 4：致命错误直接终止
                return finish(f"工具不可用：{e}", messages)
            except ToolError as e:                 # 可恢复错误：把可操作信息还给模型
                result = f"调用失败：{e}。请检查参数或改用其他工具。"

            messages.append(tool_result(call.id, truncate(result, 8000)))

    return finish("已达最大步数，未能完成，转人工处理", messages)   # 兜底出口

面试白板题里，第 2 条几乎人人会写，第 3、4 条是分水岭。 第 5 条要能区分"可恢复错误"和"致命错误"：参数格式错了应该把错误信息还给模型让它自己修（这是 ReAct 的自愈能力），下游服务 503 应该直接终止或退避重试，而不是让模型反复撞墙。

对 B 和 C，纯代码判断有极限，实践中的组合拳是：代码检测 + 上下文注入纠偏。注入的话术要具体，别写"请不要重复"，要写"你已经尝试过 X 和 Y 各两次，均未获得新信息。现在请：① 给出基于已有信息的结论，或 ② 明确说明还缺什么、需要用户提供什么。"

• max_steps：简单问答类 5～8；跨系统查询类 15～25；编码/长任务类 50+（并配合更强的预算控制与中间态持久化）。这些是起步值，必须用自己的评测集校准——统计成功任务的步数分布，取 P95 再留一点余量。
• repeat_window：连续 2～3 次相同指纹就干预。设太大等于没有。
• 单次工具返回截断：几千 token 量级起步（参见 T3-2）。
• 每轮超时：给单个工具调用设墙钟超时（如 30s），否则一个挂死的下游能拖垮整个会话。

长任务 Agent 一定会遇到进程重启、网络中断。在每轮循环结束时把 messages 与游标落盘（或写入状态存储），这样才能续跑。这也是 LangGraph 这类框架强调「durable execution / checkpointing（可持久化执行 / 检查点）」的原因——它们把这件事变成了内置能力。自己手写循环时，这是最容易漏掉、上线后最痛的一块。

• 解决什么：让模型根据真实观察调整下一步，处理"计划无法预先制定"的任务；错误可以在循环内自愈（工具报错 → 模型改参数重试）。
• 代价是什么：串行往返导致延迟成 N 倍；每轮重发历史导致成本超线性增长；上下文随步数膨胀，长循环末期模型容易忘掉最初的任务目标（context rot）；不可复现，同一输入可能走出不同轨迹。
• 什么时候不该用：路径固定的任务（直接 workflow）；有硬性低延迟要求的同步接口；任务能一次检索 + 一次生成解决时（很多所谓 Agent 场景其实是 RAG 场景）；以及需要严格审计每一步依据的场景——ReAct 的轨迹虽可记录，但决策依据是概率性的。

• 循环里别忘了把模型的回复本身 append 回 messages。漏掉这一步，模型看不到自己刚发起的调用，会重复发起——这是新手最常见 bug。
• 工具返回为空要显式表达语义：{"data": []} 改成 未找到匹配记录（订单号 A1001 在系统中不存在）。若单号来自用户输入，建议向用户确认。 一句话就能消灭开篇那类事故。
• 不要在循环里无限制拼接历史：接近上下文上限时要触发压缩（T3-6），并保证关键决定不被压掉。
• 别用异常吞掉工具错误。except: pass 会让模型永远看不到失败原因，从而永远学不会改参数。
• 给每轮打 trace（step、tool、参数、耗时、token），出事时你需要的正是开篇那张表（T3-11）。

Q3-06 是典型的白板手写题，出现在一面或二面的动手环节。题面通常很简单："写一个最小的 ReAct 循环"。陷阱在于题面不提退出条件——直接写 while True 的候选人当场出局；写了 for step in range(N) 的算及格；主动加预算闸和重复检测的，面试官会立刻换个眼神。

常见追问："如果它在两个工具之间来回跳怎么办？"（考形态 B）；"步数上限设多少？依据是什么？"（考有没有真跑过）；"2026 年还要自己解析 Thought/Action 吗？"（考时效认知）。

1. 先说清骨架：一个循环，三件事——调模型、执行工具、回填结果。
2. 边写边报出五类退出条件，把闸口在代码里标出来。这是最高效的展示方式。
3. 主动交代时效："原生 tool use 之后不需要手写文本解析了，我保留的是 ReAct 的思想而不是它的文本协议。"
4. 用一个真实的死循环故事收尾，说清你加了哪道闸。

只读过资料的回答：

• 写 while True，只靠模型说"我完成了"来退出。
• 还在手写正则解析 Thought: / Action:，且说不出为什么现在不需要了。
• 说不清"可恢复错误"和"致命错误"的处理差异，一律 except: pass。
• 只提步数上限，从没考虑过 token 预算。
• 从没想过工具返回空值也需要好好措辞。

真做过的回答：

• 同时给出步数上限 + 预算上限，并解释为什么两者都要。
• 提到动作指纹去重 / 周期检测这类无进展判断。
• 讲到注入纠偏话术，而且话术是具体的、给模型指了两条出路。
• 提到 messages 落盘续跑、每轮 trace。
• 报得出自己项目里 max_steps 的取值和取值依据（比如"成功任务步数 P95 是 9，我设了 15"）。
• 能说出"很多我们以为需要 Agent 的场景，其实一次检索加一次生成就够了"——反向判断力。