从零构建LangChain智能体：理解Agent架构与ReAct模式实践

1. 项目概述：从“程序”到“智能体”的认知跃迁

最近和不少刚入行或者从传统开发转过来的朋友聊天，发现大家对“Agent”这个概念既好奇又困惑。好奇是因为这个词现在太火了，从OpenAI到各种创业公司都在提；困惑是因为它听起来很玄乎，好像和传统的“程序”或者“脚本”差不多，但又感觉哪里不一样。我第一次接触这个概念时，也有同样的感觉，花了不少时间才把脑子里那团迷雾拨开。今天，我就以一个过来人的身份，结合当前最热门的LangChain等框架，和大家聊聊我对Agent的“第一次接触”心得，希望能帮你少走点弯路。

简单来说，你可以把传统的程序想象成一个非常听话、但也很“轴”的实习生。你给他一份极其详细的SOP（标准作业程序），第一步点哪里，第二步输什么，他都能一丝不苟地完成。但一旦遇到SOP里没写的情况，比如界面按钮位置变了，或者弹出了一个意外的提示框，他就卡住了，只会举手问你：“老板，接下来怎么办？” 而Agent（智能体），更像是一个有经验、会思考的资深员工。你只需要告诉他一个目标，比如“帮我把上个月的销售数据整理成一份PPT报告”，他就能自己去理解这个目标，拆解成“登录系统、导出数据、分析趋势、生成图表、排版成PPT”等一系列子任务，并且在这个过程中，如果发现数据格式不对或者缺少某个维度的信息，他会尝试自己想办法解决（比如去其他数据库查一下，或者用另一种方式计算），实在搞不定了再来问你。这个“自己想办法”的过程，核心就是利用大语言模型（LLM）的理解、规划和工具调用能力。

所以，Agent不是一个具体的函数或者API，它是一种架构模式，一种构建具备自主性、交互性和一定推理能力的应用系统的设计思想。它让我们的程序从“被动执行命令”进化到了“主动完成任务”。接下来，我们就一步步拆解，看看这个“资深员工”到底是怎么工作的。

2. Agent的核心架构与工作原理拆解

理解Agent，最关键的是搞明白它的核心循环，也就是它“思考-行动-观察”的工作模式。这听起来简单，但里面的门道不少。

2.1 大脑、工具与记忆：Agent的三要素

一个典型的Agent，通常由三个核心部分组成，我们可以类比成一个人：

1. 大脑（Brain）- 大语言模型（LLM）：这是Agent的决策核心。它负责理解用户的指令（或当前状态），进行推理和规划，决定下一步该做什么。它不直接操作世界，而是输出“想法”或“指令”。比如，用户说“今天天气如何？”，LLM会理解到这是一个需要查询天气的任务。现在主流的LLM如GPT-4、Claude、DeepSeek等都能担任这个角色。在LangChain中，这就是你配置的那个ChatModel或LLM对象。

2. 手脚（Hands & Feet）- 工具（Tools）：这是Agent与外部世界交互的接口。LLM自己想得再好，没法自己去打开浏览器查天气，也没法去数据库里拉取数据。工具就是它延伸出去的手脚。一个工具通常是一个函数，它封装了一个具体的操作，比如search_web(query)、query_database(sql)、send_email(to, subject, body)。LLM在决定要做什么之后，会选择调用一个或多个合适的工具，并生成调用这个工具所需的参数。在LangChain里，你可以用@tool装饰器轻松地把一个Python函数变成Agent可用的工具。

3. 经验与上下文（Experience & Context）- 记忆（Memory）：一个健谈的人不能只记得当前这一句话，他需要记住整个对话的历史，甚至更早的知识。Agent也一样。记忆模块负责存储和检索与当前任务相关的历史信息。这分为短期记忆（如当前对话的上下文）和长期记忆（如从向量数据库检索的相关知识）。有了记忆，Agent才能进行连贯的多轮对话，才能基于之前的错误进行调整。LangChain提供了多种记忆组件，如ConversationBufferMemory用于保存简单对话历史，ConversationSummaryMemory则会对长历史进行摘要以节省Token。

