1. 项目概述两小时装了一个AI Agent到底装了啥周末手痒给自己安排了一个小任务花两小时把一个能干活儿的AI Agent跑起来。不是那种你好有什么可以帮您的聊天窗口而是让它自己规划任务、调用工具、完成一个我指定的实际目标。先给没接触过这玩意的朋友说清楚一个概念我们常说的DeepSeek、ChatGPT这类产品本质上是大语言模型LLM它们是大脑——负责理解语言、生成文字、推理逻辑。但光有大脑是不够的你不能指望它自己去打开浏览器查资料、去数据库里读数据、去执行一段Python脚本。而AI Agent就是给这个大脑装上手脚的系统你给它一个目标它会自己拆解成步骤、调用对应的工具、看着结果继续推进直到把活儿干完。这篇文章我打算把这次搭建的全过程、技术选型逻辑、遇到的坑全部摊开来讲适合两类人看一是听说过Agent但一直没动手、想找个最小可运行方案入门的朋友二是做过简单LLM调用但对Agent到底比普通对话多了什么还模糊的朋友。我会把为什么要用这个框架、每个配置背后是什么原理、哪些坑必须提前避开都写清楚让你照着走一遍两小时内也能搭出一个真正跑得起来的Agent。先说结论我搭的这个Agent可以完成根据一个自然语言指令自主决定调用哪个工具完成任务这件事。整体架构不算复杂但里面涉及的几个核心概念——模型选型、工具注册、任务循环、记忆管理、MCP接入——如果你不懂原理直接照抄配置后面稍微改点需求就会出各种玄学问题。所以咱们别急着复制粘贴先把底层的逻辑捋清楚。2. 概念拆解Agent和LLM、AI模型到底什么关系2.1 它们不是同一个东西别再混着说了打开任何一篇讲AI的帖子下面评论区必有人问Agent和LLM有什么区别DeepSeek是Agent吗这种问题。我用一句话给你理清楚AI模型如DeepSeek、GPT-4o、Qwen底层的大脑输入文字、输出文字。它本身不联网、不执行代码、不操作文件系统。LLM特指大语言模型这一类AI模型是AI模型家族里目前最主流的一派负责文字理解与生成。Agent一个完整的应用架构把LLM作为核心决策组件同时给它配上工具集、外部知识库、记忆系统、任务循环控制让它能自主完成目标。打个不太严谨但好懂的比方LLM是刚毕业的高材生脑子聪明但没有工作经验不会用公司的系统和工具。Agent是一个把高材生塞进一家公司、配好电脑、开通各种系统权限、给他一套工作流程的完整团队。你只需要告诉团队我想要一个竞品分析报告团队自己会决定先查资料、再画表格、最后排版输出。所以DeepSeek属于哪个它属于LLM这一层。你可以用DeepSeek来当Agent的大脑但DeepSeek网页版本身不是一个Agent应用。这个区分搞明白了后面选型的时候才知道自己到底要配哪一层的东西。2.2 Agent的组成结构五个部件缺一不可一个能稳定干活的Agent至少包含以下五个部分模型核心Brain负责理解任务、推理规划、生成下一步动作。可以选择不同厂商的模型各有优劣。工具集ToolsAgent可以调用外部能力的具体实现比如搜索引擎、代码执行器、文件读写、API请求等。这是Agent从只会说变成会做的关键。工作记忆Memory保存当前任务上下文、历史交互、中间结果。分短期记忆当前会话和长期记忆跨会话保存的知识。规划循环Planning LoopAgent自主决定先做什么、再做什么、做完怎么验证如果执行出错还能重新规划。配置与接口Config MCP等模型的API地址、密钥、系统提示词以及通过MCPModel Context Protocol标准协议接入外部数据源和工具服务。这次的搭建方案里这五部分全部涉及。我会在后面的实操环节里逐一说明每部分具体用了什么、为什么这么选。2.3 Agent开发的热门技术栈和我的选型逻辑选型之前我快速扫了一圈主流方案从最原始的纯Prompt封装到企业级平台都有。简单分个类方案类型代表适合场景上手难度直接调用LLM API 自行编排OpenAI SDK、DeepSeek API想完全掌控逻辑、学习原理较高Agent框架LangChain、LlamaIndex、AutoGen快速搭建Agent应用、有生态组件中等企业级平台Dify、Coze、字节扣子、阿里百炼不想写代码、拖拽式配置低编程助手型Codex、Cursor聚焦代码生成与仓库操作中等我个人的选择是用Python LangChain或LangGraph DeepSeek API作为大脑外加Tavily搜索工具和MCP服务。原因有三个一是LangChain生态成熟文档和案例多踩坑时好搜解决方案二是DeepSeek API便宜且推理能力够用作为初版方案的模型核心很合适三是这套组合能从框架怎么运作的层面看清Agent原理后续要换模型、加工具都很灵活。企业级平台虽然快但很多时候是个黑盒出了问题你连日志都看不懂。想真正搞懂Agent原理我建议至少自己手搭一次框架方案。3. 搭建前准备环境、模型和工具清单3.1 硬件和基础环境要求先说个让新手安心的话搭Agent不要求你有顶配显卡。因为推理都在云端API完成本地只需要跑一个Python应用去调用接口。我这次用的是一台普通笔记本8GB内存没有独立显卡完全够用。环境要求如下Python 3.9以上推荐3.10或3.11过老的版本会跟新库冲突pip包管理器一个API密钥我用的DeepSeek后面会讲怎么申请能访问外网的网络环境因为需要调用云端模型API和搜索服务。依赖库方面核心就这几个langchain、langchain-openai因为DeepSeek兼容OpenAI的接口协议、python-dotenv管理密钥、tavily-search搜索工具。如果你要加PDF读取就再装pypdf要加数据库就装sqlalchemy按需来。注意不同的LangChain版本API变动很大2024年到2025年之间LangChain经历过一次大改版很多旧教程里的写法已经失效。建议统一用最新稳定版并参考官方最新的导入路径。3.2 模型选型为什么选DeepSeek而不是GPT或国产其他模型模型是Agent的脑子选模型的标准跟选聊天机器人不完全一样。做Agent你额外关注这几个维度函数调用/工具调用能力模型能不能按照JSON Schema格式输出我要调用哪个工具、参数是什么。这是Agent落地的核心比单纯会聊天重要得多。上下文长度Agent在执行过程中会把中间推理、工具返回结果都塞进上下文上下文太短很容易中途截断。建议至少16K起步。响应速度和成本Agent会多次调用模型一次任务可能调用三五次甚至更多成本积累比单纯聊天快响应速度也直接影响体验。我这次选择DeepSeek主要看中两点一是它的API兼容OpenAI格式接LangChain时几乎零适配成本二是价格便宜整个搭建调试过程烧不掉几毛钱特别适合反复试错。如果你手头已经有OpenAI的Key或者Qwen的Key照着后面代码改成对应的model_name和base_url就行整体逻辑完全一致。3.3 工具集规划让Agent真正具备动手能力Agent能调用什么工具决定了它能干什么活。初版方案我配了四个工具Web搜索Tavily让Agent能查询实时信息弥补模型知识截止时间的问题代码执行器Python REPL让Agent能运行Python代码做计算、数据处理、文件操作文件读写让Agent能保存结果到本地文件或者读取已有文件的内容时间查询让Agent知道当前日期时间这个在规划任务时经常用到。每一步工具调用模型都会收到工具返回的结果再决定下一步干什么。这个决策-执行-观察-再决策的循环就是Agent智能感的来源。工具不是越多越好。每多挂一个工具模型在选择时就多一分误判的可能。初版先挂最核心的四五个跑通了再逐步加。4. 实操过程两小时从零到一跑通Agent4.1 第一步申请API Key和准备项目目录约10分钟先到DeepSeek开放平台注册账号然后在控制台创建API Key。创建时注意两点一是Key只显示一次要立马复制保存到本地二是新用户一般有免费额度够调试用一阵子。然后建项目目录我习惯用这样的目录结构agent-demo/ ├── .env # 存放API密钥不进Git ├── main.py # 主程序入口 ├── requirements.txt # 依赖清单 └── tools/ ├── __init__.py # 工具汇总导出 └── search_tool.py # 搜索工具封装这个结构的好处是密钥跟代码分离后续部署到服务器或者推仓库时不会泄露工具单独一个目录加新工具时互不影响。4.2 第二步安装依赖库约15分钟创建一个虚拟环境避免污染全局Python环境python -m venv venv source venv/bin/activate # Windows上执行 venv\Scripts\activate pip install langchain langchain-openai python-dotenv tavily-search如果安装慢可以换成清华镜像源pip install -i https://pypi.tuna.tsinghua.edu.cn/simple langchain langchain-openai python-dotenv tavily-search安装过程中最容易出的问题有两个一是Python版本太老导致某些库没有对应wheel包二是网络问题导致安装中断。遇到这两个问题别慌前者升Python版本后者重新执行一次命令并加--timeout 60参数。4.3 第三步写配置文件加载密钥约5分钟在项目根目录创建.env文件DEEPSEEK_API_KEYsk-你的密钥 TAVILY_API_KEYtvly-你的密钥然后写一个加载配置的辅助函数import os from dotenv import load_dotenv load_dotenv() DEEPSEEK_API_KEY os.getenv(DEEPSEEK_API_KEY) TAVILY_API_KEY os.getenv(TAVILY_API_KEY)为什么要用.env而不是直接在代码里写死密钥因为Agent项目以后很大概率要分享给同事、推到GitHub密钥一旦进了历史记录就很难彻底清掉了。用.env加.gitignore的方式是最基本的安全习惯必须从一开始就养成。4.4 第四步初始化Agent核心并绑定工具约20分钟这里是我认为最关键的一步。我用LangChain的create_react_agent方式让模型按照**思考-行动-观察ReAct模式**的循环来工作。from langchain_openai import ChatOpenAI from langchain.agents import create_react_agent, AgentExecutor from langchain.tools import Tool from langchain_community.tools import TavilySearchResults # 初始化模型 llm ChatOpenAI( modeldeepseek-chat, api_keyDEEPSEEK_API_KEY, base_urlhttps://api.deepseek.com/v1, temperature0.1 ) # 定义工具 search_tool TavilySearchResults( api_keyTAVILY_API_KEY, max_results5 ) python_tool Tool( namepython_executor, description在需要计算、数据处理或运行Python代码时使用。 输入应该是合法的Python代码。, funcrun_python_code ) time_tool Tool( namecurrent_time, description获取当前日期和时间。当需要知道今天是什么日期时使用。, funclambda _: datetime.now().strftime(%Y-%m-%d %H:%M:%S) ) file_tool Tool( namefile_saver, description保存内容到本地文件。输入格式文件名|内容。, funcsave_to_file ) tools [search_tool, python_tool, time_tool, file_tool]这里有个容易被忽略的点每个工具的描述description比实现本身还重要。因为模型是靠描述来决定什么场景调用哪个工具的。如果你写的描述模糊模型就会乱选工具。比如python_executor的描述里要写清楚什么时候用不写的话它会拿去找资料的任务也会尝试跑代码。定义好工具后创建一个ReAct Agentfrom langchain.agents import AgentExecutor from langchain.prompts import PromptTemplate prompt PromptTemplate.from_template(你是一个能够自主完成任务的AI助手。 你可以使用以下工具{tools} 你的名字是{agent_name} 当接到任务时请按以下格式思考 Thought: 分析当前状态决定下一步行动。 Action: 选择要使用的工具名称。 Action Input: 输入给工具的参数。 Observation: 工具返回的结果。 ...循环... Thought: 任务完成整理最终答案。 Final Answer: 给用户的最终回复。 另外请记住以下规则 1. 如果任务需要实时信息优先使用搜索工具。 2. 如果涉及计算或数据处理使用python_executor。 3. 完成后用file_saver保存关键结果。 4. 不要猜测信息如果找不到就如实说明。 {agent_scratchpad}) agent create_react_agent(llm, tools, prompt) agent_executor AgentExecutor( agentagent, toolstools, verboseTrue, handle_parsing_errorsTrue, max_iterations8 )temperature0.1是刻意设置的。Agent不像聊天需要创造性它更需要稳定、可复现的决策温度越低越倾向于确定性的输出。如果你在做文案创作类Agent可以调高但工具调用型Agent请保持低温。4.5 第五步主程序入口和运行测试约20分钟写一个简单的主程序接收用户的自然语言任务交给Agent执行def main(): print(AI Agent 已启动输入任务即可执行输入exit退出) while True: user_input input( ) if user_input.lower() in [exit, quit]: break response agent_executor.invoke({input: user_input, agent_name: 助手}) print(\n 最终结果 \n) print(response[output]) print() if __name__ __main__: main()第一次运行时我建议把verboseTrue打开这样每一步思考-行动-观察都会打印出来你能直观看到Agent的大脑是怎么工作的。调试过程中这个输出信息就是最直接的debug依据。测试任务我建议从简单到复杂逐步来先问今天是什么日期验证基本问答链路通不通再试帮我搜索2025年AI Agent的最新动态并总结三点验证工具调用和结果整理能力最后试帮我计算斐波那契数列前20项然后把结果保存到fibonacci.txt验证多步骤规划和多工具协同。我第一次跑第三个任务时观察到的执行路径是先写下规划用python_executor算数列再调用file_saver保存文件最后生成总结反馈给用户。整个过程自动完成没有人类干预那一刻确实能感受到Agent和普通聊天程序的本质区别。4.6 第六步加入MCP扩展Agent的连接能力约30分钟前面的方案工具是写死在代码里的。但真实场景里我们经常要接各种外部系统数据库、企业内部API、GitHub仓库、甚至PLC控制器。如果每个都写一段胶水代码接入LangChain工作量很大而且每套系统都要一套对接方式。MCPModel Context Protocol解决的就是这个问题。它定义了一套标准协议让模型应用可以统一地发现和调用外部工具。我用MCP方式接了一个简单的SQLite数据库查询服务from langchain_mcp_adapters.tools import load_mcp_tools from mcp import ClientSession, StdioServerParameters # 通过stdio方式启动一个MCP服务器进程 server_params StdioServerParameters( commandpython, args[mcp_servers/sqlite_server.py] ) session ClientSession(server_params) mcp_tools await load_mcp_tools(session)MCP的故事很长但初版你只需要理解它是个万能插头协议只要对方提供了MCP服务你不需要知道它内部实现就能把它的能力当工具用。这个方向上接数据库、接CRIM、接浏览器自动化都有现成实现后续扩展空间非常大。5. 实测场景这个Agent到底能干什么5.1 场景一实时信息检索归纳总结我让Agent执行的任务是查一下最近一个月AI Agent开发框架有什么重要更新总结出三条最值得关注的。执行过程Agent判断这是一个需要实时信息的问题因为模型训练数据有截止日期于是调用搜索工具拿到搜索结果后逐个浏览摘要再生成三条总结。输出内容质量比直接问模型AI Agent框架有什么更新要准确得多因为有了真实搜索结果支撑。5.2 场景二多步计算文件输出任务计算1到10的平方和然后保存结果到本地文件。执行路径Agent先调用python_executor执行计算得到结果385然后调用file_saver把内容写入文件。最后提醒我文件已保存并给出了文件路径。这看起来不复杂但注意这是一次规划-执行-再规划-再执行的完整循环每个工具的选择和调用都是模型自主决策的。5.3 场景三带条件的任务规划任务如果明天会下雨提醒我带伞否则提醒我穿短袖。先查天气再决定。Agent会先调用天气相关的工具我后来加了weather工具查询预报然后根据查询结果来决定给出哪个提醒。这意味着Agent具备简单的条件判断能力能够根据中间结果调整最终输出。这三个场景跑下来你能明显感受到Agent的核心价值它不是一个被动应答的对话系统而是一个目标驱动的任务执行系统。给它一个目标它有路径、有工具、有反馈机制能自己完成任务闭环。6. 常见问题与排查技巧实录6.1 模型输出格式解析失败这是新手跑Agent遇到最多的报错。LangChain要求模型输出遵循特定格式Thought/Action/Action Input/Observation但模型的输出偶尔会偏离格式比如忘了写Action Input、或者多写了内容。我的处理方案设置handle_parsing_errorsTrue让框架在解析失败时自动把错误反馈给模型让它自我修正在系统提示词里明确输出格式模板用具体的例子示范如果频繁出错降低temperature到0或者0.1提高确定性。6.2 Agent陷入死循环表现是Agent反复调用同一个工具、得到相同结果、继续调用同一个工具直到达到max_iterations上限。排查思路这种循环通常是提示词里的规则不够明确或者工具描述让模型觉得再试一次可能会有不同结果。解决办法设置max_iterations8或更低并在系统提示词里写明如果同一工具返回相同结果两次不要再重复调用直接给出当前判断。6.3 工具返回的内容超出上下文长度当搜索结果很长、文件内容很大时工具的返回结果会把上下文撑爆导致模型报错或忽略部分内容。解决办法在工具内部做结果截断比如Tavily搜索限制只保留前几个结果文件读取只读取前N行。在工具描述里明确如果你只需要部分信息请通过参数指定。6.4 Agent调用了不合适的工具比如任务明明是查询天气Agent却调了搜索工具。这种一般是工具描述写得太泛模型没有准确理解工具边界。我的经验是给每个工具加上严格的触发条件描述和反例。比如此工具只在需要执行Python代码时使用不用于搜索资料、不用于获取实时信息。描述越清晰选对率越高。6.5 问题速查表问题可能原因快速解决办法模型一直不调用工具系统提示词没有明确要求使用工具在提示词里明确写出如果需要用到XX功能必须调用工具调用工具后不读取结果上下文被其他内容占满或者工具返回为空检查工具返回内容确认非空限制单轮上下文长度提示API Key无效Key复制不完整或已过期重新检查.env文件确认没有空格换行LangChain报模块不存在版本兼容问题更新到统一版本参考官方文档迁移指南7. 扩展方向从Demo到真正能用的Agent搭完初版下一步有几个很自然的扩展方向接入更多MCP服务数据库、企业内部API、浏览器自动化、甚至PLC控制器。MCP生态越来越丰富很多系统官方都提供了MCP服务端你只要在Agent里注册就能调用。加上记忆系统目前这个Agent是没记性的每次会话都是全新开始。接一个向量数据库比如Chroma、FAISS或者Redis让Agent能记住用户偏好、历史任务体验会有一个大提升。多Agent协作拆分成规划Agent执行Agent审核Agent的结构各司其职适合更复杂的任务。比如写代码的场景可以让一个Agent负责拆解需求一个负责写代码一个负责审查。接入企业IM或者自动化平台通过Webhook或消息队列把Agent接到钉钉、飞书、企业微信里让团队成员用自然语言就能发起任务。Java技术栈集成如果你是企业级Java开发可以关注Spring AI项目。Spring AI提供了类似LangChain的抽象但更贴合Spring生态。搭配Spring Cloud可以构建分布式Agent应用平台实现多Agent的注册发现和协同调度。我自己接下来打算做的是给这个Agent接上公司内部的知识库和工单系统让它能自动处理一些重复性的查询和表单填写类任务。8. 个人实操体会跑通整个流程之后我最大的感触是装一个Agent真的不难难的是把Agent调教得懂事。所谓懂事就是它知道什么场景该用什么工具、什么情况该停止尝试、什么信息要基于事实而不是猜测。这些能力不是模型天然具备的而是通过系统提示词、工具描述、参数配置逐渐调出来的。这个过程跟带新人很像你交代得越清楚边界划得越明确它干得就越靠谱。另外有个建议给想入门的朋友不要一开始就追求复杂的框架和花哨的功能。先搭一个最小可运行的系统然后一个一个工具地往上加每加一个就测试一轮你会慢慢建立起对Agent行为的直觉。这种亲手调出一个会干活的系统的体验比看再多教程都有用。最后分享一个小经验调试Agent的最佳方式就是看着它的逐步日志一行一行读它每一步的选择和判断。日志不会骗人Agent大部分问题的答案都藏在它的思考过程里。