这次我们来看一套号称“B站最全最细”的AI Agent零基础教程。这套教程的核心价值在于它没有停留在概念层面而是将AI Agent、RAG、MCP、LangChain、LangGraph这些热门技术栈打包并串联成一套从零到一、再到企业级实战的完整学习路径。对于想快速上手AI Agent开发但又苦于资料零散、缺乏实践项目的开发者来说这套教程提供了一个结构化的解决方案。本文不会复述视频内容而是基于这套教程涵盖的技术栈为你梳理出一条清晰的本地学习与实践路线。我们将重点关注如何搭建一个可运行的AI Agent开发环境如何理解并实践RAG、MCP等核心组件以及如何将这些技术整合成一个具备实际功能的智能体项目。整个过程会聚焦于“能不能跑起来”和“怎么用起来”包括环境依赖、关键代码示例、常见坑点以及效果验证。无论你是想入门AI Agent的在校学生还是希望将智能体技术应用于业务场景的工程师这篇文章都将为你提供一个可落地的实操指南。我们将从最基础的环境配置开始逐步深入到Agent的决策逻辑、RAG的知识库构建、MCP的工具扩展最终完成一个综合性的项目实战。1. 核心能力速览本教程所覆盖的技术栈组合旨在构建一个功能完整、可扩展的AI Agent系统。下表概括了其核心组成部分及对应的能力能力项说明项目类型AI Agent 综合学习与实践教程涵盖从基础到实战的全链路。技术栈AI Agent (智能体) RAG (检索增强生成) MCP (模型上下文协议) LangChain LangGraph。主要功能1.智能体构建让LLM具备规划、使用工具、执行多步任务的能力。2.RAG系统为LLM接入私有知识库实现精准问答。3.工具扩展通过MCP协议让Agent安全、标准化地调用外部工具如数据库、API。4.工作流编排使用LangGraph实现复杂、有状态的Agent工作流。硬件门槛开发阶段普通CPU/GPU均可主要依赖LLM API如OpenAI、DeepSeek或本地轻量模型。本地RAG/Agent如需本地运行嵌入模型或轻量级LLM建议8GB以上内存GPU非必须但可加速。启动方式基于Python环境通过命令行启动Jupyter Notebook、脚本或Web服务如Flask/FastAPI。是否支持API是。最终构建的Agent系统可以封装为RESTful API或GraphQL接口提供服务。是否支持批量任务是。通过任务队列如Celery或异步处理可以设计批量文档处理、批量问答等场景。适合场景1.个人学习零基础入门AI Agent与RAG。2.原型验证快速搭建智能客服、知识库问答、自动化流程等PoC。3.企业级应用基于模块化设计扩展为复杂的业务自动化系统。2. 适用场景与使用边界这套教程和其代表的技术栈并非万能明确其适用边界能帮助你更好地决策。适合谁用初学者对AI Agent感兴趣但不知从何下手。教程提供了结构化的学习路径。全栈/后端开发者希望将LLM能力集成到现有系统中构建智能应用。产品经理/业务分析师需要通过实践理解AI Agent的能力边界以设计更合理的AI产品功能。学生与研究爱好者寻找一个完整的、可复现的AI Agent项目作为学习或研究基础。能解决什么问题信息过载与精准问答通过RAG让大模型能够基于你提供的专属文档公司wiki、产品手册、个人笔记进行回答避免“幻觉”。任务自动化通过Agent让大模型自动分解复杂任务如“分析上周销售数据并写份报告”并调用工具查数据库、画图表、发邮件逐步完成。能力扩展与集成通过MCP以一种标准化的方式为Agent增加新能力如操作Figma、查询数据库、控制智能家居而无需大量定制代码。复杂流程编排通过LangGraph设计具有循环、分支、状态保持的复杂Agent工作流例如多轮审核、交互式诊断等。不适合什么场景追求极致单任务性能如果只是简单的文本生成或分类直接调用大模型API更简单高效。对延迟极其敏感RAG检索、Agent多步思考、工具调用都会增加延迟不适合实时性要求极高的场景。完全离线且资源受限若必须在无网络、低算力设备运行需要精心选择微型模型性能会大打折扣。缺乏明确流程的创造性任务Agent擅长执行有逻辑、可分解的任务对于天马行空的纯艺术创作其价值有限。合规与安全边界数据安全使用RAG时你的知识库文档可能包含敏感信息。务必确保嵌入模型、向量数据库部署在可信环境并管理好API密钥。工具调用风险Agent通过MCP调用工具如删除文件、发送消息具有实际影响力。必须在沙箱或严格权限控制下测试并设置用户确认机制。内容合规Agent生成的内容需符合法律法规。需要在系统层面设置内容过滤和审核策略。版权与授权为RAG系统添加的文档需确保你有使用权。Agent生成的内容若用于商业发布需注意版权风险。3. 环境准备与前置条件开始实践前需要准备好开发环境。以下是一个通用的、与教程技术栈匹配的环境清单。操作系统推荐Linux (Ubuntu 20.04) 或 macOS。Windows 10/11 也可行但可能在某些依赖安装上遇到小问题建议使用WSL2。核心要求能安装Python 3.10 和 pip。Python环境版本Python 3.10 或 3.11。这是LangChain等库兼容性最好的版本。管理工具强烈建议使用conda或venv创建独立的虚拟环境避免包冲突。# 使用 conda 创建环境 conda create -n ai-agent python3.10 conda activate ai-agent # 或使用 venv python -m venv ai-agent-env # Linux/macOS source ai-agent-env/bin/activate # Windows ai-agent-env\Scripts\activate核心依赖包基础环境准备好后需要安装核心库。以下是一个requirements.txt的示例你可以根据项目进度分批安装。# 核心框架 langchain0.1.0 langchain-community0.0.10 langgraph0.0.17 # 大模型接口 (以OpenAI为例也可换为其他) openai1.3.0 langchain-openai0.0.2 # 向量数据库与嵌入 (以Chroma为例) chromadb0.4.22 langchain-chroma0.1.0 sentence-transformers2.2.2 # 用于本地嵌入模型 # RAG相关 unstructured0.10.30 # 文档解析 pypdf3.17.4 # PDF处理 markdown3.5.1 # Web框架 (用于提供API) fastapi0.104.1 uvicorn[standard]0.24.0 # 工具调用与MCP (示例) mcp1.0.0 # 假设的MCP客户端库实际需根据具体实现调整 # 其他工具 python-dotenv1.0.0 # 管理环境变量 requests2.31.0使用pip安装pip install -r requirements.txtLLM访问权限云端API你需要一个可用的LLM API密钥如 OpenAI API Key、DeepSeek API Key、文心一言API Key等。将其保存在.env文件中。# .env 文件示例 OPENAI_API_KEYsk-your-key-here OPENAI_BASE_URLhttps://api.openai.com/v1 # 或国内代理地址本地模型可选如果想完全本地运行需要部署兼容OpenAI API的本地模型服务如 Ollama、LM Studio、vLLM并准备相应的模型文件。这对硬件有一定要求。开发工具代码编辑器VS Code 或 PyCharm。Jupyter Notebook可选用于分步骤学习和实验。pip install jupyter4. 安装部署与启动方式本教程涉及多个模块通常以Jupyter Notebook分章节学习最终整合为一个可运行的Python脚本或Web服务。以下是典型的启动流程。4.1 获取教程代码与资源假设教程材料以代码仓库形式提供。# 克隆示例仓库 (此处为示意实际仓库地址需替换) git clone https://github.com/example/ai-agent-tutorial.git cd ai-agent-tutorial4.2 分模块学习与运行教程可能按模块组织每个模块是一个独立的Notebook或脚本。LangChain基础运行01_langchain_basics.ipynb学习Prompt、Chain、Memory等基础概念。RAG系统搭建运行02_build_rag_system.ipynb学习文档加载、切分、向量化存储与检索。Agent与Tools运行03_create_agent_with_tools.ipynb学习如何定义工具并让Agent调用。LangGraph工作流运行04_langgraph_workflow.ipynb学习用图的方式编排复杂Agent逻辑。MCP集成运行05_integrate_mcp.ipynb学习如何通过MCP协议接入外部工具。4.3 启动综合Agent服务学完各部分后通常会有一个综合的app.py或main.py启动一个Web服务来提供Agent能力。# 启动一个基于FastAPI的Agent服务 python app.py # 或使用uvicorn直接启动 uvicorn app:app --host 0.0.0.0 --port 8000 --reload启动后在浏览器访问http://localhost:8000/docs即可看到自动生成的API文档。4.4 一键启动脚本高级对于企业级项目可能会提供docker-compose.yml或启动脚本。# Docker Compose 示例 docker-compose up -d # 或使用启动脚本 ./start.sh这种方式通常会同时启动向量数据库如Chroma、Agent API服务、任务队列等组件。5. 功能测试与效果验证下面我们针对教程涵盖的核心技术点设计一套验证流程确保每个部分都能按预期工作。5.1 RAG知识库问答测试测试目的验证文档加载、向量化、检索和答案生成的完整流程是否通畅。操作步骤准备测试文档创建一个test_docs/目录放入一份PDF或TXT格式的产品说明书。运行知识库构建脚本将文档切片、生成向量并存入向量数据库。# build_knowledge_base.py 示例片段 from langchain_community.document_loaders import PyPDFLoader from langchain.text_splitter import RecursiveCharacterTextSplitter from langchain_huggingface import HuggingFaceEmbeddings from langchain_chroma import Chroma loader PyPDFLoader(./test_docs/product_manual.pdf) documents loader.load() text_splitter RecursiveCharacterTextSplitter(chunk_size500, chunk_overlap50) splits text_splitter.split_documents(documents) embeddings HuggingFaceEmbeddings(model_nameall-MiniLM-L6-v2) vectorstore Chroma.from_documents(documentssplits, embeddingembeddings, persist_directory./chroma_db) print(知识库构建完成)运行问答测试脚本针对文档内容提问。# test_rag.py 示例片段 from langchain_chroma import Chroma from langchain_huggingface import HuggingFaceEmbeddings from langchain.chains import RetrievalQA from langchain_openai import ChatOpenAI import os from dotenv import load_dotenv load_dotenv() embeddings HuggingFaceEmbeddings(model_nameall-MiniLM-L6-v2) vectorstore Chroma(persist_directory./chroma_db, embedding_functionembeddings) llm ChatOpenAI(modelgpt-3.5-turbo, api_keyos.getenv(OPENAI_API_KEY)) qa_chain RetrievalQA.from_chain_type(llm, retrievervectorstore.as_retriever()) question 这款产品的主要特性是什么 result qa_chain.invoke({query: question}) print(f问题{question}) print(f答案{result[result]})预期结果脚本能成功运行并输出一个基于产品说明书内容生成的、准确的答案。失败排查文档加载失败检查文件路径、格式确保已安装pypdf或unstructured。向量化失败检查网络如需下载模型或嵌入模型名称。检索无结果检查chunk_size是否合适或尝试不同的文本分割器。答案质量差调整检索的k值返回文档数量或优化提示词。5.2 基础Agent工具调用测试测试目的验证Agent能否正确理解任务、选择并执行工具。操作步骤定义一个简单的工具例如计算器或获取当前时间。# define_tools.py from langchain.tools import tool import datetime tool def get_current_time(timezone: str Asia/Shanghai) - str: 获取指定时区的当前时间。 # 简化实现实际应使用pytz等库 now datetime.datetime.now() return now.strftime(%Y-%m-%d %H:%M:%S) tool def calculator(expression: str) - str: 计算一个数学表达式的结果。 try: # 警告使用eval有安全风险仅用于演示 result eval(expression) return str(result) except Exception as e: return f计算错误{e}创建Agent并测试。# test_agent.py from langchain_openai import ChatOpenAI from langchain.agents import AgentExecutor, create_tool_calling_agent from langchain.prompts import ChatPromptTemplate import os from dotenv import load_dotenv from define_tools import get_current_time, calculator load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, api_keyos.getenv(OPENAI_API_KEY)) tools [get_current_time, calculator] prompt ChatPromptTemplate.from_messages([ (system, 你是一个有帮助的助手可以调用工具来回答问题。), (human, {input}), (placeholder, {agent_scratchpad}), ]) agent create_tool_calling_agent(llm, tools, prompt) agent_executor AgentExecutor(agentagent, toolstools, verboseTrue) # 测试 result1 agent_executor.invoke({input: 现在上海时间是几点}) print(result1[output]) result2 agent_executor.invoke({input: 计算一下(15 7) * 3 等于多少}) print(result2[output])预期结果Agent能正确调用get_current_time和calculator工具并返回结果。失败排查Agent不调用工具检查提示词prompt格式是否符合create_tool_calling_agent要求或尝试更换LLM模型gpt-4的工具调用能力更强。工具执行错误检查工具函数的输入输出格式是否符合LangChain Tool的规范。5.3 LangGraph工作流测试测试目的验证能否用LangGraph构建一个具有状态和循环的多步骤Agent。操作步骤定义一个简单的审批工作流提交申请 - 条件判断 - 批准/拒绝 - 结束。# test_langgraph.py from typing import TypedDict, Annotated, List import operator from langgraph.graph import StateGraph, END from langchain_openai import ChatOpenAI from langchain_core.messages import HumanMessage import os from dotenv import load_dotenv load_dotenv() llm ChatOpenAI(modelgpt-3.5-turbo, api_keyos.getenv(OPENAI_API_KEY)) # 1. 定义状态 class AgentState(TypedDict): messages: Annotated[List, operator.add] # 消息列表 decision: str # 决策结果 # 2. 定义节点函数 def submit_application(state: AgentState): 提交申请节点 return {messages: [HumanMessage(content我申请购买一台新笔记本预算8000元。)]} def review_application(state: AgentState): 审批节点由LLM判断 last_message state[messages][-1].content response llm.invoke(f作为审批员请审核以下申请{last_message}。只需回复‘批准’或‘拒绝’。) decision response.content.strip() return {decision: decision} def approve_action(state: AgentState): 批准后的动作 return {messages: [HumanMessage(contentf申请已批准决策{state[decision]})]} def reject_action(state: AgentState): 拒绝后的动作 return {messages: [HumanMessage(contentf申请被拒绝。决策{state[decision]})]} # 3. 构建图 workflow StateGraph(AgentState) workflow.add_node(submit, submit_application) workflow.add_node(review, review_application) workflow.add_node(approve, approve_action) workflow.add_node(reject, reject_action) workflow.set_entry_point(submit) workflow.add_edge(submit, review) # 4. 条件边根据review节点的结果决定流向 def decide_next_step(state: AgentState): if state[decision] 批准: return approve else: return reject workflow.add_conditional_edges(review, decide_next_step, {approve: approve, reject: reject}) workflow.add_edge(approve, END) workflow.add_edge(reject, END) # 5. 编译并运行 app workflow.compile() initial_state {messages: [], decision: } result app.invoke(initial_state) for msg in result[messages]: print(f{msg.type}: {msg.content}) print(f最终决策{result[decision]})预期结果工作流能顺利执行根据LLM的“审批”结果正确流向“批准”或“拒绝”分支并输出相应信息。失败排查图编译错误检查StateGraph和节点的添加顺序确保入口点和边正确连接。LLM判断不固定调整给LLM的指令使其输出更稳定或加入后处理逻辑。6. 接口API与批量任务一个成熟的AI Agent系统需要提供稳定的API接口和批量处理能力。6.1 封装为FastAPI服务将上述RAG或Agent功能封装成Web API便于集成。# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel from typing import List import uvicorn from your_agent_module import get_agent_executor # 假设你的Agent逻辑在这里 app FastAPI(titleAI Agent API) class QueryRequest(BaseModel): question: str session_id: str None # 用于多轮对话 class BatchRequest(BaseModel): queries: List[str] app.post(/v1/chat) async def chat_with_agent(request: QueryRequest): 与Agent单次对话 try: agent_executor get_agent_executor() result agent_executor.invoke({input: request.question}) return {answer: result[output], session_id: request.session_id} except Exception as e: raise HTTPException(status_code500, detailstr(e)) app.post(/v1/batch_process) async def batch_process(request: BatchRequest): 批量处理问题简易版实际应用需异步队列 responses [] agent_executor get_agent_executor() for query in request.queries: try: result agent_executor.invoke({input: query}) responses.append({question: query, answer: result[output]}) except Exception as e: responses.append({question: query, error: str(e)}) return {results: responses} if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)启动服务后即可通过curl或 Pythonrequests调用。curl -X POST http://localhost:8000/v1/chat \ -H Content-Type: application/json \ -d {question: 今天天气怎么样}6.2 实现异步批量任务对于大量文档处理或长时间任务需要使用异步任务队列如Celery Redis。# tasks.py (Celery示例) from celery import Celery from your_rag_module import process_document # 你的文档处理函数 app Celery(agent_tasks, brokerredis://localhost:6379/0, backendredis://localhost:6379/0) app.task def async_build_rag_from_file(file_path: str, collection_name: str): 异步任务处理文档并构建RAG知识库 try: result process_document(file_path, collection_name) return {status: success, collection: collection_name, chunks: result} except Exception as e: return {status: failed, error: str(e)}在API中调用异步任务# 在FastAPI app.py中 from tasks import async_build_rag_from_file app.post(/v1/ingest_document) async def ingest_document(file_url: str, collection: str): task async_build_rag_from_file.delay(file_url, collection) return {task_id: task.id, status: processing}7. 资源占用与性能观察在本地开发和测试时关注资源占用有助于优化和排错。7.1 主要资源消耗点LLM API调用主要成本和时间在网络请求。使用异步、批处理API可提升效率。本地嵌入模型运行sentence-transformers等模型时会占用CPU/内存和显存如果可用GPU。all-MiniLM-L6-v2模型约80MB内存。向量数据库ChromaDB在内存中存储索引和向量文档越多内存占用越大。持久化到磁盘可减轻内存压力但检索会变慢。Agent推理复杂的Agent逻辑、多步工具调用会增加LLM的调用次数从而增加延迟和成本。7.2 性能观察与优化建议监控API延迟在代码中记录每个LLM调用的耗时。import time start time.time() response llm.invoke(prompt) latency time.time() - start print(fLLM调用耗时{latency:.2f}秒)优化RAG检索分块策略调整chunk_size和chunk_overlap找到平衡检索精度和速度的最佳值。索引算法Chroma默认使用HNSW。对于超大知识库可以考虑专业向量数据库如Qdrant, Weaviate。缓存对常见问题的检索结果进行缓存。精简Agent工作流避免不必要的工具调用循环。为工具提供清晰、具体的描述减少Agent理解偏差。使用更高效的LLM如gpt-3.5-turbo相比gpt-4更快更便宜。使用本地轻量模型对于简单任务可以尝试用Ollama本地运行llama3:8b等模型消除网络延迟但需要足够的GPU内存。8. 常见问题与排查方法在学习和实践过程中你可能会遇到以下典型问题。问题现象可能原因排查方式解决方案导入LangChain相关库报错版本不兼容或依赖缺失。检查pip list确认已安装库及其版本。查看错误信息中的缺失模块。1. 使用虚拟环境。2. 严格按照requirements.txt安装。3. 查阅LangChain官方文档确认版本兼容性。运行代码时提示API Key错误环境变量未正确设置或API Key无效。检查.env文件是否存在变量名是否正确。在Python中print(os.getenv(‘OPENAI_API_KEY’))测试。1. 确保.env文件在项目根目录。2. 重启终端或IDE使环境变量生效。3. 在代码中直接临时设置os.environ[‘OPENAI_API_KEY’] ‘key’进行测试。RAG检索不到相关内容文档分块不合理、嵌入模型不匹配或检索参数k太小。1. 检查向量库中是否有数据。2. 打印检索到的原始文本块看是否相关。3. 尝试不同的文本分割器。1. 调整chunk_size(如 200-1000)。2. 增加检索返回数量k。3. 尝试不同的嵌入模型如text-embedding-ada-002API。Agent一直循环调用工具或不调用工具提示词设计不佳、工具描述不清或LLM能力不足。1. 开启Agent的verboseTrue模式查看其思考过程。2. 检查工具函数的description是否清晰。1. 优化系统提示词明确Agent的角色和工具使用规则。2. 为工具提供详细的描述和参数示例。3. 尝试使用能力更强的LLM如GPT-4。LangGraph工作流状态混乱状态State定义不清晰或节点函数修改了不应修改的状态字段。打印每个节点执行前后的状态值。1. 使用TypedDict和Annotated明确定义状态结构。2. 确保节点函数返回的字典只更新它应该更新的字段。服务启动后接口访问超时端口被占用、服务未成功启动或防火墙限制。1. 检查服务日志是否有错误。2. 用netstat -an | grep 8000(Linux) 或lsof -i:8000(macOS) 查看端口占用。3. 尝试用curl localhost:8000/docs在本地测试。1. 更换服务端口。2. 确保在代码中正确调用了uvicorn.run。3. 如果是云服务器检查安全组规则是否开放了对应端口。处理长文档时内存溢出一次性加载整个大文件到内存。监控任务管理器或使用memory_profiler工具。1. 使用流式加载文档如果库支持。2. 将大文档拆分成多个小文件分批处理。3. 增加系统交换空间swap。9. 最佳实践与使用建议基于这套技术栈构建生产级应用时以下几点建议能帮你走得更稳。从简单开始逐步迭代不要一开始就设计复杂的多Agent系统。先实现一个最简单的RAG问答或单工具Agent确保管道通畅再逐步增加复杂度。重视提示词工程Agent和RAG的效果严重依赖提示词。为系统提示词、工具描述、检索后处理提示词建立模板库并进行A/B测试。实现完整的日志与监控记录每一次LLM调用、工具执行、用户查询和最终输出。这有助于分析性能瓶颈、调试错误和优化效果。为RAG知识库建立维护流程知识库不是一次构建就一劳永逸。建立文档更新、向量库重建、版本管理的流程。安全第一工具调用对Agent可调用的工具进行严格的权限控制和输入验证尤其是文件操作、网络请求等。用户输入对用户输入进行过滤防止Prompt注入攻击。输出内容对Agent生成的内容进行合规性审查特别是涉及法律、医疗、金融等领域。设计降级与兜底策略当LLM API不可用、工具调用失败或RAG检索无结果时系统应有友好的降级响应而不是直接崩溃。性能测试与成本估算在上线前模拟真实用户负载进行压力测试。同时估算LLM API调用的成本设置用量告警。10. 总结与下一步这套“最全最细”的AI Agent教程其核心价值在于提供了一个体系化的实践地图。它让你不再孤立地学习LangChain、RAG或Agent而是看到它们如何协同工作解决真实问题。最值得尝试的起点建议你从RAG知识库问答开始。这是需求明确、效果直观、且能立即解决信息检索问题的一个模块。成功搭建一个能回答你个人文档问题的系统会带来巨大的正反馈。最容易踩的坑环境配置和版本兼容性。严格按照教程或本文建议的Python版本和库版本操作能避开80%的初期问题。另一个常见坑是对LLM能力的期望过高需要不断通过提示词工程和流程设计来引导和约束它。后续深入方向探索更强大的本地模型随着Llama 3、Qwen等开源模型的进步尝试用Ollama或vLLM在本地部署降低对云端API的依赖和成本。集成更丰富的MCP工具将你的Agent连接到数据库、内部业务系统、Slack、GitHub等打造真正自动化的办公助手。实现复杂的多Agent协作使用LangGraph或AutoGen框架设计多个各司其职的Agent如分析员、撰稿员、审核员协同完成一个项目。优化RAG的检索质量尝试混合检索向量关键词、重排序Re-Rank、查询改写等技术进一步提升答案的准确率。AI Agent的开发是一个快速迭代的工程实践过程。收藏这篇文章在搭建和调试你的第一个智能体时随时回来对照检查和排查问题。现在就从创建一个虚拟环境、安装第一个LangChain库开始吧。