2.2 ReAct模式：Agent的思考行动闭环

光有组件还不够，得有一套机制让它们运转起来。目前最主流、也最有效的模式之一就是ReAct（Reason + Act）。这个模式完美地体现了“思考-行动-观察”的循环。

我画个简单的伪代码流程，你一看就懂：

循环开始： 1. 思考（Think）: LLM根据【用户问题 + 历史对话 + 已观察到的工具结果】，分析当前状况，决定下一步是“直接给出最终答案”还是“需要调用某个工具”。 2. 行动（Act）: 如果决定调用工具，LLM会精确地输出要调用的工具名称和输入参数。例如：`Action: search_web, Action Input: "上海今日天气预报"`。 3. 观察（Observe）: 系统执行指定的工具，并将工具返回的结果（Observation）反馈给LLM。例如：`Observation: 上海今日晴，气温15-22°C，东南风3级`。 4. 再思考（Think Again）: LLM结合新的观察结果，再次思考。如果信息已足够回答用户，则输出最终答案；如果不够，则继续循环，决定调用下一个工具。 循环结束（当LLM输出最终答案时）

这个循环可能会进行很多轮。比如一个复杂任务：“找出特斯拉和比亚迪过去一个季度的股价变化，并分析其主要原因。” Agent可能会先调用搜索工具查股价数据，再调用另一个搜索工具查新闻和分析报告，最后调用代码工具计算变化率并生成总结。LLM在每一轮都要判断“我现在知道什么”、“我还需要什么”、“我该用什么工具去获取”。

注意：让LLM严格按照指定格式（如Action: ... Action Input: ...）输出是实践中的第一个小坑。如果格式不对，系统就无法正确解析。这通常需要通过精心设计的提示词（Prompt）和输出解析器（Output Parser）来约束。LangChain的AgentExecutor已经帮我们处理了大部分这类脏活累活。

3. 从零构建你的第一个LangChain Agent

理论说再多，不如动手跑一遍。我们用一个最经典的例子——让Agent联网搜索并回答问题，来感受一下Agent是如何工作的。这里我选择LangChain，因为它生态丰富、文档详细，是学习Agent概念的最佳起点之一。

3.1 环境准备与工具定义

首先，确保你的Python环境（建议3.8以上）已经安装了必要的包。我们这里需要LangChain的核心包、OpenAI的LLM（或者其他你喜欢的模型，如通过Ollama本地部署的），以及一个搜索工具。这里我用duckduckgo-search作为例子，因为它无需API Key。

pip install langchain langchain-openai duckduckgo-search

接下来，我们写代码。第一步，设置LLM。你需要一个OpenAI的API Key。

import os from langchain_openai import ChatOpenAI # 建议将API Key设置在环境变量中，不要硬编码在代码里 os.environ["OPENAI_API_KEY"] = "你的-api-key" # 初始化LLM，这里使用GPT-3.5-turbo，性价比高，适合实验 llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0) # temperature控制创造性，0表示更确定性的输出，适合任务执行

第二步，定义工具。我们需要一个能让Agent去执行搜索的工具。

from langchain.tools import Tool from duckduckgo_search import DDGS def search_online(query: str) -> str: """使用DuckDuckGo搜索网络信息。""" try: with DDGS() as ddgs: # 获取最相关的几条结果 results = [r for r in ddgs.text(query, max_results=3)] if results: # 将结果拼接成一个字符串返回 return "\n".join([f"{r['title']}: {r['body']}" for r in results]) else: return "未找到相关信息。" except Exception as e: return f"搜索过程中出现错误：{e}" # 将函数包装成LangChain Tool对象 search_tool = Tool( name="WebSearch", # 工具名称，LLM会通过这个名字来调用 func=search_online, # 工具对应的函数 description="当您需要获取最新的、实时的信息时非常有用，比如当前事件、天气、新闻或未知的具体事实。" # 工具描述，这是给LLM看的，非常重要！ )

这里有个关键细节：description（工具描述）写得好不好，直接决定了Agent能否正确使用这个工具。描述要清晰说明工具的用途和适用场景，LLM就是靠这段描述来判断“我该不该用这个工具”。比如，如果你把搜索工具描述成“用于计算数学”，那LLM就永远不会用它来查新闻。

