在实际 AI 项目开发中很多开发者会陷入一个误区认为只要掌握了某个大模型 API 的调用或者拼接几个开源框架就能快速构建出智能、可靠的 AI Agent。然而从零开始构建一个能理解复杂指令、具备记忆、能使用工具并自主决策的智能体远比调用单一接口复杂。这涉及到对 Transformer 架构的理解、对提示工程的精细设计、对 RAG 知识库的构建以及对 LangChain 等框架的灵活运用。本文旨在为希望系统学习 AI Agent 开发的工程师提供一个清晰、可落地的学习路径和实战指南我们将从核心概念入手逐步搭建一个具备基础能力的 AI Agent并深入探讨其内部机制与生产环境下的最佳实践。本文适合有一定 Python 基础希望深入 AI 应用层开发的开发者。通过阅读和实践你将能够理解 AI Agent 的核心组件掌握使用 LangChain 构建智能体的基本方法并了解如何集成 RAG 系统来增强 Agent 的知识与准确性。1. 理解 AI Agent 的核心架构与工作原理在深入代码之前我们必须先厘清 AI Agent 究竟是什么以及它如何工作。这有助于我们在后续开发中做出正确的技术选型和架构设计。1.1 AI Agent 的定义与核心组件AI Agent智能体并非一个单一的模型而是一个系统。它通常被设计为能够感知环境、进行推理、做出决策并执行行动以实现特定目标的软件实体。一个典型的 AI Agent 包含以下几个核心组件大脑Brain/Core LLM通常是一个大型语言模型LLM如 GPT、LLaMA 等负责理解输入、进行逻辑推理和生成文本输出。它是 Agent 的“思考”中心。记忆Memory使 Agent 能够记住之前的对话或交互历史。这可以是简单的对话缓冲区也可以是更复杂的向量存储用于长期记忆和上下文检索。工具Tools扩展 Agent 能力的外部函数或 API。例如计算器、网络搜索、数据库查询、代码执行器等。Agent 通过“思考”决定何时以及如何使用这些工具。规划Planning对于复杂任务Agent 需要将其分解为一系列子步骤或动作并规划执行顺序。ReActReasoning Acting模式是其中的典型代表。行动Action根据规划和工具使用的结果执行具体的操作并将结果返回给“大脑”进行下一轮思考。1.2 Transformer 架构现代 LLM 的基石要深入理解 Agent 的“大脑”必须对 Transformer 架构有基本认识。Transformer 摒弃了 RNN 的序列计算模式完全基于自注意力Self-Attention机制使其能够并行处理序列数据并捕获长距离依赖。其核心工作流程可以简化为输入表示将文本转换为词向量并加上位置编码。编码器堆叠输入经过多层编码器每层包含多头自注意力机制和前馈神经网络用于提取和理解输入信息的复杂特征。解码器堆叠对于生成式模型在编码器输出的基础上通过掩码自注意力和编码器-解码器注意力机制逐步生成输出序列。对于开发者而言无需从头实现 Transformer但理解其注意力机制有助于你更好地设计提示词Prompt因为提示词本质上是为模型提供特定的“注意力焦点”。例如在 RAG 中我们通过检索相关文档片段将这些信息作为上下文放入提示词就是在引导模型将“注意力”集中在这些最相关的信息上。1.3 RAG为 Agent 注入精准的外部知识LLM 存在知识截止日期和幻觉问题。检索增强生成RAG是解决该问题的关键技术。它通过以下步骤工作索引将外部知识源文档、网页、数据库进行分块并转换为向量Embeddings存入向量数据库。检索当用户提问时将问题也转换为向量并在向量数据库中搜索与之最相似的文本块。增强将检索到的相关文本块作为上下文与原始问题一起构造提示词提交给 LLM。生成LLM 基于增强后的上下文即检索到的知识生成更准确、更可靠的答案。在 AI Agent 中RAG 可以作为一个强大的“工具”或“记忆”模块让 Agent 能够回答超出其训练数据范围的专业问题。1.4 LangChain 与 LangGraph构建 Agent 的框架选择LangChain 是一个用于开发由 LLM 驱动的应用程序的框架。它通过提供标准化的接口、组件和链Chain极大地简化了与 LLM 交互、管理提示、连接工具和构建复杂工作流的流程。对于构建 AgentLangChain 提供了AgentExecutor、Tool等核心概念。而 LangGraph 是建立在 LangChain 之上的一个库专门用于构建有状态、多参与者的图工作流。它更适合构建复杂的、循环的 Agent 系统其中 Agent 需要根据中间结果动态决定下一步行动。简单来说LangChain Agent 更偏向于线性的“思考-行动”循环而 LangGraph 允许你定义更复杂的决策状态机。特性LangChain AgentLangGraph核心模型基于 ReAct 等模式的 Agent 执行器基于图Graph的工作流状态管理相对简单主要在记忆和工具输入输出间流转显式、灵活的状态State管理可自定义适用场景大多数需要工具调用的单 Agent 任务多 Agent 协作、复杂决策流程、有严格步骤循环的任务学习曲线较低入门快速较高需要理解图节点和边对于初学者建议从 LangChain 的 Agent 开始理解基本范式后再探索 LangGraph。2. 环境准备与核心依赖配置在开始构建 Agent 之前我们需要搭建一个稳定的 Python 开发环境并安装必要的库。这里我们以 OpenAI 的 GPT 系列模型作为 LLM 驱动使用 Chroma 作为向量数据库。2.1 Python 环境与包管理确保你的系统已安装 Python推荐 3.8 或以上版本。使用虚拟环境是 Python 开发的最佳实践可以避免包依赖冲突。# 创建并激活一个名为 ai_agent 的虚拟环境 python -m venv ai_agent # 在 Windows 上激活 ai_agent\Scripts\activate # 在 macOS/Linux 上激活 source ai_agent/bin/activate激活后命令行提示符前会出现(ai_agent)标识。2.2 安装核心依赖库我们将使用pip安装 LangChain、向量数据库客户端、Embedding 模型以及 OpenAI SDK。# 安装 LangChain 核心库和 OpenAI 集成 pip install langchain langchain-openai # 安装文本分割和 Embedding 相关库 pip install langchain-text-splitters langchain-community # 安装 Chroma 向量数据库及其客户端 pip install chromadb # 安装用于网页内容加载的库用于 RAG 示例 pip install beautifulsoup4 requests # 安装环境变量管理库用于安全存储 API Key pip install python-dotenv注意依赖库版本迭代很快如果遇到兼容性问题可以尝试指定稍早的稳定版本例如pip install langchain0.1.0。生产环境中务必使用requirements.txt文件锁定所有依赖版本。2.3 配置 API 密钥为了调用 OpenAI 的模型你需要一个有效的 API Key。请勿将密钥硬编码在代码中。在项目根目录创建一个名为.env的文件。在.env文件中添加你的 OpenAI API KeyOPENAI_API_KEY你的-api-key-here在代码中使用python-dotenv加载这个环境变量。# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY)3. 构建你的第一个基础 AI Agent我们将从一个最简单的 Agent 开始一个能使用计算器工具的数学助手。这个例子将清晰地展示 LangChain 中 Agent、Tool、LLM 如何协同工作。3.1 定义自定义工具Tool在 LangChain 中任何可以被 Agent 调用的函数都需要包装成Tool对象。我们需要定义工具的名称、描述和函数本身。描述至关重要因为 LLM 会根据描述来决定是否以及何时使用该工具。# tools/calculator_tool.py from langchain.tools import tool import math tool def calculator(expression: str) - str: 计算一个数学表达式的值。支持加减乘除-*/、乘方**和括号。 输入必须是一个明确的数学表达式字符串。 示例: “(3 5) * 2”, “10 / 2”, “2 ** 10” try: # 警告直接使用 eval 有安全风险仅用于演示。 # 生产环境应使用更安全的表达式求值库如 ast.literal_eval 或自定义解析器。 result eval(expression, {__builtins__: None}, {math: math}) return str(result) except Exception as e: return f计算错误{e} # 可以创建工具列表供后续使用 CUSTOM_TOOLS [calculator]3.2 初始化 LLM 和 Agent我们使用 LangChain 的create_react_agent来构建一个基于 ReAct 提示策略的 Agent。ReAct 让 Agent 以“思考 - 行动 - 观察”的循环来解决问题。# agent/basic_agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from tools.calculator_tool import CUSTOM_TOOLS from config import OPENAI_API_KEY # 1. 初始化 LLM # 使用 GPT-3.5-turbo 模型温度设为 0 以获得更确定性的输出 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyOPENAI_API_KEY) # 2. 获取 ReAct 提示模板 # LangChain Hub 是一个预置提示模板的仓库 prompt hub.pull(hwchase17/react) # 3. 使用工具和 LLM 创建 Agent agent create_react_agent(llm, CUSTOM_TOOLS, prompt) # 4. 创建 Agent 执行器它负责运行循环并处理工具调用 agent_executor AgentExecutor(agentagent, toolsCUSTOM_TOOLS, verboseTrue, handle_parsing_errorsTrue)3.3 运行并观察 Agent 的思考过程通过verboseTrue参数我们可以直观地看到 Agent 内部的“思考”过程。# run_agent.py from agent.basic_agent import agent_executor if __name__ __main__: # 提问一个需要计算的问题 question “如果我有 125 美元一本书价格是 27 美元我能买几本还剩多少钱” print(f用户问题: {question}) print(- * 50) try: response agent_executor.invoke({input: question}) print(f\n最终答案: {response[output]}) except Exception as e: print(f执行出错: {e})运行python run_agent.py你将在控制台看到类似以下的输出已简化用户问题: 如果我有 125 美元一本书价格是 27 美元我能买几本还剩多少钱 -------------------------------------------------- Entering new AgentExecutor chain... 我需要计算能买几本书以及剩余多少钱。这是一个除法并求余数的问题。 我应该使用计算器工具。 行动: calculator 行动输入: 125 / 27 观察: 4.62962962962963 思考这给了我每本书的价格对应的数量但不是整数本。我需要计算整数本和余数。 我应该计算整除和模运算。 行动: calculator 行动输入: 125 // 27 观察: 4 思考所以能买4本。现在计算剩余金额。 行动: calculator 行动输入: 125 % 27 观察: 17 思考所以用125美元购买27美元一本的书可以买4本还剩下17美元。 最终答案: 你可以购买4本书还会剩下17美元。 Finished chain. 最终答案: 你可以购买4本书还会剩下17美元。这个过程清晰地展示了 ReAct 模式Agent 先“思考”需要计算然后“行动”调用计算器工具得到“观察”结果后再进行下一轮“思考”直到得出最终答案。4. 为 Agent 集成 RAG 知识库系统现在我们赋予 Agent 访问特定领域知识的能力。我们将构建一个简单的 RAG 系统让 Agent 能够回答关于“LangChain 框架”的问题即使这些知识不在其原始训练数据中。4.1 准备知识文档与向量化首先我们需要一些关于 LangChain 的文本资料例如官方文档的片段。这里我们以一段示例文本开始。# knowledge/langchain_docs.txt LangChain 是一个用于开发由语言模型驱动的应用程序的框架。 它使应用程序能够 - 具有上下文感知能力将语言模型与上下文源提示指令、少量示例、内容等联系起来。 - 具有推理能力依赖语言模型进行推理如何根据上下文回答问题、采取什么行动等。 LangChain 的主要价值在于 1. 组件化为处理语言模型提供抽象以及每个抽象的实现集合。 2. 链式调用将组件组合成链完成特定任务。 3. 流式处理许多链式调用支持流式处理提供实时反馈。 Agent 是 LangChain 中的一个核心概念它使用语言模型来决定采取一系列行动的顺序。接下来我们编写代码来加载、分割文本生成向量并存储到 Chroma 数据库。# rag/vector_store.py from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma import os from config import OPENAI_API_KEY # 1. 加载文档 loader TextLoader(knowledge/langchain_docs.txt, encodingutf-8) documents loader.load() # 2. 分割文档 # 分割是为了避免文本过长超出模型上下文限制并提高检索精度 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块的最大字符数 chunk_overlap50 # 块之间的重叠字符保持上下文连贯 ) docs text_splitter.split_documents(documents) print(f原始文档被分割成 {len(docs)} 个块。) # 3. 初始化 Embedding 模型 embeddings OpenAIEmbeddings(modeltext-embedding-3-small, api_keyOPENAI_API_KEY) # 4. 创建并持久化向量数据库 # persist_directory 指定数据库存储路径 vectorstore Chroma.from_documents( documentsdocs, embeddingembeddings, persist_directory./chroma_db_langchain # 数据将保存到此目录 ) print(向量数据库创建并持久化完成。)运行此脚本后会在chroma_db_langchain目录下生成向量数据库文件。4.2 创建 RAG 检索工具现在我们将向量数据库的检索功能封装成一个 LangChain Tool以便 Agent 在需要时调用。# tools/rag_tool.py from langchain.tools import tool from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from config import OPENAI_API_KEY # 加载已存在的向量数据库 embeddings OpenAIEmbeddings(modeltext-embedding-3-small, api_keyOPENAI_API_KEY) vectorstore Chroma( persist_directory./chroma_db_langchain, embedding_functionembeddings ) tool def search_langchain_knowledge(query: str) - str: 在 LangChain 框架的官方文档知识库中搜索相关信息。 当用户询问关于 LangChain 的概念、组件、用法或特性时使用此工具。 输入应该是明确的问题或关键词。 # 执行相似性搜索返回最相关的 3 个文档块 docs vectorstore.similarity_search(query, k3) content \n\n.join([doc.page_content for doc in docs]) return f根据知识库相关信息如下\n{content}4.3 构建具备 RAG 能力的增强型 Agent我们将计算器工具和 RAG 检索工具组合起来创建一个更强大的 Agent。# agent/enhanced_agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from tools.calculator_tool import calculator from tools.rag_tool import search_langchain_knowledge from config import OPENAI_API_KEY # 组合工具 tools [calculator, search_langchain_knowledge] llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue)4.4 测试混合能力 Agent现在我们可以向这个 Agent 提出混合型问题。# run_enhanced_agent.py from agent.enhanced_agent import agent_executor questions [ “LangChain 框架的主要价值是什么”, “计算一下 2 的 10 次方是多少”, “在 LangChain 中Agent 和 Chain 有什么区别” ] for q in questions: print(f\n{*60}) print(f用户问题: {q}) print(f{*60}) try: response agent_executor.invoke({input: q}) print(f\nAgent 回答: {response[output]}) except Exception as e: print(f执行出错: {e})对于第一个问题Agent 会调用search_langchain_knowledge工具从我们构建的知识库中检索并生成答案。对于第二个问题它会调用计算器。对于第三个问题它同样会先尝试检索知识库来回答。这演示了 Agent 如何根据问题类型自主选择工具。5. 生产环境考量与最佳实践将实验性的 AI Agent 推向生产环境需要解决稳定性、安全性、成本和可观测性等一系列问题。5.1 安全性加固工具执行沙箱化绝对避免在工具中直接使用eval()或exec()执行不可信的字符串。对于计算器应使用安全的数学表达式解析库如ast.literal_eval用于简单字面量或numexpr。对于代码执行等高风险工具必须在隔离的 Docker 容器或沙箱环境中运行。输入验证与清理对所有用户输入和工具输入进行严格的验证、过滤和转义防止提示词注入、SQL 注入等攻击。API 密钥管理永远不要将密钥提交到代码仓库。使用.env文件、云服务商密钥管理服务如 AWS KMS, GCP Secret Manager或专业的密钥管理工具。输出内容过滤对 LLM 生成的内容进行审核防止生成有害、偏见或敏感信息。可以设置内容过滤策略或使用 Moderation API。5.2 性能与成本优化提示词优化精心设计提示词明确指令和格式减少不必要的上下文可以降低 Token 消耗并提高响应质量。使用ChatPromptTemplate进行模块化管理。缓存策略对频繁且结果不变的查询如某些知识库检索、固定计算实施缓存。LangChain 提供了LLMCache等组件。异步处理对于 I/O 密集型操作如调用多个 API、检索向量数据库使用异步Async模式可以显著提高吞吐量。模型选型根据任务复杂度选择合适的模型。简单的分类或提取任务可能不需要最强大的模型。考虑使用更小、更快的模型或对回答进行分层处理先用小模型过滤复杂问题再用大模型。5.3 可观测性与错误处理结构化日志记录完整的 Agent 执行链包括每一步的思考、工具调用、输入输出。这对于调试和审计至关重要。可以将 LangChain 的 callback 系统集成到你的日志框架中。超时与重试为 LLM 调用和工具调用设置合理的超时时间并实现指数退避的重试机制以应对网络波动或服务限流。优雅降级当核心工具如搜索引擎失效时Agent 应能提供有意义的反馈或尝试替代方案而不是直接崩溃。监控指标监控 Token 使用量、请求延迟、错误率、工具调用频率等关键指标。5.4 RAG 系统优化分块策略文本分块的大小和重叠度需要根据文档类型和问题特点进行调整。过大会丢失精度过小会丢失上下文。可以尝试不同的分割器按字符、递归、按标记等。检索优化多路检索结合关键词搜索如 BM25和向量搜索提高召回率。重排序使用更精细的模型对初步检索出的多个结果进行重排序提升 top-k 结果的相关性。元数据过滤在检索时加入来源、日期等元数据过滤条件。提示词工程设计专门的 RAG 提示词模板明确指示模型“基于以下上下文回答问题”并处理“上下文不包含答案”的情况要求模型诚实回答“不知道”。6. 常见问题排查指南在开发 AI Agent 过程中你可能会遇到以下典型问题。问题现象可能原因检查与解决步骤Agent 不调用工具直接回答问题1. 工具描述不够清晰。2. LLM 温度temperature过高导致输出随机。3. 提示词模板不适合工具调用。1. 检查工具函数的docstring确保清晰描述了工具的功能和适用场景。2. 将temperature设为 0 或一个较低的值如 0.1。3. 尝试使用不同的 Agent 类型如ZERO_SHOT_REACT_DESCRIPTION或自定义提示词。工具调用解析失败1. LLM 输出的格式不符合 Agent 解析器OutputParser的预期。2. 工具参数类型不匹配。1. 设置handle_parsing_errorsTrue并查看详细错误日志。2. 在verboseTrue模式下观察 LLM 的原始输出检查其是否包含Action:和Action Input:的规范格式。3. 确保工具函数参数类型是简单的字符串、整数等。RAG 检索结果不相关1. Embedding 模型不适合当前领域文本。2. 文本分块策略不佳。3. 检索数量 k 设置不当。1. 尝试不同的 Embedding 模型如text-embedding-3-large。2. 调整chunk_size和chunk_overlap或尝试按句子、段落分割。3. 调整similarity_search的k值并考虑使用similarity_search_with_score查看相关性分数。响应速度慢1. LLM API 调用延迟高。2. 向量数据库检索慢。3. 网络问题。1. 考虑使用更快的模型或本地模型。2. 检查向量数据库索引是否合理对于大规模数据考虑使用 HNSW 等高效索引算法。3. 实现异步调用和缓存。API 密钥错误或配额不足1. 环境变量未正确加载。2. API Key 无效或过期。3. 达到速率限制或用量上限。1. 确认.env文件路径正确且变量名无误。2. 在 OpenAI 平台检查 API Key 状态和剩余额度。3. 实现请求的速率限制和退避重试逻辑。7. 进阶方向与学习路径掌握了基础 Agent 和 RAG 的构建后你可以向以下几个方向深入探索复杂工作流与多 Agent 系统学习使用LangGraph来构建有状态的、循环的、多参与者协作的工作流。例如一个负责调研、一个负责写作、一个负责审核的多个 Agent 协同完成报告生成。更强大的工具集为你的 Agent 集成更多真实世界的工具如网络搜索通过SerpAPI或DuckDuckGoSearch获取实时信息。代码执行在安全沙箱中运行 Python 代码来分析数据或验证逻辑。数据库操作连接 SQL 或 NoSQL 数据库进行数据查询和更新。API 调用连接企业内部或第三方 RESTful API。记忆机制深化超越简单的对话缓冲区实现向量存储记忆将历史对话中的重要信息向量化存储实现长期、语义化的记忆检索。摘要记忆在对话轮次增多时自动对早期历史进行摘要以节省上下文窗口。评估与持续改进建立 Agent 的评估体系包括准确性评估通过人工标注或基准测试集如HotPotQA来评估答案质量。工具使用评估评估其调用工具的正确性和效率。基于反馈的优化收集用户反馈用于优化提示词或工具设计。构建 AI Agent 是一个迭代过程从最小可行产品开始逐步增加复杂性、稳定性和智能性。始终以解决实际用户问题为核心谨慎地引入新技术并建立完善的测试和监控机制是成功将 AI Agent 从概念推向生产的关键。 从零构建AI Agent：基于LangChain与RAG的实战开发指南
在实际 AI 项目开发中很多开发者会陷入一个误区认为只要掌握了某个大模型 API 的调用或者拼接几个开源框架就能快速构建出智能、可靠的 AI Agent。然而从零开始构建一个能理解复杂指令、具备记忆、能使用工具并自主决策的智能体远比调用单一接口复杂。这涉及到对 Transformer 架构的理解、对提示工程的精细设计、对 RAG 知识库的构建以及对 LangChain 等框架的灵活运用。本文旨在为希望系统学习 AI Agent 开发的工程师提供一个清晰、可落地的学习路径和实战指南我们将从核心概念入手逐步搭建一个具备基础能力的 AI Agent并深入探讨其内部机制与生产环境下的最佳实践。本文适合有一定 Python 基础希望深入 AI 应用层开发的开发者。通过阅读和实践你将能够理解 AI Agent 的核心组件掌握使用 LangChain 构建智能体的基本方法并了解如何集成 RAG 系统来增强 Agent 的知识与准确性。1. 理解 AI Agent 的核心架构与工作原理在深入代码之前我们必须先厘清 AI Agent 究竟是什么以及它如何工作。这有助于我们在后续开发中做出正确的技术选型和架构设计。1.1 AI Agent 的定义与核心组件AI Agent智能体并非一个单一的模型而是一个系统。它通常被设计为能够感知环境、进行推理、做出决策并执行行动以实现特定目标的软件实体。一个典型的 AI Agent 包含以下几个核心组件大脑Brain/Core LLM通常是一个大型语言模型LLM如 GPT、LLaMA 等负责理解输入、进行逻辑推理和生成文本输出。它是 Agent 的“思考”中心。记忆Memory使 Agent 能够记住之前的对话或交互历史。这可以是简单的对话缓冲区也可以是更复杂的向量存储用于长期记忆和上下文检索。工具Tools扩展 Agent 能力的外部函数或 API。例如计算器、网络搜索、数据库查询、代码执行器等。Agent 通过“思考”决定何时以及如何使用这些工具。规划Planning对于复杂任务Agent 需要将其分解为一系列子步骤或动作并规划执行顺序。ReActReasoning Acting模式是其中的典型代表。行动Action根据规划和工具使用的结果执行具体的操作并将结果返回给“大脑”进行下一轮思考。1.2 Transformer 架构现代 LLM 的基石要深入理解 Agent 的“大脑”必须对 Transformer 架构有基本认识。Transformer 摒弃了 RNN 的序列计算模式完全基于自注意力Self-Attention机制使其能够并行处理序列数据并捕获长距离依赖。其核心工作流程可以简化为输入表示将文本转换为词向量并加上位置编码。编码器堆叠输入经过多层编码器每层包含多头自注意力机制和前馈神经网络用于提取和理解输入信息的复杂特征。解码器堆叠对于生成式模型在编码器输出的基础上通过掩码自注意力和编码器-解码器注意力机制逐步生成输出序列。对于开发者而言无需从头实现 Transformer但理解其注意力机制有助于你更好地设计提示词Prompt因为提示词本质上是为模型提供特定的“注意力焦点”。例如在 RAG 中我们通过检索相关文档片段将这些信息作为上下文放入提示词就是在引导模型将“注意力”集中在这些最相关的信息上。1.3 RAG为 Agent 注入精准的外部知识LLM 存在知识截止日期和幻觉问题。检索增强生成RAG是解决该问题的关键技术。它通过以下步骤工作索引将外部知识源文档、网页、数据库进行分块并转换为向量Embeddings存入向量数据库。检索当用户提问时将问题也转换为向量并在向量数据库中搜索与之最相似的文本块。增强将检索到的相关文本块作为上下文与原始问题一起构造提示词提交给 LLM。生成LLM 基于增强后的上下文即检索到的知识生成更准确、更可靠的答案。在 AI Agent 中RAG 可以作为一个强大的“工具”或“记忆”模块让 Agent 能够回答超出其训练数据范围的专业问题。1.4 LangChain 与 LangGraph构建 Agent 的框架选择LangChain 是一个用于开发由 LLM 驱动的应用程序的框架。它通过提供标准化的接口、组件和链Chain极大地简化了与 LLM 交互、管理提示、连接工具和构建复杂工作流的流程。对于构建 AgentLangChain 提供了AgentExecutor、Tool等核心概念。而 LangGraph 是建立在 LangChain 之上的一个库专门用于构建有状态、多参与者的图工作流。它更适合构建复杂的、循环的 Agent 系统其中 Agent 需要根据中间结果动态决定下一步行动。简单来说LangChain Agent 更偏向于线性的“思考-行动”循环而 LangGraph 允许你定义更复杂的决策状态机。特性LangChain AgentLangGraph核心模型基于 ReAct 等模式的 Agent 执行器基于图Graph的工作流状态管理相对简单主要在记忆和工具输入输出间流转显式、灵活的状态State管理可自定义适用场景大多数需要工具调用的单 Agent 任务多 Agent 协作、复杂决策流程、有严格步骤循环的任务学习曲线较低入门快速较高需要理解图节点和边对于初学者建议从 LangChain 的 Agent 开始理解基本范式后再探索 LangGraph。2. 环境准备与核心依赖配置在开始构建 Agent 之前我们需要搭建一个稳定的 Python 开发环境并安装必要的库。这里我们以 OpenAI 的 GPT 系列模型作为 LLM 驱动使用 Chroma 作为向量数据库。2.1 Python 环境与包管理确保你的系统已安装 Python推荐 3.8 或以上版本。使用虚拟环境是 Python 开发的最佳实践可以避免包依赖冲突。# 创建并激活一个名为 ai_agent 的虚拟环境 python -m venv ai_agent # 在 Windows 上激活 ai_agent\Scripts\activate # 在 macOS/Linux 上激活 source ai_agent/bin/activate激活后命令行提示符前会出现(ai_agent)标识。2.2 安装核心依赖库我们将使用pip安装 LangChain、向量数据库客户端、Embedding 模型以及 OpenAI SDK。# 安装 LangChain 核心库和 OpenAI 集成 pip install langchain langchain-openai # 安装文本分割和 Embedding 相关库 pip install langchain-text-splitters langchain-community # 安装 Chroma 向量数据库及其客户端 pip install chromadb # 安装用于网页内容加载的库用于 RAG 示例 pip install beautifulsoup4 requests # 安装环境变量管理库用于安全存储 API Key pip install python-dotenv注意依赖库版本迭代很快如果遇到兼容性问题可以尝试指定稍早的稳定版本例如pip install langchain0.1.0。生产环境中务必使用requirements.txt文件锁定所有依赖版本。2.3 配置 API 密钥为了调用 OpenAI 的模型你需要一个有效的 API Key。请勿将密钥硬编码在代码中。在项目根目录创建一个名为.env的文件。在.env文件中添加你的 OpenAI API KeyOPENAI_API_KEY你的-api-key-here在代码中使用python-dotenv加载这个环境变量。# config.py import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY)3. 构建你的第一个基础 AI Agent我们将从一个最简单的 Agent 开始一个能使用计算器工具的数学助手。这个例子将清晰地展示 LangChain 中 Agent、Tool、LLM 如何协同工作。3.1 定义自定义工具Tool在 LangChain 中任何可以被 Agent 调用的函数都需要包装成Tool对象。我们需要定义工具的名称、描述和函数本身。描述至关重要因为 LLM 会根据描述来决定是否以及何时使用该工具。# tools/calculator_tool.py from langchain.tools import tool import math tool def calculator(expression: str) - str: 计算一个数学表达式的值。支持加减乘除-*/、乘方**和括号。 输入必须是一个明确的数学表达式字符串。 示例: “(3 5) * 2”, “10 / 2”, “2 ** 10” try: # 警告直接使用 eval 有安全风险仅用于演示。 # 生产环境应使用更安全的表达式求值库如 ast.literal_eval 或自定义解析器。 result eval(expression, {__builtins__: None}, {math: math}) return str(result) except Exception as e: return f计算错误{e} # 可以创建工具列表供后续使用 CUSTOM_TOOLS [calculator]3.2 初始化 LLM 和 Agent我们使用 LangChain 的create_react_agent来构建一个基于 ReAct 提示策略的 Agent。ReAct 让 Agent 以“思考 - 行动 - 观察”的循环来解决问题。# agent/basic_agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from tools.calculator_tool import CUSTOM_TOOLS from config import OPENAI_API_KEY # 1. 初始化 LLM # 使用 GPT-3.5-turbo 模型温度设为 0 以获得更确定性的输出 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyOPENAI_API_KEY) # 2. 获取 ReAct 提示模板 # LangChain Hub 是一个预置提示模板的仓库 prompt hub.pull(hwchase17/react) # 3. 使用工具和 LLM 创建 Agent agent create_react_agent(llm, CUSTOM_TOOLS, prompt) # 4. 创建 Agent 执行器它负责运行循环并处理工具调用 agent_executor AgentExecutor(agentagent, toolsCUSTOM_TOOLS, verboseTrue, handle_parsing_errorsTrue)3.3 运行并观察 Agent 的思考过程通过verboseTrue参数我们可以直观地看到 Agent 内部的“思考”过程。# run_agent.py from agent.basic_agent import agent_executor if __name__ __main__: # 提问一个需要计算的问题 question “如果我有 125 美元一本书价格是 27 美元我能买几本还剩多少钱” print(f用户问题: {question}) print(- * 50) try: response agent_executor.invoke({input: question}) print(f\n最终答案: {response[output]}) except Exception as e: print(f执行出错: {e})运行python run_agent.py你将在控制台看到类似以下的输出已简化用户问题: 如果我有 125 美元一本书价格是 27 美元我能买几本还剩多少钱 -------------------------------------------------- Entering new AgentExecutor chain... 我需要计算能买几本书以及剩余多少钱。这是一个除法并求余数的问题。 我应该使用计算器工具。 行动: calculator 行动输入: 125 / 27 观察: 4.62962962962963 思考这给了我每本书的价格对应的数量但不是整数本。我需要计算整数本和余数。 我应该计算整除和模运算。 行动: calculator 行动输入: 125 // 27 观察: 4 思考所以能买4本。现在计算剩余金额。 行动: calculator 行动输入: 125 % 27 观察: 17 思考所以用125美元购买27美元一本的书可以买4本还剩下17美元。 最终答案: 你可以购买4本书还会剩下17美元。 Finished chain. 最终答案: 你可以购买4本书还会剩下17美元。这个过程清晰地展示了 ReAct 模式Agent 先“思考”需要计算然后“行动”调用计算器工具得到“观察”结果后再进行下一轮“思考”直到得出最终答案。4. 为 Agent 集成 RAG 知识库系统现在我们赋予 Agent 访问特定领域知识的能力。我们将构建一个简单的 RAG 系统让 Agent 能够回答关于“LangChain 框架”的问题即使这些知识不在其原始训练数据中。4.1 准备知识文档与向量化首先我们需要一些关于 LangChain 的文本资料例如官方文档的片段。这里我们以一段示例文本开始。# knowledge/langchain_docs.txt LangChain 是一个用于开发由语言模型驱动的应用程序的框架。 它使应用程序能够 - 具有上下文感知能力将语言模型与上下文源提示指令、少量示例、内容等联系起来。 - 具有推理能力依赖语言模型进行推理如何根据上下文回答问题、采取什么行动等。 LangChain 的主要价值在于 1. 组件化为处理语言模型提供抽象以及每个抽象的实现集合。 2. 链式调用将组件组合成链完成特定任务。 3. 流式处理许多链式调用支持流式处理提供实时反馈。 Agent 是 LangChain 中的一个核心概念它使用语言模型来决定采取一系列行动的顺序。接下来我们编写代码来加载、分割文本生成向量并存储到 Chroma 数据库。# rag/vector_store.py from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings from langchain_community.vectorstores import Chroma import os from config import OPENAI_API_KEY # 1. 加载文档 loader TextLoader(knowledge/langchain_docs.txt, encodingutf-8) documents loader.load() # 2. 分割文档 # 分割是为了避免文本过长超出模型上下文限制并提高检索精度 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块的最大字符数 chunk_overlap50 # 块之间的重叠字符保持上下文连贯 ) docs text_splitter.split_documents(documents) print(f原始文档被分割成 {len(docs)} 个块。) # 3. 初始化 Embedding 模型 embeddings OpenAIEmbeddings(modeltext-embedding-3-small, api_keyOPENAI_API_KEY) # 4. 创建并持久化向量数据库 # persist_directory 指定数据库存储路径 vectorstore Chroma.from_documents( documentsdocs, embeddingembeddings, persist_directory./chroma_db_langchain # 数据将保存到此目录 ) print(向量数据库创建并持久化完成。)运行此脚本后会在chroma_db_langchain目录下生成向量数据库文件。4.2 创建 RAG 检索工具现在我们将向量数据库的检索功能封装成一个 LangChain Tool以便 Agent 在需要时调用。# tools/rag_tool.py from langchain.tools import tool from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from config import OPENAI_API_KEY # 加载已存在的向量数据库 embeddings OpenAIEmbeddings(modeltext-embedding-3-small, api_keyOPENAI_API_KEY) vectorstore Chroma( persist_directory./chroma_db_langchain, embedding_functionembeddings ) tool def search_langchain_knowledge(query: str) - str: 在 LangChain 框架的官方文档知识库中搜索相关信息。 当用户询问关于 LangChain 的概念、组件、用法或特性时使用此工具。 输入应该是明确的问题或关键词。 # 执行相似性搜索返回最相关的 3 个文档块 docs vectorstore.similarity_search(query, k3) content \n\n.join([doc.page_content for doc in docs]) return f根据知识库相关信息如下\n{content}4.3 构建具备 RAG 能力的增强型 Agent我们将计算器工具和 RAG 检索工具组合起来创建一个更强大的 Agent。# agent/enhanced_agent.py from langchain import hub from langchain.agents import create_react_agent, AgentExecutor from langchain_openai import ChatOpenAI from tools.calculator_tool import calculator from tools.rag_tool import search_langchain_knowledge from config import OPENAI_API_KEY # 组合工具 tools [calculator, search_langchain_knowledge] llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue)4.4 测试混合能力 Agent现在我们可以向这个 Agent 提出混合型问题。# run_enhanced_agent.py from agent.enhanced_agent import agent_executor questions [ “LangChain 框架的主要价值是什么”, “计算一下 2 的 10 次方是多少”, “在 LangChain 中Agent 和 Chain 有什么区别” ] for q in questions: print(f\n{*60}) print(f用户问题: {q}) print(f{*60}) try: response agent_executor.invoke({input: q}) print(f\nAgent 回答: {response[output]}) except Exception as e: print(f执行出错: {e})对于第一个问题Agent 会调用search_langchain_knowledge工具从我们构建的知识库中检索并生成答案。对于第二个问题它会调用计算器。对于第三个问题它同样会先尝试检索知识库来回答。这演示了 Agent 如何根据问题类型自主选择工具。5. 生产环境考量与最佳实践将实验性的 AI Agent 推向生产环境需要解决稳定性、安全性、成本和可观测性等一系列问题。5.1 安全性加固工具执行沙箱化绝对避免在工具中直接使用eval()或exec()执行不可信的字符串。对于计算器应使用安全的数学表达式解析库如ast.literal_eval用于简单字面量或numexpr。对于代码执行等高风险工具必须在隔离的 Docker 容器或沙箱环境中运行。输入验证与清理对所有用户输入和工具输入进行严格的验证、过滤和转义防止提示词注入、SQL 注入等攻击。API 密钥管理永远不要将密钥提交到代码仓库。使用.env文件、云服务商密钥管理服务如 AWS KMS, GCP Secret Manager或专业的密钥管理工具。输出内容过滤对 LLM 生成的内容进行审核防止生成有害、偏见或敏感信息。可以设置内容过滤策略或使用 Moderation API。5.2 性能与成本优化提示词优化精心设计提示词明确指令和格式减少不必要的上下文可以降低 Token 消耗并提高响应质量。使用ChatPromptTemplate进行模块化管理。缓存策略对频繁且结果不变的查询如某些知识库检索、固定计算实施缓存。LangChain 提供了LLMCache等组件。异步处理对于 I/O 密集型操作如调用多个 API、检索向量数据库使用异步Async模式可以显著提高吞吐量。模型选型根据任务复杂度选择合适的模型。简单的分类或提取任务可能不需要最强大的模型。考虑使用更小、更快的模型或对回答进行分层处理先用小模型过滤复杂问题再用大模型。5.3 可观测性与错误处理结构化日志记录完整的 Agent 执行链包括每一步的思考、工具调用、输入输出。这对于调试和审计至关重要。可以将 LangChain 的 callback 系统集成到你的日志框架中。超时与重试为 LLM 调用和工具调用设置合理的超时时间并实现指数退避的重试机制以应对网络波动或服务限流。优雅降级当核心工具如搜索引擎失效时Agent 应能提供有意义的反馈或尝试替代方案而不是直接崩溃。监控指标监控 Token 使用量、请求延迟、错误率、工具调用频率等关键指标。5.4 RAG 系统优化分块策略文本分块的大小和重叠度需要根据文档类型和问题特点进行调整。过大会丢失精度过小会丢失上下文。可以尝试不同的分割器按字符、递归、按标记等。检索优化多路检索结合关键词搜索如 BM25和向量搜索提高召回率。重排序使用更精细的模型对初步检索出的多个结果进行重排序提升 top-k 结果的相关性。元数据过滤在检索时加入来源、日期等元数据过滤条件。提示词工程设计专门的 RAG 提示词模板明确指示模型“基于以下上下文回答问题”并处理“上下文不包含答案”的情况要求模型诚实回答“不知道”。6. 常见问题排查指南在开发 AI Agent 过程中你可能会遇到以下典型问题。问题现象可能原因检查与解决步骤Agent 不调用工具直接回答问题1. 工具描述不够清晰。2. LLM 温度temperature过高导致输出随机。3. 提示词模板不适合工具调用。1. 检查工具函数的docstring确保清晰描述了工具的功能和适用场景。2. 将temperature设为 0 或一个较低的值如 0.1。3. 尝试使用不同的 Agent 类型如ZERO_SHOT_REACT_DESCRIPTION或自定义提示词。工具调用解析失败1. LLM 输出的格式不符合 Agent 解析器OutputParser的预期。2. 工具参数类型不匹配。1. 设置handle_parsing_errorsTrue并查看详细错误日志。2. 在verboseTrue模式下观察 LLM 的原始输出检查其是否包含Action:和Action Input:的规范格式。3. 确保工具函数参数类型是简单的字符串、整数等。RAG 检索结果不相关1. Embedding 模型不适合当前领域文本。2. 文本分块策略不佳。3. 检索数量 k 设置不当。1. 尝试不同的 Embedding 模型如text-embedding-3-large。2. 调整chunk_size和chunk_overlap或尝试按句子、段落分割。3. 调整similarity_search的k值并考虑使用similarity_search_with_score查看相关性分数。响应速度慢1. LLM API 调用延迟高。2. 向量数据库检索慢。3. 网络问题。1. 考虑使用更快的模型或本地模型。2. 检查向量数据库索引是否合理对于大规模数据考虑使用 HNSW 等高效索引算法。3. 实现异步调用和缓存。API 密钥错误或配额不足1. 环境变量未正确加载。2. API Key 无效或过期。3. 达到速率限制或用量上限。1. 确认.env文件路径正确且变量名无误。2. 在 OpenAI 平台检查 API Key 状态和剩余额度。3. 实现请求的速率限制和退避重试逻辑。7. 进阶方向与学习路径掌握了基础 Agent 和 RAG 的构建后你可以向以下几个方向深入探索复杂工作流与多 Agent 系统学习使用LangGraph来构建有状态的、循环的、多参与者协作的工作流。例如一个负责调研、一个负责写作、一个负责审核的多个 Agent 协同完成报告生成。更强大的工具集为你的 Agent 集成更多真实世界的工具如网络搜索通过SerpAPI或DuckDuckGoSearch获取实时信息。代码执行在安全沙箱中运行 Python 代码来分析数据或验证逻辑。数据库操作连接 SQL 或 NoSQL 数据库进行数据查询和更新。API 调用连接企业内部或第三方 RESTful API。记忆机制深化超越简单的对话缓冲区实现向量存储记忆将历史对话中的重要信息向量化存储实现长期、语义化的记忆检索。摘要记忆在对话轮次增多时自动对早期历史进行摘要以节省上下文窗口。评估与持续改进建立 Agent 的评估体系包括准确性评估通过人工标注或基准测试集如HotPotQA来评估答案质量。工具使用评估评估其调用工具的正确性和效率。基于反馈的优化收集用户反馈用于优化提示词或工具设计。构建 AI Agent 是一个迭代过程从最小可行产品开始逐步增加复杂性、稳定性和智能性。始终以解决实际用户问题为核心谨慎地引入新技术并建立完善的测试和监控机制是成功将 AI Agent 从概念推向生产的关键。