在实际的 AI 大模型应用开发中很多人面临的瓶颈并不是“调用大模型 API”而是如何让大模型真正完成一项带约束、带工具、带多步骤决策的复杂任务。DeepAgents 作为面向智能体应用的新一代框架就是用来解决这一层问题的。它不是简单封装一个 Chat 调用而是把 Agent 的规划、工具调用、上下文管理和多角色协作从框架层面统一起来让开发人员能够用工程化方式搭建 AI 应用。这篇文章会围绕 DeepAgents 的核心机制展开先说明框架解决什么问题再带你从零搭建一个可运行的 Agent 应用然后逐层拆解工具注册、对话循环、状态管理和参数配置的原理最后给出调试排错和生产落地的建议。学完之后你既能跑通最小示例也能理解框架背后的设计思路应用到实际项目时不会只停留在改参数层面。1. 先理解 DeepAgents 在 AI 应用开发里到底解决什么问题1.1 从“单轮问答”到“智能体应用”的变化早期的 AI 应用大多是一个输入框加一个大模型接口把用户问题发给大模型再把返回结果展示给用户。这种模式适合翻译、摘要、闲聊等单轮生成任务但它不满足更复杂的业务场景。复杂场景有四个典型特征需要完成多个步骤且步骤之间存在依赖关系。需要访问外部数据比如数据库、文件、天气接口、订单系统。需要根据中间结果决定下一步动作而不是一次性生成最终答案。需要把大模型和公司内部已有的服务集成而不是让大模型孤立运行。这类应用就是智能体应用也就是通常说的 Agent。DeepAgents 这类框架的核心价值是把“模型怎么想”和“程序怎么做”这两个层面衔接起来。模型负责理解任务、拆解步骤、决定调用哪个工具程序负责真正执行工具、返回结果、控制循环。1.2 DeepAgents 的定位不是模型而是 Agent 运行时框架DeepAgents 并不是一个新的基础大模型也不是单纯的大模型 API 封装层。它更接近一个 Agent 运行时框架负责管理以下内容Agent 对象的结构化定义。模型与工具之间的调用协议。多轮对话中的上下文保存和更新。多个 Agent 之间的任务交接。工具函数的安全注册和结果返回。对比普通的大模型 SDKDeepAgents 多出来的核心能力是“让模型具备使用工具的能力”。模型本身不知道你的订单接口长什么样但通过 DeepAgents 注册的工具描述和参数定义模型可以在回答前先调用工具拿到结果后再组织最终回复。1.3 什么场景适合用 DeepAgents从实际项目角度看以下场景适合用 DeepAgents场景描述不用的后果客服机器人查订单、查物流、退换货引导模型只能给通用话术无法拿到真实数据数据分析助手用户用自然语言查询报表需要自己解析 SQL 和结果集逻辑复杂文档处理 Agent读取文件、抽取字段、写入表格模型无法直接操作文件系统代码生成与执行生成脚本并执行验证需要自行处理代码安全和执行环境多角色协作任务主编、研究员、审校协作写报告单次调用无法完成多轮评审和修改如果你只是做一个“把问题丢给模型然后显示回复”的工具不需要引入 DeepAgents。但当你开始设计包含工具、状态、步骤和异常处理的应用时框架带来的收益就很明显。2. 环境准备与最小项目结构2.1 环境要求在开始写代码之前先确认机器环境满足要求。DeepAgents 底层依赖 Python 和大模型 SDK建议按以下清单核对项目建议要求说明Python 版本3.10 及以上Agent SDK 对类型注解和异步支持要求较高操作系统Windows 10/11、macOS、Linux框架本身跨平台命令略有差异大模型 API支持 OpenAI 兼容接口或对应云厂商接口需要提前准备好 API Key网络环境能正常访问大模型接口局域网或内网部署需确认白名单包管理工具pip 或 uv推荐使用虚拟环境这里要提醒一点不同版本依赖的官方 SDK 名称和导入路径可能在后续版本中调整。落地时先打开官方文档确认你使用的版本对应的安装包名再执行安装。不要盲目复制旧项目里的 requirements.txt。2.2 创建虚拟环境并安装依赖使用虚拟环境能避免多个项目之间依赖冲突。创建一个新的项目目录然后初始化虚拟环境mkdir deepagents-demo cd deepagents-demo python -m venv .venv激活虚拟环境# Windows .venv\Scripts\activate # macOS / Linux source .venv/bin/activate激活后命令行前缀会变成(.venv)这样后续安装的包都会进入当前项目环境。安装 DeepAgents 相关依赖时建议先指定版本范围这样便于排查问题。实际版本号以你安装时的官方发布版本为准这里给出的是安装思路pip install --upgrade pip pip install deepagents pip install openai如果你的模型服务需要通过环境变量配置 Key可以在项目根目录创建.env文件MODEL_API_KEY你的密钥 MODEL_BASE_URLhttps://你的接口地址 MODEL_NAMEgpt-4o-mini在 Python 中加载环境变量时可以使用python-dotenvpip install python-dotenv2.3 项目文件结构一个最小可运行的 DeepAgents 项目通常包含以下几个文件deepagents-demo/ ├── .env ├── requirements.txt ├── agent.py ├── tools.py └── main.pytools.py定义 Agent 可以调用的工具函数。agent.py定义 Agent 的指令、模型、工具列表。main.py程序入口负责接收用户输入并运行 Agent。这种拆分不是强制的但推荐这样做。工具和 Agent 配置混在一起时项目变复杂后很难维护。尤其是工具数量超过十个以后独立的工具模块能让排查问题更快。3. 从零实现一个最小可运行的 DeepAgents 应用3.1 先定义一个工具让 Agent 能查询实时信息模型本身不知道实时数据所以要给 Agent 注册一个查询工具。这里用一个模拟天气查询的函数作为示例。工具函数的核心特点是输入和返回值都应该是 JSON 可序列化的基本类型这样模型才能理解并正确调用。# tools.py import random def get_weather(city: str) - str: 查询指定城市的天气情况。 Args: city: 城市名称例如 北京、上海、广州。 Returns: 包含天气描述和温度的字符串。 temperature random.randint(15, 32) condition random.choice([晴, 多云, 小雨, 阴]) return f{city} 当前天气{condition}温度{temperature}℃这里有一个容易被忽略的点工具函数够不够“能被模型正确调用”取决于函数名、参数名、参数类型和 docstring 是否清晰。模型靠这些信息决定要不要调用工具、传什么参数。如果参数名是a、b这种无意义名称模型很可能传错值。如果要接入真实业务函数内部替换成 HTTP 请求、数据库查询或 Redis 读取即可。重点是保持出入口简单。3.2 定义 Agent把模型、指令和工具组合起来接下来在agent.py中创建 Agent。需要指定三样东西Agent 的身份和指令。使用的模型名称。可用的工具列表。# agent.py from agents import Agent from tools import get_weather def create_weather_agent() - Agent: return Agent( nameWeatherAssistant, instructions( 你是一个天气助手。 当用户询问某个城市的天气时 你必须先调用 get_weather 工具获取实时天气 再根据工具返回结果组织回答。 ), modelgpt-4o-mini, tools[get_weather], )这里的instructions是很多人容易写得太随意的地方。指令直接决定了 Agent 在复杂情况下如何决策。比如这里明确写了“必须先调用工具再回答”模型就会优先走工具调用路径。如果不加这句话模型可能会凭训练数据里的常识直接回答一个过时天气。model参数需要和你实际使用的模型服务对应。如果使用的是兼容 OpenAI 协议的私有化服务可以在这里传已经配置好的模型名称并在初始化客户端时通过环境变量指向服务地址。3.3 编写入口接收输入并运行 Agent在main.py中创建运行时入口使用Runner执行 Agent并输出最终结果。# main.py import asyncio from dotenv import load_dotenv from agent import create_weather_agent from agents import Runner load_dotenv() async def main(): agent create_weather_agent() user_input input(请输入你的问题) result await Runner.run(agent, inputuser_input) print(最终回答) print(result.final_output) if __name__ __main__: asyncio.run(main())运行python main.py输入请输入你的问题北京今天天气怎么样预期输出会先由 Agent 调起工具再返回类似这样的回答最终回答 北京当前天气多云温度25℃到这里一个最小闭环已经跑通了。整个链路是用户输入 - Agent 理解任务 - 模型决策调用工具 - 工具执行并返回结果 - 模型组织最终回答 - 输出到控制台。3.4 增加多轮对话能力上面的示例只处理单轮输入。实际应用几乎都要支持多轮对话因为用户会在对话中补充信息比如“那上海呢”“明天呢”。如果每轮都重新创建 Agent上下文就会被清空模型无法理解“那”指的是什么。DeepAgents 支持显式传递历史对话内容。可以把之前的消息传递给下一次运行也可以使用框架提供的内存管理功能。下面是不借助额外存储的传参方式# main.py import asyncio from dotenv import load_dotenv from agent import create_weather_agent from agents import Runner load_dotenv() async def main(): agent create_weather_agent() history [] while True: user_input input(你) if user_input.lower() in [exit, quit, 退出]: break history.append({role: user, content: user_input}) result await Runner.run(agent, inputhistory) history.append({role: assistant, content: result.final_output}) print(助手, result.final_output) if __name__ __main__: asyncio.run(main())这里的关键变化是每次传给Runner.run的input不再是一句字符串而是包含多轮消息的列表。Agent 会在内部根据这些消息恢复上下文再决定如何回应当前问题。4. DeepAgents 框架核心机制拆解4.1 Agent 不只是“提示词 模型”而是一个状态机初学者容易把 Agent 理解成“带着很长提示词的模型调用”。实际上Agent 的运行过程是一个带状态的循环模型接收系统指令、历史消息和当前用户消息。模型判断是否需要调用工具。如果不需要直接生成最终回答。如果需要模型输出工具名称和参数。框架解析模型输出调用对应工具。工具返回值被作为新的消息追加进上下文。模型拿到工具结果后继续判断直到不再调用工具为止。这个循环就是为什么工具调用比普通问答复杂的原因。一次用户请求可能触发多次工具调用模型需要根据每次工具结果调整后续步骤。DeepAgents 把循环过程藏在框架内部让开发者只需要定义 Agent 和工具不需要手动写 while 循环去解析模型输出。4.2 工具注册的本质给模型一份“可调用函数清单”工具注册时框架会把函数名、docstring、参数名、参数类型、返回值说明一起转换成模型可读的 JSON Schema。模型在推理时看到这组 Schema才知道有工具可用以及该怎么调用。所以工具代码的质量直接影响模型调用成功率。下面这个反面例子非常典型def process(a, b): # do something return a b这段代码模型很难用对因为a和b没有语义。改成这样后模型就能正确理解def calculate_discount(price: float, discount_rate: float) - float: 根据原价和折扣率计算折后价格。 Args: price: 商品原价单位元。 discount_rate: 折扣率0.8 表示八折。 Returns: 折后价格单位元。 return round(price * discount_rate, 2)另一个常见问题是工具函数传入或返回了无法序列化的对象比如datetime、Decimal、自定义类实例。模型和框架之间靠 JSON 交换数据遇到不可序列化类型会直接报错。工具函数出入口尽量使用字符串、数字、布尔值、列表和字典。4.3 多个工具时模型怎么选择当 Agent 注册了多个工具时模型会根据用户问题、工具描述和参数 Schema 做选择。例如一个 Agent 同时注册了“查天气”和“查明日日出时间”用户问“北京明天适合跑步吗”模型可能先调用查天气工具也可能连续调用两个工具取决于工具描述是否覆盖到“适合跑步”这个语义。这个选择过程不能完全依赖模型自觉。工程上要主动帮助模型做决策给工具起明确的名字。在 docstring 里写清楚“什么时候应该调用这个工具”。不要把功能相似的工具都注册上去。如果某些工具只对特定业务开放应该拆分 Agent而不是堆在同一个 Agent 里。4.4 Agent 与 Agent 之间如何协作DeepAgents 支持把复杂任务拆成多个 Agent再让它们互相交接。比如做一个报告生成系统可以拆成研究员 Agent、写作者 Agent、审校 Agent。研究人员负责收集资料写作者负责生成初稿审校负责检查格式和逻辑。这种多 Agent 协作模式适合任务链路较长、每一步需要不同专家能力的场景。但也不是越多越好。每增加一个 Agent就增加了一次模型决策成本也增加了追踪问题的复杂度。项目初期建议先用单 Agent 加多工具的方式跑通业务确实需要角色分离时再拆分。5. 关键参数详解与配置建议5.1 模型参数控制输出质量和成本DeepAgents 底层调用大模型时通常支持透传模型推理参数。常见的包括温度、最大输出 token、超时时间等。常用参数速查表参数含义默认值调小影响调大影响推荐场景temperature采样随机性0.7 左右输出更确定输出更多样客服、数据提取用低值创意生成用高值max_tokens最大生成长度模型默认回答容易被截断成本变高、延迟变大按业务内容长度估算再加余量timeout请求超时框架默认复杂任务容易超时用户等待太久工具调用较多时适当调大model模型名称必填--根据业务选匹配的模型档次工具调用类任务建议把temperature调低比如 0 到 0.3 之间。工具选择是逻辑决策不是创意生成。温度太高会让模型偶尔选择错误的工具或生成不存在的参数。5.2 Agent 指令的设计原则指令是 Agent 的“系统提示词”。它直接影响模型在关键路径上的行为。好的指令应该包含角色定位。必须执行的流程。禁止做的事。输出格式要求。遇到异常时的处理方式。示例你是订单查询助手。 当用户查询订单时必须按以下步骤执行 1. 先调用 get_order_info 工具。 2. 如果返回结果为空明确告知用户“未查询到订单”。 3. 如果订单状态为“已发货”同时调用 get_express_info 查询物流信息。 4. 不要在未调用工具的情况下臆造订单信息。这里每一步都对应一种可能的执行路径。指令写得越具体模型在边界情况下的表现越稳定。5.3 工具调用开关与最大迭代轮数部分场景中你可能希望 Agent 只看不调工具或者只调用一个特定工具。DeepAgents 允许对 Agent 配置工具使用策略比如强制调用某个工具、允许全部工具、禁止工具。如果允许模型自由调用多个工具一定要关注最大迭代轮数。工具循环没有被限制时模型可能在异常情况下反复调用同一个工具既浪费 token 又增加延迟。建议给工具调用类 Agent 设置合理的最大轮数并增加超时或熔断逻辑。6. 验证、调试与常见问题排查6.1 如何确认 Agent 真的走了工具调用路径很多人跑完程序只看到最终回答就以为 Agent 正常工作。这里要特别提醒如果工具函数里加了随机值但你连续几次输入相同城市得到不同结果说明工具确实被调用了。如果结果完全依赖模型常识那可能工具从未被触发。更可靠的验证方式是开启框架的日志或查看中间消息。可以在代码中打印 Agent 运行过程的全部消息流看看模型是否输出了工具调用消息、工具结果是否正确回传。以常见调试方式为例result await Runner.run(agent, inputuser_input) for item in result.new_items: print(item)这样可以直观看到整个执行链路。后续版本接口可能调整关键是理解思路检查模型输出中是否存在“工具调用请求”以及“工具返回结果”这两个关键环节。6.2 常见报错与排查路径问题现象常见原因检查方式处理建议ModuleNotFoundError: No module named agents未安装依赖或安装到其他虚拟环境执行pip list检查包是否在当前环境先激活虚拟环境再安装依赖工具从未被调用指令不够明确、工具描述不清晰、模型不支持工具调用检查模型是否支持 function calling打印中间消息调整指令改为强制先调用工具模型调用工具时报参数错误工具参数类型与 Schema 不一致或缺省参数导致模型没传全查看报错信息中的参数名给关键参数提供默认值简化参数结构返回结果无法 JSON 序列化工具返回了自定义对象、datetime 等类型打印返回类型在出口处转成字符串或基本类型多轮对话上下文错乱历史消息结构不对或重复传入了系统消息打印传入的 messages 列表按框架要求的消息结构组织历史记录工具调用循环不退出未设置最大迭代轮数或工具结果让模型反复重试查看日志中相同工具被调用次数设置最大轮数并在指令中增加失败退出条件6.3 实战排错工具调用了但是答案离谱假设用户问“北京天气”日志显示工具调用成功工具返回“小雨9℃”但最终回答却写“北京天气晴朗适合外出”。这个问题的根源不在工具调用链路而在最终生成阶段。常见原因是系统指令没有强调“必须依据工具结果回答”。模型认为自己是通用助手凭习惯补充了与工具结果矛盾的信息。解决方式在指令中明确写工具返回结果是唯一事实来源。 回答天气问题时必须完全参考 get_weather 的返回值。 不得补充工具结果之外的天气信息。这个坑在业务数据场景里尤其严重。订单金额、用户余额、库存数量都必须以工具返回为准不能交给模型自由发挥。7. 从 Demo 到生产还需要补齐什么7.1 不要把大模型错误当成普通程序异常处理普通程序异常有明确的异常类型和堆栈。大模型应用的报错往往是“结果错了”而不是“程序崩了”。框架能保证代码不抛异常但无法保证模型每一次决策都正确。生产环境的 Agent 应用需要增加验证环节工具调用参数的合法性校验。返回结果的格式校验。关键业务数据的二次确认。模型输出中的敏感信息过滤。超出置信区间的结果回退策略。比如订单查询场景模型返回“订单已退款”之前应该和订单系统返回的字段逐项核对不能只依赖模型归纳。7.2 配置外置化与环境隔离开发、测试、生产环境的模型名称、API Key、工具服务地址往往不同。不要把这些配置硬编码在代码里。推荐使用环境变量或配置中心管理。import os model_name os.getenv(MODEL_NAME, gpt-4o-mini) api_key os.getenv(MODEL_API_KEY, ) api_base os.getenv(MODEL_BASE_URL, )这样同一个代码包可以部署到不同环境只要各环境配置不同环境变量即可。7.3 日志、监控与可观测性Agent 应用的链路比普通接口更长传统日志只能看到“入参”和“出参”中间过程完全黑盒。生产环境建议至少记录以下内容用户输入。模型使用的指令模板版本。每一轮模型输出内容。工具调用名称、入参、出参、耗时。是否触发工具循环、最大轮数等风险控制。最终回答内容。这些日志不仅是排查依据也是后续优化指令的数据基础。没有日志就无法定位是模型决策错、工具返回错还是提示词引导不够。7.4 安全边界和权限控制要让大模型 Agent 真正落地必须先想清楚它能碰什么、不能碰什么。比如一个可以查数据库的 Agent如果只做过登录校验而没有做行级权限控制模型会变成绕过权限体系的入口。常用的安全策略包括工具函数内部做二次鉴权。对模型可访问的数据范围做白名单。写操作类工具默认不开放改用人工确认模式。对工具调用频率做限流。对敏感字段做脱敏。框架层面的工具机制不等于安全机制。开发人员要假设“模型可能在任何时刻调用任何已注册工具”然后据此设计权限边界。8. 可复用清单与下一步学习路径8.1 新项目落地检查清单每次开发 DeepAgents 应用前可以先过一遍这份清单检查项是否完成说明确认模型服务支持工具调用必检不支持 function calling 的模型无法完成 Agent 闭环确认 Python 版本和虚拟环境必检避免依赖装错环境工具函数出入口是 JSON 可序列化类型必检避免运行时序列化报错工具 docstring 说明了调用条件和参数含义必检直接影响模型调用准确率Agent 指令里说明了关键流程和禁止事项必检避免模型凭常识自由发挥设置最大工具调用轮数建议防止异常情况下无限循环开启日志或消息打印建议开发阶段必须能看到中间链路生产配置使用环境变量必检避免环境间配置串用工具函数内部做了权限校验生产必检防止未授权访问数据最终回答有格式校验生产建议防止模型输出不可解析内容8.2 排查顺序建议遇到问题后按以下顺序定位效率最高确认安装包和环境变量是否正确。确认模型是否支持工具调用。打印原始消息流确认模型是否输出工具调用请求。确认工具是否真正执行返回值是否正常。确认 Agent 指令是否要求模型依据工具结果回答。最后再检查网络、超时、限流等外部因素。这个顺序的核心逻辑是先确认链路断在哪一层再改对应层的配置。很多人一上来就调 temperature 或换模型其实问题可能只是工具函数参数名不清晰。8.3 学习顺序建议如果刚接触 DeepAgents不建议直接读完整框架源码。建议按以下路径学习先跑通最小工具调用示例。增加多工具选择和条件判断。加入多轮对话和上下文记忆。拆分成多个 Agent理解任务交接。阅读框架官方文档中关于事件流和生命周期的说明。接入真实业务数据设计权限和验证机制。每一步都以“能解释清楚为什么这样配置”为目标。框架 API 会升级但工具调用、上下文管理、多轮循环、状态控制这些核心概念不会变。理解原理后即使未来换一个 Agent 框架迁移成本也会低很多。DeepAgents 最值得投入时间学习的部分不是某个具体的 API 写法而是它如何把“模型决策”和“程序执行”稳定地连接起来。把这个连接机制理解透AI 大模型应用开发就不再只是调接口而是真正在设计和实现一个能干活、可维护、可进化的智能体系统。