最近在尝试将大模型能力集成到实际业务中时发现一个普遍痛点虽然大模型本身很强大但如何让它像“智能员工”一样自主理解任务、使用工具、并完成复杂工作流是项目落地的关键瓶颈。网上关于Agent的资料要么过于学术化要么就是零散的代码片段缺乏一套从零到一、手把手带你构建可运行智能体的完整教程。本文正是为了解决这个问题。我将结合最新的开源框架和实战经验为你拆解AI Agent的核心概念、主流框架、以及从环境搭建到项目部署的全流程。无论你是刚接触大模型的新手还是想将Agent能力融入现有系统的开发者都能从本文中找到可复现的代码、清晰的配置和避坑指南。学完本文你将能独立搭建一个具备规划、工具调用和记忆能力的智能体应用。1. AI Agent从概念到价值在深入代码之前我们必须先厘清一个核心问题AI Agent究竟是什么以及它为何能成为大模型应用的下一个爆发点简单来说AI Agent智能体是一个能够感知环境、自主决策并执行行动以实现特定目标的软件实体。它不同于传统的“一问一答”式聊天机器人。你可以把它想象成一个拥有“大脑”大模型、“双手”工具调用和“记忆”历史上下文的虚拟助手。这个“大脑”负责理解你的意图、制定计划“双手”可以操作各种软件工具如搜索、计算、写文件“记忆”则让它能记住对话历史和任务上下文进行连贯的多轮交互。为什么开发者需要关注Agent解决复杂任务大模型单次交互的上下文长度和推理能力有限。Agent通过“思考-行动-观察”的循环可以将一个复杂问题如“分析本季度销售数据并生成报告”拆解为多个可执行的子步骤查询数据库、数据清洗、生成图表、撰写总结。连接现实世界大模型本身是“虚拟”的它无法直接操作你的数据库、发送邮件或调用API。Agent通过工具调用Tool Calling能力成为了大模型与现实世界应用程序之间的“桥梁”。实现自动化与个性化结合长期记忆如向量数据库Agent可以学习用户偏好提供持续、个性化的服务成为真正的个人工作助理或智能客服。核心组件拆解一个典型的AI Agent系统通常包含以下几个核心模块规划模块Planner将用户目标分解为任务序列或决策路径。记忆模块Memory包括短期记忆对话历史和长期记忆向量知识库。工具模块ToolsAgent可以调用的函数集合如搜索引擎、计算器、代码执行器、API客户端等。行动模块Action根据规划和工具调用结果执行具体操作。反思模块Reflection对执行结果进行评估必要时调整计划。理解了这些我们就知道搭建一个Agent本质上是为一个大模型配备一套使其“能动起来”的机制。2. 环境准备与核心工具选型工欲善其事必先利其器。在开始编码前我们需要搭建一个稳定且高效的开发环境。本文将使用目前最主流、社区最活跃的Python技术栈。2.1 基础环境配置首先确保你的系统已安装以下基础软件Python: Agent开发强烈推荐使用Python 3.10或3.11版本它们在兼容性和性能上最为平衡。避免使用Python 3.12等过新版本可能遇到一些库的兼容性问题。# 检查Python版本 python --version # 或 python3 --version包管理工具: 使用pip进行包管理。建议先升级到最新版并考虑使用虚拟环境如venv或conda来隔离项目依赖避免全局污染。# 升级pip pip install --upgrade pip # 创建虚拟环境以venv为例 python -m venv agent_env # 激活虚拟环境 # Windows: .\agent_env\Scripts\activate # Linux/Mac: source agent_env/bin/activate2.2 大模型接入选择Agent的“大脑”需要一个大模型。你有多种选择云端API推荐新手/快速原型直接调用OpenAI GPT、百度文心、智谱GLM等提供的API。优点是稳定、省心无需担心算力。关键点你需要准备相应的API Key并注意费用和网络可达性。本地部署模型追求数据隐私/定制化使用Ollama、vLLM、Transformers等框架在本地或私有服务器上部署开源模型如Llama 3、Qwen、ChatGLM等。关键点需要一定的GPU资源并熟悉模型加载和推理优化。为了教程的通用性我们将以OpenAI API和Ollama本地模型两种方式分别演示你可以根据自身条件选择。2.3 Agent框架选型这是本教程的核心。目前社区有多个优秀的Agent框架它们封装了规划、工具调用、记忆等复杂逻辑让我们能更专注于业务。LangChain / LangGraph: 生态最庞大、功能最全面的框架模块化设计学习曲线稍陡但极其灵活强大。AutoGen: 由微软推出专注于多智能体协作对话适合构建复杂的多角色对话系统。CrewAI: 在LangChain基础上构建更侧重于角色扮演和团队协作概念清晰易于上手。Semantic Kernel (SK): 微软出品与.NET生态结合紧密也支持Python强调“插件”和“规划器”的概念。本教程选择 LangChain因为其文档最全、社区案例最多学会了它再迁移到其他框架也更容易。同时我们会简要介绍 CrewAI 的快速上手方式。安装核心依赖# 激活虚拟环境后安装LangChain及常用组件 pip install langchain langchain-community langchain-openai langchain-chroma # 如果需要网页搜索等工具可以安装 pip install duckduckgo-search # 用于本地知识库向量数据库 pip install chromadb # 用于与Ollama交互 pip install langchain-ollama3. 从零构建你的第一个智能体天气预报查询助手让我们从一个具体的、可运行的例子开始。我们将构建一个能理解用户关于天气的模糊提问如“北京明天暖和吗”并调用工具查询具体天气信息最后组织成友好回复的Agent。3.1 项目结构初始化创建一个新的项目目录结构如下weather_agent/ ├── main.py # 主程序入口 ├── tools/ # 自定义工具目录 │ └── weather_tool.py ├── .env # 存储API密钥等敏感信息记得加入.gitignore └── requirements.txt # 依赖列表在requirements.txt中写入langchain langchain-openai langchain-community python-dotenv requests运行pip install -r requirements.txt安装依赖。3.2 创建自定义工具Tools工具是Agent的手臂。我们首先创建一个模拟的天气查询工具。在实际项目中你可以替换为真实的天气API如和风天气、OpenWeatherMap。文件tools/weather_tool.pyfrom langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type import requests # 定义工具的输入参数模型 class WeatherQueryInput(BaseModel): location: str Field(description城市名称例如北京、上海) date: Optional[str] Field(default今天, description查询日期例如今天、明天、2024-10-27) class WeatherQueryTool(BaseTool): name get_weather description 根据城市和日期查询天气情况。如果日期是‘今天’或‘明天’工具会进行转换。 args_schema: Type[BaseModel] WeatherQueryInput def _run(self, location: str, date: str 今天) - str: 执行工具调用的核心逻辑。 # 这里是模拟数据真实情况应调用天气API # 例如response requests.get(fhttps://api.weatherapi.com/v1/forecast.json?keyYOUR_KEYq{location}days2) print(f[工具调用] 正在查询 {location} 在 {date} 的天气...) # 模拟API返回 mock_data { 北京: {今天: 晴15~25℃微风, 明天: 多云18~27℃东南风3级}, 上海: {今天: 小雨20~28℃东风4级, 明天: 阴22~30℃微风}, } city_weather mock_data.get(location) if not city_weather: return f抱歉未找到 {location} 的天气信息。 weather_info city_weather.get(date, city_weather.get(今天, 信息暂不可用)) return f{location}在{date}的天气情况是{weather_info} async def _arun(self, location: str, date: str 今天) - str: 异步版本可选。 raise NotImplementedError(此工具不支持异步调用)关键点解释BaseTool: LangChain中所有工具的基类。args_schema: 使用Pydantic模型严格定义工具的输入参数和描述这能帮助大模型更准确地理解如何调用该工具。name和description: 至关重要大模型根据这些描述来决定在什么情况下调用哪个工具。描述要清晰、具体。_run: 工具的实际执行函数。3.3 配置大模型与构建Agent文件main.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain_core.prompts import PromptTemplate from tools.weather_tool import WeatherQueryTool # 1. 加载环境变量从.env文件读取API Key load_dotenv() openai_api_key os.getenv(OPENAI_API_KEY) # 如果没有设置可以临时写在这里仅用于测试生产环境务必用.env if not openai_api_key: # 提示请先在项目根目录创建.env文件并写入 OPENAI_API_KEYyour_key_here openai_api_key your-openai-api-key-here # 请替换 # 2. 初始化大语言模型 llm ChatOpenAI( modelgpt-3.5-turbo, # 或 gpt-4 temperature0.1, # 较低的温度使输出更稳定、更倾向于调用工具 openai_api_keyopenai_api_key ) # 3. 准备工具列表 tools [WeatherQueryTool()] # 4. 定义Agent的提示词模板 # ReAct框架的提示词会引导模型进行“思考(Thought)-行动(Action)-观察(Observation)”的循环 prompt_template 你是一个乐于助人的天气查询助手。你的目标是回答用户关于天气的任何问题。 你可以使用以下工具 {tools} 请严格按照以下格式回答 问题用户提出的原始问题 思考分析用户问题决定是否需要使用工具以及使用哪个工具 行动需要调用的工具名称以及一个格式正确的输入JSON对象。格式json {{action: “{tool_name}”, action_input: {{location: “城市名”, date: “日期”}}}}观察工具返回的结果 ... (这个思考-行动-观察的循环可以重复多次) 思考我现在有最终答案了吗 最终答案对用户问题的清晰、完整、友好的总结回答。现在开始问题{input} 思考 prompt PromptTemplate.from_template(prompt_template)5. 创建Agentagent create_react_agent(llmllm, toolstools, promptprompt)6. 创建Agent执行器agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设置为True可以看到Agent的详细思考过程调试非常有用 handle_parsing_errorsTrue, # 处理解析错误 max_iterations5, # 限制最大循环次数防止死循环 early_stopping_methodgenerate, # 提前停止策略 )7. 运行Agentifname main: # 示例查询 queries [ “北京今天天气怎么样”, “帮我看看上海明天是否需要带伞” ] for query in queries: print(f\n{*50}) print(f用户问题: {query}) print(f{*50}) try: result agent_executor.invoke({input: query}) print(f\n助手回复: {result[output]}) except Exception as e: print(f执行出错: {e})### 3.4 运行与结果分析 在项目根目录下创建 .env 文件并填入你的OpenAI API KeyOPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx然后运行程序 bash python main.py你将看到类似以下的输出verbose模式 用户问题: 北京今天天气怎么样 进入新的Agent执行链... 思考用户想了解北京今天的天气。我有一个工具可以查询天气。我应该使用这个工具。 行动 json {action: get_weather, action_input: {location: 北京, date: 今天}}观察[工具调用] 正在查询 北京 在 今天 的天气... 北京在今天天气情况是晴15~25℃微风 思考我已经获得了所需的天气信息可以给出最终答案。 最终答案北京今天的天气是晴天气温在15到25摄氏度之间有微风。助手回复: 北京今天的天气是晴天气温在15到25摄氏度之间有微风。**恭喜** 你已经成功创建了一个具备基础推理和工具调用能力的AI Agent。它能够理解自然语言问题规划需要调用“天气查询工具”并以正确的格式调用它最后将结果组织成通顺的回复。 ## 4. 进阶实战构建具备记忆与知识库的智能客服 单一工具和单轮对话的Agent能力有限。接下来我们构建一个更复杂的Agent它具备**对话记忆**和**自定义知识库检索**能力模拟一个智能客服场景。 ### 4.1 设计目标与架构 目标创建一个客服Agent它能 1. **记住对话历史**在多轮对话中引用之前提到的信息。 2. **检索内部知识库**从公司产品文档例如一个PDF手册中查找信息来回答问题。 3. **综合回答**结合对话历史和检索到的知识生成回答。 架构流程用户提问 - Agent思考 - [可选检索知识库] - [可选调用其他工具] - 生成回答 - 更新记忆### 4.2 实现对话记忆Memory LangChain提供了多种记忆后端。这里使用最简单的 ConversationBufferMemory。 安装额外依赖 bash pip install tiktoken # 用于计算Token管理记忆长度更新main.py或新建customer_service_agent.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain.memory import ConversationBufferMemory from langchain.chains import ConversationalRetrievalChain from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma load_dotenv() # 1. 初始化LLM和Embeddings llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) embeddings OpenAIEmbeddings() # 用于将文本转换为向量 # 2. 创建知识库以PDF为例 def create_knowledge_base(pdf_path: str): 加载PDF文档并创建向量数据库。 print(正在加载知识库文档...) loader PyPDFLoader(pdf_path) documents loader.load() # 将长文档切分成小块便于检索 text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个块的大小 chunk_overlap200, # 块之间的重叠避免语义断裂 length_functionlen, ) splits text_splitter.split_documents(documents) print(f文档被切分为 {len(splits)} 个片段。) # 创建向量存储这里使用Chroma轻量级且可持久化 vectorstore Chroma.from_documents( documentssplits, embeddingembeddings, persist_directory./chroma_db # 指定持久化目录 ) vectorstore.persist() # 保存到磁盘下次可直接加载 print(知识库创建完成并已保存。) return vectorstore # 假设我们有一个“产品手册.pdf” # 首次运行需要创建知识库 # knowledge_base create_knowledge_base(“产品手册.pdf”) # 后续运行可以直接加载 knowledge_base Chroma( persist_directory./chroma_db, embedding_functionembeddings ) # 3. 创建记忆 memory ConversationBufferMemory( memory_keychat_history, return_messagesTrue, # 返回消息对象而非字符串 output_keyanswer # 指定输出对应的key ) # 4. 创建对话检索链这是LangChain的高级Chain封装了记忆和检索 qa_chain ConversationalRetrievalChain.from_llm( llmllm, retrieverknowledge_base.as_retriever( search_kwargs{k: 3} # 每次检索返回最相关的3个片段 ), memorymemory, verboseTrue, # 查看检索和生成过程 return_source_documentsTrue, # 返回参考来源便于验证 ) # 5. 运行对话 if __name__ __main__: print(智能客服已启动。输入‘退出’或‘quit’结束对话。) while True: user_input input(\n用户: ) if user_input.lower() in [退出, quit, exit]: print(客服对话结束。) break # 调用链 result qa_chain.invoke({question: user_input}) print(f\n客服: {result[answer]}) # 如果需要可以查看检索到的来源 # for doc in result[source_documents]: # print(f 来源: {doc.metadata[source]} - 页码 {doc.metadata.get(page, N/A)})关键点解释记忆MemoryConversationBufferMemory保存了完整的对话历史。在每次调用时它会自动将历史记录和当前问题组合起来发送给LLM从而实现上下文连贯。检索器Retrieverknowledge_base.as_retriever()将向量数据库转换为检索器。当用户提问时它会从知识库中查找最相关的文本片段并将这些片段作为“参考材料”提供给LLM让LLM基于此生成答案。这解决了大模型“胡编乱造”的问题使其回答有据可依。链ChainConversationalRetrievalChain是一个高级抽象它把LLM、记忆、检索器串联起来形成了一个完整的“问答流水线”。4.3 使用本地模型Ollama替代OpenAI如果你希望完全在本地运行可以使用Ollama部署开源模型。安装并运行Ollama访问 Ollama官网 下载安装。然后在终端拉取一个模型例如Llama 3ollama pull llama3:8b ollama run llama3:8b # 测试运行修改代码切换LLM# 替换 from langchain_openai import ChatOpenAI from langchain_ollama import ChatOllama # 替换 llm ChatOpenAI(...) llm ChatOllama( modelllama3:8b, # 与ollama run使用的模型名一致 base_urlhttp://localhost:11434, # Ollama默认地址 temperature0.1 ) # 注意本地模型的Embeddings也需要替换例如使用sentence-transformers # pip install sentence-transformers # from langchain_huggingface import HuggingFaceEmbeddings # embeddings HuggingFaceEmbeddings(model_nameall-MiniLM-L6-v2)5. 常见问题与排查指南FAQ在开发Agent过程中你一定会遇到各种问题。以下是一些高频问题及其解决方案。问题现象可能原因排查步骤与解决方案Agent不调用工具直接回答问题1. 工具描述(description)不够清晰。2. LLM的temperature参数过高导致随机性太强。3. 提示词Prompt未明确要求使用工具。1. 检查并重写工具描述确保其准确描述了工具的功能和使用场景。2. 将temperature调低如0.1增加输出的确定性。3. 优化提示词在模板中加入强引导如“你必须使用可用工具来回答问题”。工具调用参数格式错误1.args_schema定义与_run方法参数不匹配。2. LLM未能正确解析用户意图为JSON。1. 确保Pydantic模型的字段名和类型与_run方法参数完全一致。2. 开启verboseTrue查看Agent的原始“行动”输出检查JSON是否合法。可以使用handle_parsing_errorsTrue让执行器尝试自动修复。本地模型Ollama响应慢或报错1. 模型未正确加载或内存不足。2. Ollama服务未启动或端口被占用。3. 模型不支持Tool Calling格式。1. 检查终端运行ollama run是否正常。确保机器有足够内存如7B模型约需14GB。2. 运行ollama serve确保服务在运行并检查base_url是否正确。3. 并非所有开源模型都原生支持工具调用。可尝试使用ReAct提示词框架如本文示例或选用明确支持工具调用的模型如Qwen2.5-Coder。知识库检索结果不相关1. 文档切分Chunk策略不合理。2. Embedding模型不匹配或效果差。3. 检索数量k值设置不当。1. 调整chunk_size和chunk_overlap。对于技术文档可以尝试按标题切分MarkdownHeaderTextSplitter。2. 尝试不同的Embedding模型如text-embedding-3-small,bge-large-zh-v1.5。3. 适当增加k值如从3调到5但注意可能引入噪声。对话记忆混乱或丢失1. 记忆对象未在对话循环中正确传递。2. 对话轮次太多超出上下文长度。1. 确保在Chain或Agent执行时每次都传入同一个memory对象。2. 使用ConversationSummaryMemory或ConversationBufferWindowMemory来限制记忆长度只保留最近几轮对话。遇到“Rate limit”或“Authentication”错误1. OpenAI API密钥错误或余额不足。2. 请求频率超限。1. 检查.env文件中的密钥是否正确并在OpenAI官网检查用量。2. 为代码添加重试逻辑和请求间隔如使用tenacity库或升级API套餐。6. 工程化最佳实践与进阶方向当你掌握了基础构建方法后将这些原型投入生产环境或进行复杂项目开发时需要关注以下工程化实践。6.1 提示词工程优化提示词是Agent的“指挥棒”。一个好的提示词能极大提升表现。角色设定明确告诉Agent它扮演的角色“你是一个专业的天气分析师”。步骤约束强制其按照“思考-行动-观察”的格式输出便于解析。输出格式明确指定最终答案的格式如“请用中文以要点列表形式回答”。负面约束告诉它不要做什么“不要假设用户未提供的信息”。使用少样本示例Few-Shot在提示词中提供1-2个完整的输入输出示例能显著提升模型在复杂任务上的表现。6.2 智能体架构模式对于复杂任务单个Agent可能力不从心可以考虑以下模式主管模式Manager-Agent一个主管Agent接收用户任务将其拆解并分配给多个具备特定技能的“子Agent”如研究Agent、写作Agent、审核Agent最后汇总结果。工作流模式Sequential使用LangGraph或CrewAI定义明确的任务执行流程图让Agent按固定流程工作适合标准化业务流程。辩论模式Debate多个Agent从不同角度分析同一问题通过“辩论”得出更全面、可靠的结论。6.3 可观测性与评估Agent系统是动态的必须监控。日志记录详细记录每个Agent的思考过程、工具调用输入/输出、最终结果。这不仅是调试的需要也是后续优化和评估的数据基础。链路追踪Tracing使用LangSmithLangChain官方平台或OpenTelemetry等工具可视化整个Agent调用的链路方便定位性能瓶颈和错误节点。评估体系建立评估标准可以是基于规则的评估检查输出是否包含关键词、是否符合格式。基于LLM的评估用另一个LLM如GPT-4作为裁判评估答案的相关性、正确性、友好度。人工评估对关键输出进行抽样人工检查。6.4 安全与合规这是企业级应用的生命线。工具权限控制不是所有工具都应对所有用户开放。例如删除数据库的工具需要极高的权限。在工具调用前加入身份验证和权限校验层。输入输出过滤与审查对用户的输入和Agent的输出进行内容安全过滤防止生成有害、偏见或敏感信息。数据隐私如果使用云端API确保传输的数据不包含用户个人身份信息PII。考虑对敏感数据进行脱敏或使用本地模型。防止无限循环与资源耗尽严格设置max_iterations最大循环次数和max_execution_time最大执行时间并在代码层面做好异常捕获和资源清理。6.5 性能优化缓存对频繁且结果不变的LLM调用或工具调用如查询静态知识实施缓存可以大幅降低成本和延迟。LangChain内置了LLMCache支持。异步处理如果Agent需要调用多个独立的外部API使用异步asyncio可以并行执行显著减少总等待时间。模型选择在链的不同环节使用不同规格的模型。例如用小型/快速模型处理意图分类和路由用大型/强力模型处理需要深度推理的最终生成。从构建一个简单的天气查询助手到创建一个具备记忆和知识库的客服系统你已经走完了AI Agent开发的核心路径。这条路径的核心在于理解“规划-工具-记忆”这个铁三角并学会使用像LangChain这样的框架来组装它们。接下来的学习路线可以沿着两个方向深入纵向深入框架深入研究LangGraph来构建有状态、多分支的复杂工作流学习CrewAI来设计角色明确的多智能体团队。横向扩展能力为你的Agent集成更多强大的工具如网络搜索、代码执行、数据分析pandas、图像生成等使其成为一个真正的“全能助手”。记住所有的复杂系统都是从简单的模块开始的。最好的学习方式就是动手实践选择一个你感兴趣的具体场景比如自动整理周报、智能代码审查、个性化学习伴侣从定义一个工具、设计一个提示词开始逐步迭代最终构建出属于你自己的智能体应用。 从零构建AI智能体：基于LangChain的规划、工具调用与记忆实战
最近在尝试将大模型能力集成到实际业务中时发现一个普遍痛点虽然大模型本身很强大但如何让它像“智能员工”一样自主理解任务、使用工具、并完成复杂工作流是项目落地的关键瓶颈。网上关于Agent的资料要么过于学术化要么就是零散的代码片段缺乏一套从零到一、手把手带你构建可运行智能体的完整教程。本文正是为了解决这个问题。我将结合最新的开源框架和实战经验为你拆解AI Agent的核心概念、主流框架、以及从环境搭建到项目部署的全流程。无论你是刚接触大模型的新手还是想将Agent能力融入现有系统的开发者都能从本文中找到可复现的代码、清晰的配置和避坑指南。学完本文你将能独立搭建一个具备规划、工具调用和记忆能力的智能体应用。1. AI Agent从概念到价值在深入代码之前我们必须先厘清一个核心问题AI Agent究竟是什么以及它为何能成为大模型应用的下一个爆发点简单来说AI Agent智能体是一个能够感知环境、自主决策并执行行动以实现特定目标的软件实体。它不同于传统的“一问一答”式聊天机器人。你可以把它想象成一个拥有“大脑”大模型、“双手”工具调用和“记忆”历史上下文的虚拟助手。这个“大脑”负责理解你的意图、制定计划“双手”可以操作各种软件工具如搜索、计算、写文件“记忆”则让它能记住对话历史和任务上下文进行连贯的多轮交互。为什么开发者需要关注Agent解决复杂任务大模型单次交互的上下文长度和推理能力有限。Agent通过“思考-行动-观察”的循环可以将一个复杂问题如“分析本季度销售数据并生成报告”拆解为多个可执行的子步骤查询数据库、数据清洗、生成图表、撰写总结。连接现实世界大模型本身是“虚拟”的它无法直接操作你的数据库、发送邮件或调用API。Agent通过工具调用Tool Calling能力成为了大模型与现实世界应用程序之间的“桥梁”。实现自动化与个性化结合长期记忆如向量数据库Agent可以学习用户偏好提供持续、个性化的服务成为真正的个人工作助理或智能客服。核心组件拆解一个典型的AI Agent系统通常包含以下几个核心模块规划模块Planner将用户目标分解为任务序列或决策路径。记忆模块Memory包括短期记忆对话历史和长期记忆向量知识库。工具模块ToolsAgent可以调用的函数集合如搜索引擎、计算器、代码执行器、API客户端等。行动模块Action根据规划和工具调用结果执行具体操作。反思模块Reflection对执行结果进行评估必要时调整计划。理解了这些我们就知道搭建一个Agent本质上是为一个大模型配备一套使其“能动起来”的机制。2. 环境准备与核心工具选型工欲善其事必先利其器。在开始编码前我们需要搭建一个稳定且高效的开发环境。本文将使用目前最主流、社区最活跃的Python技术栈。2.1 基础环境配置首先确保你的系统已安装以下基础软件Python: Agent开发强烈推荐使用Python 3.10或3.11版本它们在兼容性和性能上最为平衡。避免使用Python 3.12等过新版本可能遇到一些库的兼容性问题。# 检查Python版本 python --version # 或 python3 --version包管理工具: 使用pip进行包管理。建议先升级到最新版并考虑使用虚拟环境如venv或conda来隔离项目依赖避免全局污染。# 升级pip pip install --upgrade pip # 创建虚拟环境以venv为例 python -m venv agent_env # 激活虚拟环境 # Windows: .\agent_env\Scripts\activate # Linux/Mac: source agent_env/bin/activate2.2 大模型接入选择Agent的“大脑”需要一个大模型。你有多种选择云端API推荐新手/快速原型直接调用OpenAI GPT、百度文心、智谱GLM等提供的API。优点是稳定、省心无需担心算力。关键点你需要准备相应的API Key并注意费用和网络可达性。本地部署模型追求数据隐私/定制化使用Ollama、vLLM、Transformers等框架在本地或私有服务器上部署开源模型如Llama 3、Qwen、ChatGLM等。关键点需要一定的GPU资源并熟悉模型加载和推理优化。为了教程的通用性我们将以OpenAI API和Ollama本地模型两种方式分别演示你可以根据自身条件选择。2.3 Agent框架选型这是本教程的核心。目前社区有多个优秀的Agent框架它们封装了规划、工具调用、记忆等复杂逻辑让我们能更专注于业务。LangChain / LangGraph: 生态最庞大、功能最全面的框架模块化设计学习曲线稍陡但极其灵活强大。AutoGen: 由微软推出专注于多智能体协作对话适合构建复杂的多角色对话系统。CrewAI: 在LangChain基础上构建更侧重于角色扮演和团队协作概念清晰易于上手。Semantic Kernel (SK): 微软出品与.NET生态结合紧密也支持Python强调“插件”和“规划器”的概念。本教程选择 LangChain因为其文档最全、社区案例最多学会了它再迁移到其他框架也更容易。同时我们会简要介绍 CrewAI 的快速上手方式。安装核心依赖# 激活虚拟环境后安装LangChain及常用组件 pip install langchain langchain-community langchain-openai langchain-chroma # 如果需要网页搜索等工具可以安装 pip install duckduckgo-search # 用于本地知识库向量数据库 pip install chromadb # 用于与Ollama交互 pip install langchain-ollama3. 从零构建你的第一个智能体天气预报查询助手让我们从一个具体的、可运行的例子开始。我们将构建一个能理解用户关于天气的模糊提问如“北京明天暖和吗”并调用工具查询具体天气信息最后组织成友好回复的Agent。3.1 项目结构初始化创建一个新的项目目录结构如下weather_agent/ ├── main.py # 主程序入口 ├── tools/ # 自定义工具目录 │ └── weather_tool.py ├── .env # 存储API密钥等敏感信息记得加入.gitignore └── requirements.txt # 依赖列表在requirements.txt中写入langchain langchain-openai langchain-community python-dotenv requests运行pip install -r requirements.txt安装依赖。3.2 创建自定义工具Tools工具是Agent的手臂。我们首先创建一个模拟的天气查询工具。在实际项目中你可以替换为真实的天气API如和风天气、OpenWeatherMap。文件tools/weather_tool.pyfrom langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type import requests # 定义工具的输入参数模型 class WeatherQueryInput(BaseModel): location: str Field(description城市名称例如北京、上海) date: Optional[str] Field(default今天, description查询日期例如今天、明天、2024-10-27) class WeatherQueryTool(BaseTool): name get_weather description 根据城市和日期查询天气情况。如果日期是‘今天’或‘明天’工具会进行转换。 args_schema: Type[BaseModel] WeatherQueryInput def _run(self, location: str, date: str 今天) - str: 执行工具调用的核心逻辑。 # 这里是模拟数据真实情况应调用天气API # 例如response requests.get(fhttps://api.weatherapi.com/v1/forecast.json?keyYOUR_KEYq{location}days2) print(f[工具调用] 正在查询 {location} 在 {date} 的天气...) # 模拟API返回 mock_data { 北京: {今天: 晴15~25℃微风, 明天: 多云18~27℃东南风3级}, 上海: {今天: 小雨20~28℃东风4级, 明天: 阴22~30℃微风}, } city_weather mock_data.get(location) if not city_weather: return f抱歉未找到 {location} 的天气信息。 weather_info city_weather.get(date, city_weather.get(今天, 信息暂不可用)) return f{location}在{date}的天气情况是{weather_info} async def _arun(self, location: str, date: str 今天) - str: 异步版本可选。 raise NotImplementedError(此工具不支持异步调用)关键点解释BaseTool: LangChain中所有工具的基类。args_schema: 使用Pydantic模型严格定义工具的输入参数和描述这能帮助大模型更准确地理解如何调用该工具。name和description: 至关重要大模型根据这些描述来决定在什么情况下调用哪个工具。描述要清晰、具体。_run: 工具的实际执行函数。3.3 配置大模型与构建Agent文件main.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain_core.prompts import PromptTemplate from tools.weather_tool import WeatherQueryTool # 1. 加载环境变量从.env文件读取API Key load_dotenv() openai_api_key os.getenv(OPENAI_API_KEY) # 如果没有设置可以临时写在这里仅用于测试生产环境务必用.env if not openai_api_key: # 提示请先在项目根目录创建.env文件并写入 OPENAI_API_KEYyour_key_here openai_api_key your-openai-api-key-here # 请替换 # 2. 初始化大语言模型 llm ChatOpenAI( modelgpt-3.5-turbo, # 或 gpt-4 temperature0.1, # 较低的温度使输出更稳定、更倾向于调用工具 openai_api_keyopenai_api_key ) # 3. 准备工具列表 tools [WeatherQueryTool()] # 4. 定义Agent的提示词模板 # ReAct框架的提示词会引导模型进行“思考(Thought)-行动(Action)-观察(Observation)”的循环 prompt_template 你是一个乐于助人的天气查询助手。你的目标是回答用户关于天气的任何问题。 你可以使用以下工具 {tools} 请严格按照以下格式回答 问题用户提出的原始问题 思考分析用户问题决定是否需要使用工具以及使用哪个工具 行动需要调用的工具名称以及一个格式正确的输入JSON对象。格式json {{action: “{tool_name}”, action_input: {{location: “城市名”, date: “日期”}}}}观察工具返回的结果 ... (这个思考-行动-观察的循环可以重复多次) 思考我现在有最终答案了吗 最终答案对用户问题的清晰、完整、友好的总结回答。现在开始问题{input} 思考 prompt PromptTemplate.from_template(prompt_template)5. 创建Agentagent create_react_agent(llmllm, toolstools, promptprompt)6. 创建Agent执行器agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 设置为True可以看到Agent的详细思考过程调试非常有用 handle_parsing_errorsTrue, # 处理解析错误 max_iterations5, # 限制最大循环次数防止死循环 early_stopping_methodgenerate, # 提前停止策略 )7. 运行Agentifname main: # 示例查询 queries [ “北京今天天气怎么样”, “帮我看看上海明天是否需要带伞” ] for query in queries: print(f\n{*50}) print(f用户问题: {query}) print(f{*50}) try: result agent_executor.invoke({input: query}) print(f\n助手回复: {result[output]}) except Exception as e: print(f执行出错: {e})### 3.4 运行与结果分析 在项目根目录下创建 .env 文件并填入你的OpenAI API KeyOPENAI_API_KEYsk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx然后运行程序 bash python main.py你将看到类似以下的输出verbose模式 用户问题: 北京今天天气怎么样 进入新的Agent执行链... 思考用户想了解北京今天的天气。我有一个工具可以查询天气。我应该使用这个工具。 行动 json {action: get_weather, action_input: {location: 北京, date: 今天}}观察[工具调用] 正在查询 北京 在 今天 的天气... 北京在今天天气情况是晴15~25℃微风 思考我已经获得了所需的天气信息可以给出最终答案。 最终答案北京今天的天气是晴天气温在15到25摄氏度之间有微风。助手回复: 北京今天的天气是晴天气温在15到25摄氏度之间有微风。**恭喜** 你已经成功创建了一个具备基础推理和工具调用能力的AI Agent。它能够理解自然语言问题规划需要调用“天气查询工具”并以正确的格式调用它最后将结果组织成通顺的回复。 ## 4. 进阶实战构建具备记忆与知识库的智能客服 单一工具和单轮对话的Agent能力有限。接下来我们构建一个更复杂的Agent它具备**对话记忆**和**自定义知识库检索**能力模拟一个智能客服场景。 ### 4.1 设计目标与架构 目标创建一个客服Agent它能 1. **记住对话历史**在多轮对话中引用之前提到的信息。 2. **检索内部知识库**从公司产品文档例如一个PDF手册中查找信息来回答问题。 3. **综合回答**结合对话历史和检索到的知识生成回答。 架构流程用户提问 - Agent思考 - [可选检索知识库] - [可选调用其他工具] - 生成回答 - 更新记忆### 4.2 实现对话记忆Memory LangChain提供了多种记忆后端。这里使用最简单的 ConversationBufferMemory。 安装额外依赖 bash pip install tiktoken # 用于计算Token管理记忆长度更新main.py或新建customer_service_agent.pyimport os from dotenv import load_dotenv from langchain_openai import ChatOpenAI, OpenAIEmbeddings from langchain.memory import ConversationBufferMemory from langchain.chains import ConversationalRetrievalChain from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_community.vectorstores import Chroma load_dotenv() # 1. 初始化LLM和Embeddings llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) embeddings OpenAIEmbeddings() # 用于将文本转换为向量 # 2. 创建知识库以PDF为例 def create_knowledge_base(pdf_path: str): 加载PDF文档并创建向量数据库。 print(正在加载知识库文档...) loader PyPDFLoader(pdf_path) documents loader.load() # 将长文档切分成小块便于检索 text_splitter RecursiveCharacterTextSplitter( chunk_size1000, # 每个块的大小 chunk_overlap200, # 块之间的重叠避免语义断裂 length_functionlen, ) splits text_splitter.split_documents(documents) print(f文档被切分为 {len(splits)} 个片段。) # 创建向量存储这里使用Chroma轻量级且可持久化 vectorstore Chroma.from_documents( documentssplits, embeddingembeddings, persist_directory./chroma_db # 指定持久化目录 ) vectorstore.persist() # 保存到磁盘下次可直接加载 print(知识库创建完成并已保存。) return vectorstore # 假设我们有一个“产品手册.pdf” # 首次运行需要创建知识库 # knowledge_base create_knowledge_base(“产品手册.pdf”) # 后续运行可以直接加载 knowledge_base Chroma( persist_directory./chroma_db, embedding_functionembeddings ) # 3. 创建记忆 memory ConversationBufferMemory( memory_keychat_history, return_messagesTrue, # 返回消息对象而非字符串 output_keyanswer # 指定输出对应的key ) # 4. 创建对话检索链这是LangChain的高级Chain封装了记忆和检索 qa_chain ConversationalRetrievalChain.from_llm( llmllm, retrieverknowledge_base.as_retriever( search_kwargs{k: 3} # 每次检索返回最相关的3个片段 ), memorymemory, verboseTrue, # 查看检索和生成过程 return_source_documentsTrue, # 返回参考来源便于验证 ) # 5. 运行对话 if __name__ __main__: print(智能客服已启动。输入‘退出’或‘quit’结束对话。) while True: user_input input(\n用户: ) if user_input.lower() in [退出, quit, exit]: print(客服对话结束。) break # 调用链 result qa_chain.invoke({question: user_input}) print(f\n客服: {result[answer]}) # 如果需要可以查看检索到的来源 # for doc in result[source_documents]: # print(f 来源: {doc.metadata[source]} - 页码 {doc.metadata.get(page, N/A)})关键点解释记忆MemoryConversationBufferMemory保存了完整的对话历史。在每次调用时它会自动将历史记录和当前问题组合起来发送给LLM从而实现上下文连贯。检索器Retrieverknowledge_base.as_retriever()将向量数据库转换为检索器。当用户提问时它会从知识库中查找最相关的文本片段并将这些片段作为“参考材料”提供给LLM让LLM基于此生成答案。这解决了大模型“胡编乱造”的问题使其回答有据可依。链ChainConversationalRetrievalChain是一个高级抽象它把LLM、记忆、检索器串联起来形成了一个完整的“问答流水线”。4.3 使用本地模型Ollama替代OpenAI如果你希望完全在本地运行可以使用Ollama部署开源模型。安装并运行Ollama访问 Ollama官网 下载安装。然后在终端拉取一个模型例如Llama 3ollama pull llama3:8b ollama run llama3:8b # 测试运行修改代码切换LLM# 替换 from langchain_openai import ChatOpenAI from langchain_ollama import ChatOllama # 替换 llm ChatOpenAI(...) llm ChatOllama( modelllama3:8b, # 与ollama run使用的模型名一致 base_urlhttp://localhost:11434, # Ollama默认地址 temperature0.1 ) # 注意本地模型的Embeddings也需要替换例如使用sentence-transformers # pip install sentence-transformers # from langchain_huggingface import HuggingFaceEmbeddings # embeddings HuggingFaceEmbeddings(model_nameall-MiniLM-L6-v2)5. 常见问题与排查指南FAQ在开发Agent过程中你一定会遇到各种问题。以下是一些高频问题及其解决方案。问题现象可能原因排查步骤与解决方案Agent不调用工具直接回答问题1. 工具描述(description)不够清晰。2. LLM的temperature参数过高导致随机性太强。3. 提示词Prompt未明确要求使用工具。1. 检查并重写工具描述确保其准确描述了工具的功能和使用场景。2. 将temperature调低如0.1增加输出的确定性。3. 优化提示词在模板中加入强引导如“你必须使用可用工具来回答问题”。工具调用参数格式错误1.args_schema定义与_run方法参数不匹配。2. LLM未能正确解析用户意图为JSON。1. 确保Pydantic模型的字段名和类型与_run方法参数完全一致。2. 开启verboseTrue查看Agent的原始“行动”输出检查JSON是否合法。可以使用handle_parsing_errorsTrue让执行器尝试自动修复。本地模型Ollama响应慢或报错1. 模型未正确加载或内存不足。2. Ollama服务未启动或端口被占用。3. 模型不支持Tool Calling格式。1. 检查终端运行ollama run是否正常。确保机器有足够内存如7B模型约需14GB。2. 运行ollama serve确保服务在运行并检查base_url是否正确。3. 并非所有开源模型都原生支持工具调用。可尝试使用ReAct提示词框架如本文示例或选用明确支持工具调用的模型如Qwen2.5-Coder。知识库检索结果不相关1. 文档切分Chunk策略不合理。2. Embedding模型不匹配或效果差。3. 检索数量k值设置不当。1. 调整chunk_size和chunk_overlap。对于技术文档可以尝试按标题切分MarkdownHeaderTextSplitter。2. 尝试不同的Embedding模型如text-embedding-3-small,bge-large-zh-v1.5。3. 适当增加k值如从3调到5但注意可能引入噪声。对话记忆混乱或丢失1. 记忆对象未在对话循环中正确传递。2. 对话轮次太多超出上下文长度。1. 确保在Chain或Agent执行时每次都传入同一个memory对象。2. 使用ConversationSummaryMemory或ConversationBufferWindowMemory来限制记忆长度只保留最近几轮对话。遇到“Rate limit”或“Authentication”错误1. OpenAI API密钥错误或余额不足。2. 请求频率超限。1. 检查.env文件中的密钥是否正确并在OpenAI官网检查用量。2. 为代码添加重试逻辑和请求间隔如使用tenacity库或升级API套餐。6. 工程化最佳实践与进阶方向当你掌握了基础构建方法后将这些原型投入生产环境或进行复杂项目开发时需要关注以下工程化实践。6.1 提示词工程优化提示词是Agent的“指挥棒”。一个好的提示词能极大提升表现。角色设定明确告诉Agent它扮演的角色“你是一个专业的天气分析师”。步骤约束强制其按照“思考-行动-观察”的格式输出便于解析。输出格式明确指定最终答案的格式如“请用中文以要点列表形式回答”。负面约束告诉它不要做什么“不要假设用户未提供的信息”。使用少样本示例Few-Shot在提示词中提供1-2个完整的输入输出示例能显著提升模型在复杂任务上的表现。6.2 智能体架构模式对于复杂任务单个Agent可能力不从心可以考虑以下模式主管模式Manager-Agent一个主管Agent接收用户任务将其拆解并分配给多个具备特定技能的“子Agent”如研究Agent、写作Agent、审核Agent最后汇总结果。工作流模式Sequential使用LangGraph或CrewAI定义明确的任务执行流程图让Agent按固定流程工作适合标准化业务流程。辩论模式Debate多个Agent从不同角度分析同一问题通过“辩论”得出更全面、可靠的结论。6.3 可观测性与评估Agent系统是动态的必须监控。日志记录详细记录每个Agent的思考过程、工具调用输入/输出、最终结果。这不仅是调试的需要也是后续优化和评估的数据基础。链路追踪Tracing使用LangSmithLangChain官方平台或OpenTelemetry等工具可视化整个Agent调用的链路方便定位性能瓶颈和错误节点。评估体系建立评估标准可以是基于规则的评估检查输出是否包含关键词、是否符合格式。基于LLM的评估用另一个LLM如GPT-4作为裁判评估答案的相关性、正确性、友好度。人工评估对关键输出进行抽样人工检查。6.4 安全与合规这是企业级应用的生命线。工具权限控制不是所有工具都应对所有用户开放。例如删除数据库的工具需要极高的权限。在工具调用前加入身份验证和权限校验层。输入输出过滤与审查对用户的输入和Agent的输出进行内容安全过滤防止生成有害、偏见或敏感信息。数据隐私如果使用云端API确保传输的数据不包含用户个人身份信息PII。考虑对敏感数据进行脱敏或使用本地模型。防止无限循环与资源耗尽严格设置max_iterations最大循环次数和max_execution_time最大执行时间并在代码层面做好异常捕获和资源清理。6.5 性能优化缓存对频繁且结果不变的LLM调用或工具调用如查询静态知识实施缓存可以大幅降低成本和延迟。LangChain内置了LLMCache支持。异步处理如果Agent需要调用多个独立的外部API使用异步asyncio可以并行执行显著减少总等待时间。模型选择在链的不同环节使用不同规格的模型。例如用小型/快速模型处理意图分类和路由用大型/强力模型处理需要深度推理的最终生成。从构建一个简单的天气查询助手到创建一个具备记忆和知识库的客服系统你已经走完了AI Agent开发的核心路径。这条路径的核心在于理解“规划-工具-记忆”这个铁三角并学会使用像LangChain这样的框架来组装它们。接下来的学习路线可以沿着两个方向深入纵向深入框架深入研究LangGraph来构建有状态、多分支的复杂工作流学习CrewAI来设计角色明确的多智能体团队。横向扩展能力为你的Agent集成更多强大的工具如网络搜索、代码执行、数据分析pandas、图像生成等使其成为一个真正的“全能助手”。记住所有的复杂系统都是从简单的模块开始的。最好的学习方式就是动手实践选择一个你感兴趣的具体场景比如自动整理周报、智能代码审查、个性化学习伴侣从定义一个工具、设计一个提示词开始逐步迭代最终构建出属于你自己的智能体应用。