这类教程最值得先看的不是功能列表而是能不能帮你把零散的概念串成一条能跑通的链路。很多人学 AI Agent 时容易卡在“每个词都听过但不知道怎么连起来用”的阶段。2026年的最新进展核心是把架构、工具调用、RAG增强和MCP协议这些模块从理论概念变成了有明确输入、输出和判断标准的生产流程。如果你是想自己动手搭建一个能处理实际任务的智能体或者想理解企业里是怎么把这些技术落地的那这篇梳理会直接告诉你每一步该准备什么、先做什么、成功长什么样、出问题该看哪里。我不会深究每个底层算法的推导而是聚焦在“怎么把它们组装成一个能工作、可调试的系统”上。1. 先拆解“AI Agent”到底在解决什么问题很多人一上来就去看架构图但更容易上手的方式是先明确你要用 Agent 干什么。它不是一个万能的黑盒而是针对特定问题的一套自动化处理流程。1.1 从“聊天”到“做事”的转变传统的大模型对话是你问一句它答一句答案基于训练数据。而 AI Agent 的核心是“做事”它需要能理解复杂指令拆解成步骤调用外部工具比如查数据库、发邮件、执行代码并管理整个执行过程的状态。比如你让它“分析上周销售数据并生成报告邮件发给经理”这就是一个典型的 Agent 任务它需要调用数据查询工具、分析工具、报告生成工具和邮件发送工具。所以判断一个场景是否需要 Agent就看这个任务是否需要多步骤决策和与外部系统交互。如果只是简单问答用增强后的 RAG 可能就够了如果需要串联多个动作并处理过程中的不确定性那就得上 Agent。1.2 智能体的基本组成大脑、记忆与手脚一个可运行的 Agent 通常由几个核心模块组成理解这些模块是后续搭建的基础大脑推理与规划通常是一个大语言模型LLM。它负责理解用户意图、拆解任务、制定计划Plan和在执行中做决策Reasoning。这是 Agent 的“指挥官”。记忆短期与长期Agent 需要有记忆来保存对话历史短期记忆和从过往经验中学习长期记忆。这能让它在多轮交互中保持上下文避免重复或矛盾。简单的实现可以用对话历史列表复杂的会引入向量数据库来存储和检索相关经验。工具手脚这是 Agent 与真实世界交互的接口。工具可以是一个函数、一个 API、一个命令行程序。比如search_web搜索、execute_sql查数据库、send_email发邮件。Agent 需要知道在什么情况下调用哪个工具并处理工具的返回结果。工作流协调器当任务复杂时可能需要多个 Agent 协同Multi-Agent或者一个 Agent 内部有复杂的执行循环如 ReAct 模式思考-行动-观察。工作流引擎负责调度这些步骤处理分支、循环和错误。搭建时不要试图一次性实现所有模块。我建议先从“一个能调用简单工具的单一 Agent”开始跑通整个循环再逐步增加记忆、复杂工作流和多 Agent 协同。2. 环境与工具准备选型决定上手速度在写第一行代码之前选对工具栈能省掉一大半的折腾时间。2026年的生态已经比较成熟不需要从零造轮子。2.1 核心框架与平台选择目前主要有两类选择开源框架和低代码平台。开源框架适合开发者灵活度高LangChain / LangGraph生态最丰富社区活跃文档和示例多。LangChain 用于构建链LangGraph 专门用于构建有状态的、多环节的工作流Agent 本质就是一种工作流。入门时可能会觉得概念多但它是理解 Agent 组件的最佳教材之一。LlamaIndex如果你构建的 Agent 严重依赖 RAG从私有数据中获取信息LlamaIndex 在数据连接、索引和检索方面更专精可以很好地与 LangChain 配合使用。Semantic Kernel (Microsoft)与 .NET 生态结合紧密概念清晰Plugins, Planners, Memories。如果你主要使用 C# 或 Azure 云服务这是个好选择。AutoGen (Microsoft)专注于多 Agent 对话和协作预设了多种 Agent 角色如 UserProxy, Assistant能快速搭建多 Agent 讨论场景。低代码/云平台适合快速原型和业务人员Dify, Flowise这类平台提供了可视化编排工作流的能力。你可以通过拖拽组件LLM、工具、条件判断来构建 Agent无需深入编码。对于验证想法和构建内部工具非常快但自定义复杂逻辑和深度调试可能受限。怎么选如果目标是学习和深度控制从 LangChain 开始。如果目标是快速给业务部门做一个演示或内部工具用 Dify 这类平台可能几小时就能出原型。2.2 大模型 API 与本地部署Agent 的大脑需要一个大模型。你有两个选择调用云端 APIOpenAI GPT-4/4o, Anthropic Claude, 国内各大厂的模型。优点是不用操心部署性能稳定功能新。缺点是持续使用有成本且数据需要出境国内模型无此问题。对于学习和原型开发这是最快的方式。本地部署开源模型使用 Ollama, LM Studio 或 vLLM 等工具在本地运行 Llama、Qwen、DeepSeek 等模型。优点是数据完全私有无网络延迟长期成本可能更低。缺点是对硬件GPU 内存有要求模型能力可能略逊于顶级闭源模型。起步建议直接用 OpenAI 或 Claude 的 API。先确保你的 Agent 逻辑是正确的再考虑成本和数据隐私问题将大脑替换为本地模型。这样能避免早期同时调试模型部署和 Agent 逻辑两方面的复杂问题。2.3 其他基础设施向量数据库用于实现 RAG 和长期记忆。轻量级起步可以用ChromaDB内存型简单或FAISSFacebook 开源的高效相似性搜索库。生产环境可以考虑Qdrant,Weaviate,Milvus等它们支持持久化、分布式和更丰富的过滤条件。Spring AI 2.0 与 Qdrant 的集成就是一个企业级 RAG 的常见组合。开发环境Python 3.9 是主流。准备好虚拟环境conda 或 venv管理好依赖包版本这是避免“在我机器上能跑”问题的第一步。3. 核心环节一让 Agent 学会使用工具Tool Calling工具调用是 Agent 从“空想”到“实干”的关键一步。这里的目标是让 LLM 能根据你的描述在合适的时机调用正确的工具并理解返回结果。3.1 如何定义工具工具本质上是一个函数你需要用框架能理解的方式描述它。以 LangChain 为例from langchain.tools import tool from langchain.agents import AgentExecutor, create_react_agent from langchain import hub # 1. 定义一个简单的计算器工具 tool def calculator(expression: str) - str: 计算一个数学表达式。例如calculator(\2 2\) 返回 4。 try: # 安全提示生产环境请勿使用eval此处仅为示例 result eval(expression) return f计算结果: {result} except Exception as e: return f计算错误: {e} # 2. 定义一个查询天气的工具模拟 tool def get_weather(city: str) - str: 查询指定城市的天气。 # 这里应该调用真实的天气API返回模拟数据 return f{city}的天气是晴朗25摄氏度。 # 将工具放入列表 tools [calculator, get_weather]关键点在于tool装饰器和函数文档字符串docstring。LLM 主要靠这个文档字符串来理解工具的用途、输入参数和格式。所以文档字符串要写得清晰、具体包含示例。3.2 创建 Agent 并执行有了工具你需要一个 Agent 来使用它们。ReAct 模式是一个经典且有效的起点。# 3. 选择LLM这里以ChatOpenAI为例需设置你的API_KEY from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o, temperature0) # 4. 获取一个预设的ReAct提示词模板 prompt hub.pull(hwchase17/react) # 5. 创建ReAct Agent agent create_react_agent(llm, tools, prompt) # 6. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 7. 运行 result agent_executor.invoke({ input: 请问北京现在的天气怎么样如果温度高于20度就计算一下温度5的平方是多少。 }) print(result[output])当你运行这段代码并设置verboseTrue时会在控制台看到 Agent 的思考过程Thought: 用户想知道北京天气然后根据温度做一个计算。我需要先调用天气工具。 Action: get_weather Action Input: {city: 北京} Observation: 北京的天气是晴朗25摄氏度。 Thought: 现在温度是25度高于20度。我需要计算255的平方。我需要调用计算器工具。 Action: calculator Action Input: {expression: (255)**2} Observation: 计算结果: 900 Thought: 我得到了所有信息可以回答用户了。 Final Answer: 北京现在天气晴朗25摄氏度。因为温度高于20度我计算了255的平方结果是900。这就是工具调用的核心流程思考Thought- 决定行动Action- 执行工具Action Input- 观察结果Observation- 继续思考。verboseTrue是调试 Agent 逻辑的利器一定要善用。3.3 常见问题与排查工具不被调用首先检查工具的文档字符串是否清晰。LLM 可能无法理解工具的用途。其次检查提示词Prompt确保它鼓励 Agent 使用工具。ReAct 模板通常已经优化过这一点。工具输入格式错误LLM 有时会生成不符合工具函数参数格式的输入。使用handle_parsing_errorsTrue可以让执行器尝试修复小错误。更稳妥的做法是在工具函数内部做好参数校验和类型转换。无限循环或错误使用工具Agent 可能陷入“思考-调用-失败-再思考”的循环。可以设置max_iterations最大迭代次数和max_execution_time最大执行时间来强制终止。例如AgentExecutor(..., max_iterations10, max_execution_time30)。4. 核心环节二用 RAG 为 Agent 注入专业知识如果 Agent 只能调用通用工具那它还是个“通才”。RAG检索增强生成能让它变成某个垂直领域的“专家”比如回答公司内部文档问题、分析特定技术资料。4.1 RAG 全链路拆解不止是向量检索一个完整的 RAG 系统远不止“文本切块-向量化-搜索”那么简单。企业级应用时痛点往往出现在全链路的各个环节文档加载与解析支持 PDF、Word、PPT、HTML、Markdown、数据库等。痛点格式复杂扫描版PDF、表格、图表导致信息提取不全或错乱。文本分割切块策略直接影响效果。盲目按固定字符数切分如 500 字一块会割裂语义。更好的策略是按语义分割使用自然语言处理NLP模型识别段落、句子边界。递归分割先按大标题分再按小标题分最后按段落分形成层次结构。重叠分割让相邻块有部分文字重叠避免答案恰好被切在块边界。向量化与索引将文本块转换为向量Embedding存入向量数据库。痛点Embedding 模型对专业术语表征能力不足索引速度慢影响实时性。检索用户提问时将问题也向量化从数据库中找出最相似的几个文本块Top-K。痛点单纯的余弦相似度可能检索不准需要结合关键词过滤Metadata Filtering如按文档类型、日期过滤和重排序Rerank模型来提升精度。增强生成将检索到的文本块作为上下文连同问题一起送给 LLM让它生成答案。痛点上下文太长超出模型限制上下文包含无关或矛盾信息导致答案“幻觉”。4.2 动手搭建一个简单的 RAG 系统我们用 LangChain 和 Chroma 快速实现一个基础版让你感受全流程。from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA # 1. 加载文档这里用文本文件示例 loader TextLoader(./公司制度.txt, encodingutf-8) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块大小 chunk_overlap50, # 重叠大小 length_functionlen, separators[\n\n, \n, 。, , , , , ] # 递归分割符 ) docs text_splitter.split_documents(documents) # 3. 创建向量存储 embeddings OpenAIEmbeddings() # 需要OPENAI_API_KEY vectorstore Chroma.from_documents(documentsdocs, embeddingembeddings, persist_directory./chroma_db) # 持久化到本地目录下次可直接加载 # 4. 创建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相似的3个块 # 5. 创建问答链 llm ChatOpenAI(modelgpt-4o, temperature0) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将所有检索到的上下文“塞”进提示词 retrieverretriever, return_source_documentsTrue # 返回来源文档便于溯源 ) # 6. 提问 question 我们公司的年假制度是怎样的 result qa_chain.invoke({query: question}) print(答案:, result[result]) print(\n来源文档:) for doc in result[source_documents]: print(f- {doc.page_content[:200]}...) # 打印前200字符这个流程跑通后你就有了一个最简单的知识库问答系统。但这就是 RAG 的全部吗远不是。这只是一个起点。4.3 从“能用”到“好用”RAG 的优化实战企业级 RAG 的痛点需要针对性优化检索质量差找不准优化 Embedding 模型尝试text-embedding-3-small/large或开源模型如BGE-M3、voyage-2在专业语料上微调效果更佳。引入重排序Rerank使用 Cohere Rerank、BGE Reranker 等模型对初步检索结果重新打分排序把最相关的排到最前面。这能显著提升精度尤其是当 Top-K 设置较大时。混合检索Hybrid Search结合向量检索语义相似和关键词检索如 BM25字面匹配。有些问题用关键词更准如产品型号“ABC-123”。生成答案有幻觉编造引用溯源Groundedness要求 LLM 在生成答案时必须引用来源文档的片段。这既能增强可信度也方便人工核查。在提示词Prompt中明确指令“请基于以下上下文回答并引用相关段落。”Prompt 工程设计更好的提示词如“如果上下文信息不足以回答问题请直接说‘根据现有资料无法回答’不要编造信息。”处理复杂问题多跳问答Agentic RAG这就是将 RAG 和 Agent 结合。让 Agent 来主导检索过程。例如对于一个复杂问题“我们产品A和竞争对手B在Q3的销量对比如何”Agent 可以规划第一步检索产品A的Q3销售报告第二步检索竞争对手B的市场分析第三步调用计算工具进行对比第四步生成最终报告。这比一次性检索所有信息更精准。评估 RAG 系统不能只靠感觉。可以看几个指标检索命中率检索到的块是否包含答案、答案相关性、事实准确性与源文档对比、引用正确率。用一批测试问题来量化评估。5. 核心环节三理解 MCP 协议——工具的“通用插座”当你为 Agent 开发了越来越多的工具会发现一个麻烦每个框架LangChain, AutoGen等定义工具的方式略有不同工具也难以在不同项目间复用。这就是MCPModel Context Protocol要解决的问题。5.1 MCP 是什么为什么需要它你可以把 MCP 想象成工具的“USB-C 接口”或“通用插座”。它是一个开放协议定义了工具、数据源如何以一种标准化的方式向 LLM 应用如 Agent描述自己、提供能力。在没有 MCP 之前你在 LangChain 里写了一个tool。换到另一个基于 Claude 的 Agent 平台可能得用它的 SDK 重新定义一遍。工具的逻辑比如连接公司数据库的代码是相同的但“包装形式”要改。有了 MCP 之后你按照 MCP 协议的标准格式将你的数据库连接能力写成一个MCP 服务器。任何支持 MCP 协议的客户端比如 Claude Desktop, 新的 LangChain 版本都能自动发现、加载并使用这个工具。一次开发处处可用。工具实现了与上层应用框架的解耦。5.2 MCP 的核心概念与工作流程MCP 服务器Server提供工具和数据源的一方。它暴露出一些“资源”Resources如数据库表、API端点和“工具”Tools如查询、更新操作。服务器启动后等待客户端连接。MCP 客户端Client使用工具的一方比如 Claude Desktop、你的自定义 Agent 应用。客户端通过标准方式如 stdio 或 HTTP连接到服务器获取服务器提供的资源和工具列表。协议通信客户端和服务器通过 JSON-RPC 消息进行通信。消息类型包括list_tools列出工具、call_tool调用工具、read_resource读取资源等。一个简化的工作流你写了一个CompanyDBServer它通过 MCP 协议提供了query_sales_data工具。你在 Claude Desktop 中配置它连接到这个服务器。你在 Claude 的聊天框里说“帮我查一下上海地区本季度的销售数据。”Claude作为 MCP 客户端自动识别出这个请求可以调用query_sales_data工具它通过 MCP 协议向你的服务器发送call_tool请求。你的服务器执行真正的数据库查询并将结果通过 MCP 协议返回给 Claude。Claude 将结果组织成自然语言回复给你。5.3 对开发者的意义工具生态标准化未来可能会出现一个“MCP 工具市场”你可以像安装插件一样为你的 Agent 添加天气预报、股票查询、项目管理等各种能力而无需关心底层是哪个框架。关注点分离你可以专注于编写工具的核心业务逻辑MCP 服务器而让不同的前端Chatbot, Agent 框架低代码平台来消费它。安全与管控企业可以统一开发和部署 MCP 服务器严格控制内部工具如何被 LLM 访问而不是在每个应用里重复编写和授权。目前MCP 主要由 Anthropic 推动但正在成为行业趋势。学习它意味着你在为未来更模块化、更开放的 Agent 开发模式做准备。即使你现在不深入实现理解这个概念也能帮你更好地规划工具层。6. 企业级应用落地从 Demo 到生产系统把单个 Agent 跑通只是第一步。要把它变成企业里一个可靠的生产系统需要跨越好几个台阶。6.1 架构设计考量单体 vs 微服务简单的内部工具可以是一个单体应用。但如果涉及多个部门、高并发、独立扩缩容就需要将 Agent 核心、工具服务、RAG 索引服务等拆分成微服务。状态管理Agent 对话是有状态的。在 Web 应用中需要为每个用户会话维护独立的状态记忆、对话历史。不能把状态简单放在内存里需要用 Redis、数据库或专门的会话存储来管理。异步与流式响应复杂的 Agent 任务可能耗时很长几十秒。必须采用异步处理如 Celery 任务队列和流式响应Server-Sent Events 或 WebSocket让用户能看到实时进展而不是一直白屏等待。可观测性这是生产系统的生命线。必须记录详细的日志Agent 的思考过程、工具调用、耗时、监控指标请求量、延迟、错误率、Token 消耗和链路追踪一个请求在所有微服务间的流转。使用 Prometheus, Grafana, LangSmith 等工具。6.2 安全、合规与成本控制数据泄露防护确保 Agent 不会在提示词或工具调用中将敏感数据PII发送给外部 LLM API。需要在调用前做数据脱敏。对于本地模型也要注意内部系统的访问权限。工具调用权限不是所有用户都能调用所有工具。需要建立权限体系例如只有财务人员能调用“生成财务报表”工具。这需要在 Agent 调用工具前进行身份认证和授权校验。内容安全与审核对用户的输入和 Agent 的生成结果进行安全过滤防止生成违法、违规或有毒内容。可以接入内容安全 API 或使用本地审核模型。成本控制监控每个请求的 Token 消耗特别是当使用了长上下文、大量检索内容时。设置预算告警和用量限制。对于内部工具可以考虑缓存常见问题的答案。6.3 工作流编排与多 Agent 协同对于复杂业务流程单个 Agent 可能力不从心需要引入工作流引擎和多 Agent 协同。工作流引擎使用LangGraph或n8n这类工具来编排复杂、有状态的流程。LangGraph 更贴近代码适合开发者n8n 是可视化低代码平台适合业务人员参与设计。场景示例一个客户投诉处理流程。先由“分类 Agent”判断投诉类型然后路由给“技术支持 Agent”或“售后 Agent”它们各自调用工具查询订单、知识库如果需要升级再通知“人工坐席 Agent”。多 Agent 协同让多个各有所长的 Agent 合作完成任务。例如一个“规划 Agent”负责拆解任务一个“研究 Agent”负责搜索信息一个“写作 Agent”负责整理报告一个“审核 Agent”负责检查质量。它们通过共享的工作区或消息总线进行通信。AutoGen框架专门为此设计。6.4 持续迭代与评估上线不是终点。需要建立评估体系单元测试为每个工具函数、RAG 检索器写测试。集成测试模拟端到端的用户对话验证整个 Agent 流程。人工评估定期抽样检查 Agent 的处理结果标注好坏形成评估数据集。A/B 测试对比新老版本的 Agent 或不同的提示词策略用真实用户反馈和数据指标任务完成率、用户满意度来决定哪个更好。反馈循环提供用户反馈入口如“这个回答有帮助吗”将不满意的案例加入改进池用于优化提示词、工具或检索策略。7. 学习路径与实战建议面对这么多概念和技术一个可行的学习路径能让你少走弯路。7.1 分阶段学习路线第一阶段建立直觉1-2周目标跑通一个最简单的 Agent 和 RAG。行动用 LangChain OpenAI API按照本文第3、4节的代码亲手实现一个能调用2个工具如计算器、网络搜索模拟的 Agent以及一个基于 TXT/PDF 文档的问答 RAG。关键是要看到完整的输入-处理-输出循环。第二阶段深入核心组件2-4周目标理解每个模块的细节和可选项。行动工具调用尝试更多类型的工具读写文件、调用真实 API学习 ReAct 之外的 Agent 类型如 Plan-and-Execute。RAG 优化体验不同的文本分割策略、换用不同的 Embedding 模型、尝试加入重排序Rerank步骤。用一组问题评估优化前后的效果差异。记忆实现一个能记住对话历史的简单记忆模块。第三阶段系统集成与生产化4周目标搭建一个接近生产可用的原型。行动将 Agent 封装成 REST API。接入真实的向量数据库如 Qdrant。实现简单的异步任务队列。加入日志和基础监控。了解 MCP 协议的概念和前景。第四阶段探索前沿与架构持续目标解决更复杂的问题。行动学习 LangGraph 编排复杂工作流、用 AutoGen 搭建多 Agent 系统、研究 Agentic RAG 模式、关注最新的开源框架和论文。7.2 给新手的避坑指南不要一开始就追求完美架构先用最直接的方式跑通端到端流程哪怕代码很“丑”。有了可工作的原型再考虑重构和优化。重视提示词Prompt但别神话它清晰的指令、上下文和格式要求对 Agent 表现至关重要。但很多问题不是改 Prompt 能解决的可能是工具定义不清、检索结果不准或模型能力边界。日志是你的第一调试工具一定要打开 Agent 执行过程的详细日志verboseTrue。看到它的“思考”过程你才能定位问题到底出在规划、工具调用还是生成阶段。从模拟工具开始在连接真实数据库或内部系统前先用一个返回固定数据的“模拟工具”来验证 Agent 的逻辑是否正确。避免早期陷入网络、权限等无关问题的调试。评估重于感觉不要只靠几个例子判断好坏。准备一个包含各种边界情况的测试集用一致的指标正确性、完整性、相关性来评估每次改动。AI Agent 的开发是一个系统工程它结合了软件工程、提示词工程和大模型能力。最好的学习方式就是动手选一个具体的、小的问题比如“个人旅行规划助手”、“技术文档问答机器人”从零开始搭建遇到问题就查资料、调试。当你完整地走完开发、调试、优化和部署的流程后对这些概念的理解才会真正深刻。 AI Agent开发实战：从工具调用、RAG到MCP协议的完整落地指南
这类教程最值得先看的不是功能列表而是能不能帮你把零散的概念串成一条能跑通的链路。很多人学 AI Agent 时容易卡在“每个词都听过但不知道怎么连起来用”的阶段。2026年的最新进展核心是把架构、工具调用、RAG增强和MCP协议这些模块从理论概念变成了有明确输入、输出和判断标准的生产流程。如果你是想自己动手搭建一个能处理实际任务的智能体或者想理解企业里是怎么把这些技术落地的那这篇梳理会直接告诉你每一步该准备什么、先做什么、成功长什么样、出问题该看哪里。我不会深究每个底层算法的推导而是聚焦在“怎么把它们组装成一个能工作、可调试的系统”上。1. 先拆解“AI Agent”到底在解决什么问题很多人一上来就去看架构图但更容易上手的方式是先明确你要用 Agent 干什么。它不是一个万能的黑盒而是针对特定问题的一套自动化处理流程。1.1 从“聊天”到“做事”的转变传统的大模型对话是你问一句它答一句答案基于训练数据。而 AI Agent 的核心是“做事”它需要能理解复杂指令拆解成步骤调用外部工具比如查数据库、发邮件、执行代码并管理整个执行过程的状态。比如你让它“分析上周销售数据并生成报告邮件发给经理”这就是一个典型的 Agent 任务它需要调用数据查询工具、分析工具、报告生成工具和邮件发送工具。所以判断一个场景是否需要 Agent就看这个任务是否需要多步骤决策和与外部系统交互。如果只是简单问答用增强后的 RAG 可能就够了如果需要串联多个动作并处理过程中的不确定性那就得上 Agent。1.2 智能体的基本组成大脑、记忆与手脚一个可运行的 Agent 通常由几个核心模块组成理解这些模块是后续搭建的基础大脑推理与规划通常是一个大语言模型LLM。它负责理解用户意图、拆解任务、制定计划Plan和在执行中做决策Reasoning。这是 Agent 的“指挥官”。记忆短期与长期Agent 需要有记忆来保存对话历史短期记忆和从过往经验中学习长期记忆。这能让它在多轮交互中保持上下文避免重复或矛盾。简单的实现可以用对话历史列表复杂的会引入向量数据库来存储和检索相关经验。工具手脚这是 Agent 与真实世界交互的接口。工具可以是一个函数、一个 API、一个命令行程序。比如search_web搜索、execute_sql查数据库、send_email发邮件。Agent 需要知道在什么情况下调用哪个工具并处理工具的返回结果。工作流协调器当任务复杂时可能需要多个 Agent 协同Multi-Agent或者一个 Agent 内部有复杂的执行循环如 ReAct 模式思考-行动-观察。工作流引擎负责调度这些步骤处理分支、循环和错误。搭建时不要试图一次性实现所有模块。我建议先从“一个能调用简单工具的单一 Agent”开始跑通整个循环再逐步增加记忆、复杂工作流和多 Agent 协同。2. 环境与工具准备选型决定上手速度在写第一行代码之前选对工具栈能省掉一大半的折腾时间。2026年的生态已经比较成熟不需要从零造轮子。2.1 核心框架与平台选择目前主要有两类选择开源框架和低代码平台。开源框架适合开发者灵活度高LangChain / LangGraph生态最丰富社区活跃文档和示例多。LangChain 用于构建链LangGraph 专门用于构建有状态的、多环节的工作流Agent 本质就是一种工作流。入门时可能会觉得概念多但它是理解 Agent 组件的最佳教材之一。LlamaIndex如果你构建的 Agent 严重依赖 RAG从私有数据中获取信息LlamaIndex 在数据连接、索引和检索方面更专精可以很好地与 LangChain 配合使用。Semantic Kernel (Microsoft)与 .NET 生态结合紧密概念清晰Plugins, Planners, Memories。如果你主要使用 C# 或 Azure 云服务这是个好选择。AutoGen (Microsoft)专注于多 Agent 对话和协作预设了多种 Agent 角色如 UserProxy, Assistant能快速搭建多 Agent 讨论场景。低代码/云平台适合快速原型和业务人员Dify, Flowise这类平台提供了可视化编排工作流的能力。你可以通过拖拽组件LLM、工具、条件判断来构建 Agent无需深入编码。对于验证想法和构建内部工具非常快但自定义复杂逻辑和深度调试可能受限。怎么选如果目标是学习和深度控制从 LangChain 开始。如果目标是快速给业务部门做一个演示或内部工具用 Dify 这类平台可能几小时就能出原型。2.2 大模型 API 与本地部署Agent 的大脑需要一个大模型。你有两个选择调用云端 APIOpenAI GPT-4/4o, Anthropic Claude, 国内各大厂的模型。优点是不用操心部署性能稳定功能新。缺点是持续使用有成本且数据需要出境国内模型无此问题。对于学习和原型开发这是最快的方式。本地部署开源模型使用 Ollama, LM Studio 或 vLLM 等工具在本地运行 Llama、Qwen、DeepSeek 等模型。优点是数据完全私有无网络延迟长期成本可能更低。缺点是对硬件GPU 内存有要求模型能力可能略逊于顶级闭源模型。起步建议直接用 OpenAI 或 Claude 的 API。先确保你的 Agent 逻辑是正确的再考虑成本和数据隐私问题将大脑替换为本地模型。这样能避免早期同时调试模型部署和 Agent 逻辑两方面的复杂问题。2.3 其他基础设施向量数据库用于实现 RAG 和长期记忆。轻量级起步可以用ChromaDB内存型简单或FAISSFacebook 开源的高效相似性搜索库。生产环境可以考虑Qdrant,Weaviate,Milvus等它们支持持久化、分布式和更丰富的过滤条件。Spring AI 2.0 与 Qdrant 的集成就是一个企业级 RAG 的常见组合。开发环境Python 3.9 是主流。准备好虚拟环境conda 或 venv管理好依赖包版本这是避免“在我机器上能跑”问题的第一步。3. 核心环节一让 Agent 学会使用工具Tool Calling工具调用是 Agent 从“空想”到“实干”的关键一步。这里的目标是让 LLM 能根据你的描述在合适的时机调用正确的工具并理解返回结果。3.1 如何定义工具工具本质上是一个函数你需要用框架能理解的方式描述它。以 LangChain 为例from langchain.tools import tool from langchain.agents import AgentExecutor, create_react_agent from langchain import hub # 1. 定义一个简单的计算器工具 tool def calculator(expression: str) - str: 计算一个数学表达式。例如calculator(\2 2\) 返回 4。 try: # 安全提示生产环境请勿使用eval此处仅为示例 result eval(expression) return f计算结果: {result} except Exception as e: return f计算错误: {e} # 2. 定义一个查询天气的工具模拟 tool def get_weather(city: str) - str: 查询指定城市的天气。 # 这里应该调用真实的天气API返回模拟数据 return f{city}的天气是晴朗25摄氏度。 # 将工具放入列表 tools [calculator, get_weather]关键点在于tool装饰器和函数文档字符串docstring。LLM 主要靠这个文档字符串来理解工具的用途、输入参数和格式。所以文档字符串要写得清晰、具体包含示例。3.2 创建 Agent 并执行有了工具你需要一个 Agent 来使用它们。ReAct 模式是一个经典且有效的起点。# 3. 选择LLM这里以ChatOpenAI为例需设置你的API_KEY from langchain_openai import ChatOpenAI llm ChatOpenAI(modelgpt-4o, temperature0) # 4. 获取一个预设的ReAct提示词模板 prompt hub.pull(hwchase17/react) # 5. 创建ReAct Agent agent create_react_agent(llm, tools, prompt) # 6. 创建执行器 agent_executor AgentExecutor(agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue) # 7. 运行 result agent_executor.invoke({ input: 请问北京现在的天气怎么样如果温度高于20度就计算一下温度5的平方是多少。 }) print(result[output])当你运行这段代码并设置verboseTrue时会在控制台看到 Agent 的思考过程Thought: 用户想知道北京天气然后根据温度做一个计算。我需要先调用天气工具。 Action: get_weather Action Input: {city: 北京} Observation: 北京的天气是晴朗25摄氏度。 Thought: 现在温度是25度高于20度。我需要计算255的平方。我需要调用计算器工具。 Action: calculator Action Input: {expression: (255)**2} Observation: 计算结果: 900 Thought: 我得到了所有信息可以回答用户了。 Final Answer: 北京现在天气晴朗25摄氏度。因为温度高于20度我计算了255的平方结果是900。这就是工具调用的核心流程思考Thought- 决定行动Action- 执行工具Action Input- 观察结果Observation- 继续思考。verboseTrue是调试 Agent 逻辑的利器一定要善用。3.3 常见问题与排查工具不被调用首先检查工具的文档字符串是否清晰。LLM 可能无法理解工具的用途。其次检查提示词Prompt确保它鼓励 Agent 使用工具。ReAct 模板通常已经优化过这一点。工具输入格式错误LLM 有时会生成不符合工具函数参数格式的输入。使用handle_parsing_errorsTrue可以让执行器尝试修复小错误。更稳妥的做法是在工具函数内部做好参数校验和类型转换。无限循环或错误使用工具Agent 可能陷入“思考-调用-失败-再思考”的循环。可以设置max_iterations最大迭代次数和max_execution_time最大执行时间来强制终止。例如AgentExecutor(..., max_iterations10, max_execution_time30)。4. 核心环节二用 RAG 为 Agent 注入专业知识如果 Agent 只能调用通用工具那它还是个“通才”。RAG检索增强生成能让它变成某个垂直领域的“专家”比如回答公司内部文档问题、分析特定技术资料。4.1 RAG 全链路拆解不止是向量检索一个完整的 RAG 系统远不止“文本切块-向量化-搜索”那么简单。企业级应用时痛点往往出现在全链路的各个环节文档加载与解析支持 PDF、Word、PPT、HTML、Markdown、数据库等。痛点格式复杂扫描版PDF、表格、图表导致信息提取不全或错乱。文本分割切块策略直接影响效果。盲目按固定字符数切分如 500 字一块会割裂语义。更好的策略是按语义分割使用自然语言处理NLP模型识别段落、句子边界。递归分割先按大标题分再按小标题分最后按段落分形成层次结构。重叠分割让相邻块有部分文字重叠避免答案恰好被切在块边界。向量化与索引将文本块转换为向量Embedding存入向量数据库。痛点Embedding 模型对专业术语表征能力不足索引速度慢影响实时性。检索用户提问时将问题也向量化从数据库中找出最相似的几个文本块Top-K。痛点单纯的余弦相似度可能检索不准需要结合关键词过滤Metadata Filtering如按文档类型、日期过滤和重排序Rerank模型来提升精度。增强生成将检索到的文本块作为上下文连同问题一起送给 LLM让它生成答案。痛点上下文太长超出模型限制上下文包含无关或矛盾信息导致答案“幻觉”。4.2 动手搭建一个简单的 RAG 系统我们用 LangChain 和 Chroma 快速实现一个基础版让你感受全流程。from langchain_community.document_loaders import TextLoader from langchain_text_splitters import RecursiveCharacterTextSplitter from langchain_openai import OpenAIEmbeddings, ChatOpenAI from langchain_community.vectorstores import Chroma from langchain.chains import RetrievalQA # 1. 加载文档这里用文本文件示例 loader TextLoader(./公司制度.txt, encodingutf-8) documents loader.load() # 2. 分割文本 text_splitter RecursiveCharacterTextSplitter( chunk_size500, # 每个块大小 chunk_overlap50, # 重叠大小 length_functionlen, separators[\n\n, \n, 。, , , , , ] # 递归分割符 ) docs text_splitter.split_documents(documents) # 3. 创建向量存储 embeddings OpenAIEmbeddings() # 需要OPENAI_API_KEY vectorstore Chroma.from_documents(documentsdocs, embeddingembeddings, persist_directory./chroma_db) # 持久化到本地目录下次可直接加载 # 4. 创建检索器 retriever vectorstore.as_retriever(search_kwargs{k: 3}) # 检索最相似的3个块 # 5. 创建问答链 llm ChatOpenAI(modelgpt-4o, temperature0) qa_chain RetrievalQA.from_chain_type( llmllm, chain_typestuff, # 简单地将所有检索到的上下文“塞”进提示词 retrieverretriever, return_source_documentsTrue # 返回来源文档便于溯源 ) # 6. 提问 question 我们公司的年假制度是怎样的 result qa_chain.invoke({query: question}) print(答案:, result[result]) print(\n来源文档:) for doc in result[source_documents]: print(f- {doc.page_content[:200]}...) # 打印前200字符这个流程跑通后你就有了一个最简单的知识库问答系统。但这就是 RAG 的全部吗远不是。这只是一个起点。4.3 从“能用”到“好用”RAG 的优化实战企业级 RAG 的痛点需要针对性优化检索质量差找不准优化 Embedding 模型尝试text-embedding-3-small/large或开源模型如BGE-M3、voyage-2在专业语料上微调效果更佳。引入重排序Rerank使用 Cohere Rerank、BGE Reranker 等模型对初步检索结果重新打分排序把最相关的排到最前面。这能显著提升精度尤其是当 Top-K 设置较大时。混合检索Hybrid Search结合向量检索语义相似和关键词检索如 BM25字面匹配。有些问题用关键词更准如产品型号“ABC-123”。生成答案有幻觉编造引用溯源Groundedness要求 LLM 在生成答案时必须引用来源文档的片段。这既能增强可信度也方便人工核查。在提示词Prompt中明确指令“请基于以下上下文回答并引用相关段落。”Prompt 工程设计更好的提示词如“如果上下文信息不足以回答问题请直接说‘根据现有资料无法回答’不要编造信息。”处理复杂问题多跳问答Agentic RAG这就是将 RAG 和 Agent 结合。让 Agent 来主导检索过程。例如对于一个复杂问题“我们产品A和竞争对手B在Q3的销量对比如何”Agent 可以规划第一步检索产品A的Q3销售报告第二步检索竞争对手B的市场分析第三步调用计算工具进行对比第四步生成最终报告。这比一次性检索所有信息更精准。评估 RAG 系统不能只靠感觉。可以看几个指标检索命中率检索到的块是否包含答案、答案相关性、事实准确性与源文档对比、引用正确率。用一批测试问题来量化评估。5. 核心环节三理解 MCP 协议——工具的“通用插座”当你为 Agent 开发了越来越多的工具会发现一个麻烦每个框架LangChain, AutoGen等定义工具的方式略有不同工具也难以在不同项目间复用。这就是MCPModel Context Protocol要解决的问题。5.1 MCP 是什么为什么需要它你可以把 MCP 想象成工具的“USB-C 接口”或“通用插座”。它是一个开放协议定义了工具、数据源如何以一种标准化的方式向 LLM 应用如 Agent描述自己、提供能力。在没有 MCP 之前你在 LangChain 里写了一个tool。换到另一个基于 Claude 的 Agent 平台可能得用它的 SDK 重新定义一遍。工具的逻辑比如连接公司数据库的代码是相同的但“包装形式”要改。有了 MCP 之后你按照 MCP 协议的标准格式将你的数据库连接能力写成一个MCP 服务器。任何支持 MCP 协议的客户端比如 Claude Desktop, 新的 LangChain 版本都能自动发现、加载并使用这个工具。一次开发处处可用。工具实现了与上层应用框架的解耦。5.2 MCP 的核心概念与工作流程MCP 服务器Server提供工具和数据源的一方。它暴露出一些“资源”Resources如数据库表、API端点和“工具”Tools如查询、更新操作。服务器启动后等待客户端连接。MCP 客户端Client使用工具的一方比如 Claude Desktop、你的自定义 Agent 应用。客户端通过标准方式如 stdio 或 HTTP连接到服务器获取服务器提供的资源和工具列表。协议通信客户端和服务器通过 JSON-RPC 消息进行通信。消息类型包括list_tools列出工具、call_tool调用工具、read_resource读取资源等。一个简化的工作流你写了一个CompanyDBServer它通过 MCP 协议提供了query_sales_data工具。你在 Claude Desktop 中配置它连接到这个服务器。你在 Claude 的聊天框里说“帮我查一下上海地区本季度的销售数据。”Claude作为 MCP 客户端自动识别出这个请求可以调用query_sales_data工具它通过 MCP 协议向你的服务器发送call_tool请求。你的服务器执行真正的数据库查询并将结果通过 MCP 协议返回给 Claude。Claude 将结果组织成自然语言回复给你。5.3 对开发者的意义工具生态标准化未来可能会出现一个“MCP 工具市场”你可以像安装插件一样为你的 Agent 添加天气预报、股票查询、项目管理等各种能力而无需关心底层是哪个框架。关注点分离你可以专注于编写工具的核心业务逻辑MCP 服务器而让不同的前端Chatbot, Agent 框架低代码平台来消费它。安全与管控企业可以统一开发和部署 MCP 服务器严格控制内部工具如何被 LLM 访问而不是在每个应用里重复编写和授权。目前MCP 主要由 Anthropic 推动但正在成为行业趋势。学习它意味着你在为未来更模块化、更开放的 Agent 开发模式做准备。即使你现在不深入实现理解这个概念也能帮你更好地规划工具层。6. 企业级应用落地从 Demo 到生产系统把单个 Agent 跑通只是第一步。要把它变成企业里一个可靠的生产系统需要跨越好几个台阶。6.1 架构设计考量单体 vs 微服务简单的内部工具可以是一个单体应用。但如果涉及多个部门、高并发、独立扩缩容就需要将 Agent 核心、工具服务、RAG 索引服务等拆分成微服务。状态管理Agent 对话是有状态的。在 Web 应用中需要为每个用户会话维护独立的状态记忆、对话历史。不能把状态简单放在内存里需要用 Redis、数据库或专门的会话存储来管理。异步与流式响应复杂的 Agent 任务可能耗时很长几十秒。必须采用异步处理如 Celery 任务队列和流式响应Server-Sent Events 或 WebSocket让用户能看到实时进展而不是一直白屏等待。可观测性这是生产系统的生命线。必须记录详细的日志Agent 的思考过程、工具调用、耗时、监控指标请求量、延迟、错误率、Token 消耗和链路追踪一个请求在所有微服务间的流转。使用 Prometheus, Grafana, LangSmith 等工具。6.2 安全、合规与成本控制数据泄露防护确保 Agent 不会在提示词或工具调用中将敏感数据PII发送给外部 LLM API。需要在调用前做数据脱敏。对于本地模型也要注意内部系统的访问权限。工具调用权限不是所有用户都能调用所有工具。需要建立权限体系例如只有财务人员能调用“生成财务报表”工具。这需要在 Agent 调用工具前进行身份认证和授权校验。内容安全与审核对用户的输入和 Agent 的生成结果进行安全过滤防止生成违法、违规或有毒内容。可以接入内容安全 API 或使用本地审核模型。成本控制监控每个请求的 Token 消耗特别是当使用了长上下文、大量检索内容时。设置预算告警和用量限制。对于内部工具可以考虑缓存常见问题的答案。6.3 工作流编排与多 Agent 协同对于复杂业务流程单个 Agent 可能力不从心需要引入工作流引擎和多 Agent 协同。工作流引擎使用LangGraph或n8n这类工具来编排复杂、有状态的流程。LangGraph 更贴近代码适合开发者n8n 是可视化低代码平台适合业务人员参与设计。场景示例一个客户投诉处理流程。先由“分类 Agent”判断投诉类型然后路由给“技术支持 Agent”或“售后 Agent”它们各自调用工具查询订单、知识库如果需要升级再通知“人工坐席 Agent”。多 Agent 协同让多个各有所长的 Agent 合作完成任务。例如一个“规划 Agent”负责拆解任务一个“研究 Agent”负责搜索信息一个“写作 Agent”负责整理报告一个“审核 Agent”负责检查质量。它们通过共享的工作区或消息总线进行通信。AutoGen框架专门为此设计。6.4 持续迭代与评估上线不是终点。需要建立评估体系单元测试为每个工具函数、RAG 检索器写测试。集成测试模拟端到端的用户对话验证整个 Agent 流程。人工评估定期抽样检查 Agent 的处理结果标注好坏形成评估数据集。A/B 测试对比新老版本的 Agent 或不同的提示词策略用真实用户反馈和数据指标任务完成率、用户满意度来决定哪个更好。反馈循环提供用户反馈入口如“这个回答有帮助吗”将不满意的案例加入改进池用于优化提示词、工具或检索策略。7. 学习路径与实战建议面对这么多概念和技术一个可行的学习路径能让你少走弯路。7.1 分阶段学习路线第一阶段建立直觉1-2周目标跑通一个最简单的 Agent 和 RAG。行动用 LangChain OpenAI API按照本文第3、4节的代码亲手实现一个能调用2个工具如计算器、网络搜索模拟的 Agent以及一个基于 TXT/PDF 文档的问答 RAG。关键是要看到完整的输入-处理-输出循环。第二阶段深入核心组件2-4周目标理解每个模块的细节和可选项。行动工具调用尝试更多类型的工具读写文件、调用真实 API学习 ReAct 之外的 Agent 类型如 Plan-and-Execute。RAG 优化体验不同的文本分割策略、换用不同的 Embedding 模型、尝试加入重排序Rerank步骤。用一组问题评估优化前后的效果差异。记忆实现一个能记住对话历史的简单记忆模块。第三阶段系统集成与生产化4周目标搭建一个接近生产可用的原型。行动将 Agent 封装成 REST API。接入真实的向量数据库如 Qdrant。实现简单的异步任务队列。加入日志和基础监控。了解 MCP 协议的概念和前景。第四阶段探索前沿与架构持续目标解决更复杂的问题。行动学习 LangGraph 编排复杂工作流、用 AutoGen 搭建多 Agent 系统、研究 Agentic RAG 模式、关注最新的开源框架和论文。7.2 给新手的避坑指南不要一开始就追求完美架构先用最直接的方式跑通端到端流程哪怕代码很“丑”。有了可工作的原型再考虑重构和优化。重视提示词Prompt但别神话它清晰的指令、上下文和格式要求对 Agent 表现至关重要。但很多问题不是改 Prompt 能解决的可能是工具定义不清、检索结果不准或模型能力边界。日志是你的第一调试工具一定要打开 Agent 执行过程的详细日志verboseTrue。看到它的“思考”过程你才能定位问题到底出在规划、工具调用还是生成阶段。从模拟工具开始在连接真实数据库或内部系统前先用一个返回固定数据的“模拟工具”来验证 Agent 的逻辑是否正确。避免早期陷入网络、权限等无关问题的调试。评估重于感觉不要只靠几个例子判断好坏。准备一个包含各种边界情况的测试集用一致的指标正确性、完整性、相关性来评估每次改动。AI Agent 的开发是一个系统工程它结合了软件工程、提示词工程和大模型能力。最好的学习方式就是动手选一个具体的、小的问题比如“个人旅行规划助手”、“技术文档问答机器人”从零开始搭建遇到问题就查资料、调试。当你完整地走完开发、调试、优化和部署的流程后对这些概念的理解才会真正深刻。