LangChain Agent 实战：从原理到落地

这篇本来想写成标准的”LangChain 教程”——讲 ReAct、讲工具调用、讲 Memory。但写到一半发现，网上这种教程一搜一大堆，没必要再写一份。所以改成”我在做气量智能问数项目时用 LangChain Agent 的真实经验”，把那些官方文档和教程不会告诉你的事写出来。

Agent 是什么（不废话版）

如果你已经知道 Agent 是大模型 + 工具 + 记忆，可以直接跳到下面”我踩的坑”部分。

简单说：传统 LLM 只能生成文本，Agent 让 LLM 能”行动”——决定要不要调工具、调哪个工具、怎么解析结果、多次推理直到完成目标。

经典范式是 ReAct（Reasoning + Acting）：

1
2
3
4
5
6
Thought: 我需要先查询天气
Action: get_weather
Action Input: 北京
Observation: 晴，25°C
Thought: 现在可以给出穿衣建议了
Final Answer: 北京今天晴，25°C，建议穿短袖。

我用 Agent 做的真实项目：气量智能问数

我在金建做的”气量智能问数”项目，本质上就是一个 Agent。架构大致是：

  • 大模型：Qwen / DeepSeek（不是 OpenAI，国内项目首选）
  • 工具集：query_schema（查表结构）、query_table_relation（查表关系）、generate_sql（生成 SQL）、validate_sql（校验 SQL）、execute_sql（执行 SQL）
  • 编排框架：Dify（可视化编排）+ LangChain（复杂逻辑用 Python 写）
  • 记忆：短期对话历史 + 长期业务术语库

我踩过的坑（这些网上没人告诉你）

坑 1：模型”乱调工具”在生产环境多可怕

刚上线测试时，我让模型处理”查用户数”这个问题，它调了 8 次工具——查 schema、查表关系、生成 SQL、校验、执行、结果转自然语言、再调一次 schema、再生成 SQL……整个链路耗时 12 秒，token 消耗是预期的 5 倍。

排查发现：工具描述写得不好，模型不知道”什么时候该用哪个工具”。

修复方式：

  • 每个工具的描述必须具体到”什么场景用”，不能只写”查询数据库”
  • 工具之间的依赖关系要明确说出来（”调 generate_sql 前必须先调 query_schema”）
  • 用 few-shot 给模型”调用样例”

后来我有个深刻的认知：Agent 项目的 50% 工作量在写工具描述和 Prompt，不在写代码。很多团队觉得”模型不够聪明”——其实是工具描述烂。

坑 2：循环没有终止条件 = 死循环 + 钱烧光

有一次测试，模型陷入了一个循环：

1
2
3
4
5
6
Thought: 上次 SQL 错了，再生成一次
Action: generate_sql
Observation: SQL 错了
Thought: 上次 SQL 错了，再生成一次
Action: generate_sql
... (重复 30 次)

30 次生成 + 30 次执行 = 30 次 LLM 调用 + token 烧了几十块。如果是生产环境跑着，这是钱在烧。

修复方式：

  • 强制 max_iterations：LangChain AgentExecutor 可以设置 max_iterations=5
  • 每次重试要”真的不一样”：检查生成的 SQL 和上一次是否有差异，没差异直接终止
  • 超时熔断：整个 Agent 执行超过 N 秒直接终止

教训：Agent 项目必须做”成本护栏”。LLM 是按 token 计费的，一个死循环可以让你一晚上烧掉一周的预算。

坑 3：工具粒度错了，模型直接抓瞎

我第一版把”执行 SQL”做成了一个工具 execute_sql。结果模型遇到复杂场景时完全不知道什么时候该用——它把”执行 SQL”当成了”做所有事”的工具。

后来我把它拆成 3 个工具：

  • dry_run_sql（不执行，只校验）
  • execute_readonly_sql（只读查询）
  • execute_with_permission（带权限的查询）

拆完后模型选择工具的准确率从 60% 提升到 90%+。

教训：工具的粒度要和”业务动作”对齐，不要按”代码函数”来切。execute_sql 是代码函数，但”安全执行 SQL”是业务动作。

坑 4：Memory 用错了，对话历史变噪音

早期我用 LangChain 的 ConversationBufferMemory，把所有对话历史都塞给模型。结果用户问”上个月用气量”——模型把上上次、上上上次的对话也带上了，污染了上下文。

后来改成：

  • 只保留当前 session 的最近 3 轮对话
  • 业务术语、用户偏好等”长期记忆”单独存（向量库），按需检索注入
  • 历史查询结果不直接喂给模型，而是作为”参考”

教训：Memory 不是”记得越多越好”，是”记得对才好”。给模型太多上下文，反而让它的注意力被分散。

坑 5：评估怎么做？没有银弹

LangChain 官方提供了 Agent 评估框架，但评估”业务上答对没”非常难。比如用户问”片区 3 的用户数”，模型返回 1234，但真实是 1235——这算对还是错？SQL 写对了但数据差 1 个，是”业务答错”还是”数据时延”？

我后来用了几种评估方式混合：

  1. SQL 准确率：人工标注 gold set，看模型生成的 SQL 是否和 gold SQL 语义等价
  2. 业务结果准确率：抽样 100 个查询人工核对（成本高但有用）
  3. 用户反馈：让用户对每个回答点”有用/没用”

教训：没有一种评估方式能完整反映 Agent 的真实表现。生产环境一定要多种评估结合，并持续跟踪。

工程化的几条硬规则

踩了这么多坑之后，我给自己定了几个硬规则：

  1. 工具数量控制在 10 个以内。超过 10 个，模型选择工具的准确率断崖式下降
  2. 每个工具必须有清晰的”何时用”描述。这是模型能不能用好工具的关键
  3. 必须有 max_iterations 和超时熔断。这是成本和稳定性的护栏
  4. 必须记录 Thought / Action / Observation 完整日志。出问题时回溯链路
  5. 必须有 gold set 持续回归。LLM 升级、prompt 改动都可能让效果回归
  6. 业务方预期管理——别承诺”100% 准确”，准备 fallback

最后一点真心话

Agent 是这两年 AI 落地的”明星概念”，各种 Agent 框架（LangChain、AutoGPT、AgentScope、Dify Agent）百花齐放。

但做了几个 Agent 项目后我越来越觉得：

Agent 的”工程化”远比”算法”重要。算法选型错了最多效果差 10%，工程化没做好可能直接上线就崩。

如果你刚开始做 Agent 项目，我的建议是：

  1. 先从 2-3 个工具的小场景开始——别上来就搞 20 个工具的复杂 Agent
  2. 工具描述字字斟酌——这是效果上限的关键
  3. 监控好 token 消耗和工具调用次数——这两个是 Agent 项目的核心 KPI
  4. 别追求”全自动 Agent”——半自动（人审核关键决策）比全自动稳定得多

网上那些”5 分钟搭一个 Agent”的视频看着很爽，但真到生产你会发现——能跑 ≠ 能用，能用 ≠ 能用好。