1. 项目概述为什么“从零玩转Agent开发”是当下最值得投入的技能最近和不少做开发的朋友聊天发现一个挺有意思的现象大家要么已经在捣鼓AI Agent要么正摩拳擦掌准备入场。这感觉有点像几年前移动互联网刚火起来的时候你不懂点App开发好像就落伍了。现在不懂点Agent开发似乎也快跟不上趟了。这个“从零玩转Agent开发”的项目说白了就是一份给开发者尤其是对AI应用感兴趣但还没上手的开发者的实战地图。它要解决的正是那种“我知道Agent很牛但具体怎么搞从哪开始用什么工具”的普遍焦虑。Agent或者说智能体早已不是科幻电影里的概念。你可以把它理解为一个高度自主的“数字员工”。它不像传统的程序你输入A它只会输出B。Agent能理解你的意图比如“帮我分析一下上周的销售数据并写份报告”然后自己规划步骤先去数据库拉数据再用Python跑个分析最后调用大模型生成文字报告甚至还能把报告发到你邮箱。整个过程你只需要下一个指令。它的核心价值在于“自主性”和“工具使用能力”这直接指向了降本增效和创造新交互模式的巨大潜力。那么这个项目适合谁呢如果你是后端、前端或者对自动化脚本熟悉的开发者想给自己的技能树加上“AI赋能”这一强力分支那这就是为你准备的。即便你之前没深度接触过机器学习只要编程基础扎实理解API调用就能跟着上手。项目会避开那些深奥的数学公式聚焦在“如何用现有的轮子快速造出一辆能跑的车”。我们会从最根本的原理和架构思想讲起然后手把手带你用主流框架比如LangChain实现几个有代表性的Agent让你不仅知其然更知其所以然最终具备设计和开发实用AI智能体的能力。2. 核心架构解析拆解一个AI智能体的五脏六腑要造Agent先得懂它的身体结构。一个典型的、功能完整的AI Agent其架构可以类比为一个现代化公司的核心团队。光有一个聪明的“大脑”大语言模型是远远不够的它需要一套协同工作的“器官系统”。2.1 核心组件与工作流一个标准的Agent架构通常包含以下几个核心组件它们通过清晰的工作流串联起来感知模块这是Agent的“耳朵”和“眼睛”。它负责接收用户的输入无论是文本、语音还是文件。更关键的是它需要对输入进行初步的理解和结构化比如从一句模糊的指令中提取出关键意图和实体。例如用户说“看看我上个月的支出情况”感知模块需要解析出意图是“查询财务数据”实体是“时间上个月”、“类型支出”。规划与推理模块这是Agent的“策略部门”。它根据感知模块理解的任务进行任务分解和规划。对于一个复杂任务Agent需要决定先做什么、后做什么可能会拆解成多个子任务。这个模块的核心是“思维链”能力。例如面对“帮我订一张明天北京飞上海的最便宜机票并预约一辆下午2点到浦东机场的接机车”这个任务规划模块会生成一个执行计划子任务1查询明天北京-上海的航班价格并排序子任务2选择最便宜的航班并获取详情子任务3根据航班落地时间查询下午2点浦东机场附近的租车服务子任务4整合信息并确认。记忆模块这是Agent的“笔记本”和“经验库”。它分为短期记忆和长期记忆。短期记忆保存当前对话的上下文确保Agent能理解“你”、“它”、“这个”等指代关系。长期记忆则存储历史交互、学到的知识、用户偏好等使Agent能够进行个性化服务并积累经验。没有记忆的Agent每次对话都是“初次见面”。工具调用模块这是Agent的“手”和“脚”是其超越纯聊天机器人的关键。Agent本身不具备直接操作世界的能力它需要通过调用各种工具API、函数、数据库查询、命令行等来执行具体动作。工具调用模块负责管理工具清单、根据规划模块的指令选择合适的工具、格式化调用参数、执行调用并解析返回结果。比如要查机票价格它就调用“航班查询API”要写邮件它就调用“邮件发送服务”。行动与响应模块这是Agent的“嘴巴”和“执行终端”。它将工具调用的结果、推理的结论进行整合、润色最终生成对人类友好的自然语言响应或者直接执行某个动作如发送邮件、创建日历事件。好的响应不仅是信息的堆砌更是对执行过程和结果的清晰交代。这五个模块并非总是线性执行而是一个动态的循环感知 - 规划 - [记忆查询] - 工具调用 - 行动 - [结果作为新感知] - 再规划…… 直到任务完成或无法继续。2.2 主流架构模式对比在实际开发中根据任务复杂度和对可控性的要求我们常采用几种架构模式单一代理模式一个Agent包办所有。结构简单适合目标明确、步骤线性的任务。例如一个专门回答公司内部知识库问题的客服Agent。但复杂任务下其规划和纠错能力有限。多代理协作模式多个具备不同专长的Agent组成团队通过通信协同完成复杂任务。例如一个“数据分析师”Agent负责查询和整理数据一个“报告撰写员”Agent负责根据数据生成文案一个“审查员”Agent负责检查报告质量。这种模式模块化好、能力强但设计和管理复杂度高。分层控制模式一个“管理者”Agent负责顶层任务分解和协调将子任务分派给不同的“工作者”Agent执行。这结合了上述两者的优点是目前处理复杂商业流程的主流思路。注意架构设计没有银弹。选择哪种模式取决于你的应用场景。对于新手强烈建议从单一代理模式开始重点攻克“工具调用”这一关。这是Agent从“聊天”走向“实干”的质变点理解了它再扩展成多代理或分层架构就会水到渠成。3. 开发框架实战以LangChain为核心构建你的第一个Agent理解了架构我们就要动手了。工欲善其事必先利其器。目前AI Agent开发领域生态丰富但LangChain无疑是认知度最高、生态最成熟的框架之一。它就像一个提供了各种标准接口和预制组件的“智能体工厂”能极大降低开发门槛。我们以LangChain为例展示如何快速搭建一个实用Agent。3.1 环境搭建与框架选型首先你需要一个Python环境建议3.8以上。安装LangChain非常简单pip install langchain langchain-community如果你打算使用OpenAI的模型还需要安装OpenAI的包并设置API Keypip install openai export OPENAI_API_KEY你的密钥为什么选LangChain因为它抽象得好。它将Agent的核心组件——LLM、记忆、工具、推理逻辑——都模块化了。你不需要从零开始写网络请求、管理对话状态、设计工具调用协议LangChain提供了高层的、声明式的API。同时它的社区极其活跃有海量的第三方工具集成和示例遇到问题很容易找到解决方案。对于快速原型验证和大多数生产级应用LangChain都是一个稳健的起点。当然框架不止LangChain。LangGraph是LangChain团队推出的用于构建有状态、多参与者工作流的库特别适合构建我们前面提到的多代理或复杂工作流。如果你设计的Agent需要严格的流程控制、循环、分支LangGraph比基础的LangChain Agent执行器更强大。而像AutoGen这类框架则更侧重于多智能体对话协作的研究与开发。作为入门牢牢掌握LangChain是性价比最高的选择。3.2 核心概念与快速上手在LangChain中构建一个Agent主要涉及几个核心对象LLM大语言模型是Agent的大脑。你可以用OpenAI的GPT也可以用 Anthropic 的Claude或通过Ollama部署本地模型。Tool工具。任何你能用Python函数封装的能力都可以成为Tool比如搜索、计算、数据库查询、调用第三方API。Agent智能体本身。它是一个由LLM驱动的推理引擎决定在给定输入和工具集的情况下应该采取什么行动。AgentExecutor代理执行器。它负责运行Agent管理其与工具交互的循环直到得出最终答案。下面我们来实现一个最简单的、能使用搜索工具和计算器的Agent。from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain_community.tools import DuckDuckGoSearchRun, WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper from langchain_openai import ChatOpenAI from langchain import hub # 1. 初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 2. 定义工具 search DuckDuckGoSearchRun() wikipedia WikipediaQueryRun(api_wrapperWikipediaAPIWrapper()) # 一个简单的计算器工具 def calculator(input_str: str) - str: 用于执行数学计算。输入应为一个数学表达式如 3 5 * 2。 try: # 警告使用eval有安全风险此处仅作演示。生产环境应使用安全计算库如ast.literal_eval或专门数学库。 result eval(input_str) return str(result) except Exception as e: return f计算错误{e} calc_tool Tool( nameCalculator, funccalculator, description当需要进行数学计算时使用此工具。输入一个数学表达式如 10 5 * 2。 ) tools [search, wikipedia, calc_tool] # 3. 获取预设的提示词模板。ReAct是一个经典的Agent推理框架。 prompt hub.pull(hwchase17/react) # 4. 创建Agent agent create_react_agent(llm, tools, prompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 运行Agent result agent_executor.invoke({input: 特斯拉汽车的创始人是谁他今年多大了请用中文回答。}) print(result[output])运行这段代码你会看到控制台输出详细的思考过程因为verboseTrue 进入新的AgentExecutor链... 思考用户问了两个问题特斯拉汽车的创始人是谁以及他今年多大。我需要先查一下特斯拉的创始人信息。 行动Search 行动输入特斯拉汽车创始人 观察埃隆·马斯克... 思考好的创始人是埃隆·马斯克。现在需要知道他今年多大这可能需要计算或者直接搜索他的年龄。 行动Search 行动输入埃隆·马斯克 年龄 2024 观察埃隆·马斯克出生于1971年6月28日... 思考现在我有了出生日期可以计算2024年的年龄。这需要计算器工具。 行动Calculator 行动输入2024 - 1971 观察53 思考所以埃隆·马斯克在2024年是53岁。现在可以组织最终答案了。 最终答案特斯拉汽车的创始人是埃隆·马斯克。他出生于1971年6月28日在2024年是53岁。 链结束。这个简单的例子展示了Agent完整的“思考-行动-观察”循环。它自动选择了正确的工具并串联使用了多个工具来完成任务。3.3 打造自定义工具让Agent连接你的业务系统内置工具虽好但真正的威力在于让Agent接入你自己的业务逻辑。创建自定义工具非常简单核心就是定义一个Python函数然后用Tool类包装它。假设我们有一个内部系统可以查询员工信息。我们可以为其创建一个工具from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type # 定义工具的输入参数模型 class EmployeeQueryInput(BaseModel): employee_name: str Field(description需要查询的员工姓名) info_type: Optional[str] Field(defaultall, description查询的信息类型如department, phone, all) # 创建自定义工具类 class EmployeeInfoTool(BaseTool): name query_employee_info description 根据员工姓名查询其部门、电话等基本信息。 args_schema: Type[BaseModel] EmployeeQueryInput def _run(self, employee_name: str, info_type: str all) - str: 实际执行工具调用的方法 # 这里模拟一个数据库查询或内部API调用 employee_database { 张三: {department: 技术部, phone: 101}, 李四: {department: 市场部, phone: 102} } if employee_name not in employee_database: return f未找到员工{employee_name} info employee_database[employee_name] if info_type all: return f员工 {employee_name} 的信息部门 - {info[department]}, 电话 - {info[phone]}. elif info_type in info: return f员工 {employee_name} 的 {info_type} 是{info[info_type]} else: return f员工 {employee_name} 没有 {info_type} 信息。 async def _arun(self, employee_name: str, info_type: str all): 异步版本可选 raise NotImplementedError(此工具不支持异步调用) # 将自定义工具加入列表 custom_tool EmployeeInfoTool() tools.append(custom_tool) # 更新Agent和执行器使用新的工具列表 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 现在Agent可以查询员工信息了 result agent_executor.invoke({input: 帮我查一下张三在哪个部门并告诉我他的电话。}) print(result[output])通过这种方式你可以将CRM、ERP、OA系统等各种内部能力封装成工具赋予你的Agent强大的业务处理能力。这是Agent开发中最具价值的一环。实操心得定义工具的描述description至关重要LLM完全依赖这个描述来决定是否以及何时调用该工具。描述要清晰、具体说明工具的用途、输入格式和输出什么。模糊的描述会导致Agent错误地调用或忽略工具。一个好的描述就像给工具写了一份清晰的“产品说明书”。4. 高级特性与生产级考量当你成功运行了第一个Agent后下一步就是让它变得更强大、更可靠能够胜任更复杂的任务并投入实际使用。4.1 记忆管理让对话拥有上下文没有记忆的Agent就像金鱼。LangChain提供了多种记忆后端。最简单的是ConversationBufferMemory它保存完整的对话历史。from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 在创建AgentExecutor时传入memory agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue ) # 现在可以进行多轮对话了 result1 agent_executor.invoke({input: 我叫王小明。}) print(result1[output]) # 可能回复“你好王小明” result2 agent_executor.invoke({input: 你还记得我的名字吗}) print(result2[output]) # 它会回答“当然你叫王小明。”对于长对话完整历史可能导致token超长且成本高。这时可以使用ConversationSummaryMemory它让LLM自动总结之前的对话只保留摘要。对于更复杂的场景如需要记住用户偏好、结构化信息可以考虑向量数据库如Chroma, Pinecone作为长期记忆将对话片段嵌入存储实现基于语义的检索。4.2 复杂工作流与LangGraph当任务需要多个步骤循环、条件判断或并行执行时基础的Agent执行器就显得力不从心。这时就该LangGraph出场了。它允许你用“图”来定义工作流节点是处理步骤可以是调用LLM、运行工具、执行函数边是控制流。假设我们要构建一个“数据分析报告生成Agent”流程是1. 理解需求2. 查询数据3. 分析数据4. 生成报告5. 如果用户不满意返回第2步调整查询。from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator # 1. 定义状态State即工作流中传递的数据结构 class AgentState(TypedDict): question: str data_query: str raw_data: str analysis: str report: str feedback: str # 2. 定义各个节点函数 def understand_need(state: AgentState): 节点理解用户需求生成数据查询语句 # 这里可以调用一个LLM来生成查询 state[data_query] f基于问题 {state[question]} 生成的查询语句 return state def query_data(state: AgentState): 节点执行数据查询 # 模拟查询 state[raw_data] f这是查询 {state[data_query]} 得到的数据结果。 return state def analyze_data(state: AgentState): 节点分析数据 state[analysis] f对数据 {state[raw_data]} 的分析结论。 return state def generate_report(state: AgentState): 节点生成报告 state[report] f基于分析 {state[analysis]} 生成的最终报告。 return state def should_continue(state: AgentState): 条件判断节点根据用户反馈决定下一步 if state.get(feedback) 满意: return end else: return revise_query def revise_based_on_feedback(state: AgentState): 节点根据反馈修订查询 state[data_query] f根据反馈 {state[feedback]} 修订后的查询。 return state # 3. 构建图 workflow StateGraph(AgentState) workflow.add_node(understand, understand_need) workflow.add_node(query, query_data) workflow.add_node(analyze, analyze_data) workflow.add_node(report, generate_report) workflow.add_node(revise, revise_based_on_feedback) # 4. 设置边控制流 workflow.set_entry_point(understand) workflow.add_edge(understand, query) workflow.add_edge(query, analyze) workflow.add_edge(analyze, report) # 从report出来后进入条件判断 workflow.add_conditional_edges( report, should_continue, { end: END, revise_query: revise } ) workflow.add_edge(revise, query) # 修订后重新查询 # 5. 编译并运行图 app workflow.compile() initial_state {question: 请分析公司Q2的销售趋势} result app.invoke(initial_state) print(result[report])通过LangGraph你可以清晰地定义和可视化复杂的工作流实现比传统线性Agent更强大的控制逻辑。这对于构建审批流、复杂决策支持系统等场景非常有用。4.3 生产环境部署与优化要让Agent走出笔记本服务真实用户需要考虑以下几点性能与延迟LLM API调用通常是主要延迟来源。优化策略包括使用流式响应streaming提升用户体验感知对耗时工具调用进行异步处理设置合理的超时和重试机制考虑对回答进行缓存例如对常见问题缓存答案。稳定性与错误处理Agent在复杂环境中会出错工具调用失败、LLM输出格式错误、网络问题。必须实现健壮的错误处理在AgentExecutor中设置handle_parsing_errorsTrue为每个工具调用添加try-catch设计兜底策略如当Agent陷入循环时强制终止并返回友好提示。可观测性与评估你需要知道Agent运行得怎么样。记录完整的执行轨迹包括思考过程、工具调用和结果这对于调试和优化至关重要。可以定期用一组测试问题评估Agent的准确率和可靠性。LangChain提供了callbacks机制可以方便地集成日志记录如LangSmith。安全与合规这是重中之重。必须对用户输入进行严格的过滤和审查防止Prompt注入攻击。对工具调用进行权限控制确保Agent不会执行危险或越权操作例如删除数据库、发送敏感信息。对于生成的内容最好加入人工审核环节或内容安全过滤器。5. 常见问题与实战排坑指南在实际开发中你一定会遇到各种“坑”。下面是一些典型问题及其解决方案很多都是我在项目中真实踩过的。5.1 Agent陷入循环或执行无关动作这是新手最常见的问题。Agent不停地调用同一个工具或者执行一些与问题完全无关的操作就是不给出最终答案。原因1工具描述不清晰或LLM理解偏差。工具的描述description是LLM选择工具的唯一依据。如果描述模糊LLM就可能误用。解决方案仔细打磨工具描述。确保描述准确说明了工具的用途、输入格式和输出示例。例如将“查询数据”改为“根据员工ID字符串格式查询员工的姓名和部门返回格式为‘姓名XXX部门XXX’”。原因2Prompt设计不佳。Agent的Prompt提示词决定了它的推理风格。默认的Prompt可能不适合你的任务。解决方案自定义Prompt。在Prompt中明确指令例如“你必须先思考再行动”、“在得到最终答案后必须立即停止输出‘最终答案’开头的内容”、“禁止重复调用同一个工具超过3次”。你可以从LangChain Hub拉取不同的Prompt模板进行试验。原因3工具返回的结果格式混乱。如果工具返回一大段HTML或混乱的JSONLLM可能无法解析导致困惑和错误的下一个动作。解决方案在工具内部对返回结果进行清洗和格式化确保输出是干净、结构化的文本。这是工具开发者的责任。5.2 工具调用速度慢或失败原因网络延迟、第三方API不稳定、工具函数本身执行慢。解决方案设置超时为每个工具调用配置合理的超时时间。实现重试对于暂时性失败如网络抖动加入指数退避的重试机制。异步调用如果Agent需要调用多个独立工具考虑使用异步Agent如create_react_agent支持异步来并行执行大幅减少总耗时。缓存对于查询类工具如果参数相同可以缓存结果一段时间避免重复调用。5.3 处理复杂、模糊的用户指令用户不会总是给出清晰的指令。“帮我做一下市场分析”这种请求太模糊了。解决方案设计一个“澄清”环节。在Agent主流程前可以增加一个“需求澄清Agent”。它的任务是与用户进行简短对话将模糊需求转化为具体的、可执行的任务列表。例如用户“帮我做一下市场分析。”澄清Agent“好的。请问您想分析哪个产品或市场时间范围是需要我重点关注哪些维度比如竞争对手、用户增长还是市场份额请提供更多细节。”用户“分析我们上季度在华南区的智能手机销售情况和主要竞争对手对比。”澄清Agent“明白。我将执行以下任务1. 查询我司上季度华南区智能手机销售数据2. 查询主要竞争对手A、B同期同区域销售数据3. 进行对比分析并生成报告。现在开始执行吗” 这样主执行Agent接收到的就是一个明确的任务列表成功率大大提升。5.4 成本控制频繁调用LLM和付费API成本可能快速上升。解决方案选择合适的模型不是所有任务都需要GPT-4。对于工具选择、简单分类等任务GPT-3.5-Turbo通常足够且便宜一个数量级。可以将任务路由到不同成本的模型。优化Prompt和上下文减少Prompt中不必要的指令使用ConversationSummaryMemory来压缩历史减少输入的token数量。设置预算和监控为API密钥设置使用量和费用上限并建立监控告警。本地模型对于敏感数据或需要极致成本控制的场景考虑使用Ollama等工具部署本地开源模型如Llama 3, Qwen。虽然能力可能稍弱但数据安全和长期成本有优势。5.5 实战检查清单在将Agent部署到生产环境前请对照此清单进行检查检查项说明是否完成工具描述每个工具的description是否清晰、无歧义是否包含输入输出示例□错误处理Agent执行器是否设置了handle_parsing_errorsTrue关键工具调用是否有try-catch□超时与重试对外部API调用是否设置了合理的超时和重试策略□记忆管理是否选择了合适的记忆策略如Buffer Summary长对话是否会超出token限制□Prompt安全是否对用户输入进行了基本的过滤防止恶意Prompt注入□权限控制Agent调用的工具是否进行了权限校验例如不能通过Agent删除所有数据库□日志与追踪是否记录了完整的Agent思考链和工具调用记录便于调试和审计□性能基准是否对典型查询的响应时间和成功率进行了测试□成本评估单次交互的平均token消耗和成本是否在可接受范围内□用户反馈闭环是否有机制收集用户对Agent回答的满意度如“点赞/点踩”用于后续优化□开发AI Agent是一个迭代的过程很少有能一次就设计完美的系统。我的经验是从一个最小可行产品开始——一个只解决一个非常具体问题的单一Agent。然后收集真实用户的交互数据观察它在哪里失败在哪里表现出色。接着有针对性地优化可能是修改Prompt可能是调整工具描述也可能是增加一个新的工具或引入记忆。慢慢地你的Agent就会变得越来越聪明、越来越可靠。这个过程本身就是探索人机协作新边界的最有趣部分。 AI Agent开发实战：从核心架构到LangChain实现
1. 项目概述为什么“从零玩转Agent开发”是当下最值得投入的技能最近和不少做开发的朋友聊天发现一个挺有意思的现象大家要么已经在捣鼓AI Agent要么正摩拳擦掌准备入场。这感觉有点像几年前移动互联网刚火起来的时候你不懂点App开发好像就落伍了。现在不懂点Agent开发似乎也快跟不上趟了。这个“从零玩转Agent开发”的项目说白了就是一份给开发者尤其是对AI应用感兴趣但还没上手的开发者的实战地图。它要解决的正是那种“我知道Agent很牛但具体怎么搞从哪开始用什么工具”的普遍焦虑。Agent或者说智能体早已不是科幻电影里的概念。你可以把它理解为一个高度自主的“数字员工”。它不像传统的程序你输入A它只会输出B。Agent能理解你的意图比如“帮我分析一下上周的销售数据并写份报告”然后自己规划步骤先去数据库拉数据再用Python跑个分析最后调用大模型生成文字报告甚至还能把报告发到你邮箱。整个过程你只需要下一个指令。它的核心价值在于“自主性”和“工具使用能力”这直接指向了降本增效和创造新交互模式的巨大潜力。那么这个项目适合谁呢如果你是后端、前端或者对自动化脚本熟悉的开发者想给自己的技能树加上“AI赋能”这一强力分支那这就是为你准备的。即便你之前没深度接触过机器学习只要编程基础扎实理解API调用就能跟着上手。项目会避开那些深奥的数学公式聚焦在“如何用现有的轮子快速造出一辆能跑的车”。我们会从最根本的原理和架构思想讲起然后手把手带你用主流框架比如LangChain实现几个有代表性的Agent让你不仅知其然更知其所以然最终具备设计和开发实用AI智能体的能力。2. 核心架构解析拆解一个AI智能体的五脏六腑要造Agent先得懂它的身体结构。一个典型的、功能完整的AI Agent其架构可以类比为一个现代化公司的核心团队。光有一个聪明的“大脑”大语言模型是远远不够的它需要一套协同工作的“器官系统”。2.1 核心组件与工作流一个标准的Agent架构通常包含以下几个核心组件它们通过清晰的工作流串联起来感知模块这是Agent的“耳朵”和“眼睛”。它负责接收用户的输入无论是文本、语音还是文件。更关键的是它需要对输入进行初步的理解和结构化比如从一句模糊的指令中提取出关键意图和实体。例如用户说“看看我上个月的支出情况”感知模块需要解析出意图是“查询财务数据”实体是“时间上个月”、“类型支出”。规划与推理模块这是Agent的“策略部门”。它根据感知模块理解的任务进行任务分解和规划。对于一个复杂任务Agent需要决定先做什么、后做什么可能会拆解成多个子任务。这个模块的核心是“思维链”能力。例如面对“帮我订一张明天北京飞上海的最便宜机票并预约一辆下午2点到浦东机场的接机车”这个任务规划模块会生成一个执行计划子任务1查询明天北京-上海的航班价格并排序子任务2选择最便宜的航班并获取详情子任务3根据航班落地时间查询下午2点浦东机场附近的租车服务子任务4整合信息并确认。记忆模块这是Agent的“笔记本”和“经验库”。它分为短期记忆和长期记忆。短期记忆保存当前对话的上下文确保Agent能理解“你”、“它”、“这个”等指代关系。长期记忆则存储历史交互、学到的知识、用户偏好等使Agent能够进行个性化服务并积累经验。没有记忆的Agent每次对话都是“初次见面”。工具调用模块这是Agent的“手”和“脚”是其超越纯聊天机器人的关键。Agent本身不具备直接操作世界的能力它需要通过调用各种工具API、函数、数据库查询、命令行等来执行具体动作。工具调用模块负责管理工具清单、根据规划模块的指令选择合适的工具、格式化调用参数、执行调用并解析返回结果。比如要查机票价格它就调用“航班查询API”要写邮件它就调用“邮件发送服务”。行动与响应模块这是Agent的“嘴巴”和“执行终端”。它将工具调用的结果、推理的结论进行整合、润色最终生成对人类友好的自然语言响应或者直接执行某个动作如发送邮件、创建日历事件。好的响应不仅是信息的堆砌更是对执行过程和结果的清晰交代。这五个模块并非总是线性执行而是一个动态的循环感知 - 规划 - [记忆查询] - 工具调用 - 行动 - [结果作为新感知] - 再规划…… 直到任务完成或无法继续。2.2 主流架构模式对比在实际开发中根据任务复杂度和对可控性的要求我们常采用几种架构模式单一代理模式一个Agent包办所有。结构简单适合目标明确、步骤线性的任务。例如一个专门回答公司内部知识库问题的客服Agent。但复杂任务下其规划和纠错能力有限。多代理协作模式多个具备不同专长的Agent组成团队通过通信协同完成复杂任务。例如一个“数据分析师”Agent负责查询和整理数据一个“报告撰写员”Agent负责根据数据生成文案一个“审查员”Agent负责检查报告质量。这种模式模块化好、能力强但设计和管理复杂度高。分层控制模式一个“管理者”Agent负责顶层任务分解和协调将子任务分派给不同的“工作者”Agent执行。这结合了上述两者的优点是目前处理复杂商业流程的主流思路。注意架构设计没有银弹。选择哪种模式取决于你的应用场景。对于新手强烈建议从单一代理模式开始重点攻克“工具调用”这一关。这是Agent从“聊天”走向“实干”的质变点理解了它再扩展成多代理或分层架构就会水到渠成。3. 开发框架实战以LangChain为核心构建你的第一个Agent理解了架构我们就要动手了。工欲善其事必先利其器。目前AI Agent开发领域生态丰富但LangChain无疑是认知度最高、生态最成熟的框架之一。它就像一个提供了各种标准接口和预制组件的“智能体工厂”能极大降低开发门槛。我们以LangChain为例展示如何快速搭建一个实用Agent。3.1 环境搭建与框架选型首先你需要一个Python环境建议3.8以上。安装LangChain非常简单pip install langchain langchain-community如果你打算使用OpenAI的模型还需要安装OpenAI的包并设置API Keypip install openai export OPENAI_API_KEY你的密钥为什么选LangChain因为它抽象得好。它将Agent的核心组件——LLM、记忆、工具、推理逻辑——都模块化了。你不需要从零开始写网络请求、管理对话状态、设计工具调用协议LangChain提供了高层的、声明式的API。同时它的社区极其活跃有海量的第三方工具集成和示例遇到问题很容易找到解决方案。对于快速原型验证和大多数生产级应用LangChain都是一个稳健的起点。当然框架不止LangChain。LangGraph是LangChain团队推出的用于构建有状态、多参与者工作流的库特别适合构建我们前面提到的多代理或复杂工作流。如果你设计的Agent需要严格的流程控制、循环、分支LangGraph比基础的LangChain Agent执行器更强大。而像AutoGen这类框架则更侧重于多智能体对话协作的研究与开发。作为入门牢牢掌握LangChain是性价比最高的选择。3.2 核心概念与快速上手在LangChain中构建一个Agent主要涉及几个核心对象LLM大语言模型是Agent的大脑。你可以用OpenAI的GPT也可以用 Anthropic 的Claude或通过Ollama部署本地模型。Tool工具。任何你能用Python函数封装的能力都可以成为Tool比如搜索、计算、数据库查询、调用第三方API。Agent智能体本身。它是一个由LLM驱动的推理引擎决定在给定输入和工具集的情况下应该采取什么行动。AgentExecutor代理执行器。它负责运行Agent管理其与工具交互的循环直到得出最终答案。下面我们来实现一个最简单的、能使用搜索工具和计算器的Agent。from langchain.agents import AgentExecutor, create_react_agent from langchain.tools import Tool from langchain_community.tools import DuckDuckGoSearchRun, WikipediaQueryRun from langchain_community.utilities import WikipediaAPIWrapper from langchain_openai import ChatOpenAI from langchain import hub # 1. 初始化LLM llm ChatOpenAI(modelgpt-3.5-turbo, temperature0) # 2. 定义工具 search DuckDuckGoSearchRun() wikipedia WikipediaQueryRun(api_wrapperWikipediaAPIWrapper()) # 一个简单的计算器工具 def calculator(input_str: str) - str: 用于执行数学计算。输入应为一个数学表达式如 3 5 * 2。 try: # 警告使用eval有安全风险此处仅作演示。生产环境应使用安全计算库如ast.literal_eval或专门数学库。 result eval(input_str) return str(result) except Exception as e: return f计算错误{e} calc_tool Tool( nameCalculator, funccalculator, description当需要进行数学计算时使用此工具。输入一个数学表达式如 10 5 * 2。 ) tools [search, wikipedia, calc_tool] # 3. 获取预设的提示词模板。ReAct是一个经典的Agent推理框架。 prompt hub.pull(hwchase17/react) # 4. 创建Agent agent create_react_agent(llm, tools, prompt) # 5. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 6. 运行Agent result agent_executor.invoke({input: 特斯拉汽车的创始人是谁他今年多大了请用中文回答。}) print(result[output])运行这段代码你会看到控制台输出详细的思考过程因为verboseTrue 进入新的AgentExecutor链... 思考用户问了两个问题特斯拉汽车的创始人是谁以及他今年多大。我需要先查一下特斯拉的创始人信息。 行动Search 行动输入特斯拉汽车创始人 观察埃隆·马斯克... 思考好的创始人是埃隆·马斯克。现在需要知道他今年多大这可能需要计算或者直接搜索他的年龄。 行动Search 行动输入埃隆·马斯克 年龄 2024 观察埃隆·马斯克出生于1971年6月28日... 思考现在我有了出生日期可以计算2024年的年龄。这需要计算器工具。 行动Calculator 行动输入2024 - 1971 观察53 思考所以埃隆·马斯克在2024年是53岁。现在可以组织最终答案了。 最终答案特斯拉汽车的创始人是埃隆·马斯克。他出生于1971年6月28日在2024年是53岁。 链结束。这个简单的例子展示了Agent完整的“思考-行动-观察”循环。它自动选择了正确的工具并串联使用了多个工具来完成任务。3.3 打造自定义工具让Agent连接你的业务系统内置工具虽好但真正的威力在于让Agent接入你自己的业务逻辑。创建自定义工具非常简单核心就是定义一个Python函数然后用Tool类包装它。假设我们有一个内部系统可以查询员工信息。我们可以为其创建一个工具from langchain.tools import BaseTool from pydantic import BaseModel, Field from typing import Optional, Type # 定义工具的输入参数模型 class EmployeeQueryInput(BaseModel): employee_name: str Field(description需要查询的员工姓名) info_type: Optional[str] Field(defaultall, description查询的信息类型如department, phone, all) # 创建自定义工具类 class EmployeeInfoTool(BaseTool): name query_employee_info description 根据员工姓名查询其部门、电话等基本信息。 args_schema: Type[BaseModel] EmployeeQueryInput def _run(self, employee_name: str, info_type: str all) - str: 实际执行工具调用的方法 # 这里模拟一个数据库查询或内部API调用 employee_database { 张三: {department: 技术部, phone: 101}, 李四: {department: 市场部, phone: 102} } if employee_name not in employee_database: return f未找到员工{employee_name} info employee_database[employee_name] if info_type all: return f员工 {employee_name} 的信息部门 - {info[department]}, 电话 - {info[phone]}. elif info_type in info: return f员工 {employee_name} 的 {info_type} 是{info[info_type]} else: return f员工 {employee_name} 没有 {info_type} 信息。 async def _arun(self, employee_name: str, info_type: str all): 异步版本可选 raise NotImplementedError(此工具不支持异步调用) # 将自定义工具加入列表 custom_tool EmployeeInfoTool() tools.append(custom_tool) # 更新Agent和执行器使用新的工具列表 agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 现在Agent可以查询员工信息了 result agent_executor.invoke({input: 帮我查一下张三在哪个部门并告诉我他的电话。}) print(result[output])通过这种方式你可以将CRM、ERP、OA系统等各种内部能力封装成工具赋予你的Agent强大的业务处理能力。这是Agent开发中最具价值的一环。实操心得定义工具的描述description至关重要LLM完全依赖这个描述来决定是否以及何时调用该工具。描述要清晰、具体说明工具的用途、输入格式和输出什么。模糊的描述会导致Agent错误地调用或忽略工具。一个好的描述就像给工具写了一份清晰的“产品说明书”。4. 高级特性与生产级考量当你成功运行了第一个Agent后下一步就是让它变得更强大、更可靠能够胜任更复杂的任务并投入实际使用。4.1 记忆管理让对话拥有上下文没有记忆的Agent就像金鱼。LangChain提供了多种记忆后端。最简单的是ConversationBufferMemory它保存完整的对话历史。from langchain.memory import ConversationBufferMemory memory ConversationBufferMemory(memory_keychat_history, return_messagesTrue) # 在创建AgentExecutor时传入memory agent_executor AgentExecutor( agentagent, toolstools, memorymemory, verboseTrue ) # 现在可以进行多轮对话了 result1 agent_executor.invoke({input: 我叫王小明。}) print(result1[output]) # 可能回复“你好王小明” result2 agent_executor.invoke({input: 你还记得我的名字吗}) print(result2[output]) # 它会回答“当然你叫王小明。”对于长对话完整历史可能导致token超长且成本高。这时可以使用ConversationSummaryMemory它让LLM自动总结之前的对话只保留摘要。对于更复杂的场景如需要记住用户偏好、结构化信息可以考虑向量数据库如Chroma, Pinecone作为长期记忆将对话片段嵌入存储实现基于语义的检索。4.2 复杂工作流与LangGraph当任务需要多个步骤循环、条件判断或并行执行时基础的Agent执行器就显得力不从心。这时就该LangGraph出场了。它允许你用“图”来定义工作流节点是处理步骤可以是调用LLM、运行工具、执行函数边是控制流。假设我们要构建一个“数据分析报告生成Agent”流程是1. 理解需求2. 查询数据3. 分析数据4. 生成报告5. 如果用户不满意返回第2步调整查询。from langgraph.graph import StateGraph, END from typing import TypedDict, Annotated import operator # 1. 定义状态State即工作流中传递的数据结构 class AgentState(TypedDict): question: str data_query: str raw_data: str analysis: str report: str feedback: str # 2. 定义各个节点函数 def understand_need(state: AgentState): 节点理解用户需求生成数据查询语句 # 这里可以调用一个LLM来生成查询 state[data_query] f基于问题 {state[question]} 生成的查询语句 return state def query_data(state: AgentState): 节点执行数据查询 # 模拟查询 state[raw_data] f这是查询 {state[data_query]} 得到的数据结果。 return state def analyze_data(state: AgentState): 节点分析数据 state[analysis] f对数据 {state[raw_data]} 的分析结论。 return state def generate_report(state: AgentState): 节点生成报告 state[report] f基于分析 {state[analysis]} 生成的最终报告。 return state def should_continue(state: AgentState): 条件判断节点根据用户反馈决定下一步 if state.get(feedback) 满意: return end else: return revise_query def revise_based_on_feedback(state: AgentState): 节点根据反馈修订查询 state[data_query] f根据反馈 {state[feedback]} 修订后的查询。 return state # 3. 构建图 workflow StateGraph(AgentState) workflow.add_node(understand, understand_need) workflow.add_node(query, query_data) workflow.add_node(analyze, analyze_data) workflow.add_node(report, generate_report) workflow.add_node(revise, revise_based_on_feedback) # 4. 设置边控制流 workflow.set_entry_point(understand) workflow.add_edge(understand, query) workflow.add_edge(query, analyze) workflow.add_edge(analyze, report) # 从report出来后进入条件判断 workflow.add_conditional_edges( report, should_continue, { end: END, revise_query: revise } ) workflow.add_edge(revise, query) # 修订后重新查询 # 5. 编译并运行图 app workflow.compile() initial_state {question: 请分析公司Q2的销售趋势} result app.invoke(initial_state) print(result[report])通过LangGraph你可以清晰地定义和可视化复杂的工作流实现比传统线性Agent更强大的控制逻辑。这对于构建审批流、复杂决策支持系统等场景非常有用。4.3 生产环境部署与优化要让Agent走出笔记本服务真实用户需要考虑以下几点性能与延迟LLM API调用通常是主要延迟来源。优化策略包括使用流式响应streaming提升用户体验感知对耗时工具调用进行异步处理设置合理的超时和重试机制考虑对回答进行缓存例如对常见问题缓存答案。稳定性与错误处理Agent在复杂环境中会出错工具调用失败、LLM输出格式错误、网络问题。必须实现健壮的错误处理在AgentExecutor中设置handle_parsing_errorsTrue为每个工具调用添加try-catch设计兜底策略如当Agent陷入循环时强制终止并返回友好提示。可观测性与评估你需要知道Agent运行得怎么样。记录完整的执行轨迹包括思考过程、工具调用和结果这对于调试和优化至关重要。可以定期用一组测试问题评估Agent的准确率和可靠性。LangChain提供了callbacks机制可以方便地集成日志记录如LangSmith。安全与合规这是重中之重。必须对用户输入进行严格的过滤和审查防止Prompt注入攻击。对工具调用进行权限控制确保Agent不会执行危险或越权操作例如删除数据库、发送敏感信息。对于生成的内容最好加入人工审核环节或内容安全过滤器。5. 常见问题与实战排坑指南在实际开发中你一定会遇到各种“坑”。下面是一些典型问题及其解决方案很多都是我在项目中真实踩过的。5.1 Agent陷入循环或执行无关动作这是新手最常见的问题。Agent不停地调用同一个工具或者执行一些与问题完全无关的操作就是不给出最终答案。原因1工具描述不清晰或LLM理解偏差。工具的描述description是LLM选择工具的唯一依据。如果描述模糊LLM就可能误用。解决方案仔细打磨工具描述。确保描述准确说明了工具的用途、输入格式和输出示例。例如将“查询数据”改为“根据员工ID字符串格式查询员工的姓名和部门返回格式为‘姓名XXX部门XXX’”。原因2Prompt设计不佳。Agent的Prompt提示词决定了它的推理风格。默认的Prompt可能不适合你的任务。解决方案自定义Prompt。在Prompt中明确指令例如“你必须先思考再行动”、“在得到最终答案后必须立即停止输出‘最终答案’开头的内容”、“禁止重复调用同一个工具超过3次”。你可以从LangChain Hub拉取不同的Prompt模板进行试验。原因3工具返回的结果格式混乱。如果工具返回一大段HTML或混乱的JSONLLM可能无法解析导致困惑和错误的下一个动作。解决方案在工具内部对返回结果进行清洗和格式化确保输出是干净、结构化的文本。这是工具开发者的责任。5.2 工具调用速度慢或失败原因网络延迟、第三方API不稳定、工具函数本身执行慢。解决方案设置超时为每个工具调用配置合理的超时时间。实现重试对于暂时性失败如网络抖动加入指数退避的重试机制。异步调用如果Agent需要调用多个独立工具考虑使用异步Agent如create_react_agent支持异步来并行执行大幅减少总耗时。缓存对于查询类工具如果参数相同可以缓存结果一段时间避免重复调用。5.3 处理复杂、模糊的用户指令用户不会总是给出清晰的指令。“帮我做一下市场分析”这种请求太模糊了。解决方案设计一个“澄清”环节。在Agent主流程前可以增加一个“需求澄清Agent”。它的任务是与用户进行简短对话将模糊需求转化为具体的、可执行的任务列表。例如用户“帮我做一下市场分析。”澄清Agent“好的。请问您想分析哪个产品或市场时间范围是需要我重点关注哪些维度比如竞争对手、用户增长还是市场份额请提供更多细节。”用户“分析我们上季度在华南区的智能手机销售情况和主要竞争对手对比。”澄清Agent“明白。我将执行以下任务1. 查询我司上季度华南区智能手机销售数据2. 查询主要竞争对手A、B同期同区域销售数据3. 进行对比分析并生成报告。现在开始执行吗” 这样主执行Agent接收到的就是一个明确的任务列表成功率大大提升。5.4 成本控制频繁调用LLM和付费API成本可能快速上升。解决方案选择合适的模型不是所有任务都需要GPT-4。对于工具选择、简单分类等任务GPT-3.5-Turbo通常足够且便宜一个数量级。可以将任务路由到不同成本的模型。优化Prompt和上下文减少Prompt中不必要的指令使用ConversationSummaryMemory来压缩历史减少输入的token数量。设置预算和监控为API密钥设置使用量和费用上限并建立监控告警。本地模型对于敏感数据或需要极致成本控制的场景考虑使用Ollama等工具部署本地开源模型如Llama 3, Qwen。虽然能力可能稍弱但数据安全和长期成本有优势。5.5 实战检查清单在将Agent部署到生产环境前请对照此清单进行检查检查项说明是否完成工具描述每个工具的description是否清晰、无歧义是否包含输入输出示例□错误处理Agent执行器是否设置了handle_parsing_errorsTrue关键工具调用是否有try-catch□超时与重试对外部API调用是否设置了合理的超时和重试策略□记忆管理是否选择了合适的记忆策略如Buffer Summary长对话是否会超出token限制□Prompt安全是否对用户输入进行了基本的过滤防止恶意Prompt注入□权限控制Agent调用的工具是否进行了权限校验例如不能通过Agent删除所有数据库□日志与追踪是否记录了完整的Agent思考链和工具调用记录便于调试和审计□性能基准是否对典型查询的响应时间和成功率进行了测试□成本评估单次交互的平均token消耗和成本是否在可接受范围内□用户反馈闭环是否有机制收集用户对Agent回答的满意度如“点赞/点踩”用于后续优化□开发AI Agent是一个迭代的过程很少有能一次就设计完美的系统。我的经验是从一个最小可行产品开始——一个只解决一个非常具体问题的单一Agent。然后收集真实用户的交互数据观察它在哪里失败在哪里表现出色。接着有针对性地优化可能是修改Prompt可能是调整工具描述也可能是增加一个新的工具或引入记忆。慢慢地你的Agent就会变得越来越聪明、越来越可靠。这个过程本身就是探索人机协作新边界的最有趣部分。