30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在实际的大模型应用开发中Agent智能体已经从一个前沿概念演变为构建复杂AI应用的核心范式。它不再仅仅是调用API生成文本而是能够理解目标、规划步骤、使用工具并执行任务最终达成目标的自主或半自主程序。对于希望从基础开发转向构建具备实际业务价值AI应用的开发者而言掌握Agent开发是必经之路。本文将围绕Agent的核心概念、主流框架、开发实践和部署要点提供一个从零到一的系统性学习路径。无论你是希望理解Agent如何工作还是计划亲手搭建一个能处理复杂流程的智能体本文都将通过具体的环境配置、代码示例和问题排查帮助你构建清晰的知识体系和实操能力。1. 理解Agent从概念到技术栈在深入代码之前必须厘清Agent是什么以及它如何与现有的大模型技术栈结合。这有助于避免后续开发中概念混淆和架构设计错误。1.1 Agent的核心定义与工作模式通俗地讲一个AI Agent就是一个被赋予了“大脑”大语言模型和“手脚”工具/函数的程序。它的核心工作是接收一个高层次的目标例如“帮我分析上个月的销售数据并写一份报告”然后自主地拆解任务、选择工具、执行步骤最终产出结果。这与传统的单次问答式调用有本质区别。从技术定义上看一个典型的Agent系统包含以下几个关键组件规划模块Planner负责将用户目标分解为可执行的子任务序列。这可以通过大模型的链式思考Chain-of-Thought或更复杂的规划算法实现。工具调用模块Tool CallingAgent需要知道它能使用哪些工具如搜索网络、执行代码、查询数据库、调用API。大模型根据当前任务上下文决定调用哪个工具并生成符合工具要求的参数。记忆模块Memory分为短期记忆当前会话的上下文和长期记忆向量数据库存储的历史信息。记忆使Agent能进行多轮对话并参考过去经验。执行与反思模块Execution Reflection执行工具调用获取结果并根据结果评估任务完成情况。如果结果不理想或遇到错误Agent需要能“反思”并调整计划。一个最小的工作流程可以概括为用户输入 - Agent规划 - 选择工具 - 执行工具 - 观察结果 - 反思/下一步 - ... - 最终输出。1.2 Agent开发的技术栈构成开发一个Agent通常需要组合以下技术层技术层常见组件/技术作用大模型层GPT-4, Claude, 文心一言通义千问 Llama 系列 GLM 等提供核心的理解、推理和生成能力。可以是云端API或本地部署模型。框架层LangChain, LlamaIndex, Semantic Kernel, AutoGen, CrewAI 等提供构建Agent所需的高层抽象如工具封装、记忆管理、工作流编排。工具层自定义Python函数搜索引擎API数据库客户端代码解释器外部系统APIAgent可调用的具体能力。框架负责将工具描述暴露给大模型。记忆层向量数据库Chroma, Pinecone, Weaviate 传统数据库存储和检索对话历史、知识片段实现长期记忆。部署层FastAPI, Gradio, Streamlit Docker, Kubernetes将Agent封装成可服务的应用提供Web界面或API接口。对于初学者建议从LangChain或LlamaIndex开始它们社区活跃、文档丰富能快速上手。对于追求更灵活工作流和复杂多Agent协作的场景可以研究CrewAI或AutoGen。2. 环境准备与核心依赖配置在开始第一个Agent项目前一个干净、版本可控的Python环境至关重要。大模型生态依赖复杂版本冲突是新手最常见的拦路虎。2.1 创建并激活虚拟环境使用conda或venv隔离项目环境。这里以venv为例# 创建项目目录并进入 mkdir my_first_agent cd my_first_agent # 创建Python虚拟环境假设使用Python 3.10 python3.10 -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate激活后命令行提示符前应显示(venv)。2.2 安装核心框架与依赖我们将以LangChain为例因为它提供了最全面的Agent构建模块。首先安装LangChain及其常用组件。# 安装LangChain核心包 pip install langchain # 安装LangChain社区包包含大量第三方工具和集成 pip install langchain-community # 安装OpenAI官方SDK如果你使用OpenAI模型 pip install openai # 安装用于解析模型输出如工具调用的包 pip install langchain-core # 安装一个简单的向量数据库用于记忆可选但推荐 pip install chromadb # 安装环境变量管理包用于安全存储API密钥 pip install python-dotenv注意langchain是一个元包它会安装一系列核心子包。在生产环境中为了减少依赖体积和冲突可以考虑只安装你需要的特定子包如pip install langchain-core langchain-openai。2.3 配置大模型访问密钥大多数Agent需要连接一个大模型作为“大脑”。以OpenAI为例你需要一个API Key。切勿将API Key硬编码在代码中。在项目根目录创建.env文件。在.env文件中写入你的密钥OPENAI_API_KEY你的实际api-key-here在代码中通过dotenv加载# config.py 或主程序开头 from dotenv import load_dotenv import os load_dotenv() # 加载 .env 文件中的环境变量 OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY 环境变量)如果你使用国内大模型如文心一言、通义千问安装对应的LangChain集成包并配置相应的API Key和Base URL。# 例如安装百度千帆文心一言的LangChain集成 pip install langchain-community # 千帆SDK通常已包含在langchain-community中或需单独安装 # pip install qianfan3. 构建你的第一个工具调用Agent理论和技术栈准备就绪后我们通过一个具体案例来实践创建一个能查询当前天气和进行简单计算的Agent。这个Agent将具备规划、工具调用和记忆的基础能力。3.1 定义自定义工具Agent的“手脚”工具本质上是能被大模型识别和调用的函数。我们需要用tool装饰器来定义它并提供一个清晰的描述这个描述会直接影响大模型是否以及如何调用它。# tools.py from langchain.tools import tool import requests import json tool def get_weather(city: str) - str: 获取指定城市的当前天气情况。输入应为城市名称例如“北京”。 # 警告这是一个模拟函数。真实场景应调用如和风天气、OpenWeatherMap等API。 # 需要注册并获取API Key。 print(f[工具调用] 正在查询{city}的天气...) # 模拟API调用和返回 weather_data { 北京: 晴15°C西北风2级, 上海: 多云18°C东南风1级, 深圳: 阵雨22°C南风3级, } return weather_data.get(city, f未找到{city}的天气信息。) tool def calculator(expression: str) - str: 计算一个数学表达式的值。输入应为字符串形式的表达式例如“3 5 * 2”。 print(f[工具调用] 正在计算表达式{expression}) try: # 安全警告在生产环境中直接使用eval是危险的可能造成代码注入。 # 这里仅用于演示。实际应用应使用更安全的计算库如numexpr或ast.literal_eval处理有限运算。 result eval(expression) return f{expression} {result} except Exception as e: return f计算错误{e} # 将工具放入列表供Agent使用 tools [get_weather, calculator]关键点tool装饰器让LangChain能识别这个函数。函数文档字符串...至关重要大模型依靠它来理解工具的功能和输入格式。工具函数内部可以包含任何Python代码实现网络请求、数据库查询、文件操作等。3.2 初始化大模型并创建Agent我们使用OpenAI的GPT-3.5-turbo作为推理模型结合上面定义的工具来创建Agent。# agent_basic.py from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain import hub from tools import tools # 导入上一步定义的工具 from config import OPENAI_API_KEY # 导入配置中的API Key # 1. 初始化大语言模型 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定适合工具调用 openai_api_keyOPENAI_API_KEY ) # 2. 获取一个预定义的提示词模板 # ReAct是“Reason Act”的缩写是一种让模型思考并决定行动的经典提示框架。 prompt hub.pull(hwchase17/react) # 从LangChain Hub拉取一个标准ReAct提示模板 # 3. 使用工具、模型和提示词创建Agent agent create_react_agent(llm, tools, prompt) # 4. 创建Agent执行器它负责运行Agent的循环思考-行动-观察 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志便于调试 handle_parsing_errorsTrue, # 优雅处理模型输出解析错误 max_iterations5, # 限制最大迭代次数防止无限循环 early_stopping_methodgenerate, # 当模型认为任务完成时停止 )代码解释ChatOpenAI是LangChain对OpenAI聊天模型的封装。create_react_agent函数将模型、工具和提示模板组合成一个ReAct模式的Agent。AgentExecutor是真正驱动Agent运行的核心它控制着“规划-执行”的循环直到任务完成或达到迭代上限。verboseTrue会让你在控制台看到Agent的思考过程对学习调试极其重要。3.3 运行并观察Agent的工作过程现在让我们用一个需要多步推理和工具调用的任务来测试这个Agent。# 继续在 agent_basic.py 中 if __name__ __main__: # 定义一个复杂任务 complex_task 如果北京现在是晴天上海比北京高3度那么上海的天气描述中的温度应该是多少先查天气再计算。 print(f用户问题: {complex_task}) print(- * 50) try: # 执行任务 result agent_executor.invoke({input: complex_task}) print(\n *50) print(最终答案:, result[output]) except Exception as e: print(fAgent执行出错: {e})运行这个脚本python agent_basic.py。你将在控制台看到类似以下的详细输出格式已简化用户问题: 如果北京现在是晴天上海比北京高3度那么上海的天气描述中的温度应该是多少先查天气再计算。 -------------------------------------------------- 进入新的Agent执行链... 思考我需要先找到北京的当前温度然后给这个温度加上3度来得到上海的温度。首先我需要调用获取天气的工具来得到北京的天气。 行动 { action: get_weather, action_input: {city: 北京} } [工具调用] 正在查询北京的天气... 观察晴15°C西北风2级 思考我从北京的天气中得知温度是15°C。现在需要计算上海的温度即15 3。 行动 { action: calculator, action_input: {expression: 15 3} } [工具调用] 正在计算表达式15 3 观察15 3 18 思考我现在知道了上海的温度应该是18°C。我可以给出最终答案了。 行动 { action: Final Answer, action_input: 根据查询北京当前气温为15°C。上海气温比北京高3°C因此上海的气温应为18°C。 } 最终答案: 根据查询北京当前气温为15°C。上海气温比北京高3°C因此上海的气温应为18°C。这个输出完美展示了ReAct Agent的工作流程思考Reason- 行动Act调用工具- 观察Observe获取工具结果- 再思考...直到最终给出答案。4. 为Agent添加记忆与持久化上一个Agent是无状态的每次对话都是独立的。要让Agent记住对话历史我们需要引入记忆组件。这里我们使用ConversationBufferMemory。4.1 使用对话缓冲区记忆# agent_with_memory.py from langchain.memory import ConversationBufferMemory from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub from tools import tools from config import OPENAI_API_KEY llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) # 1. 创建记忆对象 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 2. 在提示词模板中需要包含一个用于放置历史记忆的位置变量{chat_history}。 # 标准的hwchase17/react模板已经支持{chat_history}我们直接使用。 # 如果需要自定义可以从Hub拉取后修改。 # 3. 创建Agent时将memory关联到agent_executor的输入输出中 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, # 传入记忆对象 verboseTrue, handle_parsing_errorsTrue, max_iterations5, ) if __name__ __main__: # 第一轮对话 print(用户: 我叫小明。) response1 agent_executor.invoke({input: 我叫小明。}) print(Agent:, response1[output]) print(-*30) # 第二轮对话Agent应该能记住我的名字 print(用户: 我的名字是什么) response2 agent_executor.invoke({input: 我的名字是什么}) print(Agent:, response2[output]) # 查看当前记忆内容 print(\n当前记忆内容:) print(memory.buffer)运行后第二轮对话中Agent应该能回答“你的名字是小明”。ConversationBufferMemory简单地将所有对话历史保存在内存的一个字符串或列表中。4.2 使用向量数据库实现长期记忆对于更复杂的应用需要存储和检索大量历史信息或知识就需要向量数据库。这里以ChromaDB为例实现一个能记住过去对话细节并据此回答的Agent。# agent_with_vector_memory.py from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from langchain.memory import VectorStoreRetrieverMemory from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub from tools import tools from config import OPENAI_API_KEY import os llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) # 1. 初始化嵌入模型和向量数据库 embeddings OpenAIEmbeddings(openai_api_keyOPENAI_API_KEY) # 指定一个持久化目录 persist_directory ./chroma_db vectorstore Chroma( collection_nameagent_memory, embedding_functionembeddings, persist_directorypersist_directory ) # 2. 创建基于向量检索的记忆 # 它会把每轮对话的输入输出作为文档存入向量库并根据当前问题检索相关历史。 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3条记忆 memory VectorStoreRetrieverMemory(retrieverretriever, memory_keychat_history) # 3. 创建带此记忆的Agent agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue, ) if __name__ __main__: # 存入一些记忆 context1 用户说他最喜欢的编程语言是Python。 context2 用户计划下周去杭州出差。 memory.save_context({input: 我的喜好}, {output: context1}) memory.save_context({input: 我的计划}, {output: context2}) # 进行查询Agent应能利用长期记忆 query 我喜欢的编程语言是什么我下周有什么安排 print(f用户: {query}) result agent_executor.invoke({input: query}) print(Agent:, result[output]) # 持久化向量数据库到磁盘 vectorstore.persist()这个Agent现在能从向量数据库中检索出关于“喜好”和“计划”的记忆片段并综合回答。这对于构建知识库问答或需要长期上下文的聊天机器人非常有用。5. 生产环境部署与常见问题排查将实验性的Agent脚本转化为可稳定服务的应用需要关注部署、监控和错误处理。5.1 使用FastAPI封装Agent为Web API一个常见的模式是将Agent封装成REST API供前端或其他服务调用。# app/main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from langchain.agents import AgentExecutor from .agent_setup import create_agent_executor # 假设你的Agent创建逻辑封装在此 import logging # 配置日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) app FastAPI(titleAI Agent API) # 全局Agent执行器简单示例生产环境需考虑并发和状态隔离 agent_executor: AgentExecutor None class QueryRequest(BaseModel): message: str session_id: str None # 用于区分不同会话 class QueryResponse(BaseModel): answer: str session_id: str app.on_event(startup) async def startup_event(): 启动时初始化Agent global agent_executor try: agent_executor create_agent_executor() logger.info(Agent执行器初始化成功。) except Exception as e: logger.error(fAgent初始化失败: {e}) raise app.post(/chat, response_modelQueryResponse) async def chat_with_agent(request: QueryRequest): 与Agent对话的端点 if not agent_executor: raise HTTPException(status_code503, detailAgent未就绪) try: # 这里可以将会话ID用于获取对应的memory input_data {input: request.message} result agent_executor.invoke(input_data) return QueryResponse(answerresult[output], session_idrequest.session_id or default) except Exception as e: logger.error(f处理请求时出错: {e}, exc_infoTrue) raise HTTPException(status_code500, detailfAgent处理失败: {str(e)}) # 运行: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000使用uvicorn运行此应用你就拥有了一个/chat接口。生产环境需要添加认证、限流、更完善的会话管理和健康检查。5.2 常见问题与排查清单在开发和生产中你会遇到各种问题。下表列出了常见问题及其排查思路。问题现象可能原因检查与解决步骤Agent陷入循环不输出最终答案1. 工具描述不清晰模型无法正确调用。2. 工具返回结果格式模型无法理解。3.max_iterations设置过高且停止条件未触发。1. 检查工具函数的文档字符串确保清晰描述功能和输入格式。2. 开启verboseTrue观察模型思考步骤看是否在重复调用同一工具或空转。3. 适当降低max_iterations如设为10并确保early_stopping_method有效。报错OpenAI API认证失败1. API Key未设置或错误。2. 环境变量未正确加载。3. 账户余额不足或请求超频。1. 检查.env文件格式和变量名是否正确。2. 在代码中打印os.getenv(“OPENAI_API_KEY”)的前几位确认是否加载。3. 登录OpenAI控制台检查用量和余额。模型不调用工具直接回答1. 提示词Prompt未明确指示使用工具。2. 模型能力不足如使用gpt-3.5-turbo而非更新版本。3. 任务过于简单模型认为无需工具。1. 使用专为工具调用设计的提示模板如hwchase17/react。2. 升级到gpt-4-turbo或gpt-4o工具调用能力更强。3. 在用户问题中明确要求使用工具如“请使用计算器工具计算...”。工具调用参数解析错误1. 模型生成的参数格式与工具函数签名不匹配。2. 工具参数类型复杂如嵌套对象。1. 使用handle_parsing_errorsTrue让执行器尝试修复。2. 简化工具参数尽量使用基本类型str,int,float。3. 使用StructuredTool或Pydantic模型来定义更清晰的输入结构。向量记忆检索不到相关内容1. 嵌入模型不适合该类型文本。2. 检索参数k太小或相似度阈值不合适。3. 记忆未正确保存。1. 尝试不同的嵌入模型如text-embedding-3-small。2. 调整search_kwargs如{k: 5, “score_threshold”: 0.7}。3. 检查save_context是否被成功调用并确认向量库已持久化。API响应速度慢1. 模型本身延迟高。2. Agent迭代次数多每次迭代都需调用模型。3. 工具执行慢如网络请求。1. 考虑使用更快的模型或本地模型如通过Ollama部署。2. 优化任务规划减少不必要的迭代。3. 为工具调用设置超时并考虑异步执行工具。5.3 生产环境最佳实践配置管理将所有配置模型类型、API密钥、超时时间、数据库连接外置到环境变量或配置文件中切勿硬编码。错误处理与重试对模型API调用和外部工具调用添加健壮的错误处理如网络超时、速率限制和指数退避重试机制。日志与监控记录详细的运行日志包括模型请求/响应、工具调用记录、执行耗时。集成监控系统如Prometheus跟踪API调用次数、延迟和错误率。会话与状态隔离为每个用户或对话会话创建独立的AgentExecutor和Memory实例避免状态污染。对于Web服务可以使用基于会话ID的缓存或数据库存储记忆。成本与性能优化设置预算和用量告警。对频繁使用的查询结果或嵌入向量进行缓存。考虑在简单任务上使用小型/本地模型复杂任务再调用大模型。安全验证和清理用户输入防止提示词注入。严格限制工具的执行权限如文件系统、网络访问。避免在工具中使用eval等危险函数如必须使用需在沙箱环境中运行。6. 进阶方向与学习路径掌握了基础Agent构建后你可以向以下几个方向深入多智能体Multi-Agent系统学习使用CrewAI或AutoGen框架构建由多个各司其职的Agent如研究员、写手、评审员协作完成复杂任务的系统。更强大的规划与反思研究LangGraph或Plan-and-Execute模式实现更复杂的任务分解、执行状态跟踪和事后反思优化。与真实系统集成将Agent与你的业务系统深度集成例如连接CRM、ERP数据库或赋予它执行审批流程、生成报表的能力。前端交互使用Gradio或Streamlit快速构建聊天界面或开发完整的Web应用。本地模型部署使用Ollama、vLLM或Transformers库在本地或私有云部署开源大模型如Llama 3, Qwen降低成本和提升数据隐私性。评估与持续改进建立Agent性能的评估体系通过A/B测试、人工反馈强化学习RLHF等方式持续优化提示词和工具集。学习路径建议从LangChain官方文档和教程开始亲手复现几个示例。然后尝试用CrewAI构建一个多Agent项目。接着深入一个具体领域如“数据分析Agent”或“客服助手Agent”解决真实场景下的问题。过程中持续关注LangChain、LlamaIndex等核心框架的更新其生态发展迅速。最终你将能够设计并实现真正解决业务痛点的智能体应用。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度在实际的大模型应用开发中Agent智能体已经从一个前沿概念演变为构建复杂AI应用的核心范式。它不再仅仅是调用API生成文本而是能够理解目标、规划步骤、使用工具并执行任务最终达成目标的自主或半自主程序。对于希望从基础开发转向构建具备实际业务价值AI应用的开发者而言掌握Agent开发是必经之路。本文将围绕Agent的核心概念、主流框架、开发实践和部署要点提供一个从零到一的系统性学习路径。无论你是希望理解Agent如何工作还是计划亲手搭建一个能处理复杂流程的智能体本文都将通过具体的环境配置、代码示例和问题排查帮助你构建清晰的知识体系和实操能力。1. 理解Agent从概念到技术栈在深入代码之前必须厘清Agent是什么以及它如何与现有的大模型技术栈结合。这有助于避免后续开发中概念混淆和架构设计错误。1.1 Agent的核心定义与工作模式通俗地讲一个AI Agent就是一个被赋予了“大脑”大语言模型和“手脚”工具/函数的程序。它的核心工作是接收一个高层次的目标例如“帮我分析上个月的销售数据并写一份报告”然后自主地拆解任务、选择工具、执行步骤最终产出结果。这与传统的单次问答式调用有本质区别。从技术定义上看一个典型的Agent系统包含以下几个关键组件规划模块Planner负责将用户目标分解为可执行的子任务序列。这可以通过大模型的链式思考Chain-of-Thought或更复杂的规划算法实现。工具调用模块Tool CallingAgent需要知道它能使用哪些工具如搜索网络、执行代码、查询数据库、调用API。大模型根据当前任务上下文决定调用哪个工具并生成符合工具要求的参数。记忆模块Memory分为短期记忆当前会话的上下文和长期记忆向量数据库存储的历史信息。记忆使Agent能进行多轮对话并参考过去经验。执行与反思模块Execution Reflection执行工具调用获取结果并根据结果评估任务完成情况。如果结果不理想或遇到错误Agent需要能“反思”并调整计划。一个最小的工作流程可以概括为用户输入 - Agent规划 - 选择工具 - 执行工具 - 观察结果 - 反思/下一步 - ... - 最终输出。1.2 Agent开发的技术栈构成开发一个Agent通常需要组合以下技术层技术层常见组件/技术作用大模型层GPT-4, Claude, 文心一言通义千问 Llama 系列 GLM 等提供核心的理解、推理和生成能力。可以是云端API或本地部署模型。框架层LangChain, LlamaIndex, Semantic Kernel, AutoGen, CrewAI 等提供构建Agent所需的高层抽象如工具封装、记忆管理、工作流编排。工具层自定义Python函数搜索引擎API数据库客户端代码解释器外部系统APIAgent可调用的具体能力。框架负责将工具描述暴露给大模型。记忆层向量数据库Chroma, Pinecone, Weaviate 传统数据库存储和检索对话历史、知识片段实现长期记忆。部署层FastAPI, Gradio, Streamlit Docker, Kubernetes将Agent封装成可服务的应用提供Web界面或API接口。对于初学者建议从LangChain或LlamaIndex开始它们社区活跃、文档丰富能快速上手。对于追求更灵活工作流和复杂多Agent协作的场景可以研究CrewAI或AutoGen。2. 环境准备与核心依赖配置在开始第一个Agent项目前一个干净、版本可控的Python环境至关重要。大模型生态依赖复杂版本冲突是新手最常见的拦路虎。2.1 创建并激活虚拟环境使用conda或venv隔离项目环境。这里以venv为例# 创建项目目录并进入 mkdir my_first_agent cd my_first_agent # 创建Python虚拟环境假设使用Python 3.10 python3.10 -m venv venv # 激活虚拟环境 # Linux/macOS source venv/bin/activate # Windows venv\Scripts\activate激活后命令行提示符前应显示(venv)。2.2 安装核心框架与依赖我们将以LangChain为例因为它提供了最全面的Agent构建模块。首先安装LangChain及其常用组件。# 安装LangChain核心包 pip install langchain # 安装LangChain社区包包含大量第三方工具和集成 pip install langchain-community # 安装OpenAI官方SDK如果你使用OpenAI模型 pip install openai # 安装用于解析模型输出如工具调用的包 pip install langchain-core # 安装一个简单的向量数据库用于记忆可选但推荐 pip install chromadb # 安装环境变量管理包用于安全存储API密钥 pip install python-dotenv注意langchain是一个元包它会安装一系列核心子包。在生产环境中为了减少依赖体积和冲突可以考虑只安装你需要的特定子包如pip install langchain-core langchain-openai。2.3 配置大模型访问密钥大多数Agent需要连接一个大模型作为“大脑”。以OpenAI为例你需要一个API Key。切勿将API Key硬编码在代码中。在项目根目录创建.env文件。在.env文件中写入你的密钥OPENAI_API_KEY你的实际api-key-here在代码中通过dotenv加载# config.py 或主程序开头 from dotenv import load_dotenv import os load_dotenv() # 加载 .env 文件中的环境变量 OPENAI_API_KEY os.getenv(OPENAI_API_KEY) if not OPENAI_API_KEY: raise ValueError(请在 .env 文件中设置 OPENAI_API_KEY 环境变量)如果你使用国内大模型如文心一言、通义千问安装对应的LangChain集成包并配置相应的API Key和Base URL。# 例如安装百度千帆文心一言的LangChain集成 pip install langchain-community # 千帆SDK通常已包含在langchain-community中或需单独安装 # pip install qianfan3. 构建你的第一个工具调用Agent理论和技术栈准备就绪后我们通过一个具体案例来实践创建一个能查询当前天气和进行简单计算的Agent。这个Agent将具备规划、工具调用和记忆的基础能力。3.1 定义自定义工具Agent的“手脚”工具本质上是能被大模型识别和调用的函数。我们需要用tool装饰器来定义它并提供一个清晰的描述这个描述会直接影响大模型是否以及如何调用它。# tools.py from langchain.tools import tool import requests import json tool def get_weather(city: str) - str: 获取指定城市的当前天气情况。输入应为城市名称例如“北京”。 # 警告这是一个模拟函数。真实场景应调用如和风天气、OpenWeatherMap等API。 # 需要注册并获取API Key。 print(f[工具调用] 正在查询{city}的天气...) # 模拟API调用和返回 weather_data { 北京: 晴15°C西北风2级, 上海: 多云18°C东南风1级, 深圳: 阵雨22°C南风3级, } return weather_data.get(city, f未找到{city}的天气信息。) tool def calculator(expression: str) - str: 计算一个数学表达式的值。输入应为字符串形式的表达式例如“3 5 * 2”。 print(f[工具调用] 正在计算表达式{expression}) try: # 安全警告在生产环境中直接使用eval是危险的可能造成代码注入。 # 这里仅用于演示。实际应用应使用更安全的计算库如numexpr或ast.literal_eval处理有限运算。 result eval(expression) return f{expression} {result} except Exception as e: return f计算错误{e} # 将工具放入列表供Agent使用 tools [get_weather, calculator]关键点tool装饰器让LangChain能识别这个函数。函数文档字符串...至关重要大模型依靠它来理解工具的功能和输入格式。工具函数内部可以包含任何Python代码实现网络请求、数据库查询、文件操作等。3.2 初始化大模型并创建Agent我们使用OpenAI的GPT-3.5-turbo作为推理模型结合上面定义的工具来创建Agent。# agent_basic.py from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain import hub from tools import tools # 导入上一步定义的工具 from config import OPENAI_API_KEY # 导入配置中的API Key # 1. 初始化大语言模型 llm ChatOpenAI( modelgpt-3.5-turbo, temperature0, # 温度设为0使输出更确定适合工具调用 openai_api_keyOPENAI_API_KEY ) # 2. 获取一个预定义的提示词模板 # ReAct是“Reason Act”的缩写是一种让模型思考并决定行动的经典提示框架。 prompt hub.pull(hwchase17/react) # 从LangChain Hub拉取一个标准ReAct提示模板 # 3. 使用工具、模型和提示词创建Agent agent create_react_agent(llm, tools, prompt) # 4. 创建Agent执行器它负责运行Agent的循环思考-行动-观察 agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, # 开启详细日志便于调试 handle_parsing_errorsTrue, # 优雅处理模型输出解析错误 max_iterations5, # 限制最大迭代次数防止无限循环 early_stopping_methodgenerate, # 当模型认为任务完成时停止 )代码解释ChatOpenAI是LangChain对OpenAI聊天模型的封装。create_react_agent函数将模型、工具和提示模板组合成一个ReAct模式的Agent。AgentExecutor是真正驱动Agent运行的核心它控制着“规划-执行”的循环直到任务完成或达到迭代上限。verboseTrue会让你在控制台看到Agent的思考过程对学习调试极其重要。3.3 运行并观察Agent的工作过程现在让我们用一个需要多步推理和工具调用的任务来测试这个Agent。# 继续在 agent_basic.py 中 if __name__ __main__: # 定义一个复杂任务 complex_task 如果北京现在是晴天上海比北京高3度那么上海的天气描述中的温度应该是多少先查天气再计算。 print(f用户问题: {complex_task}) print(- * 50) try: # 执行任务 result agent_executor.invoke({input: complex_task}) print(\n *50) print(最终答案:, result[output]) except Exception as e: print(fAgent执行出错: {e})运行这个脚本python agent_basic.py。你将在控制台看到类似以下的详细输出格式已简化用户问题: 如果北京现在是晴天上海比北京高3度那么上海的天气描述中的温度应该是多少先查天气再计算。 -------------------------------------------------- 进入新的Agent执行链... 思考我需要先找到北京的当前温度然后给这个温度加上3度来得到上海的温度。首先我需要调用获取天气的工具来得到北京的天气。 行动 { action: get_weather, action_input: {city: 北京} } [工具调用] 正在查询北京的天气... 观察晴15°C西北风2级 思考我从北京的天气中得知温度是15°C。现在需要计算上海的温度即15 3。 行动 { action: calculator, action_input: {expression: 15 3} } [工具调用] 正在计算表达式15 3 观察15 3 18 思考我现在知道了上海的温度应该是18°C。我可以给出最终答案了。 行动 { action: Final Answer, action_input: 根据查询北京当前气温为15°C。上海气温比北京高3°C因此上海的气温应为18°C。 } 最终答案: 根据查询北京当前气温为15°C。上海气温比北京高3°C因此上海的气温应为18°C。这个输出完美展示了ReAct Agent的工作流程思考Reason- 行动Act调用工具- 观察Observe获取工具结果- 再思考...直到最终给出答案。4. 为Agent添加记忆与持久化上一个Agent是无状态的每次对话都是独立的。要让Agent记住对话历史我们需要引入记忆组件。这里我们使用ConversationBufferMemory。4.1 使用对话缓冲区记忆# agent_with_memory.py from langchain.memory import ConversationBufferMemory from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub from tools import tools from config import OPENAI_API_KEY llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) # 1. 创建记忆对象 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 2. 在提示词模板中需要包含一个用于放置历史记忆的位置变量{chat_history}。 # 标准的hwchase17/react模板已经支持{chat_history}我们直接使用。 # 如果需要自定义可以从Hub拉取后修改。 # 3. 创建Agent时将memory关联到agent_executor的输入输出中 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, # 传入记忆对象 verboseTrue, handle_parsing_errorsTrue, max_iterations5, ) if __name__ __main__: # 第一轮对话 print(用户: 我叫小明。) response1 agent_executor.invoke({input: 我叫小明。}) print(Agent:, response1[output]) print(-*30) # 第二轮对话Agent应该能记住我的名字 print(用户: 我的名字是什么) response2 agent_executor.invoke({input: 我的名字是什么}) print(Agent:, response2[output]) # 查看当前记忆内容 print(\n当前记忆内容:) print(memory.buffer)运行后第二轮对话中Agent应该能回答“你的名字是小明”。ConversationBufferMemory简单地将所有对话历史保存在内存的一个字符串或列表中。4.2 使用向量数据库实现长期记忆对于更复杂的应用需要存储和检索大量历史信息或知识就需要向量数据库。这里以ChromaDB为例实现一个能记住过去对话细节并据此回答的Agent。# agent_with_vector_memory.py from langchain_community.vectorstores import Chroma from langchain_openai import OpenAIEmbeddings from langchain.memory import VectorStoreRetrieverMemory from langchain.agents import AgentExecutor, create_react_agent from langchain_openai import ChatOpenAI from langchain import hub from tools import tools from config import OPENAI_API_KEY import os llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyOPENAI_API_KEY) prompt hub.pull(hwchase17/react) # 1. 初始化嵌入模型和向量数据库 embeddings OpenAIEmbeddings(openai_api_keyOPENAI_API_KEY) # 指定一个持久化目录 persist_directory ./chroma_db vectorstore Chroma( collection_nameagent_memory, embedding_functionembeddings, persist_directorypersist_directory ) # 2. 创建基于向量检索的记忆 # 它会把每轮对话的输入输出作为文档存入向量库并根据当前问题检索相关历史。 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相关的3条记忆 memory VectorStoreRetrieverMemory(retrieverretriever, memory_keychat_history) # 3. 创建带此记忆的Agent agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue, ) if __name__ __main__: # 存入一些记忆 context1 用户说他最喜欢的编程语言是Python。 context2 用户计划下周去杭州出差。 memory.save_context({input: 我的喜好}, {output: context1}) memory.save_context({input: 我的计划}, {output: context2}) # 进行查询Agent应能利用长期记忆 query 我喜欢的编程语言是什么我下周有什么安排 print(f用户: {query}) result agent_executor.invoke({input: query}) print(Agent:, result[output]) # 持久化向量数据库到磁盘 vectorstore.persist()这个Agent现在能从向量数据库中检索出关于“喜好”和“计划”的记忆片段并综合回答。这对于构建知识库问答或需要长期上下文的聊天机器人非常有用。5. 生产环境部署与常见问题排查将实验性的Agent脚本转化为可稳定服务的应用需要关注部署、监控和错误处理。5.1 使用FastAPI封装Agent为Web API一个常见的模式是将Agent封装成REST API供前端或其他服务调用。# app/main.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from langchain.agents import AgentExecutor from .agent_setup import create_agent_executor # 假设你的Agent创建逻辑封装在此 import logging # 配置日志 logging.basicConfig(levellogging.INFO) logger logging.getLogger(__name__) app FastAPI(titleAI Agent API) # 全局Agent执行器简单示例生产环境需考虑并发和状态隔离 agent_executor: AgentExecutor None class QueryRequest(BaseModel): message: str session_id: str None # 用于区分不同会话 class QueryResponse(BaseModel): answer: str session_id: str app.on_event(startup) async def startup_event(): 启动时初始化Agent global agent_executor try: agent_executor create_agent_executor() logger.info(Agent执行器初始化成功。) except Exception as e: logger.error(fAgent初始化失败: {e}) raise app.post(/chat, response_modelQueryResponse) async def chat_with_agent(request: QueryRequest): 与Agent对话的端点 if not agent_executor: raise HTTPException(status_code503, detailAgent未就绪) try: # 这里可以将会话ID用于获取对应的memory input_data {input: request.message} result agent_executor.invoke(input_data) return QueryResponse(answerresult[output], session_idrequest.session_id or default) except Exception as e: logger.error(f处理请求时出错: {e}, exc_infoTrue) raise HTTPException(status_code500, detailfAgent处理失败: {str(e)}) # 运行: uvicorn app.main:app --reload --host 0.0.0.0 --port 8000使用uvicorn运行此应用你就拥有了一个/chat接口。生产环境需要添加认证、限流、更完善的会话管理和健康检查。5.2 常见问题与排查清单在开发和生产中你会遇到各种问题。下表列出了常见问题及其排查思路。问题现象可能原因检查与解决步骤Agent陷入循环不输出最终答案1. 工具描述不清晰模型无法正确调用。2. 工具返回结果格式模型无法理解。3.max_iterations设置过高且停止条件未触发。1. 检查工具函数的文档字符串确保清晰描述功能和输入格式。2. 开启verboseTrue观察模型思考步骤看是否在重复调用同一工具或空转。3. 适当降低max_iterations如设为10并确保early_stopping_method有效。报错OpenAI API认证失败1. API Key未设置或错误。2. 环境变量未正确加载。3. 账户余额不足或请求超频。1. 检查.env文件格式和变量名是否正确。2. 在代码中打印os.getenv(“OPENAI_API_KEY”)的前几位确认是否加载。3. 登录OpenAI控制台检查用量和余额。模型不调用工具直接回答1. 提示词Prompt未明确指示使用工具。2. 模型能力不足如使用gpt-3.5-turbo而非更新版本。3. 任务过于简单模型认为无需工具。1. 使用专为工具调用设计的提示模板如hwchase17/react。2. 升级到gpt-4-turbo或gpt-4o工具调用能力更强。3. 在用户问题中明确要求使用工具如“请使用计算器工具计算...”。工具调用参数解析错误1. 模型生成的参数格式与工具函数签名不匹配。2. 工具参数类型复杂如嵌套对象。1. 使用handle_parsing_errorsTrue让执行器尝试修复。2. 简化工具参数尽量使用基本类型str,int,float。3. 使用StructuredTool或Pydantic模型来定义更清晰的输入结构。向量记忆检索不到相关内容1. 嵌入模型不适合该类型文本。2. 检索参数k太小或相似度阈值不合适。3. 记忆未正确保存。1. 尝试不同的嵌入模型如text-embedding-3-small。2. 调整search_kwargs如{k: 5, “score_threshold”: 0.7}。3. 检查save_context是否被成功调用并确认向量库已持久化。API响应速度慢1. 模型本身延迟高。2. Agent迭代次数多每次迭代都需调用模型。3. 工具执行慢如网络请求。1. 考虑使用更快的模型或本地模型如通过Ollama部署。2. 优化任务规划减少不必要的迭代。3. 为工具调用设置超时并考虑异步执行工具。5.3 生产环境最佳实践配置管理将所有配置模型类型、API密钥、超时时间、数据库连接外置到环境变量或配置文件中切勿硬编码。错误处理与重试对模型API调用和外部工具调用添加健壮的错误处理如网络超时、速率限制和指数退避重试机制。日志与监控记录详细的运行日志包括模型请求/响应、工具调用记录、执行耗时。集成监控系统如Prometheus跟踪API调用次数、延迟和错误率。会话与状态隔离为每个用户或对话会话创建独立的AgentExecutor和Memory实例避免状态污染。对于Web服务可以使用基于会话ID的缓存或数据库存储记忆。成本与性能优化设置预算和用量告警。对频繁使用的查询结果或嵌入向量进行缓存。考虑在简单任务上使用小型/本地模型复杂任务再调用大模型。安全验证和清理用户输入防止提示词注入。严格限制工具的执行权限如文件系统、网络访问。避免在工具中使用eval等危险函数如必须使用需在沙箱环境中运行。6. 进阶方向与学习路径掌握了基础Agent构建后你可以向以下几个方向深入多智能体Multi-Agent系统学习使用CrewAI或AutoGen框架构建由多个各司其职的Agent如研究员、写手、评审员协作完成复杂任务的系统。更强大的规划与反思研究LangGraph或Plan-and-Execute模式实现更复杂的任务分解、执行状态跟踪和事后反思优化。与真实系统集成将Agent与你的业务系统深度集成例如连接CRM、ERP数据库或赋予它执行审批流程、生成报表的能力。前端交互使用Gradio或Streamlit快速构建聊天界面或开发完整的Web应用。本地模型部署使用Ollama、vLLM或Transformers库在本地或私有云部署开源大模型如Llama 3, Qwen降低成本和提升数据隐私性。评估与持续改进建立Agent性能的评估体系通过A/B测试、人工反馈强化学习RLHF等方式持续优化提示词和工具集。学习路径建议从LangChain官方文档和教程开始亲手复现几个示例。然后尝试用CrewAI构建一个多Agent项目。接着深入一个具体领域如“数据分析Agent”或“客服助手Agent”解决真实场景下的问题。过程中持续关注LangChain、LlamaIndex等核心框架的更新其生态发展迅速。最终你将能够设计并实现真正解决业务痛点的智能体应用。 30款热门AI模型一站整合DeepSeek/GLM/Qwen 随心用限时 5 折。 点击领海量免费额度
 原理详解：解决 3 大充电难题与系统崩溃风险)