3.2 组装Agent并观察其思考过程

有了大脑（LLM）和工具（Tool），我们就可以创建Agent了。LangChain提供了多种预设的Agent类型，对于初学者，ZERO_SHOT_REACT_DESCRIPTION是一个很好的选择，它基于我们前面讲的ReAct模式。

from langchain.agents import initialize_agent, AgentType from langchain.memory import ConversationBufferMemory # 初始化一个简单的对话记忆，让Agent能记住上下文 memory = ConversationBufferMemory(memory_key="chat_history", return_messages=True) # 定义工具列表 tools = [search_tool] # 创建Agent agent = initialize_agent( tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, # 使用Zero-shot ReAct Agent verbose=True, # 强烈建议设为True，这样能看到Agent的思考过程！ memory=memory, handle_parsing_errors=True # 优雅地处理输出解析错误 )

现在，让我们问它一个需要实时信息的问题，看看它怎么工作。

response = agent.run("2024年诺贝尔文学奖得主是谁？") print(response)

当你运行这段代码，并将verbose设为True时，你会在控制台看到类似下面的输出，这就是Agent的“内心独白”：

> Entering new AgentExecutor chain... 我需要找到2024年诺贝尔文学奖的最新信息。这是一个关于当前事件的问题，需要最新的数据。 Action: WebSearch Action Input: 2024年诺贝尔文学奖得主 Observation: 诺贝尔奖官网信息：2024年诺贝尔文学奖将于2024年10月10日公布...（实际搜索结果） Thought: 根据搜索结果，2024年的奖项尚未公布。我需要告诉用户这个信息。 最终答案：2024年诺贝尔文学奖的得主尚未公布，预计将在2024年10月10日揭晓。 > Finished chain. 2024年诺贝尔文学奖的得主尚未公布，预计将在2024年10月10日揭晓。

看到了吗？Agent完整地走了一遍ReAct循环：

1. Thought: 它“想”到这是一个需要最新信息的问题，决定使用搜索工具。
2. Action: 它“行动”，调用了WebSearch工具，并给出了搜索词。
3. Observation: 它“观察”到了工具返回的结果（奖项未公布）。
4. Final Thought & Answer: 它根据观察结果，得出了最终答案并输出。

这个过程清晰展示了Agent的自主决策能力。你并没有告诉它“去搜索XXX”，你只问了问题，是它自己规划并执行了搜索动作。

3.3 多轮对话与记忆的体现

让我们再试一个需要多轮交互的例子，看看记忆模块的作用。

# 第一轮 response1 = agent.run("梅西效力于哪家足球俱乐部？") print("第一轮回答:", response1) # 第二轮，基于上一轮的上下文 response2 = agent.run("他是什么时候加入的？") print("第二轮回答:", response2)

在verbose模式下，你会看到在第二轮对话开始时，Agent的Prompt里已经包含了第一轮对话的历史（“Human: 梅西效力于哪家足球俱乐部？ AI: 梅西目前效力于美国职业足球大联盟的迈阿密国际俱乐部。”）。因此，它能正确理解“他”指代的就是梅西，并再次调用搜索工具去查找梅西的加盟时间。这就是记忆在起作用，使得对话能够连贯进行。

4. 深入实践：构建一个多工具协作的复杂Agent

只会搜索的Agent只是个开始。真正的威力在于让Agent协调多个工具，完成复杂的工作流。我们尝试构建一个更实用的Agent，让它既能搜索信息，又能进行简单的计算。

4.1 扩展工具集：为Agent添加“计算器”

我们给之前的Agent增加一个计算工具。

