从deepseek-ai/awesome-deepseek-agent这个名字说起它大概率是围绕 DeepSeek 生态整理的 Agent 资源合集。对于真正开始接触 Agent 开发的开发者来说这份仓库的意义不在收藏而在于提供一个可以照着前进的入口理解 DeepSeek Agent 生态有哪些框架、工具和示例再动手把最基础的 Agent 循环跑通。Agent 发展速度很快光看框架对比并不能建立长期有效的能力。更稳妥的做法是先掌握 Agent 的最小运行逻辑然后再借助 awesome 类仓库去挑选合适自己的框架。下面会沿着一条主线展开先看清这类资源仓库的定位和边界再梳理 Agent 开发前必须建立的概念然后用 DeepSeek 官方兼容接口写一个最小可运行的 Agent 示例最后讨论如何从演示代码走向生产项目、如何排查报错、如何在阅读 awesome 列表后做框架选型。1. 先看懂 awesome-deepseek-agent 的定位和使用边界1.1 Awesome 列表不是文档也不是 SDKGitHub 上awesome-*仓库通常按主题收集框架、工具、文章、示例和社区项目。deepseek-ai/awesome-deepseek-agent的关键词是 DeepSeek 和 Agent。它想要解决的信息分散问题很典型DeepSeek 负责提供模型能力Agent 则是结合模型、工具、记忆和流程去完成多步任务的软件形态。从模型到 Agent 之间会牵扯模型调用、工具协议、记忆策略、任务编排、效果评测、安全控制等多个层次。如果没有一个信息入口排查问题时会非常被动。但需要注意awesome 列表本质上属于“线索列表”而不是权威参考。它可以帮助你快速找到一堆可尝试的项目但必须继续追到官方文档、源码和 Issue 才能做出准确判断。信息类型适合回答的问题需要注意的问题awesome 列表生态里有哪些项目、大致怎么分类可能更新不及时分类粒度受仓库维护者影响官方文档当前版本支持哪些 API、参数含义、兼容范围版本变化后网文会失效要以文档为准源码某个字段到底怎么解析、执行顺序是什么阅读成本较高适合定位具体的异常示例项目一个功能如何组合起来示例为演示目的省略了生产环境的异常处理1.2 为什么 Agent 开发特别需要地图式资源仓库Agent 项目和普通 Web 项目不同它没有一套统一的行业标准。不同框架对 Tool、Skill、Memory、Plugin 的定义和处理方式都不一样。即使只是“调用一个大模型”也需要考虑消息序列、函数声明、工具返回格式、循环终止条件等因素。再往上一层还有多 Agent 的协作方式、任务规划、人工审批、日志追踪等问题。这份仓库如果维护得当会把这些问题按层次拆开例如列出官方示例、Agent 框架、记忆方案、可观测工具、评测基准等。读者可以从自己当前最缺的环节进入而不是从零开始搜索整个生态。用的时候建议按这个顺序执行先读 README 的目录结构搞清楚仓库按什么维度分类。从列表里挑出至少三个候选项目不要只看排在最前面的项目。每个候选项目都要追到官方文档和源码确认维护活跃度。只保留一到两个项目进入本地验证阶段。用最小 Demo 跑通之后再往里面加入业务逻辑。如果想长期维护这份清单也可以在本地做一份私有副本git clone https://github.com/deepseek-ai/awesome-deepseek-agent.git cd awesome-deepseek-agent后续仓库更新时直接拉取远程变更即可。1.3 资源清单无法替代本地验证Awesome 列表展示的是“有人整理过的候选方案”不是“适配你业务场景的最终答案”。例如一个框架在示例里很好用但真实项目中可能需要支持特殊鉴权、私有化部署、流式输出、多租户隔离这些通常不会出现在列表的简介里。所以在阅读列表时要给自己加一条约束任何仓库只有本地跑通最小 Demo 后才算初步可用。记录每个项目时建议至少标注四个字段项目名称、解决的问题、依赖要求、本地验证结果。否则几个月后再打开这份记录依然很难判断当时为什么收藏它。2. Agent 开发前需要建立的几个核心概念2.1 Agent 不是对模型接口的简单包装很多刚接触 Agent 的开发者会以为给大模型写一个很长的 System Prompt再让它连续回答就是一个 Agent。实际上 Agent 的核心特征是“自主决策 工具调用 循环执行”。普通对话是一次模型调用Agent 则可能因为工具返回结果再次调用模型并根据新的结果决定下一步行动。可以这样理解模型提供推理能力它决定“根据当前信息下一步该做什么”。工具提供执行能力例如计算、查数据库、调用 API。Agent 循环负责把模型决策、工具执行、结果合并起来直到任务完成或达到终止条件。DeepSeek 提供的是模型能力。Agent 部分需要开发者自己组织或者借助框架完成。这也是为什么awesome-deepseek-agent会聚焦在 DeepSeek 与 Agent 的交汇点上因为只有模型而没有 Agent 结构很难完成多步任务。2.2 Tool、Skill、Agent、Workflow 的区别在 Agent 生态里Tool、Skill、Agent、Workflow 经常被放在一起讨论但它们的粒度并不相同。概念粒度作用例子是否自带决策循环Tool单个可执行函数获取天气、执行 SQL、发送消息否Skill一组完成特定任务的指令和方法数据分析技能、发票信息提取技能通常由 Agent 或人工触发Agent有记忆、工具、决策循环的完整应用自动排障 Agent、客服 Agent是Workflow固定顺序或分支的流程先审核内容再生成回复草稿否流程预先固定在开发时最容易犯的错误是把所有东西都叫 Agent。比如一个固定调用定时任务的脚本更接近 Workflow一段只负责解析 PDF 的代码更接近 Tool而真正的 Agent 需要在没有人工干预的情况下决定调用哪些 Tool、按什么顺序调用。2.3 多 Agent 主从模式SubAgent 也可以当作 Tool 使用多 Agent 设计里经常提到主从模式。主 Agent 负责理解目标、拆解任务从 Agent 负责执行子任务并把结果返回给主 Agent。主从模式并不神秘在实现时可以把 SubAgent 看成一种“更复杂的工具调用”。这样做有几个明显好处主 Agent 的 Prompt 不需要塞入太多领域知识。子任务可以拥有独立的上下文避免无关信息污染主对话。单个 SubAgent 出错时可以隔离不影响主流程。主 Agent 可以把 SubAgent 的返回结果当作普通 Tool 结果继续推理。但缺点同样存在每次 SubAgent 调用都会产生额外的大模型请求成本更高延迟更长。如果任务本身是固定的三步使用 Workflow 会更稳定如果任务高度开放才值得用主从 Agent。3. 用 DeepSeek 兼容接口搭建最小 Agent 循环3.1 准备 Python 环境和依赖这一段以 Python 为例。先创建一个独立目录和虚拟环境避免把依赖装乱mkdir deepseek-agent-demo cd deepseek-agent-demo python3 -m venv .venv source .venv/bin/activate在 Windows 下激活命令可以换成.venv\Scripts\activate接着安装openai与python-dotenv。DeepSeek 提供 OpenAI 兼容接口因此可以使用 OpenAI Python SDK 来请求但在初始化时需要把base_url指向 DeepSeek 的接口地址。pip install -U openai python-dotenv创建.env文件把 API Key 放进去DEEPSEEK_API_KEY你的_api_key DEEPSEEK_BASE_URLhttps://api.deepseek.com不要把这个文件提交到 Git正式项目应该通过 CI/CD 的密钥管理或云平台的 Secrets 注入环境变量。3.2 一个最小可运行的 Agent 循环下面代码会实现一个非常朴素的 Agent 循环模型接收用户问题如果它认为需要工具就返回工具调用信息程序执行工具后把结果以 tool 消息的形式返回给模型模型继续判断直到不再需要调用工具。import json import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) def add_numbers(a: int, b: int) - dict: 计算两个整数的和。这里仅用于演示工具调用。 return {a: a, b: b, sum: a b} TOOL_SCHEMAS [ { type: function, function: { name: add_numbers, description: 计算两个整数的和。当用户要求做加法运算时调用。, parameters: { type: object, properties: { a: {type: integer, description: 第一个整数}, b: {type: integer, description: 第二个整数}, }, required: [a, b], }, }, } ] TOOL_IMPL { add_numbers: add_numbers, } SYSTEM_PROMPT 你是一个 DeepSeek Agent。当用户需要计算两个整数的和时必须调用 add_numbers 工具。 def run_agent(user_input: str, max_steps: int 5) - tuple[str, list, int]: messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolsTOOL_SCHEMAS, tool_choiceauto, temperature0.3, max_tokens1024, ) message response.choices[0].message assistant_message { role: assistant, content: message.content or , } tool_calls getattr(message, tool_calls, None) or [] if not tool_calls: return message.content or , messages, step 1 assistant_message[tool_calls] [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments or , }, } for tc in tool_calls ] messages.append(assistant_message) for tc in tool_calls: function_name tc.function.name try: arguments json.loads(tc.function.arguments or {}) if function_name not in TOOL_IMPL: result {error: funknown tool: {function_name}} else: result TOOL_IMPL[function_name](**arguments) except Exception as exc: result {error: f{type(exc).__name__}: {exc}} messages.append( { role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse), } ) return 达到最大步数已停止循环。, messages, max_steps if __name__ __main__: text, history, steps run_agent(请使用工具计算 3 5 的结果) print(text) print(f\nsteps{steps}, history_len{len(history)})保存为agent_demo.py然后运行python agent_demo.py如果配置正确模型会先判断需要工具然后程序执行add_numbers把结果返回给模型最后模型输出类似3 5 8的结果。3.3 这段代码的关键点这段代码虽然很短但已经具备 Agent 循环的基本要素。第一messages是核心。模型看到的不是用户一句话而是“系统提示、用户输入、助手工具调用、工具执行结果”的完整序列。顺序错误会导致接口报错。第二TOOL_SCHEMAS必须使用 JSON Schema 描述函数。模型不直接执行 Python 函数它只看函数的声明和描述然后返回一个格式化的调用意图。真正执行函数的是你的程序。第三function.arguments是字符串不是 Python 对象。代码里用json.loads(...)解析并在外层加了异常保护。真实项目里不能假设所有模型返回的 JSON 都是合法的。第四max_steps是循环终止条件。Agent 可能因为工具结果异常而连续调用模型如果不限制最大步数会产生不可控的成本和卡死风险。3.4 常用参数的影响在 DeepSeek 兼容接口中下面几个参数值得在调试时重点关注。参数示例值作用调大或调小的影响modeldeepseek-chat指定使用的模型不同模型能力不同需参考官方说明temperature0.3控制采样随机性调低更稳定调高更多样max_tokens1024限制单次回复的最大长度太小会导致回答被截断tool_choiceauto是否强制模型调用工具auto 灵活具体值需确认接口支持范围streamfalse是否流式返回内容打开后需要处理增量数据不适合最小示例Agent 场景通常会把temperature调低让模型更稳定地依据工具返回结果作答。但具体还要看业务如果任务是生成创意文案偏低温度可能显得机械。4. 从演示代码走向可维护的 Agent 工程4.1 先处理 Memory而不是一直追加消息演示代码把所有消息都拼在messages里这在短对话中没问题。真实项目里用户可能对话很多轮也可能执行了几十个工具调用。如果一直追加最终会超出模型的上下文长度也会拖慢响应速度。项目里常见的做法是分层处理记忆记忆层次存放内容实现思路短期上下文当前任务的关键消息保留 system、最近若干轮对话和在途工具调用滑动窗口固定长度历史超长部分丢弃或压缩摘要记忆已经被压缩的历史结论定期把早期消息总结成一段摘要外部记忆业务沉淀、向量数据库只在需要时检索相关片段最简单的方式是给消息列表设置保留上限。保留时要注意不能只截断到中间的 assistant/tool 消息否则会破坏 tool 与 assistant 之间的对应关系。def trim_messages(messages, max_history10): system_messages [m for m in messages if m[role] system] tail_messages messages[-max_history:] return system_messages tail_messages这个函数只是示意图。真实场景里最好从消息中拆分出“不可丢的系统消息”和“可裁剪的历史消息”裁剪后还要用长度预算校验避免出现“最后一条是 tool但前面对应的 assistant 被删掉”的情况。4.2 配置与 Prompt 要从代码中剥离在演示代码中模型名、temperature、system prompt 都写在 Python 文件里。生产项目建议把这些内容外置常见的做法是使用 YAML 或 JSONmodel: deepseek-chat temperature: 0.2 max_tokens: 1024 tool_choice: auto system_prompt: | 你是一个 DeepSeek Agent。 当用户需要计算两个整数的和时必须调用 add_numbers 工具。代码读取配置后注入模型参数。这样做的好处是调整提示词和参数不用改代码、不用重新构建镜像也方便不同环境使用不同配置。但配置外置不等于不做变更管理生产环境修改配置后必须走审批和发布流程。4.3 把 SubAgent 抽象成一种工具如果业务开始变复杂例如需要子 Agent 做代码审查、数据分析或日志分析可以在主 Agent 中新增一个“运行子 Agent”的工具。工具的描述要写清楚它适合处理什么任务。{ name: run_subagent, description: 把代码审查任务交给子 Agent 执行。仅当用户需要审查代码时使用。, parameters: { type: object, properties: { agent_name: {type: string, description: 子 Agent 名称}, task: {type: string, description: 交给子 Agent 的详细任务} }, required: [agent_name, task] } }在主 Agent 的工具执行函数里方法也很直接def run_subagent(agent_name: str, task: str) - dict: agent SUBAGENTS.get(agent_name) if agent is None: return {error: funknown subagent: {agent_name}} return agent.run(task)这种设计把主 Agent 变成调度器把子任务包装成工具由模型根据用户意图动态决定是否调用。不过要清醒地认识到每次子 Agent 的启动都会增加一次或多次模型调用。只有当子任务确实需要独立上下文和独立策略时才适合这样拆。5. Agent 运行验证与常见问题排查5.1 运行 Demo 后如何验证成功验证 Agent 不是只看“程序没抛错”。对于上面的最小示例至少应该确认三件事模型是否返回了tool_calls如果完全没有说明模型没有判断出需要工具。工具是否被真正执行可以打印函数返回值或检查日志。工具结果是否被模型引用最终回答中应该出现3 5 8或相近内容。如果一次运行没有触发工具可以先用更明确的指令测试例如“你必须调用 add_numbers 工具计算 35”。这能帮助区分是模型选择问题还是工具声明问题。5.2 常见报错排查表问题现象常见原因检查方式处理建议401 认证失败API Key 缺失或错误检查.env是否加载打印环境变量是否存在重新设置DEEPSEEK_API_KEY404 或模型不存在model 名称写错或接口不支持该模型查看官方模型列表换成官方文档中的模型名400 请求格式错误messages 不是合法列表或 role 拼写错误打印 messages 再请求使用标准 rolesystem、user、assistant、tooltool role 报错缺少 assistant 的 tool_calls或 tool_call_id 不匹配按顺序打印最近三条消息确保每次工具结果前都追加了对应的 assistant_tool_callsfunction.arguments 解析失败模型返回了不合法 JSON打印原始字符串加上json.loads和异常保护模型不调用工具工具描述不清晰或模型本身不支持该接口查看响应是否返回了tool_calls的空列表优化工具描述明确使用场景必要时换 model回答被截断max_tokens 太小观察回答结尾是否突然中断调大 max_tokens或改用流式输出后拼接上下文长度超限消息累积过多检查 messages 的 token 估算启用滑动窗口或摘要压缩5.3 排查一条报错的前后顺序当 Agent 报错时建议按照从前到后的顺序检查。先确认环境变量和 API Key 能不能请求通再确认模型名与 endpoint 是否正确。之后重点看 messages 的历史顺序尤其是 assistant 的tool_calls是否紧跟着对应的 tool 返回消息。如果一段代码之前能运行改完 Prompt 后突然出错大概率不是 API 出了问题而是模型根据新 Prompt 生成了格式不同的 tool_calls导致解析层崩溃。此时要回到解析函数先打印tool_calls的原始结构。6. 阅读 awesome 列表后如何做框架选型6.1 选型应该关注更本质的问题Awesome 列表会给你很多候选项目但不要在项目描述的“功能很长”上做决定。作为开发者真正要关注的是框架如何管理 Agent 循环、工具协议和上下文状态。可以用下面几个问题快速判断这个框架的最小 Demo 需要多少代码才能跑通它是否屏蔽了 tool_calls 的细节如果屏蔽了框架内部出问题时能否查看完整消息日志它如何管理长期记忆是插件机制、内置向量库还是只负责把内存传给模型它是否支持流式输出、人工确认、中断恢复这些生产特性它的许可证是否允许你的业务场景使用项目最近是否还有提交和 Issue 回复6.2 用清单避免被列表带偏阅读 awesome 列表时建议输出一份自己的评估表维度检查项候选 A候选 B运行门槛能否在 30 分钟内跑通文档完整度是否有环境、示例、API 说明工具协议是否支持自定义函数声明记忆能力是否提供开箱即用的会话管理可观测性是否能打印完整调用链和 token 数生产适配是否支持鉴权、日志、回滚社区活跃度最近是否有提交与 Issue 回复填表时不能只看 README 的自述。如果候选项目依赖私有组件或需要额外服务必须把它写入“运行门槛”并亲自验证。6.3 更稳妥的成长路线对大多数开发者来说不要一上来就选择最复杂的 Agent 框架。先用官方接口写一次裸 Agent 循环理解messages和tool_calls的结构再尝试在代码中加入一个只有内部逻辑的简单工具比如两个整数相加通过后再引入框架这时候你能判断框架到底帮你省了什么又隐藏了什么。这个顺序也适合使用awesome-deepseek-agent的学习路径先看列表里的官方示例和教程然后把官方接口的最小示例跑通再看框架项目。这样才能把“别人整理好的清单”变成“自己能消化的知识结构”。7. 生产化之前需要补齐的安全、成本与可观测性7.1 工具权限必须收窄Agent 的工具调用由模型自主发起这带来一个关键风险模型可能因为恶意注入、错误推断或 Prompt 冲突调用一个不合理的工具。因此工具实现必须遵循最小权限原则。不应该让 Agent 拥有无限制执行 Shell、删除文件、转账、修改数据库的权限。即使业务确实需要这些能力也应增加人工审批步骤。工具函数内部也要做参数校验和权限校验不能直接信任模型生成的参数。例如不能写出这样的工具函数去执行任意表达式# 不推荐危险 def run_calculator(expression: str): return eval(expression)推荐做法是对表达式做解析只允许四则运算或者使用安全的 AST 解析库。Agent 的工具边界本质上是业务安全边界。模型负责决策但你能不能让它决策那么多由开发者的责任边界决定。7.2 Token、延迟与费用要有监控Agent 循环会放大模型的调用次数。一次用户请求可能触发十几次模型调用工具返回结果后还会再次调用。没有预算控制会很危险。生产项目需要记录每次请求使用多少 token。一个用户会话累计使用多少 token。一次 Agent 任务产生多少次模型调用。一次任务平均延迟是多少。Python 工具执行本身耗时多少。在日志里记录模型名称、输入 token、输出 token、耗时和 Agent 步数能帮助定位很多问题。例如用户反馈回复很慢查看日志后可能发现某次任务调用了 20 次模型而不是接口本身慢。7.3 可观测性比“能跑通”更重要调试 Agent 时最困难的一点是中间状态很多模型看到了什么、工具返回了什么、为什么最终决定不调用工具这些信息如果不记录问题几乎无法复现。一个轻量手段是在每个循环步骤里打印关键信息# 供开发调试使用的示例 print(step:, step) print(model response:, message) print(tool calls:, tool_calls) print(tool results:, result)在正式系统里应该将同样的信息写入结构化日志或链路追踪服务。对 Agent 应用来说完整记录“模型输入、工具选择、工具结果、模型输出”是一条非常重要的排错链路不能省。编写 Agent 的能力不是靠背框架 API而是靠理解循环中的每一步模型如何选择工具、工具返回后如何影响下一轮模型判断、中间状态如何被记录和回溯。能把最小循环跑通再逐步引入记忆、子 Agent 和工程化配置才是阅读 awesome 类仓库后最有效的落地方式。 
长河君 · 2026/9/4 2:12:20 · 阅读 1.2k DeepSeek Agent开发实战：从awesome资源仓库到最小循环
从deepseek-ai/awesome-deepseek-agent这个名字说起它大概率是围绕 DeepSeek 生态整理的 Agent 资源合集。对于真正开始接触 Agent 开发的开发者来说这份仓库的意义不在收藏而在于提供一个可以照着前进的入口理解 DeepSeek Agent 生态有哪些框架、工具和示例再动手把最基础的 Agent 循环跑通。Agent 发展速度很快光看框架对比并不能建立长期有效的能力。更稳妥的做法是先掌握 Agent 的最小运行逻辑然后再借助 awesome 类仓库去挑选合适自己的框架。下面会沿着一条主线展开先看清这类资源仓库的定位和边界再梳理 Agent 开发前必须建立的概念然后用 DeepSeek 官方兼容接口写一个最小可运行的 Agent 示例最后讨论如何从演示代码走向生产项目、如何排查报错、如何在阅读 awesome 列表后做框架选型。1. 先看懂 awesome-deepseek-agent 的定位和使用边界1.1 Awesome 列表不是文档也不是 SDKGitHub 上awesome-*仓库通常按主题收集框架、工具、文章、示例和社区项目。deepseek-ai/awesome-deepseek-agent的关键词是 DeepSeek 和 Agent。它想要解决的信息分散问题很典型DeepSeek 负责提供模型能力Agent 则是结合模型、工具、记忆和流程去完成多步任务的软件形态。从模型到 Agent 之间会牵扯模型调用、工具协议、记忆策略、任务编排、效果评测、安全控制等多个层次。如果没有一个信息入口排查问题时会非常被动。但需要注意awesome 列表本质上属于“线索列表”而不是权威参考。它可以帮助你快速找到一堆可尝试的项目但必须继续追到官方文档、源码和 Issue 才能做出准确判断。信息类型适合回答的问题需要注意的问题awesome 列表生态里有哪些项目、大致怎么分类可能更新不及时分类粒度受仓库维护者影响官方文档当前版本支持哪些 API、参数含义、兼容范围版本变化后网文会失效要以文档为准源码某个字段到底怎么解析、执行顺序是什么阅读成本较高适合定位具体的异常示例项目一个功能如何组合起来示例为演示目的省略了生产环境的异常处理1.2 为什么 Agent 开发特别需要地图式资源仓库Agent 项目和普通 Web 项目不同它没有一套统一的行业标准。不同框架对 Tool、Skill、Memory、Plugin 的定义和处理方式都不一样。即使只是“调用一个大模型”也需要考虑消息序列、函数声明、工具返回格式、循环终止条件等因素。再往上一层还有多 Agent 的协作方式、任务规划、人工审批、日志追踪等问题。这份仓库如果维护得当会把这些问题按层次拆开例如列出官方示例、Agent 框架、记忆方案、可观测工具、评测基准等。读者可以从自己当前最缺的环节进入而不是从零开始搜索整个生态。用的时候建议按这个顺序执行先读 README 的目录结构搞清楚仓库按什么维度分类。从列表里挑出至少三个候选项目不要只看排在最前面的项目。每个候选项目都要追到官方文档和源码确认维护活跃度。只保留一到两个项目进入本地验证阶段。用最小 Demo 跑通之后再往里面加入业务逻辑。如果想长期维护这份清单也可以在本地做一份私有副本git clone https://github.com/deepseek-ai/awesome-deepseek-agent.git cd awesome-deepseek-agent后续仓库更新时直接拉取远程变更即可。1.3 资源清单无法替代本地验证Awesome 列表展示的是“有人整理过的候选方案”不是“适配你业务场景的最终答案”。例如一个框架在示例里很好用但真实项目中可能需要支持特殊鉴权、私有化部署、流式输出、多租户隔离这些通常不会出现在列表的简介里。所以在阅读列表时要给自己加一条约束任何仓库只有本地跑通最小 Demo 后才算初步可用。记录每个项目时建议至少标注四个字段项目名称、解决的问题、依赖要求、本地验证结果。否则几个月后再打开这份记录依然很难判断当时为什么收藏它。2. Agent 开发前需要建立的几个核心概念2.1 Agent 不是对模型接口的简单包装很多刚接触 Agent 的开发者会以为给大模型写一个很长的 System Prompt再让它连续回答就是一个 Agent。实际上 Agent 的核心特征是“自主决策 工具调用 循环执行”。普通对话是一次模型调用Agent 则可能因为工具返回结果再次调用模型并根据新的结果决定下一步行动。可以这样理解模型提供推理能力它决定“根据当前信息下一步该做什么”。工具提供执行能力例如计算、查数据库、调用 API。Agent 循环负责把模型决策、工具执行、结果合并起来直到任务完成或达到终止条件。DeepSeek 提供的是模型能力。Agent 部分需要开发者自己组织或者借助框架完成。这也是为什么awesome-deepseek-agent会聚焦在 DeepSeek 与 Agent 的交汇点上因为只有模型而没有 Agent 结构很难完成多步任务。2.2 Tool、Skill、Agent、Workflow 的区别在 Agent 生态里Tool、Skill、Agent、Workflow 经常被放在一起讨论但它们的粒度并不相同。概念粒度作用例子是否自带决策循环Tool单个可执行函数获取天气、执行 SQL、发送消息否Skill一组完成特定任务的指令和方法数据分析技能、发票信息提取技能通常由 Agent 或人工触发Agent有记忆、工具、决策循环的完整应用自动排障 Agent、客服 Agent是Workflow固定顺序或分支的流程先审核内容再生成回复草稿否流程预先固定在开发时最容易犯的错误是把所有东西都叫 Agent。比如一个固定调用定时任务的脚本更接近 Workflow一段只负责解析 PDF 的代码更接近 Tool而真正的 Agent 需要在没有人工干预的情况下决定调用哪些 Tool、按什么顺序调用。2.3 多 Agent 主从模式SubAgent 也可以当作 Tool 使用多 Agent 设计里经常提到主从模式。主 Agent 负责理解目标、拆解任务从 Agent 负责执行子任务并把结果返回给主 Agent。主从模式并不神秘在实现时可以把 SubAgent 看成一种“更复杂的工具调用”。这样做有几个明显好处主 Agent 的 Prompt 不需要塞入太多领域知识。子任务可以拥有独立的上下文避免无关信息污染主对话。单个 SubAgent 出错时可以隔离不影响主流程。主 Agent 可以把 SubAgent 的返回结果当作普通 Tool 结果继续推理。但缺点同样存在每次 SubAgent 调用都会产生额外的大模型请求成本更高延迟更长。如果任务本身是固定的三步使用 Workflow 会更稳定如果任务高度开放才值得用主从 Agent。3. 用 DeepSeek 兼容接口搭建最小 Agent 循环3.1 准备 Python 环境和依赖这一段以 Python 为例。先创建一个独立目录和虚拟环境避免把依赖装乱mkdir deepseek-agent-demo cd deepseek-agent-demo python3 -m venv .venv source .venv/bin/activate在 Windows 下激活命令可以换成.venv\Scripts\activate接着安装openai与python-dotenv。DeepSeek 提供 OpenAI 兼容接口因此可以使用 OpenAI Python SDK 来请求但在初始化时需要把base_url指向 DeepSeek 的接口地址。pip install -U openai python-dotenv创建.env文件把 API Key 放进去DEEPSEEK_API_KEY你的_api_key DEEPSEEK_BASE_URLhttps://api.deepseek.com不要把这个文件提交到 Git正式项目应该通过 CI/CD 的密钥管理或云平台的 Secrets 注入环境变量。3.2 一个最小可运行的 Agent 循环下面代码会实现一个非常朴素的 Agent 循环模型接收用户问题如果它认为需要工具就返回工具调用信息程序执行工具后把结果以 tool 消息的形式返回给模型模型继续判断直到不再需要调用工具。import json import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) def add_numbers(a: int, b: int) - dict: 计算两个整数的和。这里仅用于演示工具调用。 return {a: a, b: b, sum: a b} TOOL_SCHEMAS [ { type: function, function: { name: add_numbers, description: 计算两个整数的和。当用户要求做加法运算时调用。, parameters: { type: object, properties: { a: {type: integer, description: 第一个整数}, b: {type: integer, description: 第二个整数}, }, required: [a, b], }, }, } ] TOOL_IMPL { add_numbers: add_numbers, } SYSTEM_PROMPT 你是一个 DeepSeek Agent。当用户需要计算两个整数的和时必须调用 add_numbers 工具。 def run_agent(user_input: str, max_steps: int 5) - tuple[str, list, int]: messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_input}, ] for step in range(max_steps): response client.chat.completions.create( modeldeepseek-chat, messagesmessages, toolsTOOL_SCHEMAS, tool_choiceauto, temperature0.3, max_tokens1024, ) message response.choices[0].message assistant_message { role: assistant, content: message.content or , } tool_calls getattr(message, tool_calls, None) or [] if not tool_calls: return message.content or , messages, step 1 assistant_message[tool_calls] [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments or , }, } for tc in tool_calls ] messages.append(assistant_message) for tc in tool_calls: function_name tc.function.name try: arguments json.loads(tc.function.arguments or {}) if function_name not in TOOL_IMPL: result {error: funknown tool: {function_name}} else: result TOOL_IMPL[function_name](**arguments) except Exception as exc: result {error: f{type(exc).__name__}: {exc}} messages.append( { role: tool, tool_call_id: tc.id, content: json.dumps(result, ensure_asciiFalse), } ) return 达到最大步数已停止循环。, messages, max_steps if __name__ __main__: text, history, steps run_agent(请使用工具计算 3 5 的结果) print(text) print(f\nsteps{steps}, history_len{len(history)})保存为agent_demo.py然后运行python agent_demo.py如果配置正确模型会先判断需要工具然后程序执行add_numbers把结果返回给模型最后模型输出类似3 5 8的结果。3.3 这段代码的关键点这段代码虽然很短但已经具备 Agent 循环的基本要素。第一messages是核心。模型看到的不是用户一句话而是“系统提示、用户输入、助手工具调用、工具执行结果”的完整序列。顺序错误会导致接口报错。第二TOOL_SCHEMAS必须使用 JSON Schema 描述函数。模型不直接执行 Python 函数它只看函数的声明和描述然后返回一个格式化的调用意图。真正执行函数的是你的程序。第三function.arguments是字符串不是 Python 对象。代码里用json.loads(...)解析并在外层加了异常保护。真实项目里不能假设所有模型返回的 JSON 都是合法的。第四max_steps是循环终止条件。Agent 可能因为工具结果异常而连续调用模型如果不限制最大步数会产生不可控的成本和卡死风险。3.4 常用参数的影响在 DeepSeek 兼容接口中下面几个参数值得在调试时重点关注。参数示例值作用调大或调小的影响modeldeepseek-chat指定使用的模型不同模型能力不同需参考官方说明temperature0.3控制采样随机性调低更稳定调高更多样max_tokens1024限制单次回复的最大长度太小会导致回答被截断tool_choiceauto是否强制模型调用工具auto 灵活具体值需确认接口支持范围streamfalse是否流式返回内容打开后需要处理增量数据不适合最小示例Agent 场景通常会把temperature调低让模型更稳定地依据工具返回结果作答。但具体还要看业务如果任务是生成创意文案偏低温度可能显得机械。4. 从演示代码走向可维护的 Agent 工程4.1 先处理 Memory而不是一直追加消息演示代码把所有消息都拼在messages里这在短对话中没问题。真实项目里用户可能对话很多轮也可能执行了几十个工具调用。如果一直追加最终会超出模型的上下文长度也会拖慢响应速度。项目里常见的做法是分层处理记忆记忆层次存放内容实现思路短期上下文当前任务的关键消息保留 system、最近若干轮对话和在途工具调用滑动窗口固定长度历史超长部分丢弃或压缩摘要记忆已经被压缩的历史结论定期把早期消息总结成一段摘要外部记忆业务沉淀、向量数据库只在需要时检索相关片段最简单的方式是给消息列表设置保留上限。保留时要注意不能只截断到中间的 assistant/tool 消息否则会破坏 tool 与 assistant 之间的对应关系。def trim_messages(messages, max_history10): system_messages [m for m in messages if m[role] system] tail_messages messages[-max_history:] return system_messages tail_messages这个函数只是示意图。真实场景里最好从消息中拆分出“不可丢的系统消息”和“可裁剪的历史消息”裁剪后还要用长度预算校验避免出现“最后一条是 tool但前面对应的 assistant 被删掉”的情况。4.2 配置与 Prompt 要从代码中剥离在演示代码中模型名、temperature、system prompt 都写在 Python 文件里。生产项目建议把这些内容外置常见的做法是使用 YAML 或 JSONmodel: deepseek-chat temperature: 0.2 max_tokens: 1024 tool_choice: auto system_prompt: | 你是一个 DeepSeek Agent。 当用户需要计算两个整数的和时必须调用 add_numbers 工具。代码读取配置后注入模型参数。这样做的好处是调整提示词和参数不用改代码、不用重新构建镜像也方便不同环境使用不同配置。但配置外置不等于不做变更管理生产环境修改配置后必须走审批和发布流程。4.3 把 SubAgent 抽象成一种工具如果业务开始变复杂例如需要子 Agent 做代码审查、数据分析或日志分析可以在主 Agent 中新增一个“运行子 Agent”的工具。工具的描述要写清楚它适合处理什么任务。{ name: run_subagent, description: 把代码审查任务交给子 Agent 执行。仅当用户需要审查代码时使用。, parameters: { type: object, properties: { agent_name: {type: string, description: 子 Agent 名称}, task: {type: string, description: 交给子 Agent 的详细任务} }, required: [agent_name, task] } }在主 Agent 的工具执行函数里方法也很直接def run_subagent(agent_name: str, task: str) - dict: agent SUBAGENTS.get(agent_name) if agent is None: return {error: funknown subagent: {agent_name}} return agent.run(task)这种设计把主 Agent 变成调度器把子任务包装成工具由模型根据用户意图动态决定是否调用。不过要清醒地认识到每次子 Agent 的启动都会增加一次或多次模型调用。只有当子任务确实需要独立上下文和独立策略时才适合这样拆。5. Agent 运行验证与常见问题排查5.1 运行 Demo 后如何验证成功验证 Agent 不是只看“程序没抛错”。对于上面的最小示例至少应该确认三件事模型是否返回了tool_calls如果完全没有说明模型没有判断出需要工具。工具是否被真正执行可以打印函数返回值或检查日志。工具结果是否被模型引用最终回答中应该出现3 5 8或相近内容。如果一次运行没有触发工具可以先用更明确的指令测试例如“你必须调用 add_numbers 工具计算 35”。这能帮助区分是模型选择问题还是工具声明问题。5.2 常见报错排查表问题现象常见原因检查方式处理建议401 认证失败API Key 缺失或错误检查.env是否加载打印环境变量是否存在重新设置DEEPSEEK_API_KEY404 或模型不存在model 名称写错或接口不支持该模型查看官方模型列表换成官方文档中的模型名400 请求格式错误messages 不是合法列表或 role 拼写错误打印 messages 再请求使用标准 rolesystem、user、assistant、tooltool role 报错缺少 assistant 的 tool_calls或 tool_call_id 不匹配按顺序打印最近三条消息确保每次工具结果前都追加了对应的 assistant_tool_callsfunction.arguments 解析失败模型返回了不合法 JSON打印原始字符串加上json.loads和异常保护模型不调用工具工具描述不清晰或模型本身不支持该接口查看响应是否返回了tool_calls的空列表优化工具描述明确使用场景必要时换 model回答被截断max_tokens 太小观察回答结尾是否突然中断调大 max_tokens或改用流式输出后拼接上下文长度超限消息累积过多检查 messages 的 token 估算启用滑动窗口或摘要压缩5.3 排查一条报错的前后顺序当 Agent 报错时建议按照从前到后的顺序检查。先确认环境变量和 API Key 能不能请求通再确认模型名与 endpoint 是否正确。之后重点看 messages 的历史顺序尤其是 assistant 的tool_calls是否紧跟着对应的 tool 返回消息。如果一段代码之前能运行改完 Prompt 后突然出错大概率不是 API 出了问题而是模型根据新 Prompt 生成了格式不同的 tool_calls导致解析层崩溃。此时要回到解析函数先打印tool_calls的原始结构。6. 阅读 awesome 列表后如何做框架选型6.1 选型应该关注更本质的问题Awesome 列表会给你很多候选项目但不要在项目描述的“功能很长”上做决定。作为开发者真正要关注的是框架如何管理 Agent 循环、工具协议和上下文状态。可以用下面几个问题快速判断这个框架的最小 Demo 需要多少代码才能跑通它是否屏蔽了 tool_calls 的细节如果屏蔽了框架内部出问题时能否查看完整消息日志它如何管理长期记忆是插件机制、内置向量库还是只负责把内存传给模型它是否支持流式输出、人工确认、中断恢复这些生产特性它的许可证是否允许你的业务场景使用项目最近是否还有提交和 Issue 回复6.2 用清单避免被列表带偏阅读 awesome 列表时建议输出一份自己的评估表维度检查项候选 A候选 B运行门槛能否在 30 分钟内跑通文档完整度是否有环境、示例、API 说明工具协议是否支持自定义函数声明记忆能力是否提供开箱即用的会话管理可观测性是否能打印完整调用链和 token 数生产适配是否支持鉴权、日志、回滚社区活跃度最近是否有提交与 Issue 回复填表时不能只看 README 的自述。如果候选项目依赖私有组件或需要额外服务必须把它写入“运行门槛”并亲自验证。6.3 更稳妥的成长路线对大多数开发者来说不要一上来就选择最复杂的 Agent 框架。先用官方接口写一次裸 Agent 循环理解messages和tool_calls的结构再尝试在代码中加入一个只有内部逻辑的简单工具比如两个整数相加通过后再引入框架这时候你能判断框架到底帮你省了什么又隐藏了什么。这个顺序也适合使用awesome-deepseek-agent的学习路径先看列表里的官方示例和教程然后把官方接口的最小示例跑通再看框架项目。这样才能把“别人整理好的清单”变成“自己能消化的知识结构”。7. 生产化之前需要补齐的安全、成本与可观测性7.1 工具权限必须收窄Agent 的工具调用由模型自主发起这带来一个关键风险模型可能因为恶意注入、错误推断或 Prompt 冲突调用一个不合理的工具。因此工具实现必须遵循最小权限原则。不应该让 Agent 拥有无限制执行 Shell、删除文件、转账、修改数据库的权限。即使业务确实需要这些能力也应增加人工审批步骤。工具函数内部也要做参数校验和权限校验不能直接信任模型生成的参数。例如不能写出这样的工具函数去执行任意表达式# 不推荐危险 def run_calculator(expression: str): return eval(expression)推荐做法是对表达式做解析只允许四则运算或者使用安全的 AST 解析库。Agent 的工具边界本质上是业务安全边界。模型负责决策但你能不能让它决策那么多由开发者的责任边界决定。7.2 Token、延迟与费用要有监控Agent 循环会放大模型的调用次数。一次用户请求可能触发十几次模型调用工具返回结果后还会再次调用。没有预算控制会很危险。生产项目需要记录每次请求使用多少 token。一个用户会话累计使用多少 token。一次 Agent 任务产生多少次模型调用。一次任务平均延迟是多少。Python 工具执行本身耗时多少。在日志里记录模型名称、输入 token、输出 token、耗时和 Agent 步数能帮助定位很多问题。例如用户反馈回复很慢查看日志后可能发现某次任务调用了 20 次模型而不是接口本身慢。7.3 可观测性比“能跑通”更重要调试 Agent 时最困难的一点是中间状态很多模型看到了什么、工具返回了什么、为什么最终决定不调用工具这些信息如果不记录问题几乎无法复现。一个轻量手段是在每个循环步骤里打印关键信息# 供开发调试使用的示例 print(step:, step) print(model response:, message) print(tool calls:, tool_calls) print(tool results:, result)在正式系统里应该将同样的信息写入结构化日志或链路追踪服务。对 Agent 应用来说完整记录“模型输入、工具选择、工具结果、模型输出”是一条非常重要的排错链路不能省。编写 Agent 的能力不是靠背框架 API而是靠理解循环中的每一步模型如何选择工具、工具返回后如何影响下一轮模型判断、中间状态如何被记录和回溯。能把最小循环跑通再逐步引入记忆、子 Agent 和工程化配置才是阅读 awesome 类仓库后最有效的落地方式。