01. LangChain Agent 总览

学习目标

本章帮助你建立 Agent 应用的整体地图。读完后，你应该能说明 LangChain、LangGraph、LangSmith 和 Ollama 各自负责什么，并能根据任务复杂度选择 create_agent 或 LangGraph。

LangChain 负责什么

LangChain 是围绕模型构建应用的框架和运行骨架。它不替代大模型，而是帮助你把模型、消息、提示词、工具、检索结果和上下文组织到同一个程序里。

在本教程中，LangChain 主要负责：

• 调用本地 Ollama 模型。
• 构造模型能理解的消息和提示词。
• 把 Python 函数暴露成可调用工具。
• 使用 create_agent 组织基础 Agent Loop。
• 把检索结果、历史消息和运行状态传递给模型。

LangGraph 负责什么

LangGraph 是更底层的 Agent 编排框架。它适合用来描述显式状态、节点、边、条件路由、持久化和 human-in-the-loop 流程。

当 Agent 不再是简单的“模型决定是否调用工具”，而是需要固定步骤、分支判断、可恢复执行、人工审批或复杂状态管理时，LangGraph 会比单纯使用 create_agent 更清晰。

LangSmith 负责什么

LangSmith 负责追踪、评估和监控。它可以记录每次模型调用、工具调用、输入输出和错误，帮助你理解 Agent 为什么这样运行。

本教程不要求必须使用 LangSmith。你可以先通过命令行日志和调试输出来理解 Agent 行为，后续再把 LangSmith 作为可选增强加入项目。

Ollama 负责什么

Ollama 是本地模型运行时。它负责在你的机器上下载、加载和运行模型，例如 qwen3。

需要注意的是，工具调用是否稳定取决于模型能力。LangChain 可以把工具定义交给模型，但模型是否正确选择工具、是否生成合法参数、是否理解工具结果，都取决于模型本身和上下文设计。

Agent Loop

一个基础 Agent Loop 通常是这样的：

1. 用户提出任务。
2. 程序把用户任务、上下文和工具定义发送给模型。
3. 模型选择直接给出最终答案，或者请求调用某个工具。
4. 程序执行工具，并拿到工具结果。
5. 程序把工具结果返回给模型。
6. 模型继续判断是否需要更多工具调用，重复以上步骤，直到生成最终答案。

这个循环的关键点是：工具不是模型自己执行的。模型只提出工具调用请求，真正执行工具的是你的程序。

选择规则

优先使用 create_agent 的情况：

• Agent 流程主要由模型决定。
• 工具数量少，调用链路短。
• 不需要复杂分支、恢复执行或人工审批。
• 你正在学习或验证一个最小可用 Agent。

选择 LangGraph 的情况：

• 你需要显式定义节点、边和条件路由。
• 流程必须按固定步骤执行，而不是完全交给模型自由决定。
• 需要持久化状态、恢复中断任务或记录长期运行进度。
• 需要 human-in-the-loop，例如某些工具调用前必须人工确认。
• Agent 已经包含多个子流程，单个 create_agent 难以解释和调试。

简单规则是：先用 create_agent 建立最小闭环；当状态、分支和可恢复性成为核心需求时，再升级到 LangGraph。

一个最小 Agent 的组成

可以把本教程里的 Agent 拆成五个部分：

• 模型：负责理解输入、生成回答、决定是否调用工具。
• 系统提示：定义角色、边界和工具使用规则。
• 消息历史：保存当前会话中模型能看到的上下文。
• 工具集合：把外部能力暴露给模型，例如计算、查询知识库、读取文件。
• 运行循环：负责把模型的工具请求交给程序执行，再把工具结果交还给模型。

这五个部分里，只有模型是概率性的；工具和运行循环应该尽量确定、可测试、可观测。好的 Agent 工程不是让模型“什么都自己想办法”，而是把确定性的工作交给程序，把需要语言理解和决策的部分交给模型。

常见误解

• 误解一：Agent 越复杂越智能。实际项目里，复杂度越高，越需要可观测性、边界和测试。
• 误解二：LangGraph 是 LangChain 的替代品。更准确地说，LangGraph 是更底层的编排能力，很多 LangChain Agent 能力也建立在 LangGraph 思路之上。
• 误解三：本地模型能聊天，就一定能稳定调用工具。聊天能力、结构化输出能力和工具调用能力是不同能力。
• 误解四：失败都是 Prompt 问题。工具 schema、模型能力、RAG 检索质量、消息历史长度都可能导致失败。

自测问题

• 如果一个任务只需要两个工具和简单多轮对话，你会先用 create_agent 还是 LangGraph？
• 如果一个任务必须“先审核再执行”，为什么 LangGraph 更合适？
• LangSmith 解决的是模型能力问题，还是可观测性问题？

深入理解：Agent 不是一个“更聪明的模型”

Agent 经常被误解成“会自己完成任务的模型”。从工程角度看，Agent 更准确地说是一套运行协议：

1. 应用把任务、上下文、工具说明和历史消息组织成模型输入。
2. 模型基于这些输入产生下一步意图。
3. 应用解释这个意图：直接回答、调用工具、继续追问或结束。
4. 应用执行确定性动作，并把结果放回上下文。
5. 循环继续，直到满足停止条件。

所以 Agent 的能力来自两个部分：模型的语言理解和决策能力，以及应用层给它设计的可执行边界。模型可以决定“应该查知识库”，但检索器怎么查、能查哪些数据、错误怎么处理、是否允许高风险动作，都应该由程序控制。

这也是为什么 Agent 工程要把“模型决策”和“系统执行”分开。模型输出不能直接等同于系统事实，工具结果也不能不经校验就交给下游高权限操作。

工程边界：哪些事交给模型，哪些事交给代码

适合交给模型的事情：

• 理解自然语言任务。
• 在多个低风险工具之间选择。
• 总结工具结果。
• 根据上下文生成用户可读回答。
• 对模糊需求提出澄清问题。

适合交给代码的事情：

• 权限判断。
• 参数校验。
• 数据库写入。
• 支付、删除、发送通知等副作用操作。
• 重试、超时、幂等、审计。
• 判断流程是否允许进入下一步。

如果一个系统把所有判断都交给模型，它会很快变得不可预测。如果一个系统把所有语言理解都写成规则，它又会失去 LLM 的价值。好的 Agent 设计是在两者之间画清楚边界。

失败定位矩阵

现象	更可能的问题层	优先检查
模型没有调用工具	模型能力、工具描述、系统提示	tool_calls、工具 docstring、temperature
调用了错误工具	工具边界不清	工具命名、工具数量、描述相似度
工具参数格式错误	schema 复杂或模型能力不足	参数类型、字段名、是否需要拆工具
RAG 回答编造	检索弱或 prompt 边界弱	retrieved docs、工具是否被调用
多轮对话忘记前文	memory 没传入或上下文过长	messages 列表、历史裁剪策略
流程走错步骤	编排不显式	是否应该使用 LangGraph

这个矩阵不是绝对结论，但能帮助你避免“一出错就改 prompt”的惯性。