from langchain.tools import tool import math @tool def calculator(expression: str) -> str: """用于执行数学计算。输入应为一个可被Python的eval()安全计算的数学表达式字符串，例如 ‘(12 + 5) * 2‘。只支持基本算术和math库函数。""" # 警告：在实际生产环境中，直接使用eval()是极度危险的，可能造成代码注入。 # 这里仅为演示，必须对输入进行严格过滤。实践中应使用ast.literal_eval或专用数学解析库。 allowed_names = {k: v for k, v in math.__dict__.items() if not k.startswith("_")} allowed_names.update({"abs": abs, "round": round}) try: # 非常基础的过滤，切勿用于真实项目！ compiled_code = compile(expression, "<string>", "eval") for name in compiled_code.co_names: if name not in allowed_names: raise ValueError(f"禁止使用函数或变量名: {name}") result = eval(expression, {"__builtins__": {}}, allowed_names) return str(result) except Exception as e: return f"计算错误：{e}" # 更新工具列表 tools = [search_tool, calculator] agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION, verbose=True, memory=memory)

重要安全提示：上面的calculator工具为了演示简化了安全措施。绝对不要在可公开访问的服务中使用未经严格安全检查的eval()函数。在实际开发中，应使用ast.literal_eval（仅支持字面量）或像numexpr、sympy这样的安全计算库。

4.2 观察多工具协作：一个综合任务

现在，让我们问一个需要组合使用搜索和计算的问题。

response = agent.run("苹果公司当前股价是多少美元？如果我现在投资5000美元，可以买多少股？（忽略交易费用）")

观察verbose输出，一个设计良好的Agent可能会执行以下步骤：

1. Thought 1: 需要当前股价，这是实时信息，调用WebSearch。
2. Action 1: 搜索“Apple stock price today”。
3. Observation 1: 获得股价，比如“$182.50 per share”。
4. Thought 2: 现在需要计算5000美元能买多少股。这是一个数学计算，调用calculator。
5. Action 2: 计算5000 / 182.5。
6. Observation 2: 得到结果“27.397...”。
7. Thought 3: 整合信息，给出最终答案。
8. Final Answer: “根据当前股价约182.50美元，5000美元大约可以购买27股（忽略交易费用）。”

这个过程展示了Agent如何像一个项目经理一样，将一个复杂问题分解为顺序执行的子任务（搜索、计算），并为每个子任务分配合适的“资源”（工具）。

4.3 工具描述的艺术与调试技巧

在实践中，Agent“犯傻”或者选错工具的情况很常见。大部分问题都出在两个方面：提示词（Prompt）和工具描述（Tool Description）。

• 模糊的描述导致错误调用：如果你的计算工具描述是“处理数字”，那么当用户问“处理一下这个文档”时，Agent也有可能去调用计算器，因为它把“处理”这个词匹配上了。描述要尽可能精确，如“用于执行基本算术和数学函数计算”。
• 工具冲突：如果你有两个工具，一个叫search（通用搜索），一个叫search_finance（金融数据搜索），当问题关于股票时，Agent可能因为描述相似而随机选择。你需要让描述具有区分度，比如后者可以描述为“专门用于查询股票价格、公司财报等金融数据的工具”。

调试技巧：当Agent行为不符合预期时，第一件事就是把verbose打开，看它的“Thought”过程。它为什么做出了那个决定？是工具描述理解错了，还是上一步的观察结果有歧义？根据思考链来调整Prompt或工具描述，是优化Agent最有效的方法。

5. 进阶框架概览：LangGraph与智能体编排

当你开始设计涉及多个Agent协作、或者有复杂状态流转的任务时，基础的AgentExecutor可能会显得力不从心。这时就需要更强大的编排框架，这就是LangGraph出场的时候。

5.1 为什么需要LangGraph？

可以把基础的LangChain Agent看作一个“单线程”的决策循环。而LangGraph允许你定义基于图（Graph）的工作流。节点（Node）可以是Agent、工具、或者任何函数，边（Edge）定义了节点之间的流转条件。

这解决了哪些复杂场景？

• 多智能体协作：创建一个“研究员”Agent负责搜索，一个“写手”Agent负责总结，一个“评审”Agent负责检查质量，让它们接力工作。
• 循环与条件分支：根据上一步的结果，决定下一步是重试、换条路走，还是结束。比如，如果搜索没结果，就换一个关键词再搜一次。
• 持久化状态管理：复杂任务的状态（如已收集的数据、中间结论）可以更精细地在整个图中传递和管理。

5.2 一个简单的LangGraph概念示例

