进入 2025 年围绕 DeepSeek 的讨论早已不局限于“模型跑分有多高”而是逐渐转移到“怎么用它做真实业务”。最近开源社区被 repeated 刷屏的 DeepSeek Harness 就是一个典型信号它把大模型应用开发里最容易失控的那一层——工具调用、上下文维护、权限控制、多轮执行——集中封装成一套工程框架。很多开发者把它当成 Agent 开发的“标准底座”。这篇文章会从概念拆解到代码实现带你从零搭出一个最简可用的 DeepSeek Agent Harness适合已经上手过 Python、同时对 Agent 开发感兴趣的同学快速跟进。1. DeepSeek Harness 是什么Agent 开发的“驾驶舱”1.1 先理解 Harness 这个词Harness 直译是“马具”引申含义是“控制装置”或“约束系统”。放到 Agent 开发场景里Harness 可以理解为一条套在模型外面的“缰绳”模型负责“思考”和“生成”但它不能直接操作你的文件夹、数据库、微信机器人、代码仓库。Harness 负责把模型输出的意图翻译成真正的命令再把命令执行结果反馈给模型。模型继续基于结果做下一轮推理直到完成用户最初的目标。也就是说Harness 承担的是 Agent 系统中“工程层”的职责调用哪个模型、允许调用哪些工具、历史消息怎么保存、一次任务最多执行多少轮、出现错误要不要重试这些都在 Harness 里定义。没有 Harness模型只是 Chatbot有了 Harness模型才变成能动手干活的 Agent。DeepSeek Harness 之所以引发关注是因为它把这条“缰绳”做得足够轻量、足够开放。你不需要从零构建复杂的 Agent 框架只需要按照它的接口约定把 DeepSeek 模型、工具函数、上下文策略接进来就能快速得到一个具备自主执行能力的 Agent 原型。1.2 Harness 与 Agent Framework 的区别很多初学者会混淆 Harness 和 Agent FrameworkAgent 框架这里先做一个简单区分概念侧重典型职责Agent Framework上层智能体应用任务规划、Prompt 编排、多 Agent 协作、知识库接入Harness底层执行控制模型调用、工具调度、上下文管理、错误恢复、安全边界在实际项目中Harness 更像是地基Framework 更像是房间布局。你可以直接用 Harness 搭一个简单的 Agent也可以在 Harness 之上封装一套复杂的业务 Agent。DeepSeek Harness 的价值在于它把“地基”标准化了。你在本地开发的环境和代码逻辑以后也能平滑迁移到服务端不会因为换了一个调用方式就让整套 Agent 失控。1.3 为什么它会对 Agent 开发产生影响过去开发一个 Agent 最痛苦的环节不是“调模型 API”而是处理模型多次调用工具之间的状态。比如模型第一次决定调用天气查询工具。工具返回天气数据。模型需要根据这份天气数据继续规划“是否带伞”。如果用户追问“那明天呢”Agent 还要记得前面聊过的城市。这一连串交互看似简单实际落地时涉及消息记录、临时状态、工具调用的结果拼接、请求超时、上下文窗口逼近上限等问题。DeepSeek Harness 把这些问题统一收敛开发者只需要聚焦“业务工具是什么、判断逻辑怎么写”其余交给 Harness 层处理。2. 准备开发环境与项目结构2.1 环境准备本文的示例代码以 Python 为主你需要准备以下环境Python 3.10 或更高版本。Git用于获取 GitHub 上的开源项目代码。OpenAI SDKDeepSeek API 兼容 OpenAI 接口格式可以直接复用。一个 DeepSeek API Key用于调用官方模型接口。如果你的网络环境对 GitHub 的访问不稳定建议先通过系统自带网络检查工具确认连通性例如ping github.com如果出现长时间超时可以尝试切换网络环境或者过一段时间再拉取代码。不建议在未确认网络连通性的情况下反复重试 Git 命令这反而会降低效率。安装 Python 依赖的命令如下pip install openai python-dotenv2.2 获取 DeepSeek Harness 项目代码在 GitHub 上搜索 DeepSeek Harness 相关仓库时建议先查看项目的 README 和 Recent Commits了解该项目是否活跃。克隆项目到本地git clone https://github.com/your-name/deepseek-harness.git cd deepseek-harness这里的用户名是示例你需要以实际仓库地址为准。开源项目迭代很快Clone 下来后先建立虚拟环境再安装依赖避免污染全局环境python -m venv venv source venv/bin/activate # Windows 下为 venv\Scripts\activate pip install -r requirements.txt2.3 项目结构设计一个可维护的 Agent Harness 项目通常包含下面几个文件deepseek-harness/ ├── .env.example # 环境变量示例 ├── requirements.txt # 依赖清单 ├── config.py # 配置读取 ├── models.py # 消息数据结构 ├── tools.py # 工具函数与工具 Schema ├── agent.py # 核心 Agent 循环 ├── main.py # 命令行入口 └── README.md # 项目说明后面实战部分会逐个文件产出完整代码。先理解每个文件的分工有助于组合成完整闭环。3. DeepSeek API 调用基础3.1 为什么 DeepSeek API 兼容 OpenAI 格式DeepSeek 官方提供了兼容 OpenAI SDK 的接口这意味着你可以直接用openai库指定base_url来调用 DeepSeek 模型。它的好处很直接社区里大量基于 OpenAI SDK 的工具、插件、教程只要改一下base_url和模型名就能迁移到 DeepSeek。这里需要注意DeepSeek 官方的 API 文档可能随着版本更新而调整因此实际调用时要以官方文档为准。下面给出一个通用示例。3.2 使用环境变量保存密钥不要把 API Key 硬编码在代码里。我们使用.env文件保存密钥然后通过dotenv加载。先在项目根目录创建.env.example文件DEEPSEEK_API_KEYsk-xxxxxxx DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat复制为.env并填入真实的密钥cp .env.example .env3.3 最简单的模型调用示例先写一个最小请求验证密钥和网络是否正常# 文件路径hello_deepseek.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) response client.chat.completions.create( modelos.getenv(DEEPSEEK_MODEL, deepseek-chat), messages[ {role: system, content: 你是一个有用的助手。}, {role: user, content: 请用一句话介绍 Harness Engineering。}, ], ) print(response.choices[0].message.content)如果脚本能正常输出内容说明 API 调用链路是通的。这里要说明deepseek-chat是常见的对话模型标识具体模型名请以官方文档为准。如果你的账号支持不同模型可以调整DEEPSEEK_MODEL环境变量。3.4 理解模型返回结构response.choices[0].message是模型回复的核心对象它通常包含content纯文本回复内容。tool_calls当模型决定调用工具时返回的结构化调用指令。后面构建 Agent 时最核心的判断就是本次模型返回的到底是普通文本还是工具调用指令。如果是工具调用指令就需要去执行对应函数并把结果继续回传给模型。4. 从零实现一个 DeepSeek Agent Harness4.1 设计思路我们不需要一开始就做得非常复杂重点是把 Agent 的“闭环”跑通用户输入 → 模型判断 → 工具执行 → 结果回传 → 再次请求模型 → 最终输出为了实现这个闭环需要四个核心模块消息管理保存 system、user、assistant、tool 四种消息。工具注册把 Python 函数变成模型能理解的 JSON Schema。Agent 循环不断请求模型直到没有 tool_calls。错误处理工具调用失败时把错误信息反馈给模型而不是直接崩溃。下面逐步实现。4.2 定义数据结构为了清晰管理消息先定义简单数据模型文件models.py# 文件路径models.py from typing import List, Dict, Any, Optional from dataclasses import dataclass, field dataclass class ToolResult: 工具执行结果 name: str content: str is_error: bool False dataclass class AgentMessage: 一条 Agent 消息 role: str content: Optional[str] None tool_calls: Optional[List[Dict[str, Any]]] None tool_call_id: Optional[str] None虽然这部分看起来只是数据容器但它在整个循环中承担了关键作用tool_call_id必须与后面工具返回消息中的tool_call_id对应否则模型会不知道某段工具结果对应哪一次调用。4.3 实现工具注册模块工具注册的难点在于让模型知道“有哪些工具可用”以及“工具的参数是什么样的”。DeepSeek 与 OpenAI 一样支持在请求中传递tools参数每项包含type、function、name、description、parameters。我们定义一个装饰器把普通函数转换成工具定义和执行器。# 文件路径tools.py import json import time import inspect from typing import Callable, Dict, Any from dataclasses import dataclass, field dataclass class Tool: 工具定义 name: str description: str parameters: Dict[str, Any] func: Callable def to_schema(self) - Dict[str, Any]: 转换成模型可识别的工具 Schema return { type: function, function: { name: self.name, description: self.description, parameters: self.parameters, }, } def execute(self, **kwargs) - str: 执行工具并返回字符串结果 try: result self.func(**kwargs) return json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) class ToolRegistry: 工具注册中心 def __init__(self): self._tools: Dict[str, Tool] {} def register(self, name: str, description: str, parameters: Dict[str, Any]): 注册工具 def decorator(func): tool Tool( namename, descriptiondescription, parametersparameters, funcfunc, ) self._tools[name] tool return func return decorator def get_schemas(self): return [tool.to_schema() for tool in self._tools.values()] def execute(self, name: str, arguments: str) - str: if name not in self._tools: return json.dumps({error: funknown tool: {name}}, ensure_asciiFalse) try: args json.loads(arguments) if arguments else {} except json.JSONDecodeError: return json.dumps({error: invalid arguments}, ensure_asciiFalse) return self._tools[name].execute(**args)这里有两个关键点需要解释第一parameters使用 JSON Schema 结构模型会依据它生成合法的调用参数。例如{type: object, properties: {city: {type: string}}, required: [city]}模型就会在需要时生成{city: 北京}。第二execute方法内部捕获了异常并返回 JSON 字符串。这样即使工具内部报错Agent 循环也能继续把错误传给模型作为上下文让模型决定如何修正。4.4 实现核心 Agent 循环核心 Agent 循环写在agent.py中# 文件路径agent.py import os from typing import List, Dict, Any from openai import OpenAI from dotenv import load_dotenv from models import AgentMessage from tools import ToolRegistry load_dotenv() class DeepSeekAgent: def __init__(self, tool_registry: ToolRegistry, max_iterations: int 5): self.tool_registry tool_registry self.max_iterations max_iterations self.client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) self.model os.getenv(DEEPSEEK_MODEL, deepseek-chat) def run(self, user_input: str) - str: messages [ { role: system, content: 你是一个会调用工具的智能助手。当用户的问题需要工具时请调用工具并根据工具结果回答。, }, {role: user, content: user_input}, ] for _ in range(self.max_iterations): response self.client.chat.completions.create( modelself.model, messagesmessages, toolsself.tool_registry.get_schemas(), ) message response.choices[0].message # 没有工具调用说明已经生成最终回答 if not message.tool_calls: return message.content or # 1. 先把 assistant 消息追加到历史 messages.append( { role: assistant, content: message.content, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], } ) # 2. 逐个执行工具调用 for tool_call in message.tool_calls: tool_name tool_call.function.name tool_arguments tool_call.function.arguments result_str self.tool_registry.execute(tool_name, tool_arguments) messages.append( { role: tool, tool_call_id: tool_call.id, content: result_str, } ) return 已达到最大迭代次数无法完成请求。这个循环是整个 Harness 的核心我拆开解释每一步第一步把模型的 response 追加到messages。这一步不能省略因为后续请求必须把前一次tool_calls的历史带上模型才能理解“谁调用了工具”。第二步对每个tool_call执行注册表中的工具函数并把结果以role: tool消息追加到历史。tool_call_id是关联工具调用和工具结果的关键字段。第三步进入下一次循环把包含工具结果的消息整体发给模型。模型如果认为还需要继续调用工具就会再次返回tool_calls如果已经获得足够信息就会返回最终文本。max_iterations是安全阀。某些异常场景下模型可能会在多个工具之间反复调用限制迭代次数可以避免无限循环。4.5 定义实际工具这里我们定义一个能查询时间的工具和一个能计算的工具# 文件路径main.py import datetime from tools import ToolRegistry from agent import DeepSeekAgent def get_current_time() - dict: 获取当前本地时间 now datetime.datetime.now() return { year: now.year, month: now.month, day: now.day, hour: now.hour, minute: now.minute, weekday: now.strftime(%A), } def calculate(expression: str) - dict: 计算简单的数学表达式注意这里使用 eval 仅用于演示生产环境禁止使用 try: result eval(expression) return {result: result} except Exception as e: return {error: str(e)} def main(): registry ToolRegistry() # 注册时间工具 registry.register( nameget_current_time, description获取当前本地时间不需要参数, parameters{ type: object, properties: {}, }, )(get_current_time) # 注册计算工具 registry.register( namecalculate, description计算数学表达式例如 (3 5) * 2, parameters{ type: object, properties: { expression: { type: string, description: 要计算的数学表达式, } }, required: [expression], }, )(calculate) agent DeepSeekAgent(tool_registryregistry) while True: user_input input(请输入问题输入 exit 退出) if user_input.strip().lower() in (exit, quit): break answer agent.run(user_input) print(\nAgent:, answer, \n) if __name__ __main__: main()这里需要特别强调示例中的calculate使用了eval它只适合在完全可信的本地环境学习和演示。生产环境中绝对不能直接把用户输入交给eval否则会有严重的代码注入风险。最佳做法是用专门的数学解析库或者只允许白名单运算符和整数。4.6 运行 Agent在项目根目录执行python main.py输入一个问题今天是什么时间预期流程是Agent 接收到问题。模型判断需要调用get_current_time工具。Harness 执行时间工具。模型得到时间结果后生成回答。你也可以测试带参数的工具请帮我算一下 (12 34) * 6 的结果模型会调用calculate工具返回结果后再组织语言。如果你的 API 调用过程中出现了“agent terminated due to error”或“agent execution terminated due to error”这类错误通常表示工具执行过程中出现了预期之外的异常或者模型生成的参数无法被解析。此时优先检查工具函数本身是否抛异常、参数命名是否正确、tool_call_id是否正确回传。5. 运行验证与事件日志分析5.1 记录调试日志为了方便观察 Agent 内部的执行轨迹可以在DeepSeekAgent中增加一个简单的日志开关。比如在每次调用模型前打印当前消息数量在每次执行工具后打印工具名和结果。def run(self, user_input: str, verbose: bool False) - str: messages [...] for iteration in range(self.max_iterations): if verbose: print(f[Iteration {iteration 1}] 请求模型当前消息数: {len(messages)}) response ... if not message.tool_calls: return message.content or if verbose: for tc in message.tool_calls: print(f[Tool Call] {tc.function.name}({tc.function.arguments}))打印日志能帮助你快速定位问题如果发现模型在某一步重复调用同一个工具说明上下文可能缺少“已经调用过该工具”的提示需要调整 system prompt如果发现工具参数解析失败说明该工具的 JSON Schema 定义不够清晰。5.2 观察预期输出一个正常的运行日志大概是这样的[Iteration 1] 请求模型当前消息数: 2 [Tool Call] get_current_time({}) [Iteration 2] 请求模型当前消息数: 4 Agent: 当前本地时间是 2025年1月15日 14:30:00星期三。可以看到Agent 经过了两轮请求第一轮决定调用工具第二轮基于工具结果生成最终答案。这就是 Agent 开发中最典型的“思考-行动-观察”循环。6. 常见问题与排查思路6.1 GitHub 下载与网络访问类最近很多同学反馈 GitHub 访问困难或者 Git Clone 速度很慢。这里做一个不涉及任何不安全工具的通用排查问题现象常见原因解决思路ping github.com 超时本机网络配置或运营商问题检查网络连接换一个网络环境测试git clone 速度慢跨地域传输、仓库体积大使用--depth1浅克隆分时段下载网页打开失败CDN 访问不稳定稍后重试或使用官方 GitHub Desktop仓库下载中断网络波动重新 clone或从发布页下载源码包不要使用来路不明的“镜像脚本”或下载器尤其不要在未核实内容的情况下执行有 root 权限的脚本。安全永远优先于便利。6.2 Agent 执行异常类问题现象常见原因解决思路agent terminated due to error工具函数内部抛出未捕获异常在工具执行外层增加 try-except返回错误信息给模型模型不调用工具直接编答案工具描述不清晰在工具 description 中写明适用场景和参数含义模型反复调用同一个工具上下文缺少结果检查 assistant 消息和 tool 消息是否完整回传返回内容超过上下文限制多轮工具调用导致历史过长引入消息截断、摘要、滑动窗口策略API 返回 401API Key 错误检查 .env 文件和环境变量是否加载API 返回 429请求频率超过限制增加请求间隔使用退避重试6.3 本地模型还是远程 API如果你的目标是学习 Harness 原理直接用 DeepSeek API 就够了。如果你想离线部署并更好地控制数据可以考虑在本地部署量化模型。本地部署的优势是隐私和成本可控但需要额外的推理服务框架并且配置复杂度更高。从工程收敛角度来看建议先通过 API 跑通 Agent 闭环再根据需求决定是否替换成本地推理端点。只要保持 OpenAI 兼容接口不变Harness 里的核心代码基本不用改。7. 工程化最佳实践7.1 密钥与配置管理无论做个人项目还是企业项目API Key 都不能出现在代码里也不能提交到 Git 仓库。建议在.gitignore中忽略.env文件。使用环境变量或配置中心管理密钥。如果使用 CI/CD使用平台的 Secret 功能注入密钥。7.2 工具函数的健壮性工具是 Agent 能完成实际任务的唯一抓手因此它的返回值必须结构化、可预测。建议每个工具都返回 JSON 字符串并包含错误字段。这样模型看到{error: ...}后会尝试调整参数或告知用户而不是直接崩溃。工具的参数 Schema 要尽可能细化description写清楚参数含义和格式。required明确哪些参数必须提供。enum对可选值范围内的参数进行约束。7.3 上下文管理策略多轮工具调用会让messages快速增长。当上下文窗口接近上限时有几种常见处理方式截断最旧的对话消息保留 system 和最近几条。对历史工具结果做摘要而不是原样保留。将长期记忆外置到数据库或向量库仅把相关检索结果注入上下文。在 Harness 中建议把上下文管理策略独立成一个模块而不是散落在 Agent 循环里。这样后续可以轻松切换不同的策略。7.4 异常与重试模型的工具调用不总是一次成功常见失败有模型生成了错误的 JSON 参数。工具内部依赖的第三方 API 超时。上下文太长导致请求被拒绝。建议为模型调用增加指数退避重试同时在重试次数用尽后把错误信息返回给模型让模型向用户说明“当前无法完成任务”而不是让进程直接崩溃。7.5 安全边界不要让 Agent 拥有“无限权限”。在生产环境建议为每个工具定义最小权限。涉及文件删除、数据库写操作、资金相关操作时加入人工审批步骤。对工具可以访问的网络地址、文件目录做白名单限制。Harness 的价值不仅是让 Agent 能力更强更是为 Agent 划出安全边界。一个没有边界的 Agent 是危险的这一点在工程化落地时要格外重视。8. 总结与下一步学习方向这篇文章从概念出发解释了 DeepSeek Harness 在 Agent 开发中的定位然后带大家完成了一个最小闭环模型调用、工具注册、工具执行、结果回传、多轮迭代。代码虽然简化但已经包含了 Agent 开发最核心的骨架。接下来你可以从以下几个方向继续深入给 Agent 接入更多真实工具比如文件读写、数据库查询、HTTP 请求。实现基于向量数据库的长期记忆让 Agent 记住用户的偏好和历史对话。引入多 Agent 协作一个 Agent 负责规划另一个 Agent 负责执行。为 Agent 增加完整评测集量化测试工具调用准确率和任务完成率。尝试把 Harness 封装成 Web 服务通过 API 对外提供 Agent 能力。如果你正在尝试把手里的 DeepSeek API 封装成可控的 Agent 工程建议先不要急着引入重量级框架而是像本文一样从最小闭环开始。把“模型对话”和“工具调用”这条链路真正跑通之后再逐步加记忆、加策略、加权限你会发现 Agent 开发其实没有想象中那么神秘。最重要的是动手把代码跑起来。
进入 2025 年围绕 DeepSeek 的讨论早已不局限于“模型跑分有多高”而是逐渐转移到“怎么用它做真实业务”。最近开源社区被 repeated 刷屏的 DeepSeek Harness 就是一个典型信号它把大模型应用开发里最容易失控的那一层——工具调用、上下文维护、权限控制、多轮执行——集中封装成一套工程框架。很多开发者把它当成 Agent 开发的“标准底座”。这篇文章会从概念拆解到代码实现带你从零搭出一个最简可用的 DeepSeek Agent Harness适合已经上手过 Python、同时对 Agent 开发感兴趣的同学快速跟进。1. DeepSeek Harness 是什么Agent 开发的“驾驶舱”1.1 先理解 Harness 这个词Harness 直译是“马具”引申含义是“控制装置”或“约束系统”。放到 Agent 开发场景里Harness 可以理解为一条套在模型外面的“缰绳”模型负责“思考”和“生成”但它不能直接操作你的文件夹、数据库、微信机器人、代码仓库。Harness 负责把模型输出的意图翻译成真正的命令再把命令执行结果反馈给模型。模型继续基于结果做下一轮推理直到完成用户最初的目标。也就是说Harness 承担的是 Agent 系统中“工程层”的职责调用哪个模型、允许调用哪些工具、历史消息怎么保存、一次任务最多执行多少轮、出现错误要不要重试这些都在 Harness 里定义。没有 Harness模型只是 Chatbot有了 Harness模型才变成能动手干活的 Agent。DeepSeek Harness 之所以引发关注是因为它把这条“缰绳”做得足够轻量、足够开放。你不需要从零构建复杂的 Agent 框架只需要按照它的接口约定把 DeepSeek 模型、工具函数、上下文策略接进来就能快速得到一个具备自主执行能力的 Agent 原型。1.2 Harness 与 Agent Framework 的区别很多初学者会混淆 Harness 和 Agent FrameworkAgent 框架这里先做一个简单区分概念侧重典型职责Agent Framework上层智能体应用任务规划、Prompt 编排、多 Agent 协作、知识库接入Harness底层执行控制模型调用、工具调度、上下文管理、错误恢复、安全边界在实际项目中Harness 更像是地基Framework 更像是房间布局。你可以直接用 Harness 搭一个简单的 Agent也可以在 Harness 之上封装一套复杂的业务 Agent。DeepSeek Harness 的价值在于它把“地基”标准化了。你在本地开发的环境和代码逻辑以后也能平滑迁移到服务端不会因为换了一个调用方式就让整套 Agent 失控。1.3 为什么它会对 Agent 开发产生影响过去开发一个 Agent 最痛苦的环节不是“调模型 API”而是处理模型多次调用工具之间的状态。比如模型第一次决定调用天气查询工具。工具返回天气数据。模型需要根据这份天气数据继续规划“是否带伞”。如果用户追问“那明天呢”Agent 还要记得前面聊过的城市。这一连串交互看似简单实际落地时涉及消息记录、临时状态、工具调用的结果拼接、请求超时、上下文窗口逼近上限等问题。DeepSeek Harness 把这些问题统一收敛开发者只需要聚焦“业务工具是什么、判断逻辑怎么写”其余交给 Harness 层处理。2. 准备开发环境与项目结构2.1 环境准备本文的示例代码以 Python 为主你需要准备以下环境Python 3.10 或更高版本。Git用于获取 GitHub 上的开源项目代码。OpenAI SDKDeepSeek API 兼容 OpenAI 接口格式可以直接复用。一个 DeepSeek API Key用于调用官方模型接口。如果你的网络环境对 GitHub 的访问不稳定建议先通过系统自带网络检查工具确认连通性例如ping github.com如果出现长时间超时可以尝试切换网络环境或者过一段时间再拉取代码。不建议在未确认网络连通性的情况下反复重试 Git 命令这反而会降低效率。安装 Python 依赖的命令如下pip install openai python-dotenv2.2 获取 DeepSeek Harness 项目代码在 GitHub 上搜索 DeepSeek Harness 相关仓库时建议先查看项目的 README 和 Recent Commits了解该项目是否活跃。克隆项目到本地git clone https://github.com/your-name/deepseek-harness.git cd deepseek-harness这里的用户名是示例你需要以实际仓库地址为准。开源项目迭代很快Clone 下来后先建立虚拟环境再安装依赖避免污染全局环境python -m venv venv source venv/bin/activate # Windows 下为 venv\Scripts\activate pip install -r requirements.txt2.3 项目结构设计一个可维护的 Agent Harness 项目通常包含下面几个文件deepseek-harness/ ├── .env.example # 环境变量示例 ├── requirements.txt # 依赖清单 ├── config.py # 配置读取 ├── models.py # 消息数据结构 ├── tools.py # 工具函数与工具 Schema ├── agent.py # 核心 Agent 循环 ├── main.py # 命令行入口 └── README.md # 项目说明后面实战部分会逐个文件产出完整代码。先理解每个文件的分工有助于组合成完整闭环。3. DeepSeek API 调用基础3.1 为什么 DeepSeek API 兼容 OpenAI 格式DeepSeek 官方提供了兼容 OpenAI SDK 的接口这意味着你可以直接用openai库指定base_url来调用 DeepSeek 模型。它的好处很直接社区里大量基于 OpenAI SDK 的工具、插件、教程只要改一下base_url和模型名就能迁移到 DeepSeek。这里需要注意DeepSeek 官方的 API 文档可能随着版本更新而调整因此实际调用时要以官方文档为准。下面给出一个通用示例。3.2 使用环境变量保存密钥不要把 API Key 硬编码在代码里。我们使用.env文件保存密钥然后通过dotenv加载。先在项目根目录创建.env.example文件DEEPSEEK_API_KEYsk-xxxxxxx DEEPSEEK_BASE_URLhttps://api.deepseek.com DEEPSEEK_MODELdeepseek-chat复制为.env并填入真实的密钥cp .env.example .env3.3 最简单的模型调用示例先写一个最小请求验证密钥和网络是否正常# 文件路径hello_deepseek.py import os from openai import OpenAI from dotenv import load_dotenv load_dotenv() client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) response client.chat.completions.create( modelos.getenv(DEEPSEEK_MODEL, deepseek-chat), messages[ {role: system, content: 你是一个有用的助手。}, {role: user, content: 请用一句话介绍 Harness Engineering。}, ], ) print(response.choices[0].message.content)如果脚本能正常输出内容说明 API 调用链路是通的。这里要说明deepseek-chat是常见的对话模型标识具体模型名请以官方文档为准。如果你的账号支持不同模型可以调整DEEPSEEK_MODEL环境变量。3.4 理解模型返回结构response.choices[0].message是模型回复的核心对象它通常包含content纯文本回复内容。tool_calls当模型决定调用工具时返回的结构化调用指令。后面构建 Agent 时最核心的判断就是本次模型返回的到底是普通文本还是工具调用指令。如果是工具调用指令就需要去执行对应函数并把结果继续回传给模型。4. 从零实现一个 DeepSeek Agent Harness4.1 设计思路我们不需要一开始就做得非常复杂重点是把 Agent 的“闭环”跑通用户输入 → 模型判断 → 工具执行 → 结果回传 → 再次请求模型 → 最终输出为了实现这个闭环需要四个核心模块消息管理保存 system、user、assistant、tool 四种消息。工具注册把 Python 函数变成模型能理解的 JSON Schema。Agent 循环不断请求模型直到没有 tool_calls。错误处理工具调用失败时把错误信息反馈给模型而不是直接崩溃。下面逐步实现。4.2 定义数据结构为了清晰管理消息先定义简单数据模型文件models.py# 文件路径models.py from typing import List, Dict, Any, Optional from dataclasses import dataclass, field dataclass class ToolResult: 工具执行结果 name: str content: str is_error: bool False dataclass class AgentMessage: 一条 Agent 消息 role: str content: Optional[str] None tool_calls: Optional[List[Dict[str, Any]]] None tool_call_id: Optional[str] None虽然这部分看起来只是数据容器但它在整个循环中承担了关键作用tool_call_id必须与后面工具返回消息中的tool_call_id对应否则模型会不知道某段工具结果对应哪一次调用。4.3 实现工具注册模块工具注册的难点在于让模型知道“有哪些工具可用”以及“工具的参数是什么样的”。DeepSeek 与 OpenAI 一样支持在请求中传递tools参数每项包含type、function、name、description、parameters。我们定义一个装饰器把普通函数转换成工具定义和执行器。# 文件路径tools.py import json import time import inspect from typing import Callable, Dict, Any from dataclasses import dataclass, field dataclass class Tool: 工具定义 name: str description: str parameters: Dict[str, Any] func: Callable def to_schema(self) - Dict[str, Any]: 转换成模型可识别的工具 Schema return { type: function, function: { name: self.name, description: self.description, parameters: self.parameters, }, } def execute(self, **kwargs) - str: 执行工具并返回字符串结果 try: result self.func(**kwargs) return json.dumps(result, ensure_asciiFalse) except Exception as e: return json.dumps({error: str(e)}, ensure_asciiFalse) class ToolRegistry: 工具注册中心 def __init__(self): self._tools: Dict[str, Tool] {} def register(self, name: str, description: str, parameters: Dict[str, Any]): 注册工具 def decorator(func): tool Tool( namename, descriptiondescription, parametersparameters, funcfunc, ) self._tools[name] tool return func return decorator def get_schemas(self): return [tool.to_schema() for tool in self._tools.values()] def execute(self, name: str, arguments: str) - str: if name not in self._tools: return json.dumps({error: funknown tool: {name}}, ensure_asciiFalse) try: args json.loads(arguments) if arguments else {} except json.JSONDecodeError: return json.dumps({error: invalid arguments}, ensure_asciiFalse) return self._tools[name].execute(**args)这里有两个关键点需要解释第一parameters使用 JSON Schema 结构模型会依据它生成合法的调用参数。例如{type: object, properties: {city: {type: string}}, required: [city]}模型就会在需要时生成{city: 北京}。第二execute方法内部捕获了异常并返回 JSON 字符串。这样即使工具内部报错Agent 循环也能继续把错误传给模型作为上下文让模型决定如何修正。4.4 实现核心 Agent 循环核心 Agent 循环写在agent.py中# 文件路径agent.py import os from typing import List, Dict, Any from openai import OpenAI from dotenv import load_dotenv from models import AgentMessage from tools import ToolRegistry load_dotenv() class DeepSeekAgent: def __init__(self, tool_registry: ToolRegistry, max_iterations: int 5): self.tool_registry tool_registry self.max_iterations max_iterations self.client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlos.getenv(DEEPSEEK_BASE_URL, https://api.deepseek.com), ) self.model os.getenv(DEEPSEEK_MODEL, deepseek-chat) def run(self, user_input: str) - str: messages [ { role: system, content: 你是一个会调用工具的智能助手。当用户的问题需要工具时请调用工具并根据工具结果回答。, }, {role: user, content: user_input}, ] for _ in range(self.max_iterations): response self.client.chat.completions.create( modelself.model, messagesmessages, toolsself.tool_registry.get_schemas(), ) message response.choices[0].message # 没有工具调用说明已经生成最终回答 if not message.tool_calls: return message.content or # 1. 先把 assistant 消息追加到历史 messages.append( { role: assistant, content: message.content, tool_calls: [ { id: tc.id, type: function, function: { name: tc.function.name, arguments: tc.function.arguments, }, } for tc in message.tool_calls ], } ) # 2. 逐个执行工具调用 for tool_call in message.tool_calls: tool_name tool_call.function.name tool_arguments tool_call.function.arguments result_str self.tool_registry.execute(tool_name, tool_arguments) messages.append( { role: tool, tool_call_id: tool_call.id, content: result_str, } ) return 已达到最大迭代次数无法完成请求。这个循环是整个 Harness 的核心我拆开解释每一步第一步把模型的 response 追加到messages。这一步不能省略因为后续请求必须把前一次tool_calls的历史带上模型才能理解“谁调用了工具”。第二步对每个tool_call执行注册表中的工具函数并把结果以role: tool消息追加到历史。tool_call_id是关联工具调用和工具结果的关键字段。第三步进入下一次循环把包含工具结果的消息整体发给模型。模型如果认为还需要继续调用工具就会再次返回tool_calls如果已经获得足够信息就会返回最终文本。max_iterations是安全阀。某些异常场景下模型可能会在多个工具之间反复调用限制迭代次数可以避免无限循环。4.5 定义实际工具这里我们定义一个能查询时间的工具和一个能计算的工具# 文件路径main.py import datetime from tools import ToolRegistry from agent import DeepSeekAgent def get_current_time() - dict: 获取当前本地时间 now datetime.datetime.now() return { year: now.year, month: now.month, day: now.day, hour: now.hour, minute: now.minute, weekday: now.strftime(%A), } def calculate(expression: str) - dict: 计算简单的数学表达式注意这里使用 eval 仅用于演示生产环境禁止使用 try: result eval(expression) return {result: result} except Exception as e: return {error: str(e)} def main(): registry ToolRegistry() # 注册时间工具 registry.register( nameget_current_time, description获取当前本地时间不需要参数, parameters{ type: object, properties: {}, }, )(get_current_time) # 注册计算工具 registry.register( namecalculate, description计算数学表达式例如 (3 5) * 2, parameters{ type: object, properties: { expression: { type: string, description: 要计算的数学表达式, } }, required: [expression], }, )(calculate) agent DeepSeekAgent(tool_registryregistry) while True: user_input input(请输入问题输入 exit 退出) if user_input.strip().lower() in (exit, quit): break answer agent.run(user_input) print(\nAgent:, answer, \n) if __name__ __main__: main()这里需要特别强调示例中的calculate使用了eval它只适合在完全可信的本地环境学习和演示。生产环境中绝对不能直接把用户输入交给eval否则会有严重的代码注入风险。最佳做法是用专门的数学解析库或者只允许白名单运算符和整数。4.6 运行 Agent在项目根目录执行python main.py输入一个问题今天是什么时间预期流程是Agent 接收到问题。模型判断需要调用get_current_time工具。Harness 执行时间工具。模型得到时间结果后生成回答。你也可以测试带参数的工具请帮我算一下 (12 34) * 6 的结果模型会调用calculate工具返回结果后再组织语言。如果你的 API 调用过程中出现了“agent terminated due to error”或“agent execution terminated due to error”这类错误通常表示工具执行过程中出现了预期之外的异常或者模型生成的参数无法被解析。此时优先检查工具函数本身是否抛异常、参数命名是否正确、tool_call_id是否正确回传。5. 运行验证与事件日志分析5.1 记录调试日志为了方便观察 Agent 内部的执行轨迹可以在DeepSeekAgent中增加一个简单的日志开关。比如在每次调用模型前打印当前消息数量在每次执行工具后打印工具名和结果。def run(self, user_input: str, verbose: bool False) - str: messages [...] for iteration in range(self.max_iterations): if verbose: print(f[Iteration {iteration 1}] 请求模型当前消息数: {len(messages)}) response ... if not message.tool_calls: return message.content or if verbose: for tc in message.tool_calls: print(f[Tool Call] {tc.function.name}({tc.function.arguments}))打印日志能帮助你快速定位问题如果发现模型在某一步重复调用同一个工具说明上下文可能缺少“已经调用过该工具”的提示需要调整 system prompt如果发现工具参数解析失败说明该工具的 JSON Schema 定义不够清晰。5.2 观察预期输出一个正常的运行日志大概是这样的[Iteration 1] 请求模型当前消息数: 2 [Tool Call] get_current_time({}) [Iteration 2] 请求模型当前消息数: 4 Agent: 当前本地时间是 2025年1月15日 14:30:00星期三。可以看到Agent 经过了两轮请求第一轮决定调用工具第二轮基于工具结果生成最终答案。这就是 Agent 开发中最典型的“思考-行动-观察”循环。6. 常见问题与排查思路6.1 GitHub 下载与网络访问类最近很多同学反馈 GitHub 访问困难或者 Git Clone 速度很慢。这里做一个不涉及任何不安全工具的通用排查问题现象常见原因解决思路ping github.com 超时本机网络配置或运营商问题检查网络连接换一个网络环境测试git clone 速度慢跨地域传输、仓库体积大使用--depth1浅克隆分时段下载网页打开失败CDN 访问不稳定稍后重试或使用官方 GitHub Desktop仓库下载中断网络波动重新 clone或从发布页下载源码包不要使用来路不明的“镜像脚本”或下载器尤其不要在未核实内容的情况下执行有 root 权限的脚本。安全永远优先于便利。6.2 Agent 执行异常类问题现象常见原因解决思路agent terminated due to error工具函数内部抛出未捕获异常在工具执行外层增加 try-except返回错误信息给模型模型不调用工具直接编答案工具描述不清晰在工具 description 中写明适用场景和参数含义模型反复调用同一个工具上下文缺少结果检查 assistant 消息和 tool 消息是否完整回传返回内容超过上下文限制多轮工具调用导致历史过长引入消息截断、摘要、滑动窗口策略API 返回 401API Key 错误检查 .env 文件和环境变量是否加载API 返回 429请求频率超过限制增加请求间隔使用退避重试6.3 本地模型还是远程 API如果你的目标是学习 Harness 原理直接用 DeepSeek API 就够了。如果你想离线部署并更好地控制数据可以考虑在本地部署量化模型。本地部署的优势是隐私和成本可控但需要额外的推理服务框架并且配置复杂度更高。从工程收敛角度来看建议先通过 API 跑通 Agent 闭环再根据需求决定是否替换成本地推理端点。只要保持 OpenAI 兼容接口不变Harness 里的核心代码基本不用改。7. 工程化最佳实践7.1 密钥与配置管理无论做个人项目还是企业项目API Key 都不能出现在代码里也不能提交到 Git 仓库。建议在.gitignore中忽略.env文件。使用环境变量或配置中心管理密钥。如果使用 CI/CD使用平台的 Secret 功能注入密钥。7.2 工具函数的健壮性工具是 Agent 能完成实际任务的唯一抓手因此它的返回值必须结构化、可预测。建议每个工具都返回 JSON 字符串并包含错误字段。这样模型看到{error: ...}后会尝试调整参数或告知用户而不是直接崩溃。工具的参数 Schema 要尽可能细化description写清楚参数含义和格式。required明确哪些参数必须提供。enum对可选值范围内的参数进行约束。7.3 上下文管理策略多轮工具调用会让messages快速增长。当上下文窗口接近上限时有几种常见处理方式截断最旧的对话消息保留 system 和最近几条。对历史工具结果做摘要而不是原样保留。将长期记忆外置到数据库或向量库仅把相关检索结果注入上下文。在 Harness 中建议把上下文管理策略独立成一个模块而不是散落在 Agent 循环里。这样后续可以轻松切换不同的策略。7.4 异常与重试模型的工具调用不总是一次成功常见失败有模型生成了错误的 JSON 参数。工具内部依赖的第三方 API 超时。上下文太长导致请求被拒绝。建议为模型调用增加指数退避重试同时在重试次数用尽后把错误信息返回给模型让模型向用户说明“当前无法完成任务”而不是让进程直接崩溃。7.5 安全边界不要让 Agent 拥有“无限权限”。在生产环境建议为每个工具定义最小权限。涉及文件删除、数据库写操作、资金相关操作时加入人工审批步骤。对工具可以访问的网络地址、文件目录做白名单限制。Harness 的价值不仅是让 Agent 能力更强更是为 Agent 划出安全边界。一个没有边界的 Agent 是危险的这一点在工程化落地时要格外重视。8. 总结与下一步学习方向这篇文章从概念出发解释了 DeepSeek Harness 在 Agent 开发中的定位然后带大家完成了一个最小闭环模型调用、工具注册、工具执行、结果回传、多轮迭代。代码虽然简化但已经包含了 Agent 开发最核心的骨架。接下来你可以从以下几个方向继续深入给 Agent 接入更多真实工具比如文件读写、数据库查询、HTTP 请求。实现基于向量数据库的长期记忆让 Agent 记住用户的偏好和历史对话。引入多 Agent 协作一个 Agent 负责规划另一个 Agent 负责执行。为 Agent 增加完整评测集量化测试工具调用准确率和任务完成率。尝试把 Harness 封装成 Web 服务通过 API 对外提供 Agent 能力。如果你正在尝试把手里的 DeepSeek API 封装成可控的 Agent 工程建议先不要急着引入重量级框架而是像本文一样从最小闭环开始。把“模型对话”和“工具调用”这条链路真正跑通之后再逐步加记忆、加策略、加权限你会发现 Agent 开发其实没有想象中那么神秘。最重要的是动手把代码跑起来。
![[光学原理与应用-521]：对光的错误理解与纠偏](http://pic.xiahunao.cn/yaotu/[光学原理与应用-521]：对光的错误理解与纠偏)
