最近在尝试将大模型应用到实际业务中时我发现单纯调用API生成文本已经无法满足复杂需求。比如想让模型自动分析数据、调用工具、执行多步骤任务就需要引入“智能体Agent”的概念。然而围绕Agent的开发资料要么过于学术化要么零散不成体系环境搭建和任务规划等实操环节更是坑点无数。本文旨在系统梳理从零构建AI Agent的完整路径涵盖核心概念、主流框架、手把手实战及避坑指南无论你是想入门的新手还是寻求项目落地的开发者都能从中获得一套可复用的方法论和代码。1. AI Agent的核心概念为什么它是大模型的下一个爆发点在深入代码之前我们必须厘清一个基本问题什么是AI Agent它和普通的大模型调用有何本质区别简单来说AI Agent智能体是一个能够感知环境、进行决策并执行行动以达成特定目标的智能系统。你可以把它想象成一个拥有“大脑”大模型、“手脚”工具/API和“记忆”历史记录的虚拟助手。它的核心突破在于大模型不再仅仅是“应答机”而是进化为可以自主规划、调用工具、持续学习的“执行者”。1.1 普通大模型 vs. AI Agent为了更直观地理解我们通过一个对比表格来区分两者特性普通大模型调用AI Agent交互模式单轮问答QA多轮对话与自主规划核心能力文本生成、内容理解任务分解、工具调用、状态记忆、自我反思输出结果一段文本或代码一个完成的任务如生成报告、修改数据库、发送邮件主动性被动响应主动规划并执行步骤依赖环境仅需模型API需要模型、工具集、记忆模块、规划器协同工作举个例子普通大模型你问“今天北京天气如何” 它回答“今天北京晴最高气温25℃。” 信息可能过时或虚构。AI Agent你下达指令“帮我查一下北京今天的天气如果下雨就提醒我带伞。” Agent会自主规划1. 调用天气查询API获取真实数据2. 分析结果判断是否下雨3. 如果下雨通过邮件或消息工具给你发送提醒。1.2 AI Agent的核心组件架构一个典型的AI Agent系统通常包含以下几个关键组件它们共同协作完成复杂任务规划模块PlannerAgent的“思考链”。它将一个复杂目标拆解成一系列可执行的子任务或步骤。常用技术有Chain of Thought思维链和Tree of Thoughts思维树。工具调用模块Tool UseAgent的“手脚”。大模型本身无法操作外部世界通过定义和调用各种工具如搜索引擎、代码解释器、数据库API、业务系统接口来获取信息或改变状态。记忆模块MemoryAgent的“经验”。分为短期记忆保存当前对话上下文和长期记忆存储关键历史信息、用户偏好等确保Agent在长程交互中保持一致性。执行与反思模块Execution ReflectionAgent的“复盘能力”。执行动作后观察结果评估是否偏离目标并据此调整后续计划。这是实现可靠性的关键。理解了这些概念我们就能明白开发Agent不仅仅是写提示词Prompt更是设计一个能够可靠运转的智能系统。2. 环境准备搭建你的第一个Agent开发环境工欲善其事必先利其器。Agent开发涉及多种工具和框架一个清晰、隔离的环境至关重要。以下配置以Python为核心是当前最主流和活跃的生态。2.1 基础环境配置首先确保你的系统已安装Python推荐3.9或3.10版本与多数库兼容性最好。使用虚拟环境是绝对的最佳实践可以避免包依赖冲突。# 1. 创建并激活一个虚拟环境以venv为例 python -m venv agent-env # Windows agent-env\Scripts\activate # Linux/Mac source agent-env/bin/activate # 2. 升级pip pip install --upgrade pip2.2 关键依赖安装Agent开发框架众多我们将从两个最流行和易上手的开始LangChain和LlamaIndex。前者提供极其灵活的低级组件后者在数据连接和检索方面有独特优势。同时我们需要一个大模型作为Agent的“大脑”。# 安装核心框架 pip install langchain langchain-community langchain-core pip install llama-index-core llama-index-llms-openai llama-index-agent-openai # 安装常用工具和工具调用相关库 pip install langchain-openai # OpenAI官方集成 pip install langchain-experimental # 包含一些实验性但好用的Agent组件 pip install duckduckgo-search # 用于网页搜索的工具 pip install python-dotenv # 管理环境变量如API密钥版本说明LangChain等库更新频繁本文示例基于相对稳定的接口编写。如果遇到API变动请参考官方最新文档调整。2.3 大模型API配置你需要一个大型语言模型的API密钥。国内开发者可以选择智谱AI、百度文心、阿里通义等海外开发者常用OpenAI GPT系列或Anthropic Claude。这里以OpenAI为例请注意使用任何API都需遵守其服务条款。在OpenAI平台注册并获取API Key。在项目根目录创建.env文件存储密钥# .env 文件内容 OPENAI_API_KEY你的实际api-key-here在代码中通过os和dotenv加载import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 openai_api_key os.getenv(OPENAI_API_KEY)重要安全提示永远不要将API密钥硬编码在代码中或上传到GitHub等公开仓库。.env文件必须加入.gitignore。3. 核心框架与工具调用实战有了环境我们开始实战。本节将使用LangChain一步步构建一个能调用真实工具的Agent。3.1 定义你的第一个工具Tool工具是Agent能力的延伸。LangChain中工具可以用函数简单定义并使用tool装饰器。from langchain.tools import tool import datetime tool def get_current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。输入应为时区字符串例如 Asia/Shanghai 或 America/New_York。 try: from datetime import datetime, timezone as tz import pytz tz_obj pytz.timezone(timezone) current_time datetime.now(tz_obj) return f当前时间{timezone}是{current_time.strftime(%Y-%m-%d %H:%M:%S)} except Exception as e: return f时区错误{e}。请提供有效的时区名称如 Asia/Shanghai。 # 测试工具 print(get_current_time.invoke({timezone: Asia/Shanghai}))3.2 创建工具集并初始化Agent单个工具能力有限我们需要将多个工具组合起来并交给一个Agent来调度。from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 用于拉取预设的Prompt # 1. 初始化大模型使用gpt-3.5-turbo成本较低适合实验 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyopenai_api_key) # 2. 定义工具列表 tools [get_current_time] # 可以继续添加更多工具如搜索工具 # 3. 从LangChain Hub拉取一个优化过的ReAct格式提示词 prompt hub.pull(hwchase17/react) # 4. 创建ReAct Agent agent create_react_agent(llm, tools, prompt) # 5. 创建Agent执行器它负责运行Agent的循环思考-行动-观察 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue)3.3 运行你的第一个Agent现在让我们向这个配备了“看时间”工具的Agent提问。# 运行Agent result agent_executor.invoke({ input: 请问现在上海是几点钟 }) print(\n--- Agent最终回答 ---) print(result[output])预期输出verbose模式下 Entering new AgentExecutor chain... 我需要找到上海当前的时间。上海在中国的 Asia/Shanghai 时区。 我应该使用 get_current_time 工具来获取时间。 Action: get_current_time Action Input: {timezone: Asia/Shanghai} Observation: 当前时间Asia/Shanghai是2024-05-15 14:30:22 Thought: 我已经获得了上海的时间现在可以回答用户的问题了。 Action: Final Answer 当前上海的时间是 2024-05-15 14:30:22。 Finished chain. --- Agent最终回答 --- 当前上海的时间是 2024-05-15 14:30:22。恭喜你已经创建了一个能够理解问题、规划使用工具、执行工具调用并给出答案的初级AI Agent。verboseTrue让你清晰地看到了Agent内部的“思考Thought—行动Action—观察Observation”链条这正是ReAct框架的核心。4. 构建多功能Agent集成搜索与计算一个实用的Agent需要多种能力。让我们增强它加入网页搜索和数学计算工具。4.1 添加DuckDuckGo搜索工具首先安装并添加一个搜索工具让Agent能获取实时信息。from langchain_community.tools import DuckDuckGoSearchRun # 初始化搜索工具 search_tool DuckDuckGoSearchRun() # 更新工具列表 tools [get_current_time, search_tool] # 重新创建Agent和执行器 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 测试新能力 result agent_executor.invoke({ input: 搜索一下LangChain框架最新发布的版本是什么然后告诉我。 }) print(result[output])4.2 添加数学计算工具大模型不擅长精确计算我们可以接入一个计算工具。from langchain.tools import Tool from langchain_community.utilities import ArxivAPIWrapper # 使用LangChain内置的LLMMathChain作为计算工具它会让LLM生成计算式然后由Python eval执行 from langchain.chains import LLMMathChain from langchain_community.utilities import SerpAPIWrapper # 示例也可用其他计算方式 # 创建数学计算链作为工具 llm_math LLMMathChain.from_llm(llmllm, verboseTrue) math_tool Tool( nameCalculator, funcllm_math.run, description用于回答数学计算问题。输入应该是一个明确的数学表达式。 ) # 再次更新工具集 tools [get_current_time, search_tool, math_tool] agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 测试复杂任务 result agent_executor.invoke({ input: 先搜索‘北京人口’然后用计算器估算一下如果每人每天产生1.2公斤垃圾北京年垃圾总量大概多少吨 }) print(result[output])通过这个例子你可以看到Agent如何自主规划先调用搜索工具获取“北京人口”数据再调用计算器工具进行乘法运算。这已经是一个能处理多步骤现实任务的智能体雏形。5. 高级主题记忆、结构化输出与智能体类型基础工具调用只是开始。要构建更强大、更可靠的Agent必须掌握以下高级概念。5.1 为Agent添加记忆Memory没有记忆的Agent每次对话都是独立的。通过添加记忆Agent可以记住之前的对话内容实现连贯的多轮交互。from langchain.memory import ConversationBufferMemory # 创建记忆体 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 在创建Agent执行器时传入memory agent_executor_with_memory AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue ) # 第一轮对话 result1 agent_executor_with_memory.invoke({input: 我叫张三住在北京。}) print(fRound 1: {result1[output]}) # 第二轮对话Agent应该能记住我的名字 result2 agent_executor_with_memory.invoke({input: 我的名字是什么}) print(fRound 2: {result2[output]}) # 预期输出中包含“张三”ConversationBufferMemory会将所有历史对话保存在内存中。对于生产环境你可能需要考虑ConversationSummaryMemory摘要记忆或向量数据库存储的长时期记忆以节省上下文令牌。5.2 处理结构化输出让Agent返回JSON数据很多时候我们需要Agent的输出是结构化的数据如JSON以便后续程序处理。这可以通过定义带有Pydantic模型的工具或使用OpenAI的Function Calling功能实现。from langchain_openai import ChatOpenAI from langchain.tools import StructuredTool from pydantic import BaseModel, Field # 定义期望的输出结构 class UserInfo(BaseModel): name: str Field(description用户的姓名) age: int Field(description用户的年龄) city: str Field(description用户所在城市) def extract_user_info(text: str) - dict: 从一段文本中提取用户的姓名、年龄和城市信息。 # 这里为了演示我们让LLM来解析。实际应用中可能结合NER模型。 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) prompt f 请从以下文本中提取用户的姓名、年龄和城市信息并以JSON格式返回只包含name, age, city三个键。 文本{text} response llm.invoke(prompt) # 简单演示实际需要更健壮的JSON解析 import json try: return json.loads(response.content) except: return {name: 未知, age: 0, city: 未知} # 创建结构化工具 info_extraction_tool StructuredTool.from_function( funcextract_user_info, nameExtractUserInfo, description从文本提取用户信息, args_schemaUserInfo # 这里Schema主要用于描述实际参数是text ) # 可以将此工具加入Agent的工具箱5.3 不同类型的Agent架构LangChain提供了多种预设的Agent类型适用于不同场景Zero-shot ReAct最通用不提供具体示例依赖模型的推理能力。Structured Input ReAct处理需要多输入的工具。OpenAI Functions专为与OpenAI的Function Calling功能优化通常更稳定、解析更准确。Self-ask with search特别适合需要中间答案是/否的复杂问答。选择哪种Agent取决于你的工具复杂度和模型特性。通常从create_openai_tools_agent如果使用OpenAI或create_react_agent开始是不错的选择。6. 项目实战构建一个自动化数据分析Agent让我们综合运用所学构建一个相对复杂的Agent它能根据用户指令自动从网络获取数据进行分析并生成总结报告。项目目标创建一个“市场调研Agent”用户可以说“帮我分析一下最近三个月人工智能在医疗领域的最新投资趋势”Agent能自动搜索、整理信息并输出结构化报告。6.1 项目结构与设计market_research_agent/ ├── .env # 存储API密钥 ├── requirements.txt # 项目依赖 ├── main.py # 主程序入口 ├── tools/ # 自定义工具目录 │ ├── __init__.py │ ├── search_tools.py # 搜索相关工具 │ └── analysis_tools.py # 数据分析工具 └── utils/ # 工具函数 └── prompts.py # 存放提示词模板6.2 实现核心工具首先我们创建几个更强大的工具。# tools/search_tools.py from langchain.tools import tool from duckduckgo_search import DDGS import json tool def web_search(query: str, max_results: int 5) - str: 执行网页搜索并返回简洁的摘要结果。输入是一个搜索查询字符串。 try: with DDGS() as ddgs: results list(ddgs.text(query, max_resultsmax_results)) formatted_results [] for r in results: formatted_results.append({ title: r.get(title, N/A), body: r.get(body, N/A)[:200], # 截取部分内容 link: r.get(href, N/A) }) return json.dumps(formatted_results, ensure_asciiFalse, indent2) except Exception as e: return f搜索过程中出错{e} tool def news_search(topic: str, timeframe: str past month) - str: 搜索特定主题的近期新闻。 # 这里可以集成专门的新闻API如NewsAPI。为简化我们使用通用搜索并加关键词。 search_query f{topic} news {timeframe} return web_search.invoke(search_query)# tools/analysis_tools.py from langchain.tools import tool from langchain_openai import ChatOpenAI import os from dotenv import load_dotenv load_dotenv() llm ChatOpenAI(modelgpt-4, temperature0.3, openai_api_keyos.getenv(OPENAI_API_KEY)) tool def summarize_text(long_text: str) - str: 对长文本进行总结提取核心观点。 prompt f 请对以下文本进行专业、简洁的总结突出最重要的3-5个观点或事实。 文本 {long_text[:3000]} # 避免超出令牌限制 response llm.invoke(prompt) return response.content tool def generate_report(data_points: list, analysis_focus: str) - str: 根据多个数据点生成一份分析报告。 combined_data \n---\n.join([str(dp) for dp in data_points]) prompt f 你是一名资深市场分析师。请根据以下收集到的信息围绕“{analysis_focus}”这个主题生成一份结构化的分析报告。 报告需包含概述、主要发现、趋势分析、潜在机会与风险、结论。 请使用专业、客观的商业语言。 收集到的信息 {combined_data} response llm.invoke(prompt) return response.content6.3 组装智能体并创建执行流程在main.py中我们将所有组件组装起来并设计一个多步骤的工作流。# main.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import create_openai_tools_agent, AgentExecutor from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.memory import ConversationSummaryBufferMemory from tools.search_tools import web_search, news_search from tools.analysis_tools import summarize_text, generate_report load_dotenv() def main(): # 1. 初始化LLM (使用支持Function Calling的模型) llm ChatOpenAI(modelgpt-4-turbo-preview, temperature0, openai_api_keyos.getenv(OPENAI_API_KEY)) # 2. 定义工具集 tools [web_search, news_search, summarize_text, generate_report] # 3. 设计系统提示词赋予Agent角色和能力 system_prompt 你是一个高级市场调研与分析AI助手。你的任务是 1. 理解用户关于市场、行业、公司或趋势的调研需求。 2. 规划调研步骤包括使用搜索工具获取最新信息。 3. 对获取的信息进行筛选、总结和交叉验证。 4. 最终生成一份结构清晰、论据充分、语言专业的分析报告。 请一步步思考并充分利用你的工具。如果信息不足请主动提出澄清问题。 prompt ChatPromptTemplate.from_messages([ (system, system_prompt), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) # 4. 创建记忆使用摘要记忆以节省token memory ConversationSummaryBufferMemory( llmllm, memory_keychat_history, return_messagesTrue, max_token_limit1000 ) # 5. 创建Agent和执行器使用OpenAI Tools Agent对工具调用支持更好 agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue, max_iterations5 # 防止无限循环 ) # 6. 运行Agent user_query 请分析人工智能在药物发现领域近半年的主要技术突破和融资趋势。 print(f用户查询{user_query}\n) result agent_executor.invoke({input: user_query}) print(\n *50) print(最终分析报告) print(*50) print(result[output]) if __name__ __main__: main()这个Agent会自主执行以下流程1. 理解“药物发现”和“融资趋势”2. 调用news_search和web_search获取信息3. 可能调用summarize_text处理过长内容4. 最后调用generate_report生成报告。verboseTrue会让你看到整个决策过程。7. 常见问题与排查指南FAQ在开发和使用Agent过程中你一定会遇到各种问题。以下是一些典型问题及其解决方案。问题现象可能原因排查与解决思路Agent陷入循环不断重复相同动作1. 工具描述不清晰模型无法理解何时使用。2. 任务目标过于模糊或不可实现。3.max_iterations设置过高或无限制。1.优化工具描述确保description字段清晰、具体说明工具的精确用途和输入格式。2.细化用户指令给Agent更明确、可拆分的任务。3.设置迭代限制在AgentExecutor中设置max_iterations10等合理值。4.启用handle_parsing_errorsTrue防止因解析失败导致循环。工具调用参数错误或格式不对1. 模型生成的Action Input不符合工具函数的参数要求。2. 工具函数没有类型提示或提示不准确。1.使用结构化工具优先使用StructuredTool或利用OpenAI的Function Calling它们能生成更规范的参数。2.强化提示词在系统提示中强调“必须生成符合工具要求的精确输入”。3.在工具函数内部增加校验和错误处理返回友好错误信息供模型“观察”。“OpenAI API 错误无效的API密钥”1. API密钥未正确设置。2. 环境变量未加载。3. 密钥已过期或额度用尽。1.检查.env文件确保文件名正确且密钥写在OPENAI_API_KEYsk-...格式中。2.确认代码加载在代码开头调用load_dotenv()。3.打印验证print(os.getenv(“OPENAI_API_KEY”)[:10])查看是否加载成功。4.登录OpenAI控制台检查密钥状态和余额。LangChain版本更新导致API不兼容LangChain版本迭代快部分接口或模块路径会变化。1.查阅官方迁移指南通常GitHub Release或文档会有说明。2.锁定版本在requirements.txt中使用langchain0.1.0格式锁定已知可用的版本。3.使用langchain-community许多工具已迁移到此包确保已安装。Agent执行速度很慢1. 网络延迟调用OpenAI API。2. 工具本身慢如搜索。3. Agent规划步骤过多。1.使用更快的模型如gpt-3.5-turbo比gpt-4快很多。2.设置超时为网络请求配置超时时间。3.优化工具对耗时工具进行缓存或寻找替代品。4.简化任务让用户任务更直接或使用更“直接”的Agent类型。记忆Memory消耗大量Token使用ConversationBufferMemory且对话很长。1.切换为摘要记忆ConversationSummaryBufferMemory。2.限制记忆长度设置max_token_limit。3.使用向量存储长期记忆将历史对话嵌入后存入向量数据库如Chroma按需检索。8. 最佳实践与进阶学习路线掌握了基础构建方法后要打造可用于生产环境的可靠Agent还需要遵循以下最佳实践。8.1 Agent开发最佳实践工具设计原子化每个工具应只做一件事并做好。避免创建功能臃肿的“瑞士军刀”式工具。清晰的工具描述是Agent正确调用的前提。系统提示词工程系统提示词是Agent的“人格”和“工作准则”。明确其角色、目标、约束和输出格式。例如“你是一个谨慎的助手在不确定时会询问澄清问题而非猜测。”实施严格的错误处理在工具函数内部、Agent执行循环外部都要有健壮的错误处理try...except并让错误信息能反馈给模型使其有机会自我纠正。控制成本与延迟对于复杂任务设置max_iterations和max_execution_time。考虑使用更便宜的模型进行初步规划或用流式输出改善用户体验。评估与测试像测试软件一样测试你的Agent。构建涵盖成功路径、边缘情况和失败场景的测试用例。评估其准确性、可靠性和成本。安全与权限Agent能调用工具意味着它拥有工具的权限。务必实施最小权限原则。例如一个只能读取数据库的Agent绝不赋予它删除权限。对所有用户输入进行清理和验证。8.2 从入门到精通的进阶学习路线如果你想深入Agent开发领域可以按以下路径系统学习第一阶段巩固基础1-2周核心熟练掌握LangChain/LlamaIndex的Agent、Tools、Memory、Chains核心模块。实践复现本文所有示例并尝试为自己创建5-10个实用小工具如查天气、读文件、发邮件通知。第二阶段项目实战2-4周方向一自动化助手构建一个能处理日常工作的个人助理如自动整理会议纪要、管理待办事项、汇总日报。方向二垂直领域Agent结合特定领域知识如法律、金融、医疗利用RAG检索增强生成技术构建专业问答Agent。技术重点学习向量数据库Chroma, Pinecone, Weaviate掌握RAG全流程。学习如何用LlamaIndex高效构建索引。第三阶段深入原理与优化长期框架源码阅读LangChain Agent执行器的源码理解其规划、行动、观察的循环机制。高级架构学习多智能体Multi-Agent系统了解智能体间的协作与竞争如CrewAI, AutoGen框架。自定义Agent不依赖高级框架直接利用大模型的Function Calling或ReAct格式提示词从零构建更可控的Agent逻辑。评估与监控学习如何量化评估Agent的性能准确性、效率、成本并建立监控告警体系。第四阶段关注前沿开源模型关注Llama、Qwen、DeepSeek等开源模型的Agent能力进展尝试在本地部署。平台与云服务了解Google Vertex AI Agent Builder、Microsoft Copilot Studio等云原生Agent构建平台。研究论文跟进ReAct、Toolformer、TALM、ART等让模型学会使用工具的前沿研究。AI Agent的开发是一场结合了软件工程、提示词工程和应用逻辑的奇妙旅程。它没有银弹最大的挑战往往不在于让Agent“动起来”而在于让它“可靠地、安全地、高效地”完成复杂任务。
最近在尝试将大模型应用到实际业务中时我发现单纯调用API生成文本已经无法满足复杂需求。比如想让模型自动分析数据、调用工具、执行多步骤任务就需要引入“智能体Agent”的概念。然而围绕Agent的开发资料要么过于学术化要么零散不成体系环境搭建和任务规划等实操环节更是坑点无数。本文旨在系统梳理从零构建AI Agent的完整路径涵盖核心概念、主流框架、手把手实战及避坑指南无论你是想入门的新手还是寻求项目落地的开发者都能从中获得一套可复用的方法论和代码。1. AI Agent的核心概念为什么它是大模型的下一个爆发点在深入代码之前我们必须厘清一个基本问题什么是AI Agent它和普通的大模型调用有何本质区别简单来说AI Agent智能体是一个能够感知环境、进行决策并执行行动以达成特定目标的智能系统。你可以把它想象成一个拥有“大脑”大模型、“手脚”工具/API和“记忆”历史记录的虚拟助手。它的核心突破在于大模型不再仅仅是“应答机”而是进化为可以自主规划、调用工具、持续学习的“执行者”。1.1 普通大模型 vs. AI Agent为了更直观地理解我们通过一个对比表格来区分两者特性普通大模型调用AI Agent交互模式单轮问答QA多轮对话与自主规划核心能力文本生成、内容理解任务分解、工具调用、状态记忆、自我反思输出结果一段文本或代码一个完成的任务如生成报告、修改数据库、发送邮件主动性被动响应主动规划并执行步骤依赖环境仅需模型API需要模型、工具集、记忆模块、规划器协同工作举个例子普通大模型你问“今天北京天气如何” 它回答“今天北京晴最高气温25℃。” 信息可能过时或虚构。AI Agent你下达指令“帮我查一下北京今天的天气如果下雨就提醒我带伞。” Agent会自主规划1. 调用天气查询API获取真实数据2. 分析结果判断是否下雨3. 如果下雨通过邮件或消息工具给你发送提醒。1.2 AI Agent的核心组件架构一个典型的AI Agent系统通常包含以下几个关键组件它们共同协作完成复杂任务规划模块PlannerAgent的“思考链”。它将一个复杂目标拆解成一系列可执行的子任务或步骤。常用技术有Chain of Thought思维链和Tree of Thoughts思维树。工具调用模块Tool UseAgent的“手脚”。大模型本身无法操作外部世界通过定义和调用各种工具如搜索引擎、代码解释器、数据库API、业务系统接口来获取信息或改变状态。记忆模块MemoryAgent的“经验”。分为短期记忆保存当前对话上下文和长期记忆存储关键历史信息、用户偏好等确保Agent在长程交互中保持一致性。执行与反思模块Execution ReflectionAgent的“复盘能力”。执行动作后观察结果评估是否偏离目标并据此调整后续计划。这是实现可靠性的关键。理解了这些概念我们就能明白开发Agent不仅仅是写提示词Prompt更是设计一个能够可靠运转的智能系统。2. 环境准备搭建你的第一个Agent开发环境工欲善其事必先利其器。Agent开发涉及多种工具和框架一个清晰、隔离的环境至关重要。以下配置以Python为核心是当前最主流和活跃的生态。2.1 基础环境配置首先确保你的系统已安装Python推荐3.9或3.10版本与多数库兼容性最好。使用虚拟环境是绝对的最佳实践可以避免包依赖冲突。# 1. 创建并激活一个虚拟环境以venv为例 python -m venv agent-env # Windows agent-env\Scripts\activate # Linux/Mac source agent-env/bin/activate # 2. 升级pip pip install --upgrade pip2.2 关键依赖安装Agent开发框架众多我们将从两个最流行和易上手的开始LangChain和LlamaIndex。前者提供极其灵活的低级组件后者在数据连接和检索方面有独特优势。同时我们需要一个大模型作为Agent的“大脑”。# 安装核心框架 pip install langchain langchain-community langchain-core pip install llama-index-core llama-index-llms-openai llama-index-agent-openai # 安装常用工具和工具调用相关库 pip install langchain-openai # OpenAI官方集成 pip install langchain-experimental # 包含一些实验性但好用的Agent组件 pip install duckduckgo-search # 用于网页搜索的工具 pip install python-dotenv # 管理环境变量如API密钥版本说明LangChain等库更新频繁本文示例基于相对稳定的接口编写。如果遇到API变动请参考官方最新文档调整。2.3 大模型API配置你需要一个大型语言模型的API密钥。国内开发者可以选择智谱AI、百度文心、阿里通义等海外开发者常用OpenAI GPT系列或Anthropic Claude。这里以OpenAI为例请注意使用任何API都需遵守其服务条款。在OpenAI平台注册并获取API Key。在项目根目录创建.env文件存储密钥# .env 文件内容 OPENAI_API_KEY你的实际api-key-here在代码中通过os和dotenv加载import os from dotenv import load_dotenv load_dotenv() # 加载 .env 文件中的环境变量 openai_api_key os.getenv(OPENAI_API_KEY)重要安全提示永远不要将API密钥硬编码在代码中或上传到GitHub等公开仓库。.env文件必须加入.gitignore。3. 核心框架与工具调用实战有了环境我们开始实战。本节将使用LangChain一步步构建一个能调用真实工具的Agent。3.1 定义你的第一个工具Tool工具是Agent能力的延伸。LangChain中工具可以用函数简单定义并使用tool装饰器。from langchain.tools import tool import datetime tool def get_current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。输入应为时区字符串例如 Asia/Shanghai 或 America/New_York。 try: from datetime import datetime, timezone as tz import pytz tz_obj pytz.timezone(timezone) current_time datetime.now(tz_obj) return f当前时间{timezone}是{current_time.strftime(%Y-%m-%d %H:%M:%S)} except Exception as e: return f时区错误{e}。请提供有效的时区名称如 Asia/Shanghai。 # 测试工具 print(get_current_time.invoke({timezone: Asia/Shanghai}))3.2 创建工具集并初始化Agent单个工具能力有限我们需要将多个工具组合起来并交给一个Agent来调度。from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain import hub # 用于拉取预设的Prompt # 1. 初始化大模型使用gpt-3.5-turbo成本较低适合实验 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0, openai_api_keyopenai_api_key) # 2. 定义工具列表 tools [get_current_time] # 可以继续添加更多工具如搜索工具 # 3. 从LangChain Hub拉取一个优化过的ReAct格式提示词 prompt hub.pull(hwchase17/react) # 4. 创建ReAct Agent agent create_react_agent(llm, tools, prompt) # 5. 创建Agent执行器它负责运行Agent的循环思考-行动-观察 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue)3.3 运行你的第一个Agent现在让我们向这个配备了“看时间”工具的Agent提问。# 运行Agent result agent_executor.invoke({ input: 请问现在上海是几点钟 }) print(\n--- Agent最终回答 ---) print(result[output])预期输出verbose模式下 Entering new AgentExecutor chain... 我需要找到上海当前的时间。上海在中国的 Asia/Shanghai 时区。 我应该使用 get_current_time 工具来获取时间。 Action: get_current_time Action Input: {timezone: Asia/Shanghai} Observation: 当前时间Asia/Shanghai是2024-05-15 14:30:22 Thought: 我已经获得了上海的时间现在可以回答用户的问题了。 Action: Final Answer 当前上海的时间是 2024-05-15 14:30:22。 Finished chain. --- Agent最终回答 --- 当前上海的时间是 2024-05-15 14:30:22。恭喜你已经创建了一个能够理解问题、规划使用工具、执行工具调用并给出答案的初级AI Agent。verboseTrue让你清晰地看到了Agent内部的“思考Thought—行动Action—观察Observation”链条这正是ReAct框架的核心。4. 构建多功能Agent集成搜索与计算一个实用的Agent需要多种能力。让我们增强它加入网页搜索和数学计算工具。4.1 添加DuckDuckGo搜索工具首先安装并添加一个搜索工具让Agent能获取实时信息。from langchain_community.tools import DuckDuckGoSearchRun # 初始化搜索工具 search_tool DuckDuckGoSearchRun() # 更新工具列表 tools [get_current_time, search_tool] # 重新创建Agent和执行器 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 测试新能力 result agent_executor.invoke({ input: 搜索一下LangChain框架最新发布的版本是什么然后告诉我。 }) print(result[output])4.2 添加数学计算工具大模型不擅长精确计算我们可以接入一个计算工具。from langchain.tools import Tool from langchain_community.utilities import ArxivAPIWrapper # 使用LangChain内置的LLMMathChain作为计算工具它会让LLM生成计算式然后由Python eval执行 from langchain.chains import LLMMathChain from langchain_community.utilities import SerpAPIWrapper # 示例也可用其他计算方式 # 创建数学计算链作为工具 llm_math LLMMathChain.from_llm(llmllm, verboseTrue) math_tool Tool( nameCalculator, funcllm_math.run, description用于回答数学计算问题。输入应该是一个明确的数学表达式。 ) # 再次更新工具集 tools [get_current_time, search_tool, math_tool] agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 测试复杂任务 result agent_executor.invoke({ input: 先搜索‘北京人口’然后用计算器估算一下如果每人每天产生1.2公斤垃圾北京年垃圾总量大概多少吨 }) print(result[output])通过这个例子你可以看到Agent如何自主规划先调用搜索工具获取“北京人口”数据再调用计算器工具进行乘法运算。这已经是一个能处理多步骤现实任务的智能体雏形。5. 高级主题记忆、结构化输出与智能体类型基础工具调用只是开始。要构建更强大、更可靠的Agent必须掌握以下高级概念。5.1 为Agent添加记忆Memory没有记忆的Agent每次对话都是独立的。通过添加记忆Agent可以记住之前的对话内容实现连贯的多轮交互。from langchain.memory import ConversationBufferMemory # 创建记忆体 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 在创建Agent执行器时传入memory agent_executor_with_memory AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue ) # 第一轮对话 result1 agent_executor_with_memory.invoke({input: 我叫张三住在北京。}) print(fRound 1: {result1[output]}) # 第二轮对话Agent应该能记住我的名字 result2 agent_executor_with_memory.invoke({input: 我的名字是什么}) print(fRound 2: {result2[output]}) # 预期输出中包含“张三”ConversationBufferMemory会将所有历史对话保存在内存中。对于生产环境你可能需要考虑ConversationSummaryMemory摘要记忆或向量数据库存储的长时期记忆以节省上下文令牌。5.2 处理结构化输出让Agent返回JSON数据很多时候我们需要Agent的输出是结构化的数据如JSON以便后续程序处理。这可以通过定义带有Pydantic模型的工具或使用OpenAI的Function Calling功能实现。from langchain_openai import ChatOpenAI from langchain.tools import StructuredTool from pydantic import BaseModel, Field # 定义期望的输出结构 class UserInfo(BaseModel): name: str Field(description用户的姓名) age: int Field(description用户的年龄) city: str Field(description用户所在城市) def extract_user_info(text: str) - dict: 从一段文本中提取用户的姓名、年龄和城市信息。 # 这里为了演示我们让LLM来解析。实际应用中可能结合NER模型。 llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) prompt f 请从以下文本中提取用户的姓名、年龄和城市信息并以JSON格式返回只包含name, age, city三个键。 文本{text} response llm.invoke(prompt) # 简单演示实际需要更健壮的JSON解析 import json try: return json.loads(response.content) except: return {name: 未知, age: 0, city: 未知} # 创建结构化工具 info_extraction_tool StructuredTool.from_function( funcextract_user_info, nameExtractUserInfo, description从文本提取用户信息, args_schemaUserInfo # 这里Schema主要用于描述实际参数是text ) # 可以将此工具加入Agent的工具箱5.3 不同类型的Agent架构LangChain提供了多种预设的Agent类型适用于不同场景Zero-shot ReAct最通用不提供具体示例依赖模型的推理能力。Structured Input ReAct处理需要多输入的工具。OpenAI Functions专为与OpenAI的Function Calling功能优化通常更稳定、解析更准确。Self-ask with search特别适合需要中间答案是/否的复杂问答。选择哪种Agent取决于你的工具复杂度和模型特性。通常从create_openai_tools_agent如果使用OpenAI或create_react_agent开始是不错的选择。6. 项目实战构建一个自动化数据分析Agent让我们综合运用所学构建一个相对复杂的Agent它能根据用户指令自动从网络获取数据进行分析并生成总结报告。项目目标创建一个“市场调研Agent”用户可以说“帮我分析一下最近三个月人工智能在医疗领域的最新投资趋势”Agent能自动搜索、整理信息并输出结构化报告。6.1 项目结构与设计market_research_agent/ ├── .env # 存储API密钥 ├── requirements.txt # 项目依赖 ├── main.py # 主程序入口 ├── tools/ # 自定义工具目录 │ ├── __init__.py │ ├── search_tools.py # 搜索相关工具 │ └── analysis_tools.py # 数据分析工具 └── utils/ # 工具函数 └── prompts.py # 存放提示词模板6.2 实现核心工具首先我们创建几个更强大的工具。# tools/search_tools.py from langchain.tools import tool from duckduckgo_search import DDGS import json tool def web_search(query: str, max_results: int 5) - str: 执行网页搜索并返回简洁的摘要结果。输入是一个搜索查询字符串。 try: with DDGS() as ddgs: results list(ddgs.text(query, max_resultsmax_results)) formatted_results [] for r in results: formatted_results.append({ title: r.get(title, N/A), body: r.get(body, N/A)[:200], # 截取部分内容 link: r.get(href, N/A) }) return json.dumps(formatted_results, ensure_asciiFalse, indent2) except Exception as e: return f搜索过程中出错{e} tool def news_search(topic: str, timeframe: str past month) - str: 搜索特定主题的近期新闻。 # 这里可以集成专门的新闻API如NewsAPI。为简化我们使用通用搜索并加关键词。 search_query f{topic} news {timeframe} return web_search.invoke(search_query)# tools/analysis_tools.py from langchain.tools import tool from langchain_openai import ChatOpenAI import os from dotenv import load_dotenv load_dotenv() llm ChatOpenAI(modelgpt-4, temperature0.3, openai_api_keyos.getenv(OPENAI_API_KEY)) tool def summarize_text(long_text: str) - str: 对长文本进行总结提取核心观点。 prompt f 请对以下文本进行专业、简洁的总结突出最重要的3-5个观点或事实。 文本 {long_text[:3000]} # 避免超出令牌限制 response llm.invoke(prompt) return response.content tool def generate_report(data_points: list, analysis_focus: str) - str: 根据多个数据点生成一份分析报告。 combined_data \n---\n.join([str(dp) for dp in data_points]) prompt f 你是一名资深市场分析师。请根据以下收集到的信息围绕“{analysis_focus}”这个主题生成一份结构化的分析报告。 报告需包含概述、主要发现、趋势分析、潜在机会与风险、结论。 请使用专业、客观的商业语言。 收集到的信息 {combined_data} response llm.invoke(prompt) return response.content6.3 组装智能体并创建执行流程在main.py中我们将所有组件组装起来并设计一个多步骤的工作流。# main.py import os from dotenv import load_dotenv from langchain_openai import ChatOpenAI from langchain.agents import create_openai_tools_agent, AgentExecutor from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder from langchain.memory import ConversationSummaryBufferMemory from tools.search_tools import web_search, news_search from tools.analysis_tools import summarize_text, generate_report load_dotenv() def main(): # 1. 初始化LLM (使用支持Function Calling的模型) llm ChatOpenAI(modelgpt-4-turbo-preview, temperature0, openai_api_keyos.getenv(OPENAI_API_KEY)) # 2. 定义工具集 tools [web_search, news_search, summarize_text, generate_report] # 3. 设计系统提示词赋予Agent角色和能力 system_prompt 你是一个高级市场调研与分析AI助手。你的任务是 1. 理解用户关于市场、行业、公司或趋势的调研需求。 2. 规划调研步骤包括使用搜索工具获取最新信息。 3. 对获取的信息进行筛选、总结和交叉验证。 4. 最终生成一份结构清晰、论据充分、语言专业的分析报告。 请一步步思考并充分利用你的工具。如果信息不足请主动提出澄清问题。 prompt ChatPromptTemplate.from_messages([ (system, system_prompt), MessagesPlaceholder(variable_namechat_history), (human, {input}), MessagesPlaceholder(variable_nameagent_scratchpad), ]) # 4. 创建记忆使用摘要记忆以节省token memory ConversationSummaryBufferMemory( llmllm, memory_keychat_history, return_messagesTrue, max_token_limit1000 ) # 5. 创建Agent和执行器使用OpenAI Tools Agent对工具调用支持更好 agent create_openai_tools_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue, max_iterations5 # 防止无限循环 ) # 6. 运行Agent user_query 请分析人工智能在药物发现领域近半年的主要技术突破和融资趋势。 print(f用户查询{user_query}\n) result agent_executor.invoke({input: user_query}) print(\n *50) print(最终分析报告) print(*50) print(result[output]) if __name__ __main__: main()这个Agent会自主执行以下流程1. 理解“药物发现”和“融资趋势”2. 调用news_search和web_search获取信息3. 可能调用summarize_text处理过长内容4. 最后调用generate_report生成报告。verboseTrue会让你看到整个决策过程。7. 常见问题与排查指南FAQ在开发和使用Agent过程中你一定会遇到各种问题。以下是一些典型问题及其解决方案。问题现象可能原因排查与解决思路Agent陷入循环不断重复相同动作1. 工具描述不清晰模型无法理解何时使用。2. 任务目标过于模糊或不可实现。3.max_iterations设置过高或无限制。1.优化工具描述确保description字段清晰、具体说明工具的精确用途和输入格式。2.细化用户指令给Agent更明确、可拆分的任务。3.设置迭代限制在AgentExecutor中设置max_iterations10等合理值。4.启用handle_parsing_errorsTrue防止因解析失败导致循环。工具调用参数错误或格式不对1. 模型生成的Action Input不符合工具函数的参数要求。2. 工具函数没有类型提示或提示不准确。1.使用结构化工具优先使用StructuredTool或利用OpenAI的Function Calling它们能生成更规范的参数。2.强化提示词在系统提示中强调“必须生成符合工具要求的精确输入”。3.在工具函数内部增加校验和错误处理返回友好错误信息供模型“观察”。“OpenAI API 错误无效的API密钥”1. API密钥未正确设置。2. 环境变量未加载。3. 密钥已过期或额度用尽。1.检查.env文件确保文件名正确且密钥写在OPENAI_API_KEYsk-...格式中。2.确认代码加载在代码开头调用load_dotenv()。3.打印验证print(os.getenv(“OPENAI_API_KEY”)[:10])查看是否加载成功。4.登录OpenAI控制台检查密钥状态和余额。LangChain版本更新导致API不兼容LangChain版本迭代快部分接口或模块路径会变化。1.查阅官方迁移指南通常GitHub Release或文档会有说明。2.锁定版本在requirements.txt中使用langchain0.1.0格式锁定已知可用的版本。3.使用langchain-community许多工具已迁移到此包确保已安装。Agent执行速度很慢1. 网络延迟调用OpenAI API。2. 工具本身慢如搜索。3. Agent规划步骤过多。1.使用更快的模型如gpt-3.5-turbo比gpt-4快很多。2.设置超时为网络请求配置超时时间。3.优化工具对耗时工具进行缓存或寻找替代品。4.简化任务让用户任务更直接或使用更“直接”的Agent类型。记忆Memory消耗大量Token使用ConversationBufferMemory且对话很长。1.切换为摘要记忆ConversationSummaryBufferMemory。2.限制记忆长度设置max_token_limit。3.使用向量存储长期记忆将历史对话嵌入后存入向量数据库如Chroma按需检索。8. 最佳实践与进阶学习路线掌握了基础构建方法后要打造可用于生产环境的可靠Agent还需要遵循以下最佳实践。8.1 Agent开发最佳实践工具设计原子化每个工具应只做一件事并做好。避免创建功能臃肿的“瑞士军刀”式工具。清晰的工具描述是Agent正确调用的前提。系统提示词工程系统提示词是Agent的“人格”和“工作准则”。明确其角色、目标、约束和输出格式。例如“你是一个谨慎的助手在不确定时会询问澄清问题而非猜测。”实施严格的错误处理在工具函数内部、Agent执行循环外部都要有健壮的错误处理try...except并让错误信息能反馈给模型使其有机会自我纠正。控制成本与延迟对于复杂任务设置max_iterations和max_execution_time。考虑使用更便宜的模型进行初步规划或用流式输出改善用户体验。评估与测试像测试软件一样测试你的Agent。构建涵盖成功路径、边缘情况和失败场景的测试用例。评估其准确性、可靠性和成本。安全与权限Agent能调用工具意味着它拥有工具的权限。务必实施最小权限原则。例如一个只能读取数据库的Agent绝不赋予它删除权限。对所有用户输入进行清理和验证。8.2 从入门到精通的进阶学习路线如果你想深入Agent开发领域可以按以下路径系统学习第一阶段巩固基础1-2周核心熟练掌握LangChain/LlamaIndex的Agent、Tools、Memory、Chains核心模块。实践复现本文所有示例并尝试为自己创建5-10个实用小工具如查天气、读文件、发邮件通知。第二阶段项目实战2-4周方向一自动化助手构建一个能处理日常工作的个人助理如自动整理会议纪要、管理待办事项、汇总日报。方向二垂直领域Agent结合特定领域知识如法律、金融、医疗利用RAG检索增强生成技术构建专业问答Agent。技术重点学习向量数据库Chroma, Pinecone, Weaviate掌握RAG全流程。学习如何用LlamaIndex高效构建索引。第三阶段深入原理与优化长期框架源码阅读LangChain Agent执行器的源码理解其规划、行动、观察的循环机制。高级架构学习多智能体Multi-Agent系统了解智能体间的协作与竞争如CrewAI, AutoGen框架。自定义Agent不依赖高级框架直接利用大模型的Function Calling或ReAct格式提示词从零构建更可控的Agent逻辑。评估与监控学习如何量化评估Agent的性能准确性、效率、成本并建立监控告警体系。第四阶段关注前沿开源模型关注Llama、Qwen、DeepSeek等开源模型的Agent能力进展尝试在本地部署。平台与云服务了解Google Vertex AI Agent Builder、Microsoft Copilot Studio等云原生Agent构建平台。研究论文跟进ReAct、Toolformer、TALM、ART等让模型学会使用工具的前沿研究。AI Agent的开发是一场结合了软件工程、提示词工程和应用逻辑的奇妙旅程。它没有银弹最大的挑战往往不在于让Agent“动起来”而在于让它“可靠地、安全地、高效地”完成复杂任务。
![【Bug已解决】[modular] ensure branch-specific input defaults 解决方案](http://pic.xiahunao.cn/yaotu/【Bug已解决】[modular] ensure branch-specific input defaults 解决方案)
