最近把一堆本地文档——有 PDF、有 Word、还有几个 CSV 表格——整理成了一个内部问答系统，一开始用的还是常规 RAG 方案，结果被几个“看似简单但需要跨文档推理”的问题直接打脸。后来我把检索决策权交给 Agent，做了一版面向有限本地语料库的单智能体、工具调用型 Agentic RAG 原型，跑通之后明显感觉到这条路才是对的。
这篇内容不是什么大厂架构分享，就是一个真实踩坑记录式的手记，重点讲清楚三件事：为什么在这个场景下要选择 Agentic RAG 而不是传统 RAG；单智能体的工具调用机制怎么设计、怎么写代码；以及在本地语料库有限的情况下，会遇到哪些坑、怎么调试。适合正在自学 Agent 开发、或者想把自己的文档库做成一个“会自己查资料”的 AI 助手的开发者参考。
1. 从传统 RAG 到 Agentic RAG：一个本地问答场景的痛点与解法
1.1 传统 RAG 的固定管线与三大痛点
传统的 RAG 流程，本质上是一条固定管线：用户问题进来后，先做向量化，然后去向量库里检索最相似的几个文档片段，再把片段拼到 Prompt 里，最后让大模型生成回答。这个流程在“提问简单、知识面窄、单文档命中”的场景下很好用，但一旦遇到复杂问题，问题就来了。
我做这个项目的语料库大概只有几十份文档，算得上典型“有限本地语料库”。一轮跑下来，三个痛点最致命。
第一个痛点是检索意图理解不足。用户问“2023 年报告里提到了哪些技术路线，和 2024 年相比有什么变化？”，传统 RAG 会把整句话拿去向量化，结果就是向量相似度把重点落在了“技术路线”和“变化”上，检索结果分散在两年的各个章节里，最后拼出来的答案要么泛泛而谈，要么漏掉关键信息。
第二个痛点是单次检索不够用。传统 RAG 是一次性检索、一次性生成，如果第一次检索到的片段质量不够，它不会自我纠正，也不会换个关键词再查一次。本地语料库文档数量少，这问题反而不明显；但如果文档内部结构复杂，比如关键内容散落在附录、图表说明、脚注里，单次检索基本就漏了。
第三个痛点是缺乏跨片段推理能力。传统 RAG 把检索结果一股脑拼进上下文，模型只能做“复制粘贴式”的信息抽取，很难在多个片段之间做综合判断。比如对比两份报告对同一个指标的定义差异，传统 RAG 经常直接把两段话并列输出，而不是真正比较。
1.2 Agentic RAG 的工作机制：推理-行动-观察
Agentic RAG 解决上述问题的思路，是把“检索策略”从人工预设变成 Agent 自主决策。它不再规定“必须先检索一次然后生成”，而是给 Agent 一个工具集，让它根据用户问题自己判断：我需要查什么关键词、查几次、查完够不够、不够再查、够了再回答。
这套机制本质上是 Agent 领域的 ReAct 模式：推理（Thought）→ 行动（Action）→ 观察（Observation），循环往复，直到 Agent 认为自己有足够信息生成最终答案。
在我这个原型里，Agent 的每一步行动基本长这样：
- 第一步：接收用户问题，分析这个问题需要哪些信息支撑。
- 第二步：如果认为本地知识库可能有相关内容，就调用检索工具，并决定检索关键词和返回条数。
- 第三步：观察检索结果，判断信息是否完整。如果不够，换关键词或换过滤条件再来一次。
- 第四步：信息充足后，把多轮检索到的片段做综合比较，生成回答。
这里最核心的能力是工具调用（Tool Calling）。与传统 RAG 里的“工具”概念不同，Agent 的工具调用是模型在推理过程中动态生成结构化参数去调用外部函数。模型不是输出一段文字然后你正则里去提取意图，而是在生成接口层面就明确返回一个 JSON 结构，里面有工具名和参数字典。这种设计显著提高了决策的稳定性。
1.3 为什么“有限本地语料库”这个场景值得单独做一版原型
有人可能会问，既然 Agentic RAG 这么灵活，为什么不直接做一个通用版本，而是强调“有限本地语料库”？因为场景边界决定了技术方案取舍。
有限语料库意味着向量库规模最多几千到几万条片段，检索压力不大，实时检索的延迟完全可以接受。所以 Agent 可以多次调用检索工具，不用刻意做复杂的缓存和路由。这给 Agent 留下了很大的试错空间，也让工具调用的调试更简单。
另外，本地语料库还有一个特点：文档内容相对固定，不像互联网那样实时变化。Agent 在检索之后可以做更高强度的信息综合，而不必担心知识时效性问题。我后来把原型跑起来，发现它在“跨文档对比”“多条件查询”这类问题上确实比传统 RAG 高出好几个档次，但在“文档里没有的内容”这个问题上也会很诚实地承认没有——这其实是好事。
2. 架构选型与工具集的拆分思路
2.1 单智能体 vs 多智能体：为什么我选择前者
设计初始阶段，我也纠结过要不要上多智能体架构。网上很多 Agent 项目动不动就是 Planner Agent、Retriever Agent、Writer Agent 三个角色互相协作，看起来很“专业”。但冷静分析下来，对当前这个规模的原型来说，单智能体才是更合理的选择。
原因是多智能体的价值在高复杂度任务中才会体现：团队任务分解、多角色并行、任务状态管理。但它在原型阶段的代价也很明显：Agent 之间的通信协议要设计、状态同步要处理、每个 Agent 都要单独调模型、延迟叠加、调试复杂度指数级上升。
而在“面向有限本地语料库的问答”这个具体任务里，Agent 的能力边界是清晰的——它只需要做检索决策 + 信息综合。这两件事放在同一个 Agent 循环里，完全够用，还减少了中间转述的信息损耗。
我后来在复盘时得出一个判断：如果你不需要多个 Agent 并行处理不同子任务，不要为了复杂度而堆智能体数量。单智能体把工具调用和上下文管理的质量做扎实，效果往往好于一个混乱的多智能体系统。
2.2 工具集设计：检索只是其中一种能力
工具设计决定了 Agent 的能力边界。在这个原型的 v1 版本里，我设计了三个核心工具。
第一个是向量检索工具search_docs(query, top_k, doc_filter)。这是主力工具，用于语义检索。query 是检索关键词，top_k 是返回片段数量，doc_filter 是文档名过滤条件。设计这个过滤参数是很实用的考量：本地语料库里不同文档的话题方向可能差异较大，允许 Agent 指定“只在某某文档里查”，可以有效降低跨文档噪声，同时省掉不必要的重检索。
第二个是关键词匹配工具search_by_keyword(term, cond)。为什么有向量检索还要关键词匹配？因为向量检索擅长语义近似，但在精确术语上容易“差之毫厘、谬以千里”。比如文档里写的是“模型收敛速度”，用户问的是“训练时间表现”，向量检索能命中；但用户问“KFAC 优化器”，在语料库里只出现一次，且周围是公式和伪代码，向量化可能就被淹没在上下文噪声里。关键词匹配能精确锁定。
第三个是文档片段重读工具read_doc_snippet(doc_id, page, chunk_id)。这个工具是为了解决“检索片段过短导致上下文不足以综合判断”的问题。向量检索返回的是小块片段，但一个章节的逻辑往往跨越好几页，这时 Agent 可以通过这个工具，拿到文档元数据后回源头重新读取更完整的片段。这一步在跨文档对比任务里非常关键。
工具设计还有一个容易忽略的点：描述信息要写得足够清楚。工具函数的实际实现再简单，如果模型对工具描述理解错误，决策也会跑偏。我后来把每个工具的 description 都改成了“何时用、何时不用”的句式，比如描述 search_docs 时明确写出“当用户问题涉及文档中的具体事实或趋势时优先调用；当用户只是闲聊时不要调用”。这个细节对召回的准确率影响非常大。
2.3 单智能体循环中的上下文管理
单智能体循环的难点不在“循环”本身，而在上下文管理。每一次工具调用返回的观察结果都要拼进 messages 列表里，发给模型。如果 Agent 连续检索三次，每次带回 5 个片段，每个片段 800 字，那么上下文里就有上万字。指令遵循能力下降、早期信息被“挤掉”的问题都会出现。
我的做法是三层控制。
第一层控制单轮检索返回体量。向量检索工具返回前，先对候选 top_k 个片段做处理，只保留与问题相关度最高的片段，并把每个片段的文本截断到合理字数。对本地语料库来说，返回 3 到 5 个片段、每个片段 300 到 500 字，已经是很好的默认参数。
第二层控制 Agent 总迭代轮数。即使 Agent 还在检索，如果轮数超过上限（我通常设为 6），就强制它基于现有信息生成答案。这不仅能防止死循环，还倒逼 Agent 在前几轮里更认真地选关键词。
第三层是最终生成时的“上下文裁剪”。最后一轮生成前，我会把 messages 里历史检索结果压缩，只保留与最终结论相关的片段，重新组装一个干净的生成 Prompt。这一步不是必须的，但在 Agent 做了很多次检索后特别有用，尤其是上下文窗口较小的模型。
3. 原型实现：从本地文档解析到 Agent 循环跑通
3.1 本地语料库预处理与向量索引
Agent 再聪明，喂进去的文档质量差，效果也白搭。我在预处理阶段踩过不少坑，按顺序梳理出一套比较稳的处理流程。
第一步是文档解析。不同格式用不同解析库：PDF 我用 pdfplumber，遇到扫描版就直接提示需要 OCR；Word 用 python-docx；纯文本和 Markdown 直接读取。这里要特别注意，解析出来的文本往往带着页眉页脚、页码、目录、重复空行，需要在索引前做一次清理。不清理会让向量检索在嵌入时引入干扰，导致语义相似度计算偏移。
第二步是文本切分。切分策略直接决定检索结果的粒度。如果切得太碎，片段之间缺少上下文；切得太长，向量化时分词和嵌入质量都会下降。我用的基准是：按章节标题先切，章节太长再按固定窗口切，窗口大小约 600 到 1000 个字符，重叠 100 到 200 个字符。每个片段保留 metadata，包括 doc_id（文档 ID）、title（文档标题）、page（页码）、chunk_index（片段序号）。这些 metadata 在后面 Agent 的doc_filter和read_doc_snippet工具里都会用到。
第三步是向量化嵌入。本地语料库规模不大，我选的是 BGE 系列的中文小模型 bge-small-zh-v1.5。这个选择没有刻意追求最新最强，原因在于语料规模小，嵌入模型的能力上限不是瓶颈；小模型速度快，本地跑也方便。如果你对语义匹配质量不满意，后续可以换成更大的 bge-m3，本地消费级显卡也能跑得动。
第四步是向量库存储。这个原型我用 Chroma，配置简单、Python 接口比较友好，适合快速验证。如果后续要做性能优化，可以换 FAISS 或 LanceDB。
3.2 技术栈选型与关键细节
技术栈整体是 Python 3.10 + LangChain + Chroma + BGE 嵌入模型，LLM 部分用的是 OpenAI 兼容接口的 deepseek-chat。之所以选 LangChain 而不是 LangGraph，是因为原型阶段我只想要一个可控制的 Agent 循环，LangChain 的bind_tools和AgentExecutor已经足够解决问题，没必要引入更重的编排框架。
这里想多聊一句模型选型。单智能体工具调用型 Agent 对模型的要求确实比较高，模型必须足够“听话”：既能理解系统指令，又能按 JSON 结构生成工具调用参数。deepseek-chat、GPT-4o 这些模型在工具调用上都比较稳。如果用本地小模型，比如 7B 级别的开源模型，工具调用的稳定度会明显下降，经常出现“该调工具时不调、不该调时瞎调”的情况。这也是为什么很多 Agent 原型最后都回归到了大模型 API 上。
LangChain 的使用上，要注意它的工具定义是可以通过类型注解和 docstring 自动转成 JSON Schema 的。比如定义函数时写清楚参数类型、默认值和 docstring，@tool装饰器就会自动生成 OpenAI Function Calling 需要的 schema。这对维护工具描述一致性帮助很大，避免了手工维护 JSON schema 带来的误差。
3.3 Agent 核心循环的代码实现
下面这段代码是原型里最核心的 Agent 循环，参考 LangChain 的 AgentExecutor 但做了简化。流程就是：把系统提示词、对话历史、用户问题组装成 messages，传给模型；如果有 tool_calls 就执行工具并把结果附加进去再循环；否则就返回最终答案。
先定义三个工具的 schema，以 search_docs 为例：
# LangChain 内置的 create_react_agent 虽然也行，但为了后面调试方便，直接写循环 from langchain_openai import ChatOpenAI search_docs_schema = { "type": "function", "function": { "name": "search_docs", "description": "在本地知识库中进行向量检索，返回最相关的文档片段。当用户问题涉及文档内容时需要调用。", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "检索查询语句，尽量概括用户的真实信息需求"}, "top_k": {"type": "integer", "description": "返回片段数量，默认 5"}, "doc_filter": {"type": "string", "description": "按文档名过滤，可选"} }, "required": ["query"] } } } llm = ChatOpenAI( model="deepseek-chat", base_url="https://api.deepseek.com/v1", api_key="your-api-key", temperature=0.1 )然后实现 Agent 循环：
def run_agent(user_query, max_iterations=6): messages = [ {"role": "system", "content": SYSTEM_PROMPT}, {"role": "user", "content": user_query} ] for step in range(max_iterations): resp = llm.invoke(messages, tools=[search_docs_schema, ...]) msg = resp.content tool_calls = resp.additional_kwargs.get("tool_calls", []) if not tool_calls: return msg messages.append({"role": "assistant", "content": msg or "", "tool_calls": [ {"id": tc["id"], "type": "function", "function": tc["function"]} for tc in tool_calls ]}) for tc in tool_calls: tool_name = tc["function"]["name"] args = json.loads(tc["function"]["arguments"]) try: result = execute_tool(tool_name, args) except Exception as e: result = {"error": str(e)} messages.append({ "role": "tool", "tool_call_id": tc["id"], "content": json.dumps(result, ensure_ascii=False) }) return "已达最大迭代轮次，基于现有信息生成结论：\n" + messages[-1].get("content", "")execute_tool是一个简单的分发函数，映射工具名到实际 Python 函数。关键点在于异常也要作为结果返回给模型，而不是直接抛断循环。这样模型能看到“工具调用失败”这个观察，自己判断是换个参数重试还是告诉用户无法执行，更符合 Agent 的自主决策逻辑。
系统提示词这段也值得抄下来。我的 v1 版本是这样写的：
你是面向本地知识库的问答助手。你有以下工具：search_docs、search_by_keyword、read_doc_snippet。 规则： 1. 用户问题涉及文档内容时，必须调用工具获取信息，禁止凭常识直接作答。 2. 如果第一次检索结果不充分，可以调整关键词或 doc_filter 再次检索。 3. 如果多轮检索后仍无法找到资料，明确告诉用户“本地语料库中未找到相关信息”。 4. 最终回答需要结合检索到的多个片段进行综合分析，如果引用原文，请标注来源文档标题。重点在第 1 条和第 3 条。第 1 条逼 Agent 检索，第 3 条防止幻觉。这两条规则对工具调用的稳定度帮助巨大，建议直接抄。
3.4 一次端到端运行的案例拆解
用一个炼丹式的案例来说明 Agentic RAG 和传统 RAG 的实际差异。假设本地语料库里有 2023、2024 两份项目总结报告，各十几页。用户问：“2024 年团队在小模型方向的尝试和 2023 年有什么延续性？”
传统 RAG 的做法是直接向量检索整句话，然后在两篇报告里各取一个片段，拼在一起。结果经常是：内容相关但缺少时间脉络，答案像“两段摘要的并列”，而不是“延续性分析”。
Agentic RAG 的运行过程是这样的：
第一轮：模型认为需要时间对比维度，调用search_docs(query="2024 小模型 技术尝试", top_k=5, doc_filter="2024年度总结.docx")，结果返回若干片段，其中一段提到“沿用 2023 年提出的轻量化思路”。
第二轮：模型发现“沿用”这个词指向 2023 年的某个概念，继续调用search_docs(query="轻量化 思路 探索 2023", top_k=5, doc_filter="2023年度总结.docx")，拿到了 2023 年报告里关于轻量化方向的完整论述。
第三轮：模型把两轮结果放在一起，判断“2024 年的尝试是 2023 年方向的深化，主要变化是落地硬件平台”，然后生成了一段有明确因果关系的回答。
看到区别了吗？关键是模型在第二轮主动补了一次检索，补检索的触发点就是第一轮结果里的“沿用”一词。这种多轮互动在传统 RAG 里是预先写不出来的，属于 Agentic RAG 最直接的价值。
4. 调试记录：我遇到过的 5 类典型问题
4.1 Agent 不调用工具，或把工具当成摆设
现象是用户问“文档里怎么写的”，Agent 直接用自己的常识回答，完全不碰工具。这类问题多半出在系统提示词上，模型根本没意识到“有工具可用”或者“应该用工具”。我踩过几个原因：
第一，工具描述不够清晰。仅说“这是一个检索工具”模型可能忽略，但如果明确写“当用户问题需要本地文档中的具体信息时，必须调用此工具再作答”，效果立竿见影。
第二，模型上下文里没有示例。系统提示词里加了一个“示例对话”，展示了一次“用户问 → 模型调工具 → 返回结果 → 模型作答”的过程。加了示例之后，工具调用率有明显提升。
第三，模型的 tool_calls 参数没有在请求中正确传递。LangChain 的llm.invoke(messages, tools=...)里，如果 tools 没绑定，模型就算想调用也没有接口可用。这个低级错误我遇到过，调试时先检查这一层。
4.2 检索命中但上下文不对，噪声比想象中大
另一种常见现象是：Agent 调了检索工具，结果也确实回来了，但返回的片段都是“形似神不似”，看起来有印象，实质内容没用。这通常不是 Agent 的问题，而是向量检索本身质量不高。
排查思路是回看切分和嵌入配置。我遇到过一次：某份报告里的关键指标在表格里，解析后表格被拆成了无数小块，向量化后语义割裂，怎么检索都检索不出完整上下文。后来对表格单独做了“表格内容合并 + 前缀说明文字”的处理，命中率就提上来了。
还有一个小技巧，在检索工具返回内容时，把 metadata（文档名、页码和分数）一并返回给 Agent。这样 Agent 能判断结果是否是真的相关，还是仅仅语义相似。我在工具函数的返回结果里加了一段source_info字段，调试时非常有帮助。
4.3 上下文爆炸：检索结果放多了反而翻车
Agent 工具的自主性带来一个副作用：它可能调用得很欢，每次返回 5 个片段，三次下来就是十几段文字。前两轮的信息在后续推理里大概率被淹没，模型开始“遗忘”最初的用户问题。
我在测试里就翻过一次车。问题是“报告中关于推理性能的指标有哪些？”Agent 检索了三次，总共带回 15 个片段，最后回答时反而绕来绕去，还把优化器相关的内容当成推理性能指标答了出来。
解决办法是两个方面。一是为工具函数加max_result_length限制，返回前对片段做截断处理。二是 Agent 循环里加一个“检索轮次递减”机制：前几轮可以放开搜，最后生成前则只保留最近一轮、且与问题相关性最高的几个片段，忽略更早轮次的结果。简单的做法是维护一个！”
4.4 工具执行异常与 Agent 的“自救”
本地语料库解析过程中难免有异常：某个 PDF 的某页解析失败、某个 CSV 打开时编码不对、某个 docx 里含宏导致 python-docx 拒绝读取。这些异常如果直接抛给 Agent 循环外层，整个流程就崩了。
最好的处理方式是在execute_tool里把异常捕获住，转换成一条观察文本返回给 Agent。我给 search_docs 加了一层 try-except，失败时返回{"error": "检索异常，请尝试更换关键词或过滤条件"}。因为语言模型能理解这个状态，它可能会：
- 把异常当成“这次没检索到”，换个关键词再试一次；
- 把异常当成“语料库访问失败”，直接告诉用户暂时不可用。
这一步在原型阶段看起来是细节，但真正进入生产时，Agent 的容错能力基本靠这些细节堆出来。
4.5 可观测性：没有日志的 Agent 等于盲人摸象
调 Agent 和调传统函数完全不是一个思路。函数逻辑错了有堆栈，Agent 决策错了你根本不知道是模型判断问题还是工具返回问题。所以可观测性必须从第一天就开始做。
我给自己加了一个简单的 CLI 日志模块：每次模型输出后，格式化打印以下信息：
[STEP 1] User Query: ... [STEP 1] Tool Call: search_docs(query="...", top_k=5) [STEP 1] Tool Result: <doc_id=..., title=..., score=...> 片段前200字 [STEP 2] Final Answer: ...这套日志方式虽然简陋，但足够回溯大多数问题。你可以直观看到 Agent 每一步在调什么工具、传了什么参数、结果是什么、下一步改了什么策略。后来我甚至直接用这段日志作为“思考链”给 Agent 进行人工调试，判断它是真的在推理还是只是瞎猜。
这里也推荐 LangSmith 或者 Langfuse 这类可视化追踪工具，但如果只是本地原型，CLI 日志完全够用，不要为了上工具而增加上手成本。
4.6 常见问题速查表
| 现象 | 可能原因 | 解决方案 |
|---|---|---|
| Agent 从不调用工具 | 提示词未写清楚“必须调用”；tools 未绑定 | 强化系统提示词规则，加入示例对话 |
| Agent 反复调用同一个工具 | 检索结果不充分且关键词太接近 | 调整检索工具的描述，提示 Agent 更换关键词或使用 doc_filter |
| 回答与文档内容明显不符 | 向量检索命中噪声片段 | 优化切分策略，引入 rerank 或关键词匹配兜底 |
| 工具异常导致流程中断 | 未捕获工具函数内部异常 | 在 execute_tool 中 try-except，异常作为观察返回给 Agent |
| 上下文超出窗口限制 | 多轮检索累加大量片段 | 限制 top_k 和片段长度，最后生成前只保留高相关片段 |
| 模型答非所问 | 上下文被“污染” | 检索结果附带 metadata，让 Agent 按来源判断相关性 |
5. 从原型到后续方向：一些复盘体会
5.1 效果评估：哪些问题真的被 Agentic RAG 解决了
跑完这一轮原型后，我做了个比较粗的评估。拿同一批本地语料，对比传统 RAG 和 Agentic RAG 在 30 个随机问题上的表现。
结论是：在“单文档事实查询”这类简单问题上，两者差距不大，Agentic RAG 反而因为多轮交互多了些 token 消耗，速度也更慢；但在“跨文档比较”“多条件组合查询”“信息追踪类问题”上，Agentic RAG 的通过率明显更高，尤其是那种需要沿着一份文档的某个线索去定位另一份文档对应信息的问题。
我自己更看重的是另一个变化：回答的可解释性明显提升。传统 RAG 的答案你很难知道它到底主要依据哪些片段，而 Agentic RAG 因为每轮工具调用都有日志，你可以完整回溯检索链路。这在知识库类产品里是刚需，尤其是在用户质疑某条结论出处的场景下。
5.2 后续可扩展的方向：记忆、技能、rerank 与 MCP
原型能跑只是第一步，后续如果要让它成为一个真正可用的内部知识助手，有四个方向值得投入。
一是增加记忆能力。目前的 Agent 是无状态的，用户每次提问都是独立会话。现实场景里用户会连续追问：“上一条里说的那个指标，最新数据是多少？”如果让 Agent 具备跨会话记忆，体验就会好很多。这个方向可以做成简单的摘要记忆或向量记忆，给每条对话历史打标签，下一次提问时自动检索相关历史。
二是引入 rerank 模型。这算是检索质量提升的“性价比之王”。Agent 虽然会做多轮检索，但每一轮看到的候选片段质量还是取决于向量检索的上限。在向量检索之后加一个 rerank 模型重新排序，把真正相关的片段提到最前面，能在不增加额外工具调用的情况下明显提升最终质量。推荐开源的 bge-reranker 系列，本地就能跑。
三是把工具进一步封装成 Skills。我现在的三个工具是扁平函数，下一步可以做一层抽象：把“搜索 + 重读 + 综合判断”这套动作封装成一个高层级的 Skill，比如compare_docs(keywords, doc_list)。这样 Agent 只面对更少的决策点，指令遵循难度降低，行为也会更稳定。这和目前业界讨论得比较多的 Agent Skills / MCP 其实是一个思路——工具调用的底层协议逐渐标准化，Agent 需要决策的高层逻辑越来越精简。
四是接 MCP 协议，扩展外部工具。到目前为止 Agent 只能检索本地文档，如果后续想让它进一步访问企业内部 API、数据库或在线知识库，可以逐步把工具封装成 MCP Server，让 Agent 通过标准协议调用。这样工具集可以随时扩展，而 Agent 核心逻辑基本不动。
5.3 一些经验层面的总结
如果要给这个项目写一句最实在的收获，我想是：Agentic RAG 的难点不在“Agent”，而在“明确工具边界 + 清晰提示词 + 可控循环”。很多时候 Agent 表现不稳定的原因并不神秘，就是工具没描述清楚、上下文没控制好、异常没兜底。把这几点做扎实，效果自然就上去了。
另外一个细节是，原型阶段千万别陷入“调参泥潭”。我看到很多人花大量时间调整 Agent 的某个超参数，比如 max_iterations 或者 top_k，以为这样就能提升效果，其实先该做的永远是把日志打印出来，完整看一次 Agent 的决策链路。数据永远比感觉靠谱。
这个原型目前还在我本地跑着，接下来我准备先把 rerank 加上，再把多轮记忆做出来。如果你也在折腾类似的项目，欢迎交流，尤其是 Agent 工具调用稳定性这个点上，我踩过的坑大概率你也能碰到。