假设我们要构建一个“质量检查”工作流：先生成一段内容，然后检查其是否包含敏感词，如果不包含就结束，如果包含就将其过滤后再输出。

用LangGraph的思路，我们可以定义两个节点：

1. generate_node: 调用LLM生成内容。
2. censor_node: 检查并过滤敏感词。

然后定义边：

• 从generate_node到censor_node。
• 在censor_node中，判断内容是否干净。如果干净，流向END；如果不干净，流回generate_node要求重写。

这种带循环和条件判断的流程，用LangGraph来可视化设计和实现会清晰得多。虽然在这里无法展开完整的代码，但你需要知道的是，当你的智能体逻辑超越了简单的“一问一答”或“线性工具调用”，开始涉及“如果...就...”或者“让A和B先讨论一下”的时候，就该考虑LangGraph这类工具了。

6. 常见“踩坑”实录与排查指南

接触Agent开发，几乎没有不踩坑的。下面是我和同事们总结的一些典型问题及解决方案，希望能帮你提前避雷。

6.1 Token超限与上下文管理

这是新手遇到最多的问题。LLM有上下文窗口限制（比如GPT-3.5-turbo是16K Token）。当你使用长记忆、或者工具返回了大量文本（如搜索了十篇长文）时，很容易超出限制，导致API调用失败或LLM“失忆”。

解决方案：

• 精简工具输出：不要让工具返回原始HTML或整篇文档。在工具函数内部就做好摘要和提取。例如，搜索工具只返回前三段摘要，而不是全文。
• 使用摘要记忆：用ConversationSummaryMemory代替ConversationBufferMemory。它会自动将历史对话总结成一段摘要，而不是罗列所有对话，极大节省Token。
• 分块处理：对于超长文本，使用TextSplitter将其分割，并通过向量检索（RAG）的方式，只将最相关的片段放入上下文。
• 监控Token用量：在代码中计算输入的Token数（可以使用tiktoken库），在接近限制时主动清理早期记忆。

6.2 Agent陷入死循环或无效行动

有时Agent会卡在一个循环里，比如反复调用同一个工具却得不到新信息，或者不停地“思考”而不输出最终答案。

排查与解决：

1. 检查max_iterations和max_execution_time参数：在初始化AgentExecutor时，务必设置这两个参数（例如max_iterations=10），这是防止无限循环的安全绳。
2. 优化工具描述和Prompt：循环往往是因为LLM对当前状态判断失误。仔细阅读verbose日志，看Agent的“Thought”是否合理。可能是工具描述不够清晰，导致它误以为该工具能解决当前问题。也可能是系统Prompt（System Message）中关于“如何给出最终答案”的指令不够明确。
3. 引入“强制终止”工具：可以设计一个final_answer工具，当LLM认为可以结束时，显式调用这个工具来输出结果。这比让LLM自行输出“Final Answer:”更可控。

6.3 工具调用格式错误

LLM没有严格按照Action: ToolName, Action Input: args的格式输出，导致解析失败。

解决方案：

• 使用更强大的Agent类型：AgentType.ZERO_SHOT_REACT_DESCRIPTION对格式要求比较严格。可以尝试AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION，它使用更结构化的消息格式，通常能产生更规范的输出。
• 强化Prompt中的格式示例：在给Agent的系统提示中，包含几个清晰、正确的输出格式示例（Few-shot Prompting），能显著提高其遵循格式的能力。
• 依赖框架的解析器：LangChain的AgentExecutor内置了重试和错误处理逻辑（handle_parsing_errors=True），对于轻微的格式错误，它会尝试让LLM重新生成。确保这个选项是打开的。

6.4 处理不确定性与错误

工具执行可能失败（网络超时、API限流），或者返回的结果模棱两可（“未找到相关信息”）。一个健壮的Agent需要处理这些情况。

设计模式：

• 工具层重试：在工具函数内部实现简单的重试机制（如tenacity库）。
• Agent层异常处理：在AgentExecutor中，可以自定义handle_tool_error回调函数，当工具抛出异常时，将友好的错误信息作为Observation返回给LLM，让它决定下一步（例如，“网络搜索失败，请尝试更换搜索词或稍后再试”）。
• 结果验证：对于关键工具，可以设计一个“验证”步骤。例如，在调用计算器后，再用一个简单的规则检查结果是否合理（如股价不应为负数）。

