过去半年我一直在围绕 DeepSeek 做 Agent 开发最后得出一个越来越强烈的结论Agent 绝对不只是 Model Tools。真正决定一个 Agent 能不能稳定跑下去的往往是被大多数人忽略掉的第三层——DeepSeek Harness也就是把模型、工具、上下文、错误恢复全部绑在一起的那个编排系统。为了把这些探索和踩坑讲透我干脆整理成了一本书书稿的核心就是从“会调工具”到“能让 Agent 真正干活”之间那一大段没人系统讲过的内容。这篇文章不聊那种“三分钟上手写 Agent”的空话而是把我写整本书时反复验证过的架构思路、关键细节、可复现的最小实现以及一堆真实报错案例都摊开来讲。适合刚把模型接进工具调用、但总在长任务和复杂工具链里翻车的人也适合已经在做 Agent 平台想回头把编排层补扎实的工程师。1. 为什么我用一本书的篇幅否定了 “Agent Model Tools”1.1 模型会“接话”工具会“干活”但它们之间没有手先说一个常见的误解。很多人看到模型能输出 JSON 形式的函数调用就以为 Agent 已经成立了模型负责决定调哪个工具工具负责执行完事。Demo 当然可以这么跑但真实项目里你会发现模型只是“接话”的大脑工具只是“长出来的手”中间缺了一整套让两者能协同工作的神经系统。举个例子。你把一个爬虫工具和一个数据库查询工具交给模型第一轮它确实会输出“调用爬虫”的指令。问题来了模型不会真的去开爬虫它只负责说。真正要执行工具、把结果塞回上下文、判断这次结果够不够、决定要不要再调一次、如果调用失败要怎么换一种说法这些全是编排层的事。市面上大多数教程直接把这一层叫“function calling”仿佛拿到工具协议就拿到了一切。但等到并发、长上下文、工具报错、多轮复盘这些问题一起涌过来时你才会发现 model 和 tools 只是零件Agent 是那个组装好的系统。系统的价值恰恰在组装方式上不在零件清单里。1.2 Harness 到底是什么从“接线板”到“指挥室”我第一次接触 DeepSeek Harness 这个概念时下意识把它理解成一个适配器把 DeepSeek 的模型输出转成某个 Agent 前端能认的格式相当于接线板。后来真的做了几个项目才意识到 harness 更接近“指挥室”。它至少要承担四件事一是把用户目标拆成步骤管理当前做到哪一步二是统一装载工具清单模型要什么就给什么注册信息三是在每轮对话前计算上下文预算决定哪些历史该留、哪些工具结果该压缩四是做故障兜底模型输出非法 JSON、工具抛异常、语义前后矛盾都要在这一层消化掉。所以我的书开篇就给了个判断同样的 DeepSeek 模型同样一套现成的爬虫、搜索、代码工具搭在没有编排的脚本里和搭在一个设计良好的 harness 里表现差距可能比换一个大模型还大。这不是模型推理能力的差距而是系统组织的差距。1.3 写书之前我实测中踩过的三类跟头我决定把 Harness 写成书而不是零碎发几篇文章是因为这个问题太系统了。光是三类基础跟头就够写好几章。第一类跟头是上下文失控。工具返回一个 3 万字的页面模型看完就把前半轮对话全部挤出窗口最后连用户最初的目标是什么都忘了。第二类跟头是模型在同一个工具上无限循环越试越错把 API 配额烧干净才停。第三类跟头是模型“幻觉式成功”工具明明没返回有效数据模型却在最终总结里言之凿凿地编了个结果出来骗用户。这三类问题没有一个是靠换模型解决的也没有一个是靠加工具解决的全部需要 harness 在架构层面做约束。写书时我把它们各自拆成一章每个问题都配了完整的现场复现和修复方案。很多读者反馈说光是看这三章的目录就知道自己为什么老做不出可用的 Agent。2. DeepSeek Harness 的整体设计我选择“薄模型 厚编排”2.1 架构分层每一层的边界在哪里写书之前我先画了一张很笨但很有用的分层图。从下往上分别是模型接入层、对话与状态管理层、工具执行层、编排决策层、交互层。每一层都只关心自己的事情层与层之间用严格的协议通信。模型接入层负责把 DeepSeek 兼容的 chat 接口封装成统一调用屏蔽不同 API 版本之间的差异。状态管理层负责维护 messages、工具结果、临时变量它不评价什么重要什么不重要只负责存。工具执行层负责真正调用外部能力并把结果整理成模型能读的文本。最上面的编排决策层才是 harness 的大脑它决定这一轮是继续让模型思考还是执行工具还是总结收尾。这个分层的好处是每个环节都能单独测试。工具挂了不会拖垮模型接入上下文爆了也能单独优化压缩策略。实际项目里最忌讳把所有逻辑塞进一个 agent 循环函数里表面上写着简单后面越想加能力越不敢动。2.2 为什么我会坚持“薄模型 厚编排”选型的时候有两条路一路是等模型厂商把推理、长上下文、规划能力越做越强让 Agent 少操点心另一路是默认模型只是个“会接话的搭档”把可靠性全部压在编排层身上。我写书时选的是后者原因是更现实。模型能力的提升我完全左右不了但我可以在 harness 里把上下文压缩、容错重试、工具校验、任务断点这些事做到位。用同一个的 DeepSeek 系列模型把编排从“裸调”改成“厚编排”之后我的工具任务成率差不多提升了三成。模型负责聪明harness 负责可靠这样的组合才是工程上敢上线的结构。这就像你不会把整个公司的流程管理都寄托在某个员工的记忆力上。员工换谁都可以优秀但流程、审批、记录、异常上报这套系统必须稳定。Agent 也一样模型是那个员工harness 是那套系统。2.3 整本书的内容编排其实是按这个架构走的书的结构我写了好几个版本最终定稿跟架构分层完全对齐。前面几章讲模型接入和工具协议中间几章集中讲编排循环和上下文工程后面几章全部是真实环境下的故障案例与排查。我的想法是让读者可以按目录直接去补自己最弱的那一环。如果你已经被“模型 工具”的简单 demo 骗过可以直接跳到我讲编排循环和状态管理的章节那里面写满了我在项目里反复掉进去的坑。每章我都在开头标注了前置知识方便只做快速原型的人先读“最小可用配置”那节。3. 核心细节与实操要点Agent 编排里最容易翻车的 5 个环节3.1 工具契约不是让人读懂是让模型严格读懂工具描述这事很多人当成 API 文档来写这是大错。普通 API 文档是给程序员读的程序员能靠经验和上下文脑补。但模型的“工作记忆”很少它只能从 JSON Schema 和 description 字段里判断这个工具能不能解决当前问题。我写书时给了一个非常具体的规范工具名一律用下划线小写语义必须是一个动词短语比如 query_user_order、create_ticket不要出现 readData 这种命名习惯。description 里必须讲清楚“这个工具会做什么、适合什么场景、不适合什么场景”参数描述里要有单位、范围、默认值甚至可以给一个示例值。这些细节相当重要。我当时测试一个订单查询工具参数 order_status 填了“已关闭”模型连续猜了“closed”“close”“CLOSED”都没猜中。后来我在描述里加了一句“可选值只能是 pending、paid、shipped、closed”一次就对了。模型不认识你的业务枚举它只认识描述里写得清清楚楚的东西。3.2 上下文预算窗口不是用来填满的上下文窗口再大也不是给你无限塞日志用的。模型处理超长上下文时有两个问题一是前面信息会被稀释二是费 token 费时间。我在 harness 里专门维护了一张“上下文预算表”每轮都算当前 messages 的总 token。计算方式不是凭感觉而是调用前用 tiktoken 之类的工具做一次 token 统计再结合模型的 max_tokens 设置做快速估算。核心公式非常简单本轮预计 token messages 里已有 token 工具最大可能返回 token 回答预留 token。如果这个数字超过了窗口的 70%我就触发压缩策略。压缩策略我会优先去掉中间轮次的不重要工具结果只保留最终结论摘要再往前只留一个“上一个动作简述”保证模型永远知道刚才发生了什么不会被长日志冲昏头。这个看起来笨拙的办法把我很多任务的上下文溢出率降到了几乎为零。3.3 思考模式与 reasoning_content一个专坑兼容层的细节DeepSeek 系列的思考模式有一个非常典型的坑当模型开了 thinking响应里除了正常的 content还会多出一段链式思考内容也就是 reasoning_content。这部分内容如果在多轮对话里没有正确回传一些 DeepSeek 兼容端点会直接报 400错误信息写得很直接thinking mode 下 reasoning_content 必须原样传回 API。这个问题非常隐蔽因为很多只用单轮请求的人根本碰不到。只有当你把上一轮的 assistant 消息存进 messages、再作为多轮上下文继续发给同一个兼容端点时才会在第二轮突然被打回来。我在书里特意把这个问题标成“兼容层十大暗坑”之一。处理方法也不复杂在把 messages 传给下一次请求前要检查 assistant 消息里是否有 reasoning_content 字段如果有就原样保留在 assistant 消息里再发给模型。千万不要自己图省事只保留 content那样前面做的思考过程链就断了还容易触发端点校验。你要是用现成 Agent 框架最好也先确认框架有没有把这段字段完整透传。3.4 错误反馈把工具异常翻译成模型听得懂的话工具调用一定会失败这个不用怀疑。但失败的呈现方式决定了模型下一步是“聪明地挽回损失”还是“原地打转”。我自己最开始的做法是把 Python 异常直接返回给模型然后模型就开始道歉然后重试一模一样的工具再失败再道歉直到跑满步数。后来我改成把异常做一层包装工具返回的统一结构里要么是 success 加结果要么是 error 加原因原因必须写成模型能看懂的一句话。比如爬虫超时不要只返回 TimeoutError而要返回“页面请求超过 20 秒目标站点可能不稳定。建议等待 2 分钟后再重试或者改用已有缓存数据。”模型看到这句提示后就会去做下一步决策而不是盲目重试。你可能觉得这是小事但这一条改动直接决定 Agent 能不能处理意外情况。3.5 护栏最大步数、成本上限、并发隔离Harness 里我最看重的一个词是护栏。没有护栏的 Agent 不是助手是炸弹。每次任务启动时我都会给循环设最大步数上限。写书时我最常用的上限是 8 步复杂任务最多允许 15 步。一旦达到步数上限但结果还是半成品就让模型输出一份“当前进展 未完成原因”的中断报告把控制权交还给用户。同时每次工具调用后我都会做重复检测如果上一轮工具调用和这一轮完全一样、输入参数也完全一样就强制终止并提示模型换方案。成本护栏更实在我在 harness 里维护一个 token 计数每轮结束后都累加超过预算阈值就自动进入“仅总结不再调用工具”的模式。并发隔离也必不可少多个任务同时跑在同一个进程里必须给每个任务独立的临时目录和独立的会话状态否则一个任务的工具输出会串到另一个任务里排查起来会非常痛苦。4. 实操记录用 Python 搭一个能跑起来的最小 Harness4.1 准备条件理论讲太多没用我直接给出一个能运行的最小骨架。场景是让模型查天气查不到就查一个本地的静态“天气表”文件也就是给它两个工具让它在真实调用和文件检索之间做选择。依赖只需要一个 OpenAI SDK因为 DeepSeek 的接口是 OpenAI 兼容格式base_url 换成你在控制台拿到的 DeepSeek 兼容地址就行key 也填你自己的。如果你用的是本地部署或其他兼容平台配置逻辑完全一样只是 base_url 和模型名不同。pip install openai4.2 最小主循环实现下面这段代码是我书里第一版的主循环去掉了业务细节只保留骨架。它的运行逻辑很简单把 messages 发给模型如果模型返回了工具调用请求就执行对应工具把结果追加进消息然后继续循环如果没有工具调用说明模型准备直接回答用户了循环结束。from openai import OpenAI client OpenAI( api_key你的KEY, base_url你的兼容端点, ) TOOLS [ { type: function, function: { name: query_weather_from_api, description: 通过天气服务查询城市的实时天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如杭州} }, required: [city] } } }, { type: function, function: { name: query_weather_from_file, description: 从本地文本表里查询城市天气仅当 API 不可用时使用, parameters: { type: object, properties: { city: {type: string, description: 城市名如杭州} }, required: [city] } } } ] def call_tool(name, args): if name query_weather_from_api: # 这里应放真实的 API 调用现在故意让它失败 return {status: error, message: 天气服务连接超时可改用文件查询} if name query_weather_from_file: table {杭州: 多云 22 度, 上海: 小雨 19 度} result table.get(args.get(city), 没找到该城市) return {status: success, message: result} return {status: error, message: f未知工具: {name}} def run(user_input): messages [{role: user, content: user_input}] for step in range(8): # 最大步数护栏 response client.chat.completions.create( modeldeepseek-v4-flash, messagesmessages, toolsTOOLS, tool_choiceauto, ) msg response.choices[0].message if not msg.tool_calls: return msg.content messages.append(msg.model_dump(exclude_noneTrue)) for call in msg.tool_calls: tool_result call_tool(call.function.name, eval(call.function.arguments)) messages.append({ role: tool, tool_call_id: call.id, content: str(tool_result), }) return 达到最大步数任务未完成。 print(run(杭州现在天气怎么样如果查不到就看看文件表里的结果))4.3 运行后发生了什么这个例子第一次运行可能就让你意外模型会先尝试调用 query_weather_from_api然后收到工具返回的失败原因。这时因为 harness 把失败原因写得很清楚模型通常会思考一下然后调用 query_weather_from_file把文件表里的结果找出来再总结成自然语言回复用户。你可以看到这一整条链里没有一行代码说“API 挂了就去查文件”是模型在看到失败信息后自己做出的选择。真正让它能做出这个选择的是 harness 把错误原样带回来并且带着足够的上下文。如果我在工具返回那里只写了一个 error模型就不知道该往哪走这个实验基本就断了。4.4 从 1 个工具扩展到 5 个之后会发生什么你把这个骨架里的 TOOLS 列表加到 5 个、10 个之后会立刻发现两个问题。第一个问题是模型开始挑错工具明明要查订单它偏去调开发票工具因为那个工具的 description 里带了“订单”二字。第二个问题是工具结果的格式不统一有的工具返回 JSON有的返回普通文本模型在比对时经常糊涂。我的解法也很简单给每个工具的结果封装成统一的“结果信封”里面必须有 status、message、data 三个字段凡是不符合信封格式的工具返回harness 在执行层就拦截并重写。宁可执行层多写十行代码也不能让模型去猜返回格式。5. DeepSeek Harness 常见报错与排查技巧实录5.1 一张来自实际现场的报错速查表写书过程中我收集了大量真实报错下面这张表是最常被新读者问到的几类。每一行都对应一个我曾经在日志里看到过的现场。报错现场直接原因处理方式model config is missing配置文件缺失或没有指定模型名检查工作目录下的 config.toml 是否存在确认有 model 字段模型名不存在或无权访问填的模型 alias 跟服务端支持列表对不上用服务端报错里列出的支持名称重填例如 deepseek-v4-pro、deepseek-v4-flashthinking 模式下 reasoning_content 必须回传多轮消息里丢掉了 assistant 的思考内容把 assistant 消息连同 reasoning_content 字段原样存下并回传请求超过模型最大上下文长度messages 和输出预留 token 超过窗口启用上下文预算表按前文 3.2 的方法压缩和丢弃中间轮次selected model is at capacity该模型服务端负载满临时切换同系列其他模型或者指数退避后重试agent execution terminated due to error某个工具抛异常编排未接管在 harness 里把异常包装成工具返回的 error 信息再送回模型agent execution provider did not respond in time模型调用超时编排层等待时间太短延长单次调用超时并增加重试机制兼容端点上模型不支持当前调用方式前端客户端用某种协议发请求兼容层不支持确认 Agent 前端的协议版本把请求方式降级到兼容层支持的格式这张表里的很多错只看单条会觉得是环境问题但放在一起推导规律就出来了绝大部分都是模型上下文管理、思考消息回传、以及工具错误处理这三件事没做好。如果你跑 Agent 框架时三天两头遇到这类报错先别急着换模型回头检查自己 harness 层有没有把这几个细节兜住。5.2 现场排查三板斧加日志、缩复现、看原文遇到疑难报错时我最常用的排查方法有三个。第一是给 harness 每轮都打结构化的运行日志。不要只记“调用成功”或“调用失败”要把本轮模型响应原文、工具名称、参数、返回摘要、当前上下文 token 数都打印出来。很多问题光看报错看不出来一眼看到调用原文就明白了。第二是把复杂任务缩成最小复现。比如多轮对话到了第 10 轮才报错那就直接把前 9 轮的 messages 导出放到一个新的简单请求里复测。这个办法用来验证是不是历史消息内容触发的校验问题特别管用reasoning_content 回传的问题我就是这样定位出来的。第三是别只看最终报错要看上游返回的响应原文。很多兼容端点的报错只是外壳真正的细节藏在响应体的 detail 字段里。书里专门有一章教读者怎么把这些报错抓出来做归类归类做多了你就知道哪些错误值得修 harness哪些错误直接换服务商更省力。5.3 前端和安装环节的坑也不能忽视讲到 DeepSeek Harness 的安装和使用还有一个高频问题经常被忽略使用 pnpm dsh web 这类前端启动命令时过程会莫名卡住。多数时候不是命令写错了而是两个原因node 版本不匹配或前端依赖没装完整。之前整理这本书配套示例时我就遇到过 pnpm 在 web 模式下一动不动的现象。最后查出是本地 node 版本太老新依赖需要更高的运行时。解决办法是先用 node -v 确认版本再跑 pnpm install 并确认没有失败项最后再启动 pnpm dsh web。很多人一卡住就去翻服务的配置其实前端依赖环节往往才是真正的凶手。书里我把这类环境问题也单独列了一节因为再好的架构设计部署第一步就卡住后面什么也跑不起来。6. 写这本书时沉淀下的几个工作习惯6.1 先用“最小闭环”说服自己再谈通用框架我写整本书的过程中最受益的一个习惯是每次研究一个新机制前先花不超过二十分钟写一个最小闭环。比如要研究上下文压缩就先拿一个 10 轮以内的对话压压看要研究错误重试就先模拟一个必然失败的工具模型连续两次失败后的行为是什么。这样做能让我快速建立起对系统的实感而不是停留在抽象设计里。Agent 开发特别容易陷入画大图的陷阱架构图画得很漂亮一跑起来全是边界问题。最小闭环能让你在最简单的代码里看到机制的真实面貌之后再往里面加层次就有的放矢了。6.2 把“模型的错误”当成 harness 的设计输入很多人在调试 Agent 时一旦发现模型表现不对第一反应是换提示词或者换更大参数的模型。但我在项目里换了一种思路把模型的每一次错误类型当成 harness 的设计输入。比如我发现模型开始在长对话尾端忘记用户原始目标那不是我提示词写得不到位而是我的上下文压缩策略丢掉了关键信息需要调整。比如模型在工具执行失败后疯狂循环那不是我运气不好而是没有给它足够的错误原因和可选路径。这样想之后很多问题就从“不可控的模型玄学”变成了“可修复的工程问题”整本书的方法论也就自然成型了。6.3 最后留一个我在长期开发中最想强调的细节如果你只从这篇文章里带走一个细节我希望是永远给 Agent 留一条“承认失败”的路径。很多 Agent 项目把模型逼得太紧每轮都要求它一定完成任务结果模型只能靠编造来交差。“承认失败”的路径是指在步数耗尽或信息不足时允许模型输出“我暂未完成原因是 X建议下一步做 Y”而不是逼它硬产出。我在深度使用各种 Agent 框架后发现凡是能稳定处理长任务的系统几乎都在编排层内置了这条降级路径。它看起来不像智能但恰恰是这套看似保守的设计让 Agent 从“演示很聪明”变成“生产可用”。这也是我花了一整本书篇幅最想让大家建立起来的一个习惯。