如果你正在学习AI Agent开发可能会遇到这样的困境看了很多教程概念都懂但一上手就不知道从何写起或者跟着某个框架跑通了Demo但稍微改点需求就报错完全不知道如何调试和优化。更让人焦虑的是招聘要求上写着“熟悉Agent开发”但具体要掌握哪些技能、做到什么程度才算“熟悉”却模糊不清。这篇文章要解决的正是这个从“知道”到“做到”的核心断层。我们不会空谈Agent的宏大未来而是聚焦于一个非常具体的目标通过一套精心设计的、总耗时约2.5小时的实战练习让你系统性地掌握Agent开发的核心能力闭环。这2.5小时不是漫无目的的摸索而是针对“记忆”、“工具使用”、“规划与执行”、“多智能体协作”这四大Agent核心支柱的刻意训练。读完本文并完成练习你将获得一个清晰的自我评估标准你的Agent到底“牛”在哪里是能记住复杂的上下文还是能娴熟地调用各种API是能拆解复杂任务还是能与其他Agent协同工作更重要的是你将拥有一套可复现、可扩展的代码实践以及面对真实项目需求时的解决思路。1. 重新定义“牛”的Agent超越跑通Demo的四个能力维度在开始练习之前我们必须先统一认知一个“牛”的Agent绝不仅仅是能回答几个问题。它应该像一个经验丰富的数字员工具备以下四种核心工作能力记忆与上下文管理这是Agent的“工作经验”。它能否记住对话历史、用户偏好、以及任务执行过程中的中间状态能否从长上下文中精准提取关键信息而不被无关内容干扰工具使用与技能扩展这是Agent的“双手”。它能否根据任务需求自主选择并正确调用外部工具如搜索API、计算器、数据库、文件系统能否处理工具调用失败、结果异常等情况规划、分解与执行这是Agent的“大脑”。面对一个复杂目标如“为我策划一次旅行”它能否将其分解为“查询天气”、“查找机票”、“推荐景点”等一系列可执行的子任务能否根据子任务执行结果动态调整计划多智能体协作这是Agent的“团队协作能力”。在复杂场景下能否让多个各司其职的Agent如一个负责创意一个负责审核一个负责执行通过通信和协作共同完成一个单Agent难以胜任的任务市面上很多教程只带你实现了第一点或第二点但这就像只学会了走路还远不能奔跑。我们设计的2.5小时练习正是为了让你在这四个维度上都得到扎实的训练从而构建出一个真正有能力处理现实世界复杂问题的智能体。2. 环境准备选择你的“训练场”工欲善其事必先利其器。为了避免环境问题消耗不必要的精力我们选择当前最主流、对初学者最友好的技术栈。核心运行环境Python请确保你的系统已安装Python 3.8或更高版本。可以通过命令行验证python --version # 或 python3 --version核心开发框架LangChainLangChain是目前构建Agent事实上的标准框架它提供了丰富的模块化组件能极大降低开发复杂度。我们使用pip进行安装pip install langchain langchain-community langchain-core大语言模型LLM接入OpenAI API 或 本地模型Agent的“智力”来源于大语言模型。你有两个选择云端API推荐稳定便捷使用OpenAI的GPT系列。你需要一个OpenAI API Key。pip install openai然后在代码中或环境变量设置你的API Key。本地模型注重隐私与成本使用Ollama运行本地模型如Llama 3, Qwen等。# 安装Ollama (请参考官网https://ollama.com/) # 拉取一个模型例如 ollama pull llama3.2 pip install langchain-ollama辅助工具包 为了模拟真实工具调用我们还需要安装一些常用的库pip install requests python-dotenv duckduckgo-searchrequests: 用于模拟调用Web API。python-dotenv: 管理环境变量如API Key。duckduckgo-search: 提供一个免费的搜索工具。集成开发环境IDE 任何你熟悉的Python IDE均可如VSCode、PyCharm。建议使用支持Jupyter Notebook的环境方便分步执行和调试。3. 实战练习一构建具有持久记忆的会话Agent预计耗时40分钟目标让Agent不仅能回答当前问题还能引用整个会话历史中的信息实现连贯的、个性化的对话。痛点默认的LLM调用是无状态的每次提问它都会“忘记”之前的对话。我们需要为其添加“记忆”模块。核心概念ConversationBufferMemory。这是LangChain中最简单的记忆类型像一个不断增长的缓冲区保存所有历史消息。3.1 基础记忆实现让我们先创建一个能记住上下文的简单聊天机器人。# 文件agent_with_memory_basic.py from langchain_openai import ChatOpenAI from langchain.memory import ConversationBufferMemory from langchain.chains import ConversationChain # 1. 初始化LLM (这里以OpenAI为例使用本地模型请替换为ChatOllama) llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7, openai_api_key你的API Key) # 2. 创建记忆体 memory ConversationBufferMemory() # 3. 创建对话链 conversation ConversationChain( llmllm, memorymemory, verboseTrue # 开启详细日志方便观察记忆如何被使用 ) # 4. 进行多轮对话 print(Agent: 你好我是你的助手。) while True: user_input input(\n你: ) if user_input.lower() in [退出, exit, quit]: print(Agent: 再见) break response conversation.predict(inputuser_input) print(fAgent: {response})运行与验证 运行上述脚本进行如下对话你: 我叫张三。 Agent: 你好张三很高兴认识你。 你: 我最喜欢的水果是苹果。 Agent: 苹果很健康你喜欢什么品种的苹果 你: 我刚刚告诉你我的名字是什么观察Agent的回复。在最后一轮一个没有记忆的AI会不知道“我的名字”指代谁但我们的Agent应该能正确回答“张三”。通过设置verboseTrue你可以在控制台看到LangChain是如何将历史记录拼接到当前提问中的。3.2 进阶记忆窗口与摘要记忆ConversationBufferMemory会保存所有历史可能导致上下文过长超出模型限制和成本增加。ConversationBufferWindowMemory只保留最近K轮对话ConversationSummaryMemory则动态生成对话摘要。# 文件agent_with_advanced_memory.py from langchain.memory import ConversationBufferWindowMemory, ConversationSummaryMemory from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-3.5-turbo, temperature0.7) # 示例1窗口记忆只保留最近3轮 window_memory ConversationBufferWindowMemory(k3) # 示例2摘要记忆适合超长对话 summary_memory ConversationSummaryMemory(llmllm)练习任务修改上面的基础代码分别使用窗口记忆(k2)和摘要记忆进行长对话超过5轮观察并对比Agent的行为差异。思考在“客服对话”和“长期项目规划”两种场景下哪种记忆方式更合适4. 实战练习二为Agent装备“工具手”预计耗时50分钟目标让Agent学会使用外部工具来获取信息或执行操作突破纯文本生成的限制。痛点LLM的知识可能过时且无法直接操作现实世界如查询实时天气、执行计算、读写文件。核心概念ToolAgentExecutor。你将工具函数描述给Agent它学会在需要时调用它们。4.1 创建自定义工具我们创建两个工具一个计算器一个获取当前时间的工具。# 文件custom_tools.py from langchain.tools import tool from datetime import datetime import math tool def calculate(expression: str) - str: 执行数学计算。输入是一个数学表达式字符串例如 ‘(35)*2‘。只支持基本运算。 try: # 警告使用eval有安全风险此处仅用于演示。生产环境应使用安全计算库如numexpr。 result eval(expression, {__builtins__: None}, {math: math}) return f计算结果: {result} except Exception as e: return f计算错误: {e} tool def get_current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。时区参数例如 ‘Asia/Shanghai‘, ‘America/New_York‘。 from pytz import timezone as tz import pytz try: tz_obj tz(timezone) current_time datetime.now(tz_obj).strftime(%Y-%m-%d %H:%M:%S %Z%z) return f{timezone}的当前时间是: {current_time} except pytz.exceptions.UnknownTimeZoneError: return f错误未知时区 ‘{timezone}‘。请提供有效的时区名称。 # 注意需要安装pytz库: pip install pytz4.2 创建工具型Agent并执行现在我们将工具赋予Agent并观察它如何决策。# 文件agent_with_tools.py from langchain_openai import ChatOpenAI from langchain.agents import initialize_agent, AgentType from custom_tools import calculate, get_current_time llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 定义工具列表 tools [calculate, get_current_time] # 初始化Agent。AgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION 适合基于聊天的Agent使用ReAct推理框架。 agent initialize_agent( tools, llm, agentAgentType.CHAT_ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, # 必须开启才能看到Agent的思考过程 handle_parsing_errorsTrue # 优雅处理Agent输出解析错误 ) # 测试Agent queries [ “请问(128)*3等于多少” “现在纽约是几点钟” “先计算100除以25然后告诉我伦敦现在的时间。” ] for query in queries: print(f\n用户提问: {query}) try: result agent.run(query) print(fAgent最终回答: {result}) except Exception as e: print(f执行出错: {e})运行与验证 运行代码仔细观察控制台verbose模式下的输出。你会看到类似以下的思考链 Entering new AgentExecutor chain... Thought: 用户需要计算一个数学表达式我需要使用计算器工具。 Action: calculate Action Input: (128)*3 Observation: 计算结果: 60 Thought: 我得到了计算结果可以回答用户了。 Final Answer: (128)*3 等于 60。这个过程就是ReActReason Act框架的直观体现Agent先思考Reason再决定行动Act调用工具根据工具返回结果Observation再次思考最终给出答案。练习任务为Agent添加一个duckduckgo-search工具让它能回答实时性问题如“今天比特币价格多少”。尝试问一个需要按顺序调用多个工具的复杂问题如“计算北京和伦敦的时差然后用中文告诉我”观察Agent的规划能力。5. 实战练习三实现自主规划与任务分解预计耗时60分钟目标让Agent具备“项目经理”能力能够将模糊的、复杂的用户指令自动分解为一系列明确的、可执行的子任务。痛点用户指令如“帮我规划一个周末杭州旅行”直接抛给LLM可能得到一段笼统的文字。而一个真正的Agent应该能输出可执行的清单1. 查杭州周末天气 2. 查高铁票 3. 列出西湖周边景点等。核心概念Plan-and-Execute模式。我们使用LangChain的PlanAndExecute组件它包含一个“规划者”和一个“执行者”。5.1 构建规划执行Agent这个示例将模拟一个旅行规划助手。# 文件planning_agent.py from langchain_openai import ChatOpenAI from langchain_experimental.plan_and_execute import PlanAndExecute, load_agent_executor, load_chat_planner from langchain.tools import Tool from custom_tools import get_current_time # 假设我们还有之前创建的搜索工具和计算器工具 from duckduckgo_search import DDGS def search_web(query: str) - str: 使用DuckDuckGo进行网页搜索。 with DDGS() as ddgs: results [r for r in ddgs.text(query, max_results3)] return \n.join([f{r[title]}: {r[body]} for r in results]) search_tool Tool( nameWeb Search, funcsearch_web, description当需要获取最新的、未知的或实时信息时使用此工具。 ) # 定义工具集 tools [search_tool, get_current_time] # 实际项目中会有更专业的工具如航班查询API llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 1. 创建规划器负责将目标分解为步骤 planner load_chat_planner(llm) # 2. 创建执行器负责调用工具执行每个步骤 executor load_agent_executor(llm, tools, verboseTrue) # 3. 组合成规划执行Agent agent PlanAndExecute(plannerplanner, executorexecutor, verboseTrue) # 执行一个复杂任务 complex_task “为我规划一个本周六从上海出发周日返回的杭州周末游。需要考虑天气和交通。” print(f“执行任务: {complex_task}”) result agent.run(complex_task) print(f“\n最终规划结果:\n{result}”)5.2 解析与优化运行上述代码你会看到Agent首先输出一个计划例如计划: 1. 搜索本周末杭州的天气预报。 2. 搜索从上海到杭州的高铁或火车时刻表及票价。 3. 搜索杭州周末值得游览的景点或活动。 4. 综合以上信息生成一个周末游计划。然后它会逐步执行每一步调用相应的工具最终整合成一个完整的答案。关键洞察PlanAndExecute模式将“思考规划”和“行动执行”分离。规划器Planner通常使用一个LLM它不直接调用工具只负责制定高级计划。执行器Executor是另一个Agent它严格按计划步骤调用具体工具完成任务。这种架构更清晰也更容易调试。练习任务观察与调试尝试给Agent一个它现有工具无法完成的任务如“帮我预订一家西湖边的酒店”。观察它的计划和执行过程在哪里失败错误信息是什么定制规划提示load_chat_planner函数内部使用了默认的系统提示词。尝试查阅LangChain文档找到如何自定义规划器的提示词planner_prompt让它输出的计划步骤更具体、格式更统一例如强制要求每一步都以“步骤X使用[工具名]来[具体操作]”的格式输出。6. 实战练习四搭建多智能体协作系统预计耗时40分钟目标模拟一个软件团队让多个具备不同角色和专长的Agent通过对话协作完成一个单Agent难以处理的复杂任务。痛点单一Agent的能力有上限。复杂的任务如“设计并实现一个简单的网页”需要需求分析、UI设计、编码、测试等不同技能。核心概念MultiAgentCollaboration(通过CrewAI或AutoGen框架实现)。这里我们使用相对轻量的CrewAI来演示。6.1 使用CrewAI创建角色与任务我们模拟一个“技术博客创作团队”包含策划、写手、编辑三个角色。# 文件multi_agent_crew.py # 首先安装crewai包: pip install crewai from crewai import Agent, Task, Crew, Process from langchain_openai import ChatOpenAI # 配置LLM llm ChatOpenAI(modelgpt-4, temperature0.7) # 多Agent协作建议使用更强模型 # 1. 定义角色Agent planner Agent( role‘技术博客策划师’, goal‘根据热点话题策划出有深度、能吸引开发者的博客选题和详细大纲’, backstory‘你是一位资深技术布道师对AI、云计算、前端框架等趋势有敏锐的洞察力。你擅长将复杂技术转化为引人入胜的故事线。’, verboseTrue, allow_delegationTrue, # 允许将任务委派给其他Agent llmllm ) writer Agent( role‘高级技术写手’, goal‘根据策划师提供的大纲撰写专业、准确、易懂且文笔流畅的技术博客正文’, backstory‘你拥有多年技术文档和博客写作经验能用清晰的逻辑和生动的案例把技术讲透。你痛恨晦涩难懂的术语堆砌。’, verboseTrue, llmllm ) editor Agent( role‘严厉的技术编辑’, goal‘审核和润色写手完成的博客草稿确保其技术准确性、逻辑严谨性、语言无错误并符合发布标准’, backstory‘你以挑剔和严谨著称对技术细节和语言表达有极高的要求。任何模糊的表述和潜在的误导都逃不过你的眼睛。’, verboseTrue, llmllm ) # 2. 定义任务Task并指定执行者和上下文依赖 plan_task Task( description‘针对当前热点“AI Agent开发入门”策划一篇面向中级Python开发者的技术博客。输出包括标题、核心痛点、3-5个核心章节标题及简要说明、目标读者。’, expected_output‘一份完整的博客策划案文档。’, agentplanner ) write_task Task( description‘根据策划师提供的策划案撰写博客正文。要求每个章节充实有代码示例用Markdown格式有实际应用场景语言生动。字数不少于1500字。’, expected_output‘一篇完整的、格式良好的Markdown技术博客正文。’, agentwriter, context[plan_task] # 此任务依赖plan_task的输出 ) edit_task Task( description‘对写手完成的博客正文进行审核和编辑。重点检查1. 技术概念是否准确。2. 代码示例能否运行。3. 逻辑是否通顺。4. 有无错别字或语法问题。输出最终修订版。’, expected_output‘最终可发布的、经过审核的博客正文。’, agenteditor, context[write_task] # 此任务依赖write_task的输出 ) # 3. 组建团队Crew并定义工作流程 blog_crew Crew( agents[planner, writer, editor], tasks[plan_task, write_task, edit_task], processProcess.sequential, # 顺序执行策划 - 写作 - 编辑 verbose2 # 2级详细日志可以看到Agent间的交互 ) # 4. 启动团队执行任务 result blog_crew.kickoff() print(“\n” “”*50) print(“多智能体协作最终产出”) print(“”*50) print(result)运行与观察 运行代码由于任务较复杂可能需要一些时间。观察控制台输出你会看到策划师开始工作输出策划案。策划案完成后写手自动接收策划案作为输入开始撰写。写手完成后编辑接收博客草稿开始审核修改。最终输出整合了三个角色的成果。核心价值多Agent系统的魅力在于角色分工和信息流转。每个Agent专注于自己的专业领域并通过context参数自动获取上游工作的成果。这极大地扩展了AI处理复杂工作流的能力边界。练习任务修改流程将Process.sequential改为Process.hierarchical并定义一个manager_agent经理角色来协调其他Agent。观察执行流程有何不同。增加角色在团队中增加一个SEO专家角色它的任务是在编辑完成后为博客生成一组合适的关键词和元描述。7. 常见问题与排查指南在练习过程中你一定会遇到各种错误。以下是典型问题及解决方案问题现象可能原因排查步骤解决方案ModuleNotFoundError依赖库未安装或环境错误。1. 确认在正确的Python环境下运行。2. 使用pip list检查所需包是否存在。使用pip install [package-name]安装缺失的包。注意包名可能不同如langchain-openai。API密钥错误OpenAI API Key未设置或无效。1. 检查代码中openai_api_key参数或环境变量OPENAI_API_KEY。2. 在OpenAI官网检查密钥状态和余额。确保密钥正确设置。对于本地模型检查Ollama服务是否运行(ollama serve)。Agent陷入循环或输出无关内容提示词不清晰、工具描述不准确或模型温度(temperature)过高。1. 开启verboseTrue观察Agent的思考链(Thought)。2. 检查是否在无效的Action和Observation间循环。1. 降低temperature如设为0以获得更确定性的输出。2. 优化工具的描述(description)使其更精确。3. 使用更强的模型如gpt-4。解析错误 (Parsing Error)Agent输出的文本不符合框架预期的格式如JSON。查看verbose日志找到Agent原始输出看是否包含多余的解释或格式错误。1. 设置handle_parsing_errorsTrue。2. 在Agent初始化时提供更清晰的输出格式指令。3. 使用专为结构化输出设计的模型或方法。工具调用失败工具函数本身有Bug或输入参数类型不对。1. 单独测试工具函数是否能正常工作。2. 检查Agent传递给工具的Action Input是否正确。1. 修复工具函数的代码。2. 在工具描述中明确指定输入参数的格式和类型。上下文长度超限对话历史或文档内容太长超过模型token限制。观察错误信息是否包含“context length”或“token”。1. 使用ConversationSummaryMemory或ConversationBufferWindowMemory。2. 对长文本进行分块或摘要处理后再输入。多Agent CrewAI执行慢任务复杂串行执行步骤多或网络延迟。1. 确认每个Agent的任务是否过于庞大。2. 使用verbose2观察卡在哪一步。1. 简化任务描述或拆分成更小的Crew。2. 考虑使用异步或并发执行如果框架支持。3. 耐心等待复杂任务可能需要数分钟。8. 从练习到项目工程化最佳实践完成以上练习你已经掌握了Agent的核心能力。但要将其用于真实项目还需要关注工程化细节配置与密钥管理永远不要将API密钥硬编码在代码中。使用.env文件和环境变量。# .env 文件 OPENAI_API_KEYsk-...# 代码中读取 from dotenv import load_dotenv import os load_dotenv() llm ChatOpenAI(openai_api_keyos.getenv(“OPENAI_API_KEY”))日志与监控除了verboseTrue在生产环境中应集成结构化日志如logging模块记录每次Agent的思考、行动和结果便于调试和审计。错误处理与降级对工具调用、网络请求、模型调用等可能失败的操作进行try-catch包装。设计降级策略例如当搜索工具失败时让Agent基于自身知识给出保守回答。性能与成本优化缓存对重复的、耗时的LLM调用或工具查询结果进行缓存。流式输出对于长文本生成使用流式响应以提升用户体验。模型选择根据任务复杂度选择合适的模型。简单的工具调用可用gpt-3.5-turbo复杂的规划推理则用gpt-4。评估与测试为你的Agent建立测试集。例如针对“旅行规划”Agent设计一系列标准问题并评估其输出是否包含必备信息天气、交通、景点。这有助于在迭代中保证质量。安全与边界工具权限严格控制工具的能力。例如文件读写工具应限制路径数据库操作工具应使用只读或最小权限账户。输入过滤对用户输入进行基本的清理和过滤防止注入攻击。内容审核对Agent的最终输出特别是面向公众时进行内容安全审核。这2.5小时的练习是一个高度浓缩的“能力地图绘制”过程。你不再是通过零散的知识点来理解Agent而是通过亲手构建四个关键系统从内到外掌握了它的工作原理。记忆、工具、规划、协作——这四大支柱构成了当今绝大多数实用型AI Agent的骨架。真正的“牛”不在于你记住了多少框架的名字而在于当产品经理提出“我们需要一个能自动处理用户工单的AI助手”时你能立刻在脑海中勾勒出它的技术蓝图它需要ConversationSummaryMemory来理解工单历史需要集成JIRA API和知识库搜索作为工具复杂问题需要PlanAndExecute来拆解或许还需要一个审核Agent来确保回复质量。然后你能快速用代码将这些蓝图变为现实。接下来的方向也很明确选择一个你感兴趣的具体领域智能客服、个人知识管理、自动化测试将这四个练习组合起来去构建一个解决真实问题的项目。过程中你会遇到更具体的挑战比如工具API的鉴权、长文本处理的性能、多Agent协作的通信开销而解决这些挑战的过程就是你超越这2.5小时成为一名真正Agent开发者的开始。