7. 技术栈选型与学习路线建议

看到这里，你可能对Agent开发的全貌有了了解。如果想深入下去，下面是我个人建议的学习路径和技术栈思考。

7.1 核心技能栈

1. Python编程：这是基础中的基础，必须熟练。特别是函数、装饰器、异步编程（asyncio）等概念，在构建高效工具和Agent时经常用到。
2. 大语言模型基础：理解LLM的工作原理、Token概念、Prompt工程的基本技巧（如角色设定、Few-shot、思维链）。不需要深究模型架构，但要知道如何与它们有效“对话”。
3. 一个主框架：LangChain是目前生态最成熟、学习资源最丰富的选择，非常适合入门和构建复杂应用。把它的核心概念（Model, Prompt, Chain, Agent, Memory, Retrieval）搞懂，就掌握了大部分场景。
4. 工具集成能力：Agent的灵魂在于工具。你需要学会如何将各种API（如搜索引擎、数据库、邮件服务、企业内部系统）封装成安全、可靠、描述清晰的Tool。这要求你对网络请求（requests, aiohttp）、数据格式（JSON, XML）等有实操经验。
5. 部署与运维：开发完的Agent需要跑起来。了解基本的Web框架（如FastAPI）、任务队列（Celery）、以及如何将Agent部署为API服务或后台任务。

7.2 框架生态浅析：LangChain vs Others

• LangChain/LangGraph：正如前文所述，是“全家桶”式的框架，从简单的链到复杂的智能体工作流都能覆盖。优点是模块化、生态好、社区活跃；缺点是抽象层次有时较高，需要理解其设计哲学。LangGraph是LangChain官方的、用于构建有状态、多参与者工作流的库，可以看作是LangChain在复杂编排方向的延伸。
• CrewAI：专注于多智能体协作。如果你要构建的是一个团队（一组各司其职的Agent），CrewAI提供了更高层级的抽象，比如定义Agent的角色（Role）、目标（Goal）、后台故事（Backstory）以及它们之间的协作流程（Process），更容易管理多Agent项目。
• AutoGen（微软）：另一个强大的多智能体对话框架。它的特点是Agent之间可以通过对话来协商解决问题，更贴近人类团队的讨论模式。研究性质更强，配置也相对更复杂一些。

如何选择？对于绝大多数初学者和希望快速上手的开发者，从LangChain开始是最稳妥的。它提供了最平滑的学习曲线和最全面的功能覆盖。当你需要构建明确的多角色协作系统时，再去看CrewAI；当你需要研究更复杂的Agent交互模式时，再去探索AutoGen。

7.3 学习资源与下一步

• 动手，动手，再动手：Agent开发是高度实践性的。不要只看文档，一定要从pip install langchain开始，复现文中的例子，然后改造它，比如换一个工具，实现一个自动写周报的Agent，或者集成到你自己的项目中。
• 善用官方文档与社区：LangChain的官方文档质量很高，并且有大量集成示例。遇到问题，先在GitHub Issues和Discord社区里搜索，大概率已经有人遇到过并解决了。
• 从小项目开始：不要一开始就想做一个“全能办公助手”。可以从一个非常具体的小功能做起，比如“会议纪要总结Agent”、“技术文档问答Bot”。完成一个小闭环，能给你带来巨大的信心和实实在在的经验。

第一次接触Agent概念，感觉它像是一把打开新世界大门的钥匙，让程序有了“意图”和“能动性”。但真正用起来你会发现，它既强大又脆弱，强大在于它能串联起无数能力解决复杂问题，脆弱在于它的每一步都依赖精准的Prompt、清晰的工具描述和稳定的执行环境。这其中的平衡与精妙，正是开发者需要倾注心血的地方。我的体会是，把它看作一个需要精心调教和约束的、能力超群的实习生，你的角色从“编码员”变成了“架构师”和“教练”，这种转变本身就充满了挑战和乐趣。