1. 先搞清楚“Agent开发”到底在解决什么问题如果你在2026年看到“Agent开发”这个词感觉它既熟悉又模糊那很正常。它不像学Python装个环境就能跑“Hello World”那么直观。简单来说Agent开发的核心是让一个AI程序Agent能像人一样理解复杂任务、拆解步骤、调用工具、并最终完成目标。它不再是简单的“输入-输出”模型而是一个能自主决策、与环境交互的智能体。为什么现在这么多人关注因为大模型比如各种基于Transformer架构的模型能力上来了但直接用它处理复杂、多步骤的现实任务比如自动分析数据、写报告、订机票酒店依然很笨拙。你需要一个“大脑”大模型来规划和决策再配上“手和脚”各种工具和API去执行。这就是Agent要干的事。所以这个主题适合两类人看一是已经会用Python和基础机器学习想切入AI应用层做点真正能“动起来”的项目的人二是对AI如何落地到具体业务流程如自动化办公、智能客服、数据分析流水线感兴趣的技术人。最关键的价值在于它能帮你把“模型能力”转化为“可执行的、自动化的解决方案”。别被“从入门到精通”“学完即就业”这种话术唬住。Agent开发的学习路径很明确先理解架构思想再掌握核心框架最后通过项目把工具调用、任务规划、记忆、评估这些环节串起来。下面我就按这个顺序结合最常见的工具和踩坑经验拆解一遍。2. 动手前的准备环境、认知与第一个“Hello Agent”在开始写任何代码之前有三件事比选哪个框架更重要。2.1 环境与基础依赖你的机器不需要顶级显卡但需要稳定的网络和合理的内存。大多数Agent框架是Python生态的。Python环境建议使用Python 3.9或3.10。3.11虽然新但某些库的兼容性可能还是坑。用conda或venv创建独立的虚拟环境是必须的。# 使用conda的例子 conda create -n agent_dev python3.10 conda activate agent_dev基础包除了pip你大概率需要这些pip install openai anthropic # 选一个或多个大模型API的SDK pip install langchain langchain-community # 主流Agent框架之一生态丰富 # 或者 pip install llama-index # 另一个流行的框架侧重数据代理 pip install pydantic # 用于定义严谨的数据结构Agent间通信必备 pip install docker # 如果你需要让Agent操作本地或容器环境大模型API密钥这是Agent的“大脑”。准备一个OpenAI、AnthropicClaude或国内合规大模型的API Key。切记将Key存储在环境变量中不要硬编码在代码里。# 在终端中设置临时 export OPENAI_API_KEYyour-key-here # 或者在代码中通过python-dotenv加载2.2 认知准备区分“模型微调”与“Agent开发”这是新手最容易混淆的地方。看到关键词里有SFT监督微调、RLHF人类反馈强化学习可能会觉得Agent开发也要去训练模型。SFT/RLHF这是模型炼制阶段的工作。目的是让一个基础大模型如Transformer变得更听话、更安全、更擅长某种风格。这需要大量的计算资源GPU和数据属于AI基础设施层。Agent开发这是模型应用阶段的工作。假设你已经有了一个能力不错的大模型无论是GPT-4还是开源模型你的工作是设计一套机制让这个模型能有效地利用外部工具计算器、搜索引擎、数据库、业务API来完成工作。你99%的时间是在写Python代码做工程编排而不是训练模型。想清楚这一点能帮你节省大量时间直奔主题。2.3 第一个Agent让AI使用计算器我们不用任何复杂框架先用最裸的方式感受一下Agent的思想。这个Agent的任务是理解用户关于数学计算的自然语言问题然后调用Python的计算功能给出答案。import re import ast # 一个极其简单的工具Python eval计算器注意生产环境必须对输入做严格安全检查 def simple_calculator(expression: str) - str: 计算一个数学表达式字符串。 try: # 这里简单演示实际务必禁用危险函数或使用更安全的库如numexpr # 仅允许数字和基本运算符 if not re.match(r^[\d\s\\-\*\/\(\)\.]$, expression): return 错误表达式包含不安全字符。 result eval(expression) return str(result) except Exception as e: return f计算错误{e} # 一个模拟的“大模型”决策函数 def llm_decision(user_query: str) - dict: 模拟大模型的判断是否需要计算需要的话提取表达式。 # 这里用规则模拟真实场景是调用大模型API if 算一下 in user_query or 等于多少 in user_query or in user_query or * in user_query: # 简单提取数字和运算符实际应用需要用更复杂的LLM调用或正则 match re.search(r(\d[\s\\-\*\/]\d), user_query.replace( , )) if match: expression match.group(1) return {needs_calculator: True, expression: expression} return {needs_calculator: False, reason: 问题无需计算} # Agent的执行流程 def my_first_agent(user_query: str): print(f用户问题: {user_query}) # 步骤1: 规划Planning- 判断任务类型 decision llm_decision(user_query) if decision[needs_calculator]: print(fAgent决策: 需要调用计算器。表达式: {decision[expression]}) # 步骤2: 执行Execution- 调用工具 result simple_calculator(decision[expression]) # 步骤3: 响应Response response f根据计算{decision[expression]} 的结果是 {result}。 else: response f这是一个非计算问题我的当前能力无法处理。原因: {decision[reason]} print(fAgent回复: {response}) return response # 测试 if __name__ __main__: my_first_agent(请帮我算一下 128 乘以 256 等于多少) my_first_agent(今天的天气怎么样)运行这个代码你会看到用户问题: 请帮我算一下 128 乘以 256 等于多少 Agent决策: 需要调用计算器。表达式: 128*256 Agent回复: 根据计算128*256 的结果是 32768。 用户问题: 今天的天气怎么样 Agent回复: 这是一个非计算问题我的当前能力无法处理。原因: 问题无需计算这就是一个最原始的Agent感知输入问题- 规划判断用不用工具- 执行调用计算器- 响应输出结果。虽然简陋但它包含了所有核心概念。3. 使用成熟框架LangChain Agent实战自己从头造轮子学习可以但生产环境要用成熟的框架。这里以LangChain为例它是目前生态最丰富的Agent框架之一。3.1 为什么选择LangChain工具集成全内置和社区提供了大量现成工具Google搜索、Wikipedia、Shell、各种API。编排能力强清晰定义了Agent、Tool、Memory、Chain等概念方便组装复杂流程。多模型支持可以轻松切换OpenAI、Anthropic、开源模型通过Ollama等作为大脑。社区活跃遇到问题容易找到解决方案和案例。3.2 构建一个能联网搜索的Agent假设你想让Agent回答关于最新事件的问题它需要能联网搜索。安装额外依赖pip install langchain-openai # LangChain对OpenAI的官方集成 pip install duckduckgo-search # 一个免费的搜索工具编写代码import os from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain.prompts import PromptTemplate from langchain_community.tools import DuckDuckGoSearchRun # 0. 设置API Key (确保已设置环境变量 OPENAI_API_KEY) # 1. 定义工具 search_tool DuckDuckGoSearchRun(nameduckduckgo_search, description用于搜索互联网上的最新信息。) # 2. 初始化大模型Agent的大脑 llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 使用小模型降低成本temperature0让输出更确定 # 3. 定义提示词模板告诉Agent如何思考 prompt_template 你是一个有帮助的AI助手。你可以使用工具来获取信息。 请严格按照以下格式回答 问题{input} 思考我需要一步步思考。首先我需要理解问题。{agent_scratchpad} prompt PromptTemplate.from_template(prompt_template) # 4. 创建Agent tools [search_tool] agent create_react_agent(llmllm, toolstools, promptprompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 运行Agent if __name__ __main__: query 2026年巴黎奥运会的吉祥物是什么 result agent_executor.invoke({input: query}) print(\n--- 最终答案 ---) print(result[output])运行与观察 设置好OPENAI_API_KEY后运行你会看到控制台输出类似以下内容verboseTrue会打印思考过程 Entering new AgentExecutor chain... 思考我需要一步步思考。首先我需要理解问题。用户想知道2026年巴黎奥运会的吉祥物。但2024年巴黎奥运会已经举办过了2026年没有巴黎奥运会。可能是用户记错了年份或者指的是2024年巴黎奥运会的吉祥物。我应该搜索确认一下。 行动duckduckgo_search 行动输入2024年巴黎奥运会吉祥物 观察[搜索返回的结果例如“弗里吉”] 思考根据搜索结果2024年巴黎奥运会的吉祥物是“弗里吉”The Phryge。这是一个拟人化的弗里吉亚帽形象。所以用户可能指的是这个。我可以据此回答。 最终答案2024年巴黎奥运会的吉祥物是“弗里吉”The Phryge。它是一个拟人化的红色弗里吉亚帽形象。请注意2026年并没有计划举办巴黎奥运会。 Finished chain. --- 最终答案 --- 2024年巴黎奥运会的吉祥物是“弗里吉”The Phryge。它是一个拟人化的红色弗里吉亚帽形象。请注意2026年并没有计划举办巴黎奥运会。这个过程中Agent自动完成了理解歧义问题 - 决定搜索 - 解析搜索结果 - 整合信息给出准确回答。3.3 关键参数与配置解析temperature控制模型输出的随机性。0表示最确定适合需要准确性的任务如工具调用、数据提取0.7-1.0更有创造性适合写作。Agent规划阶段建议设为0或较低值如0.2避免它“胡思乱想”调用错误工具。verboseTrue调试神器。一定要打开它能完整展示Agent的“思考”Thought、“行动”Action和“观察”Observation链。出问题时这是第一排查点。handle_parsing_errorsTrue当Agent输出格式不符合框架预期时比如没按要求的Action:格式输出这个参数能防止程序直接崩溃而是尝试让模型重试或给出友好错误。生产环境建议实现更精细的错误处理。工具描述description这是最重要的提示工程部分之一。模型根据描述决定是否以及如何调用工具。描述要清晰、具体说明工具的用途、输入格式和输出什么。糟糕的描述会导致工具不被调用或被误用。4. 进阶构建具备记忆与多步骤规划的复杂Agent基础Agent只能处理单轮对话。一个实用的Agent需要记忆记住对话历史和复杂任务分解能力。4.1 为Agent添加记忆记忆让Agent能进行连贯的多轮对话。LangChain提供了简单的对话缓存。from langchain.memory import ConversationBufferMemory # 创建带记忆的执行器 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) agent_executor_with_memory AgentExecutor( agentagent, # 使用之前创建的agent toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue ) # 进行多轮对话 print(第一轮) result1 agent_executor_with_memory.invoke({input: 我叫小明。}) print(result1[output]) # 可能回复“你好小明” print(\n第二轮) result2 agent_executor_with_memory.invoke({input: 我的名字是什么}) # Agent应该记得 print(result2[output]) # 应该能回答“你叫小明。”记忆的实现方式有很多ConversationBufferMemory只是把历史对话全存下来。对于长对话可以考虑ConversationSummaryMemory总结历史或ConversationEntityMemory记住实体信息。4.2 处理复杂任务自主规划与执行有些任务不是一步就能完成的。例如“查一下北京今天天气如果下雨就推荐一个室内的活动如果晴天就推荐一个户外公园。”这需要Agent能自主规划Plan子任务。我们可以使用更强大的Agent类型如Plan-and-Execute架构或者利用LangChain的LLMChain进行显式规划。from langchain.chains import LLMChain from langchain_core.prompts import ChatPromptTemplate # 假设我们有两个工具get_weather 和 recommend_activity # 这里用函数模拟 def get_weather(city: str) - str: # 模拟API调用 weather_data {北京: 晴天, 上海: 雨天} return weather_data.get(city, 未知) def recommend_activity(weather: str, category: str) - str: activities { 雨天: {室内: 参观博物馆, 户外: 不推荐户外活动}, 晴天: {室内: 逛商场, 户外: 去奥林匹克森林公园} } return activities.get(weather, {}).get(category, 暂无推荐) # 1. 规划链让大模型拆解任务 planning_prompt ChatPromptTemplate.from_messages([ (system, 你是一个任务规划师。请将用户的复杂请求拆解成一个清晰的、可顺序执行的步骤列表。每个步骤应该是一个简单的动作。), (human, 用户请求{request}) ]) planning_llm ChatOpenAI(modelgpt-4o-mini, temperature0) planning_chain LLMChain(llmplanning_llm, promptplanning_prompt) # 2. 执行引擎根据规划步骤调用工具 def execute_plan(plan_steps: list, initial_context: dict) - dict: context initial_context.copy() for step in plan_steps: if 获取天气 in step: city context.get(city, 北京) # 可以从上下文或步骤解析中获取城市 context[weather] get_weather(city) elif 推荐活动 in step: weather context.get(weather) category 户外 if weather 晴天 else 室内 context[recommendation] recommend_activity(weather, category) # ... 可以处理更多步骤类型 return context # 3. 整合运行 def complex_agent(request: str): print(f原始请求: {request}) # 步骤A规划 plan_result planning_chain.invoke({request: request}) # 假设大模型返回的文本是“1. 获取北京今天的天气。2. 根据天气情况推荐活动。” # 这里需要解析文本为步骤列表为简化我们手动定义 steps [获取北京天气, 根据天气推荐活动] print(f规划步骤: {steps}) # 步骤B执行 context {city: 北京} final_context execute_plan(steps, context) # 步骤C生成最终回答 answer f今天北京天气是{final_context.get(weather)}。我们推荐您{final_context.get(recommendation)}。 print(f最终回答: {answer}) return answer if __name__ __main__: complex_agent(查一下北京今天天气然后推荐一个适合的活动。)这个例子展示了规划-执行的分离。在实际框架中如LangChain的PlanAndExecuteAgentExecutor这部分已经被封装好了但理解其原理至关重要。5. 从Demo到生产你必须考虑的工程问题能跑通Demo只是第一步。要让Agent可靠地运行起来你需要面对一系列工程挑战。5.1 工具调用的可靠性工具描述至关重要大模型根据描述调用工具。描述要像API文档一样精确输入是什么类型字符串、数字、列表输出什么会有什么异常输入验证与清洗不要完全信任大模型传给工具的参数。在工具函数内部一定要对输入进行类型检查、范围校验和安全性过滤特别是调用Shell或数据库时。错误处理与重试工具调用可能失败网络超时、API限流。在执行器中设置max_iterations最大迭代次数和max_execution_time超时时间。对于可重试的错误如网络错误实现指数退避重试逻辑。结构化输出让工具返回结构化的数据如Pydantic模型而不是纯文本便于后续步骤解析。LangChain的StructuredTool就支持这一点。5.2 成本与延迟控制选择模型gpt-4聪明但贵且慢gpt-4o-mini或claude-3-haiku性价比高很多。用小型、快速模型处理简单规划只在复杂推理时用大模型。减少Token消耗压缩历史使用ConversationSummaryMemory或只保留最近N轮对话。精简提示词去除不必要的系统提示。缓存结果对相同或相似的查询缓存工具调用结果或最终答案。设置超时与熔断给每个工具调用和整个Agent执行设置超时。如果某个工具连续失败暂时将其熔断避免拖垮整个系统。5.3 评估与监控你怎么知道Agent工作得好不好不能只靠人工看。定义评估指标任务完成率用户意图是否被正确满足工具调用准确率是否调用了正确工具参数是否正确步骤效率是否用了最少的步骤完成任务用户满意度通过反馈机制收集。实现日志与追踪记录每一次Agent运行的完整链条Thought, Action, Observation。使用像LangSmithLangChain官方这样的平台可以可视化追踪、调试和评估Agent运行情况这是提升效果的关键。A/B测试对比不同提示词、不同模型、不同工具组合下的Agent表现。5.4 安全与合规这是高压线。权限隔离Agent能调用的工具如数据库、内部API必须遵循最小权限原则。不要给Agent一个拥有全部权限的万能钥匙。输入输出审查对用户输入和Agent输出进行内容安全过滤防止生成有害、偏见或不合规的内容。可控性必须有一个“紧急停止”机制能够中断正在运行的Agent。对于长期运行的Agent要有状态检查点可以安全地暂停和恢复。数据隐私确保通过Agent处理的数据尤其是用户输入和工具返回结果符合数据保护法规。避免在提示词中泄露敏感信息。6. 常见问题排查清单从现象到根因当你的Agent表现不如预期时按这个顺序排查。6.1 Agent完全不调用工具检查工具描述描述是否清晰是否准确说明了工具的用途和输入格式用verboseTrue看模型的“思考”它是否理解了问题但认为不需要工具检查提示词系统提示词是否鼓励或要求Agent使用工具有些默认提示词可能过于保守。测试模型能力直接用同一个模型用Chat界面问它“要解决这个问题你需要用什么工具”看它能否正确选择。简化问题用一个极简的、明显需要工具的问题测试如“123*456等于多少”排除任务复杂度干扰。6.2 工具调用错误或参数不对查看详细日志verboseTrue会输出Action和Action Input。检查Action Input是不是你期望的格式通常是JSON字符串。验证工具函数单独写一个测试用你认为正确的参数直接调用工具函数看是否能正常工作。使用StructuredTool将工具的参数定义为Pydantic模型LangChain会帮模型更好地生成结构化参数。提供示例Few-Shot在提示词中给出一两个工具调用的正确示例引导模型学习格式。6.3 Agent陷入循环或步骤过多设置max_iterations这是防止死循环的第一道防线。通常设置10-20步。检查工具输出工具是否返回了清晰、有用的结果如果工具返回“未找到”或错误信息模型可能会试图换种方式重试。优化规划能力对于复杂任务考虑使用专门的“规划器”模型先制定步骤大纲再让“执行器”模型按步执行。Plan-and-Execute架构就是干这个的。引入“放弃”工具给Agent一个“我无法完成此任务”的工具选项当它尝试多次失败后可以优雅退出。6.4 速度慢或成本高分析verbose日志看时间花在哪里了是模型响应慢还是某个工具调用慢换用小模型对于工具选择、参数提取等简单任务gpt-3.5-turbo或更小的开源模型可能就足够了。实现缓存对频繁出现的相同或相似查询缓存最终答案或工具调用结果。批量处理如果有很多独立任务可以考虑异步或批量调用模型API如果API支持。7. 学习路径与资源建议最后给一个务实的学习路线图而不是泛泛而谈的“从入门到精通”。第一周建立直觉目标理解Agent是什么不是什么。跑通2-3个最简单的Demo如计算器、搜索。动作读完本文并亲手运行文中的代码。确保Python环境、API密钥没问题。资源官方文档OpenAI, Anthropic的Chat Completions部分了解如何与模型对话。第二到三周掌握一个主流框架目标熟练使用一个框架如LangChain构建多工具Agent。动作学习LangChain的Agent、Tool、Memory、Chain核心概念。实现一个能使用3种不同工具搜索、计算、查字典的Agent。为Agent添加对话记忆。资源LangChain官方教程和API文档。重点看Agents和Tools模块。第四到六周项目实战与深入目标完成一个端到端的小项目比如“个人旅行规划助手”或“技术文档问答机器人”。动作设计项目流程用户输入 - Agent规划 - 调用多个工具天气API、地图API、知识库 - 整合输出。处理工具调用的错误、重试和超时。尝试不同的Agent类型ReAct, Plan-and-Execute。学习使用LangSmith进行调试和追踪。资源GitHub上寻找类似的开源项目参考阅读其代码结构。长期关注架构与优化目标设计可维护、可扩展、可靠的Agent系统。关注点架构模式单Agent vs. 多Agent协作CrewAI, AutoGen。评估体系如何自动化评估Agent表现生产部署如何将Agent封装成API服务如何管理配置和密钥成本优化模型路由、缓存策略、Token压缩。最重要的建议是不要一开始就追求大而全的“终极架构”。从一个能解决具体微小问题的Agent开始让它稳定可靠地运行起来然后再逐步增加复杂性。在这个过程中你会遇到所有典型问题而解决这些问题的经验才是教程无法教给你的、最值钱的部分。 AI Agent开发实战指南：从原理到工程落地
1. 先搞清楚“Agent开发”到底在解决什么问题如果你在2026年看到“Agent开发”这个词感觉它既熟悉又模糊那很正常。它不像学Python装个环境就能跑“Hello World”那么直观。简单来说Agent开发的核心是让一个AI程序Agent能像人一样理解复杂任务、拆解步骤、调用工具、并最终完成目标。它不再是简单的“输入-输出”模型而是一个能自主决策、与环境交互的智能体。为什么现在这么多人关注因为大模型比如各种基于Transformer架构的模型能力上来了但直接用它处理复杂、多步骤的现实任务比如自动分析数据、写报告、订机票酒店依然很笨拙。你需要一个“大脑”大模型来规划和决策再配上“手和脚”各种工具和API去执行。这就是Agent要干的事。所以这个主题适合两类人看一是已经会用Python和基础机器学习想切入AI应用层做点真正能“动起来”的项目的人二是对AI如何落地到具体业务流程如自动化办公、智能客服、数据分析流水线感兴趣的技术人。最关键的价值在于它能帮你把“模型能力”转化为“可执行的、自动化的解决方案”。别被“从入门到精通”“学完即就业”这种话术唬住。Agent开发的学习路径很明确先理解架构思想再掌握核心框架最后通过项目把工具调用、任务规划、记忆、评估这些环节串起来。下面我就按这个顺序结合最常见的工具和踩坑经验拆解一遍。2. 动手前的准备环境、认知与第一个“Hello Agent”在开始写任何代码之前有三件事比选哪个框架更重要。2.1 环境与基础依赖你的机器不需要顶级显卡但需要稳定的网络和合理的内存。大多数Agent框架是Python生态的。Python环境建议使用Python 3.9或3.10。3.11虽然新但某些库的兼容性可能还是坑。用conda或venv创建独立的虚拟环境是必须的。# 使用conda的例子 conda create -n agent_dev python3.10 conda activate agent_dev基础包除了pip你大概率需要这些pip install openai anthropic # 选一个或多个大模型API的SDK pip install langchain langchain-community # 主流Agent框架之一生态丰富 # 或者 pip install llama-index # 另一个流行的框架侧重数据代理 pip install pydantic # 用于定义严谨的数据结构Agent间通信必备 pip install docker # 如果你需要让Agent操作本地或容器环境大模型API密钥这是Agent的“大脑”。准备一个OpenAI、AnthropicClaude或国内合规大模型的API Key。切记将Key存储在环境变量中不要硬编码在代码里。# 在终端中设置临时 export OPENAI_API_KEYyour-key-here # 或者在代码中通过python-dotenv加载2.2 认知准备区分“模型微调”与“Agent开发”这是新手最容易混淆的地方。看到关键词里有SFT监督微调、RLHF人类反馈强化学习可能会觉得Agent开发也要去训练模型。SFT/RLHF这是模型炼制阶段的工作。目的是让一个基础大模型如Transformer变得更听话、更安全、更擅长某种风格。这需要大量的计算资源GPU和数据属于AI基础设施层。Agent开发这是模型应用阶段的工作。假设你已经有了一个能力不错的大模型无论是GPT-4还是开源模型你的工作是设计一套机制让这个模型能有效地利用外部工具计算器、搜索引擎、数据库、业务API来完成工作。你99%的时间是在写Python代码做工程编排而不是训练模型。想清楚这一点能帮你节省大量时间直奔主题。2.3 第一个Agent让AI使用计算器我们不用任何复杂框架先用最裸的方式感受一下Agent的思想。这个Agent的任务是理解用户关于数学计算的自然语言问题然后调用Python的计算功能给出答案。import re import ast # 一个极其简单的工具Python eval计算器注意生产环境必须对输入做严格安全检查 def simple_calculator(expression: str) - str: 计算一个数学表达式字符串。 try: # 这里简单演示实际务必禁用危险函数或使用更安全的库如numexpr # 仅允许数字和基本运算符 if not re.match(r^[\d\s\\-\*\/\(\)\.]$, expression): return 错误表达式包含不安全字符。 result eval(expression) return str(result) except Exception as e: return f计算错误{e} # 一个模拟的“大模型”决策函数 def llm_decision(user_query: str) - dict: 模拟大模型的判断是否需要计算需要的话提取表达式。 # 这里用规则模拟真实场景是调用大模型API if 算一下 in user_query or 等于多少 in user_query or in user_query or * in user_query: # 简单提取数字和运算符实际应用需要用更复杂的LLM调用或正则 match re.search(r(\d[\s\\-\*\/]\d), user_query.replace( , )) if match: expression match.group(1) return {needs_calculator: True, expression: expression} return {needs_calculator: False, reason: 问题无需计算} # Agent的执行流程 def my_first_agent(user_query: str): print(f用户问题: {user_query}) # 步骤1: 规划Planning- 判断任务类型 decision llm_decision(user_query) if decision[needs_calculator]: print(fAgent决策: 需要调用计算器。表达式: {decision[expression]}) # 步骤2: 执行Execution- 调用工具 result simple_calculator(decision[expression]) # 步骤3: 响应Response response f根据计算{decision[expression]} 的结果是 {result}。 else: response f这是一个非计算问题我的当前能力无法处理。原因: {decision[reason]} print(fAgent回复: {response}) return response # 测试 if __name__ __main__: my_first_agent(请帮我算一下 128 乘以 256 等于多少) my_first_agent(今天的天气怎么样)运行这个代码你会看到用户问题: 请帮我算一下 128 乘以 256 等于多少 Agent决策: 需要调用计算器。表达式: 128*256 Agent回复: 根据计算128*256 的结果是 32768。 用户问题: 今天的天气怎么样 Agent回复: 这是一个非计算问题我的当前能力无法处理。原因: 问题无需计算这就是一个最原始的Agent感知输入问题- 规划判断用不用工具- 执行调用计算器- 响应输出结果。虽然简陋但它包含了所有核心概念。3. 使用成熟框架LangChain Agent实战自己从头造轮子学习可以但生产环境要用成熟的框架。这里以LangChain为例它是目前生态最丰富的Agent框架之一。3.1 为什么选择LangChain工具集成全内置和社区提供了大量现成工具Google搜索、Wikipedia、Shell、各种API。编排能力强清晰定义了Agent、Tool、Memory、Chain等概念方便组装复杂流程。多模型支持可以轻松切换OpenAI、Anthropic、开源模型通过Ollama等作为大脑。社区活跃遇到问题容易找到解决方案和案例。3.2 构建一个能联网搜索的Agent假设你想让Agent回答关于最新事件的问题它需要能联网搜索。安装额外依赖pip install langchain-openai # LangChain对OpenAI的官方集成 pip install duckduckgo-search # 一个免费的搜索工具编写代码import os from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain.prompts import PromptTemplate from langchain_community.tools import DuckDuckGoSearchRun # 0. 设置API Key (确保已设置环境变量 OPENAI_API_KEY) # 1. 定义工具 search_tool DuckDuckGoSearchRun(nameduckduckgo_search, description用于搜索互联网上的最新信息。) # 2. 初始化大模型Agent的大脑 llm ChatOpenAI(modelgpt-4o-mini, temperature0) # 使用小模型降低成本temperature0让输出更确定 # 3. 定义提示词模板告诉Agent如何思考 prompt_template 你是一个有帮助的AI助手。你可以使用工具来获取信息。 请严格按照以下格式回答 问题{input} 思考我需要一步步思考。首先我需要理解问题。{agent_scratchpad} prompt PromptTemplate.from_template(prompt_template) # 4. 创建Agent tools [search_tool] agent create_react_agent(llmllm, toolstools, promptprompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 运行Agent if __name__ __main__: query 2026年巴黎奥运会的吉祥物是什么 result agent_executor.invoke({input: query}) print(\n--- 最终答案 ---) print(result[output])运行与观察 设置好OPENAI_API_KEY后运行你会看到控制台输出类似以下内容verboseTrue会打印思考过程 Entering new AgentExecutor chain... 思考我需要一步步思考。首先我需要理解问题。用户想知道2026年巴黎奥运会的吉祥物。但2024年巴黎奥运会已经举办过了2026年没有巴黎奥运会。可能是用户记错了年份或者指的是2024年巴黎奥运会的吉祥物。我应该搜索确认一下。 行动duckduckgo_search 行动输入2024年巴黎奥运会吉祥物 观察[搜索返回的结果例如“弗里吉”] 思考根据搜索结果2024年巴黎奥运会的吉祥物是“弗里吉”The Phryge。这是一个拟人化的弗里吉亚帽形象。所以用户可能指的是这个。我可以据此回答。 最终答案2024年巴黎奥运会的吉祥物是“弗里吉”The Phryge。它是一个拟人化的红色弗里吉亚帽形象。请注意2026年并没有计划举办巴黎奥运会。 Finished chain. --- 最终答案 --- 2024年巴黎奥运会的吉祥物是“弗里吉”The Phryge。它是一个拟人化的红色弗里吉亚帽形象。请注意2026年并没有计划举办巴黎奥运会。这个过程中Agent自动完成了理解歧义问题 - 决定搜索 - 解析搜索结果 - 整合信息给出准确回答。3.3 关键参数与配置解析temperature控制模型输出的随机性。0表示最确定适合需要准确性的任务如工具调用、数据提取0.7-1.0更有创造性适合写作。Agent规划阶段建议设为0或较低值如0.2避免它“胡思乱想”调用错误工具。verboseTrue调试神器。一定要打开它能完整展示Agent的“思考”Thought、“行动”Action和“观察”Observation链。出问题时这是第一排查点。handle_parsing_errorsTrue当Agent输出格式不符合框架预期时比如没按要求的Action:格式输出这个参数能防止程序直接崩溃而是尝试让模型重试或给出友好错误。生产环境建议实现更精细的错误处理。工具描述description这是最重要的提示工程部分之一。模型根据描述决定是否以及如何调用工具。描述要清晰、具体说明工具的用途、输入格式和输出什么。糟糕的描述会导致工具不被调用或被误用。4. 进阶构建具备记忆与多步骤规划的复杂Agent基础Agent只能处理单轮对话。一个实用的Agent需要记忆记住对话历史和复杂任务分解能力。4.1 为Agent添加记忆记忆让Agent能进行连贯的多轮对话。LangChain提供了简单的对话缓存。from langchain.memory import ConversationBufferMemory # 创建带记忆的执行器 memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) agent_executor_with_memory AgentExecutor( agentagent, # 使用之前创建的agent toolstools, memorymemory, verboseTrue, handle_parsing_errorsTrue ) # 进行多轮对话 print(第一轮) result1 agent_executor_with_memory.invoke({input: 我叫小明。}) print(result1[output]) # 可能回复“你好小明” print(\n第二轮) result2 agent_executor_with_memory.invoke({input: 我的名字是什么}) # Agent应该记得 print(result2[output]) # 应该能回答“你叫小明。”记忆的实现方式有很多ConversationBufferMemory只是把历史对话全存下来。对于长对话可以考虑ConversationSummaryMemory总结历史或ConversationEntityMemory记住实体信息。4.2 处理复杂任务自主规划与执行有些任务不是一步就能完成的。例如“查一下北京今天天气如果下雨就推荐一个室内的活动如果晴天就推荐一个户外公园。”这需要Agent能自主规划Plan子任务。我们可以使用更强大的Agent类型如Plan-and-Execute架构或者利用LangChain的LLMChain进行显式规划。from langchain.chains import LLMChain from langchain_core.prompts import ChatPromptTemplate # 假设我们有两个工具get_weather 和 recommend_activity # 这里用函数模拟 def get_weather(city: str) - str: # 模拟API调用 weather_data {北京: 晴天, 上海: 雨天} return weather_data.get(city, 未知) def recommend_activity(weather: str, category: str) - str: activities { 雨天: {室内: 参观博物馆, 户外: 不推荐户外活动}, 晴天: {室内: 逛商场, 户外: 去奥林匹克森林公园} } return activities.get(weather, {}).get(category, 暂无推荐) # 1. 规划链让大模型拆解任务 planning_prompt ChatPromptTemplate.from_messages([ (system, 你是一个任务规划师。请将用户的复杂请求拆解成一个清晰的、可顺序执行的步骤列表。每个步骤应该是一个简单的动作。), (human, 用户请求{request}) ]) planning_llm ChatOpenAI(modelgpt-4o-mini, temperature0) planning_chain LLMChain(llmplanning_llm, promptplanning_prompt) # 2. 执行引擎根据规划步骤调用工具 def execute_plan(plan_steps: list, initial_context: dict) - dict: context initial_context.copy() for step in plan_steps: if 获取天气 in step: city context.get(city, 北京) # 可以从上下文或步骤解析中获取城市 context[weather] get_weather(city) elif 推荐活动 in step: weather context.get(weather) category 户外 if weather 晴天 else 室内 context[recommendation] recommend_activity(weather, category) # ... 可以处理更多步骤类型 return context # 3. 整合运行 def complex_agent(request: str): print(f原始请求: {request}) # 步骤A规划 plan_result planning_chain.invoke({request: request}) # 假设大模型返回的文本是“1. 获取北京今天的天气。2. 根据天气情况推荐活动。” # 这里需要解析文本为步骤列表为简化我们手动定义 steps [获取北京天气, 根据天气推荐活动] print(f规划步骤: {steps}) # 步骤B执行 context {city: 北京} final_context execute_plan(steps, context) # 步骤C生成最终回答 answer f今天北京天气是{final_context.get(weather)}。我们推荐您{final_context.get(recommendation)}。 print(f最终回答: {answer}) return answer if __name__ __main__: complex_agent(查一下北京今天天气然后推荐一个适合的活动。)这个例子展示了规划-执行的分离。在实际框架中如LangChain的PlanAndExecuteAgentExecutor这部分已经被封装好了但理解其原理至关重要。5. 从Demo到生产你必须考虑的工程问题能跑通Demo只是第一步。要让Agent可靠地运行起来你需要面对一系列工程挑战。5.1 工具调用的可靠性工具描述至关重要大模型根据描述调用工具。描述要像API文档一样精确输入是什么类型字符串、数字、列表输出什么会有什么异常输入验证与清洗不要完全信任大模型传给工具的参数。在工具函数内部一定要对输入进行类型检查、范围校验和安全性过滤特别是调用Shell或数据库时。错误处理与重试工具调用可能失败网络超时、API限流。在执行器中设置max_iterations最大迭代次数和max_execution_time超时时间。对于可重试的错误如网络错误实现指数退避重试逻辑。结构化输出让工具返回结构化的数据如Pydantic模型而不是纯文本便于后续步骤解析。LangChain的StructuredTool就支持这一点。5.2 成本与延迟控制选择模型gpt-4聪明但贵且慢gpt-4o-mini或claude-3-haiku性价比高很多。用小型、快速模型处理简单规划只在复杂推理时用大模型。减少Token消耗压缩历史使用ConversationSummaryMemory或只保留最近N轮对话。精简提示词去除不必要的系统提示。缓存结果对相同或相似的查询缓存工具调用结果或最终答案。设置超时与熔断给每个工具调用和整个Agent执行设置超时。如果某个工具连续失败暂时将其熔断避免拖垮整个系统。5.3 评估与监控你怎么知道Agent工作得好不好不能只靠人工看。定义评估指标任务完成率用户意图是否被正确满足工具调用准确率是否调用了正确工具参数是否正确步骤效率是否用了最少的步骤完成任务用户满意度通过反馈机制收集。实现日志与追踪记录每一次Agent运行的完整链条Thought, Action, Observation。使用像LangSmithLangChain官方这样的平台可以可视化追踪、调试和评估Agent运行情况这是提升效果的关键。A/B测试对比不同提示词、不同模型、不同工具组合下的Agent表现。5.4 安全与合规这是高压线。权限隔离Agent能调用的工具如数据库、内部API必须遵循最小权限原则。不要给Agent一个拥有全部权限的万能钥匙。输入输出审查对用户输入和Agent输出进行内容安全过滤防止生成有害、偏见或不合规的内容。可控性必须有一个“紧急停止”机制能够中断正在运行的Agent。对于长期运行的Agent要有状态检查点可以安全地暂停和恢复。数据隐私确保通过Agent处理的数据尤其是用户输入和工具返回结果符合数据保护法规。避免在提示词中泄露敏感信息。6. 常见问题排查清单从现象到根因当你的Agent表现不如预期时按这个顺序排查。6.1 Agent完全不调用工具检查工具描述描述是否清晰是否准确说明了工具的用途和输入格式用verboseTrue看模型的“思考”它是否理解了问题但认为不需要工具检查提示词系统提示词是否鼓励或要求Agent使用工具有些默认提示词可能过于保守。测试模型能力直接用同一个模型用Chat界面问它“要解决这个问题你需要用什么工具”看它能否正确选择。简化问题用一个极简的、明显需要工具的问题测试如“123*456等于多少”排除任务复杂度干扰。6.2 工具调用错误或参数不对查看详细日志verboseTrue会输出Action和Action Input。检查Action Input是不是你期望的格式通常是JSON字符串。验证工具函数单独写一个测试用你认为正确的参数直接调用工具函数看是否能正常工作。使用StructuredTool将工具的参数定义为Pydantic模型LangChain会帮模型更好地生成结构化参数。提供示例Few-Shot在提示词中给出一两个工具调用的正确示例引导模型学习格式。6.3 Agent陷入循环或步骤过多设置max_iterations这是防止死循环的第一道防线。通常设置10-20步。检查工具输出工具是否返回了清晰、有用的结果如果工具返回“未找到”或错误信息模型可能会试图换种方式重试。优化规划能力对于复杂任务考虑使用专门的“规划器”模型先制定步骤大纲再让“执行器”模型按步执行。Plan-and-Execute架构就是干这个的。引入“放弃”工具给Agent一个“我无法完成此任务”的工具选项当它尝试多次失败后可以优雅退出。6.4 速度慢或成本高分析verbose日志看时间花在哪里了是模型响应慢还是某个工具调用慢换用小模型对于工具选择、参数提取等简单任务gpt-3.5-turbo或更小的开源模型可能就足够了。实现缓存对频繁出现的相同或相似查询缓存最终答案或工具调用结果。批量处理如果有很多独立任务可以考虑异步或批量调用模型API如果API支持。7. 学习路径与资源建议最后给一个务实的学习路线图而不是泛泛而谈的“从入门到精通”。第一周建立直觉目标理解Agent是什么不是什么。跑通2-3个最简单的Demo如计算器、搜索。动作读完本文并亲手运行文中的代码。确保Python环境、API密钥没问题。资源官方文档OpenAI, Anthropic的Chat Completions部分了解如何与模型对话。第二到三周掌握一个主流框架目标熟练使用一个框架如LangChain构建多工具Agent。动作学习LangChain的Agent、Tool、Memory、Chain核心概念。实现一个能使用3种不同工具搜索、计算、查字典的Agent。为Agent添加对话记忆。资源LangChain官方教程和API文档。重点看Agents和Tools模块。第四到六周项目实战与深入目标完成一个端到端的小项目比如“个人旅行规划助手”或“技术文档问答机器人”。动作设计项目流程用户输入 - Agent规划 - 调用多个工具天气API、地图API、知识库 - 整合输出。处理工具调用的错误、重试和超时。尝试不同的Agent类型ReAct, Plan-and-Execute。学习使用LangSmith进行调试和追踪。资源GitHub上寻找类似的开源项目参考阅读其代码结构。长期关注架构与优化目标设计可维护、可扩展、可靠的Agent系统。关注点架构模式单Agent vs. 多Agent协作CrewAI, AutoGen。评估体系如何自动化评估Agent表现生产部署如何将Agent封装成API服务如何管理配置和密钥成本优化模型路由、缓存策略、Token压缩。最重要的建议是不要一开始就追求大而全的“终极架构”。从一个能解决具体微小问题的Agent开始让它稳定可靠地运行起来然后再逐步增加复杂性。在这个过程中你会遇到所有典型问题而解决这些问题的经验才是教程无法教给你的、最值钱的部分。