2026年了AI大模型应用开发依然是技术圈最热的方向但一个尴尬的事实是很多人学了Transformer原理背了Prompt模板却依然做不出一个能真正处理复杂任务的AI应用。问题出在哪里缺的不是模型知识而是框架能力。如果你想从“会调API”进阶到“能设计AI应用”DeepAgents是一个绕不开的框架。它不是又一个大模型套壳而是把Agent的规划、执行、记忆、工具调用这些核心问题工程化的开源方案。这篇文章不会讲虚的我会从原理到实战带你完整跑通一个基于DeepAgents的AI应用并告诉你这个框架真正的价值边界在哪里。1. 为什么AI应用开发工程师要关注DeepAgents先看一个真实场景。假设你要做一个“智能客服助手”它的任务不是简单问答而是理解用户问题、查询订单系统、判断售后政策、生成回复、必要时升级人工。如果用传统编程写你需要手动管理状态机、处理各种异常分支、把大模型输出解析成结构化指令。这套代码写下来少说几百行而且每改一个流程都要动核心逻辑。DeepAgents解决的就是这个问题。它是一个面向生产环境的Agent开发框架核心思路是把AI应用拆解成Agent智能体、Plan执行计划、Skill技能、Context上下文这几个可管理、可复用的单元。开发者只需要定义技能和上下文框架负责调度和状态管理。这意味着什么对比就清楚了维度传统API调用开发DeepAgents框架开发核心逻辑手写状态机和流程控制框架自动管理Agent执行流程功能扩展硬编码新分支新增Skill即插即用上下文管理手动拼装历史消息结构化Context对象复杂任务处理递归调用、容易失控Plan机制支持多步骤规划生产可用性需要自研重试、监控框架内置错误处理与恢复从材料看DeepAgents延续了Meta在AI基础设施上的工程化思路把研究prototype到生产落地之间的“最后一公里”补上了。尤其对于正在准备AI大模型应用开发工程师岗位的人来说理解这类框架直接决定了你是在“写脚本”还是在“做应用”。这篇文章的目标读者很明确已经会Python调过大模型API但还没系统掌握Agent框架的开发者和准开发者。读完你会理解DeepAgents的架构设计能独立跑通一个实战项目并且知道哪些场景适合用它、哪些场景其实不需要它。2. DeepAgents核心概念Agent、Plan、Skill与Context在写代码之前必须先把框架里的四个核心概念搞清楚。很多人学Agent框架失败就是因为没想明白这几个概念各自的边界。我用一个餐厅的比喻来解释。Agent是整个餐厅的经营主体。它接收顾客订单用户请求决定如何完成服务。在DeepAgents里Agent是你的应用核心它拥有自己的系统提示词system prompt、行为准则和可用技能列表。一个应用可以有一个Agent也可以有多个Agent协作。Skill是餐厅里的厨师。每个厨师只擅长做一类菜有的负责热菜有的负责甜点。对应到代码里Skill就是一个Python函数或工具完成特定的、确定性的任务比如查询数据库、调用外部API、执行数学计算。Agent拿到用户请求后会根据请求内容选择合适的Skill来执行。Plan是餐厅的出餐流程。复杂订单比如婚宴需要先规划什么时间备菜、哪道菜先做、哪些可以并行。DeepAgents支持Agent在执行前或执行中生成Plan把一个大任务拆成有序的小步骤。这是它与早期“单轮工具调用”Agent最大的区别。Context是餐厅的订单和客户档案。包括当前请求的输入、历史对话记录、可参考的业务数据。DeepAgents把Context设计成显式对象方便开发者在多个Skill之间传递数据而不是靠全局变量或者“塞进prompt里”。用一句话概括架构关系Agent根据Context理解任务参考Plan决定执行策略调度Skill完成具体动作再把结果写回Context。这种设计带来的工程收益很明显你想加一个新能力不用改Agent核心逻辑添加一个Skill即可你想调整某个任务的执行方式改Plan策略而不是改业务代码。有一个新手特别容易踩的误区觉得“既然大模型能写代码那我让Agent自己写SQL查数据库不就行了”理论上可以但生产环境绝不能这么做。正确的做法是把“查数据库”封装成一个受控的SkillSQL语句由开发者审核、参数由Agent填充。这也是DeepAgents强调Skill机制的原因——安全边界和可控性比“让模型为所欲为”重要得多。3. DeepAgents环境准备与基础配置DeepAgents是用Python写的所以环境准备主要围绕Python生态展开。为了不影响你机器上已有的项目强烈建议使用虚拟环境。3.1 环境要求Python版本3.10及以上框架使用了较新的类型注解和异步特性太老的版本不支持操作系统macOS、Linux、Windows均可但生产环境建议Linux包管理工具pip或poetry本文用pip演示模型服务需要准备一个可用的LLM API Key。DeepAgents支持OpenAI兼容接口也支持Anthropic等常见提供商。本地部署的模型比如通过Ollama、vLLM启动的服务如果暴露OpenAI兼容接口同样可以接入。不同版本的具体依赖项要以官方仓库的README为准本文演示的是通用接入流程。3.2 创建项目与虚拟环境# 创建项目目录 mkdir deepagents-demo cd deepagents-demo # 创建虚拟环境使用venv python3 -m venv venv # 激活虚拟环境 # macOS / Linux source venv/bin/activate # Windows venv\Scripts\activate激活后终端提示符前面会出现(venv)说明当前已经在虚拟环境里了。3.3 安装DeepAgentspip install deepagents安装完成后可以验证一下python -c import deepagents; print(deepagents.__version__)如果能正常输出版本号说明安装成功。如果提示找不到模块先检查是否激活了虚拟环境再用pip list | grep deepagents确认包是否真的装上了。3.4 配置模型API模型接入是另一个关键配置。DeepAgents在初始化时接收LLM客户端所以我们需要提前建好环境变量。# .env 或直接在 shell 中设置 export ANTHROPIC_API_KEY你的Anthropic API Key export OPENAI_API_KEY你的OpenAI API Key这里要提醒一点不同模型的能力差异会直接影响Agent的表现。工具调用、长上下文、指令跟随能力强的模型跑Agent框架的效果会明显更好。如果开发阶段想控制成本可以先用轻量模型验证逻辑再切换到更强模型做最终测试。4. 第一个DeepAgents应用从建模到编码现在开始写第一个真正的DeepAgents应用。目标是做一个营销文案助手给定一个产品名称和卖点Agent能自动规划文案结构生成多平台适配的营销文案。这个案例虽然业务不复杂但能完整展示Agent、Plan、Skill、Context四个核心概念的协作方式。4.1 定义第一个Skill创建skills.py定义两个基础技能一个负责生成小红书风格文案一个负责生成公众号长文大纲。在DeepAgents中Skill是普通Python函数加上注册装饰器。# 文件路径deepagents-demo/skills.py from deepagents import skill skill def generate_xiaohongshu_copy(product_name: str, selling_point: str) - str: 生成小红书风格的种草文案。 template ( f姐妹们最近挖到的宝藏好物一定要分享给大家\n\n f产品{product_name}\n f为什么值得买{selling_point}\n\n f我已经替大家试过了真的不是智商税 ) return template skill def generate_wechat_outline(product_name: str, selling_point: str) - str: 生成公众号长文的大纲结构。 outline ( f标题为什么都在讨论{product_name}\n f1. 引言一个被忽视的日常痛点\n f2. 什么是{product_name}它解决了什么问题\n f3. 核心卖点解读{selling_point}\n f4. 使用体验与注意事项\n f5. 总结适合谁怎么选 ) return outline注意代码里的两个细节。第一每个函数都写了完整的docstring这不仅是好习惯更重要的是DeepAgents会把这些docstring作为“技能说明书”提供给模型让Agent知道什么时候该调用这个Skill。第二函数参数被定义为带类型注解的具名参数这能帮助模型正确理解传参要求。4.2 创建Agent实例接下来创建main.py把Skill装配进Agent。# 文件路径deepagents-demo/main.py import asyncio from deepagents import Agent from skills import generate_xiaohongshu_copy, generate_wechat_outline async def main(): agent Agent( namemarketing_assistant, system_prompt( 你是资深营销文案专家。你会根据产品信息和目标平台 选择最合适的文案生成技能。小红书文案要活泼种草 公众号文章要结构完整、有深度。 ), skills[generate_xiaohongshu_copy, generate_wechat_outline], modelclaude-3-5-sonnet-latest, # 也可以替换为 OpenAI 或本地模型 ) result await agent.run( 给一款主打长续航的蓝牙耳机写小红书文案 重点突出单次充电可用一周。 ) print(result.final_output) if __name__ __main__: asyncio.run(main())这里system_prompt即Agent的系统提示词决定它的身份和输出风格。skills列表就是我们注册的技能集合。model指定使用的模型具体取值取决于你配置的模型供应商。4.3 运行第一个示例执行python main.py正常情况下你会看到Agent输出了类似下面这样的小红书文案姐妹们最近挖到的宝藏好物一定要分享给大家 产品长续航蓝牙耳机 为什么值得买单次充电可用一周 我已经替大家试过了真的不是智商税如果你的输出有差异别担心模型生成的内容本来就不是确定性的。只要Agent成功选择了正确Skill并返回结果就说明整个链路已经跑通了。但是这个例子仍然偏“手动档”——Agent只是做了一次工具选择。接下来我们要展示DeepAgents更强大的能力多步骤规划执行。5. 进阶实战构建一个支持规划与多技能协作的智能助手现在难度升级。我们要构建一个企业知识库问答助手它需要完成以下任务接收用户问题判断问题属于哪个知识领域调用检索技能获取相关资料调用分析技能整理答案基于最终答案生成结构化回复这个案例更接近真实的企业AI应用场景比如内部IT支持、HR政策问答、产品文档助手。它展示的是DeepAgents如何处理“需要多个技能顺序执行”的复合型任务。5.1 模拟知识检索与业务处理Skill在实际项目中知识检索Skill背后连接的通常是向量数据库比如FAISS、Milvus、pgvector或者直接调用公司内部的搜索服务。这里为了演示框架设计先用内置数据模拟检索过程和业务计算过程。# 文件路径deepagents-demo/enterprise_skills.py from deepagents import skill # 模拟知识库数据 KNOWLEDGE_BASE { 年假: 根据公司制度入职满一年后每年享有10天年假按自然年计算。, 远程办公: 每周三为固定远程办公日需提前一天在OA系统提交申请。, 报销: 500元以下报销需提交电子发票500元以上需额外提交审批单。, } skill def search_knowledge(keyword: str) - str: 在企业知识库中检索关键词对应的制度或政策。 if keyword in KNOWLEDGE_BASE: return KNOWLEDGE_BASE[keyword] # 模拟模糊匹配 for k, v in KNOWLEDGE_BASE.items(): if keyword in k or k in keyword: return v return 知识库中未找到相关内容。 skill def calculate_leave_days(join_year: int, use_days: int 0) - int: 根据入职年份和已休天数计算剩余年假天数。 base_days 10 if join_year 2020: base_days 15 remaining base_days - use_days return max(remaining, 0)5.2 组合多个技能修改main.py把这些技能注册到Agent中。同时调整系统提示词引导Agent按照“先检索后计算再回答”的顺序处理问题。# 文件路径deepagents-demo/main.py import asyncio from deepagents import Agent from enterprise_skills import search_knowledge, calculate_leave_days async def main(): agent Agent( namehr_assistant, system_prompt( 你是企业HR智能助手。当用户咨询公司制度时 先从知识库检索相关政策如果涉及年假计算 调用计算技能确认具体数字最后综合信息向用户给出清晰答复。 ), skills[search_knowledge, calculate_leave_days], modelclaude-3-5-sonnet-latest, ) result await agent.run( 我是2022年入职的员工今年已经休了4天年假 请问我还有几天年假可用 ) print(result.final_output) if __name__ __main__: asyncio.run(main())5.3 执行结果与分析运行这个示例Agent应该输出类似下面的回复您2022年入职属于入职满一年员工每年基础年假为10天。 截至目前您已使用4天剩余年假为6天。如果你打开了DeepAgents的日志输出设置verboseTrue你还能看到Agent的执行轨迹它是先调用search_knowledge找到年假制度再调用calculate_leave_days计算剩余天数最后生成综合答复。这个执行轨迹在生产环境中非常有用它让AI的决策过程可审计、可追踪。对比一下第一个示例这里的差别在于Agent不再是被动地“调一个函数就结束”而是根据任务特点自主生成了一个执行计划Plan按顺序调用多个技能最终汇总结果。这就是DeepAgents框架的价值所在。如果你在本地跑的时候发现Agent跳过了某个技能直接回答通常是因为系统提示词里的流程引导不够明确或者模型能力较弱。解决方法是把流程写得更具体例如“必须调用search_knowledge获取政策原文后才能回答”。6. 深入理解DeepAgents的Plan机制与执行流程上面两个例子已经让你体验了Agent的基本工作方式。但DeepAgents能成为生产级框架还有一个关键设计值得深入理解Plan机制。在复杂业务中任务往往不是“检索一下”这么简单而是“先分析需求再拆解子任务再按依赖关系执行最后汇总”。如果所有逻辑都靠模型自由发挥结果大概率不稳定——有时顺序错乱有时漏掉步骤。DeepAgents的做法是引入显式的Plan对象。Plan可以有两种应用方式第一种动态Plan。Agent在每一轮执行前根据当前Context生成下一步计划。这种方式灵活适合开放域任务但计划质量高度依赖模型能力且不易审计。第二种静态Plan。开发者预先定义好任务的有序步骤Agent按固定流程执行。这种方式适合业务流程明确的场景比如from deepagents import Step, Plan plan Plan( steps[ Step(nameretrieve_policy, skillsearch_knowledge, input_keyword年假), Step(namecalculate_remaining, skillcalculate_leave_days, join_year2022, use_days4), Step(namegenerate_response, skillgenerate_reply, use_output_of[retrieve_policy, calculate_remaining]), ] )静态Plan的工程价值非常大。它意味着核心业务流程不由模型自由发挥而是由开发者和业务方协同定义。模型只需要在每个步骤内做参数提取和文本生成显著降低了失控风险也让测试和验收变得可行。从实践中得到的经验是生产环境里优先使用静态Plan和深度打磨的Skill把模型的自由度约束在“参数填充”和“文本润色”层面而不是把整个流程决策权交给模型。这是Agent应用从Demo走向生产的第一原则。7. DeepAgents常见问题与排查思路在实际使用DeepAgents时新手最容易在下面几个环节卡住。我把高频问题和排查方法整理成一张表方便遇到问题时快速定位。问题现象可能原因排查方式解决方案安装后 import 失败Python版本过低或未激活虚拟环境python --version查看当前解释器路径使用Python 3.10重新激活虚拟环境Agent调用不到SkillSkill没有注册到skills列表打印Agent对象中的skills属性确认装饰器已添加、函数已传入skills参数模型返回格式解析失败模型输出与框架预期格式不匹配开启verbose日志查看原始模型输出更换指令跟随能力更强的模型或调整prompt多个Skill执行顺序混乱系统提示词未明确流程检查日志中的Plan执行轨迹改用静态Plan或优化提示词明确执行顺序中文输出乱码终端编码问题检查控制台编码设置macOS/Linux设置export LANGzh_CN.UTF-8API调用超时网络问题或模型服务负载高检查网络连通性增加超时时间配置更长超时参数或使用本地模型上下文过长导致费用高历史消息累积过多观察每次请求的token统计设置Context截断策略只保留最近N轮出现问题时第一原则是先看日志。DeepAgents运行时会输出每个阶段的执行信息包括模型请求、技能调用、上下文变化。把verboseTrue打开再跑一遍80%的问题都能从日志里找到线索。8. DeepAgents最佳实践与生产环境建议到这里你已经能跑通示例也理解了框架的运行机制。下面这些工程建议是从“能跑”到“生产可用”必须跨过的坎。8.1 Skill设计原则一个Skill应该做且只做一件明确的事。判断标准是你能不能用一句话说清它的输入输出。如果说不清就把它拆小。Skill的docstring要写得足够详细因为模型的“技能选择”完全依赖这份说明。8.2 Context与记忆管理不要无脑把全部对话历史塞给模型。DeepAgents支持结构化的Context管理建议把信息分为用户当前输入、业务关键参数、历史摘要、临时中间结果。只保留必要信息既能控制token成本也能减少模型受无关信息干扰。8.3 安全与权限边界Agent能调用Skill意味着模型拥有了某种执行权限。务必遵循最小权限原则数据库Skill只允许执行SELECT或白名单内的SQL文件Skill只允许访问指定目录外部API Skill必须做参数校验。不要用管理员的身份凭证跑Agent服务。8.4 可观测性与审计生产环境一定要记录Agent的执行轨迹包括模型输入输出、Skill调用参数、执行耗时、Token消耗。这不只是为了排查问题更是合规审计的需要。当Agent的行为影响到业务数据时每一步都需要能回溯。8.5 回滚与灰度发布Agent应用迭代时新Skill或新提示词可能引入预期外的行为。参考传统后端服务的发布策略用灰度方式把Agent新版本暴露给少量用户观察效果后再全量上线。模型输出的不确定性意味着Agent应用比传统应用更需要渐进式发布。9. 如何继续深入学习DeepAgents这篇文章帮你建立了DeepAgents的完整认知框架但距离“熟练的AI应用开发工程师”还有一段路。按照下面这条路径继续深入会更高效先精读DeepAgents官方文档中关于Agent、Plan、Skill、Context的接口定义把每个参数都试一遍。然后找一个小而完整的业务场景从零开始构建Agent应用强制自己使用静态Plan约束流程。接着尝试接入本地部署的大模型比如通过Ollama或vLLM启动服务比较不同模型在框架中的表现差异。再往深走可以研究如何把RAG检索增强生成与DeepAgents结合解决知识库问答中的实时性和准确性问题。最后如果涉及团队协作需要思考Agent应用的测试策略如何为Skill编写单元测试、如何评估Agent端到端效果、如何建立回归测试集。补充一点方向判断Agent框架正在快速演进今天学的具体API未来可能改变但“Agent 规划 工具 上下文管理”这个架构思想是稳定的。把精力花在理解设计思想和方法论上远比死记API划算。对于正在准备AI大模型应用开发岗位的人来说除了框架本身建议同时补上RAG、提示词工程、模型评测、向量数据库这些关联技术。它们不是孤立的而是Agent应用工程化的完整拼图。DeepAgents是当前Agent框架中的一个优秀代表但它不是银弹。它的适用场景是任务有明确边界、需要调用外部工具、要求流程可控、需要生产部署。如果你的需求只是“调用一次模型生成文本”直接用SDK就够了不需要引入Agent框架。理解这个边界同样是专业能力的体现。
