用DeepSeek Harness从零构建可用AI Agent的完整实战

2023 年底我第一次产生“要让大模型自己干活”的念头，当时还在用最笨的方式写代码：把问题喂给模型，再用一堆 if-else 解析它的回答，试图猜它想干什么。跑了两周，代码越写越乱，最后发现真正的问题不是模型不够聪明，而是缺一个能把“思考、决策、调用工具”串起来的执行框架。直到我接触到 DeepSeek Harness，才算把 AI Agent 从玩具脚本变成了真正能交付任务的工具链。这篇文章就是我基于 DeepSeek Harness 从零到一搭建第一个可用 Agent 的完整记录，覆盖安装配置、核心原理、完整代码和踩过的坑，适合想在本地跑一个能用工具的 Agent，或者准备往 AI Agent 开发方向转的读者。

1. AI Agent 的概念拆解：从聊天机器人到能干活的 Agent

1.1 先厘清概念：Agent 不是“会聊天的模型”

很多人一听到 AI Agent 就以为是聊天机器人的升级版，其实根本不是一回事。聊天机器人是“你问我答”，模型输出即终点，回答完就结束；而 Agent 是“你派活、它完成”，模型只是大脑，关键是它得自己规划步骤、调用工具、检查结果，直到任务真的落地。

打个比方，普通大模型 API 相当于一个智商 150、但没有手脚、也不允许离开椅子的顾问。你跟他说什么，他都答得头头是道，但让他“把这件事办妥”，他无能为力。而 Agent 就是从这个顾问升级成了“实习生”：你说“帮我把这 20 份周报读一遍，提炼共性问题，写一份纪要放回共享盘”，他会拆解成“读文件—归纳—写纪要—保存”，中途发现信息不够还会自己回去补充。

要实现这种能力，Agent 至少要具备三样东西：工具调用，也就是能实际操作外部世界的手脚；任务规划，把大目标拆成可执行的小步骤；记忆状态，能记住“我已经做了什么，下一步该干什么”。这也是 DeepSeek Harness 这类框架核心解决的三件事。

1.2 DeepSeek Harness 在整套体系里扮演什么角色

先解释“Harness”这个词。它不是某个框架的专有名词，软件工程里“test harness”指的是“测试夹具、执行控制器”。放到 AI 领域，Harness 的含义就是把模型执行过程“缰绳化”管理起来：模型不是直接裸露在业务代码里，而是跑在一条预设的执行管线上。

DeepSeek Harness 本质上就是围绕 DeepSeek 模型封装的这样一套 Agent 执行管线。它跟 LangChain 这类大而全的框架定位不太一样：LangChain 功能多但抽象层级多，新手看文档容易迷失；DeepSeek Harness 更轻、更聚焦，针对 DeepSeek 模型本身的工具调用协议、输出格式容错、上下文字段做了更深的适配。社区里也有人把它当成轻量版 LangGraph 用，因为它的循环控制足够直观，没有那么多绕来绕去的概念。

我选择用它还有一个现实原因：AI Agent 开发里，模型的“工具调用稳定性”直接决定任务成败。通用框架要兼容几十种模型，往往在适配度和容错上做取舍；而围绕单一模型深度优化的 Harness，至少在解析模型返回的 JSON 参数时更干净。这块后面讲实操时你们会感受到。

2. DeepSeek Harness 安装与初始配置：环境、命令与最小验证

2.1 环境准备：Python 版本、虚拟环境与 API Key

先说环境。我本地是 macOS + zsh，Windows 下用 PowerShell 也差不多。DeepSeek Harness 目前社区 0.1.x 版本要求 Python 3.10 以上，不建议用 3.9，否则一些类型注解和内置泛型会报错。这个坑我帮朋友排过，没必要省。

第一步建虚拟环境。不管什么系统，我都强烈建议用 venv 隔离，不要直接装到全局 Python。之前有人图省事直接 pip 装，结果和项目里的 Pydantic 版本冲突，改了两天才消停。命令很简单：

python3 -m venv .venv source .venv/bin/activate # Windows 使用 .venv\Scripts\activate

接着安装框架。以我用的 0.1.x 版本为例，包名是deepseek-harness：

pip install -U deepseek-harness

装完可以顺手验证一下导入是否正常：

python -c "from deepseek_harness import Agent; print('import ok')"

如果这里报错，先看 pip 源和 Python 版本，别急着往下走。

然后是 API Key。最稳的方式是用环境变量，不要写死在代码里：

export DEEPSEEK_API_KEY="sk-xxxx"

安全性多说一句：不要把 key 提交到 Git 仓库。项目里建一个.env文件，用python-dotenv加载，同时把.env加进.gitignore。DeepSeek Harness 也支持自动读.env，但显式加载更可靠。

2.2 十行代码跑通最小 Agent，验证安装是否正常

框架装完别急着写一大坨业务代码，先跑一个不带任何工具的最小 Agent，确认模型 API、执行循环、日志输出全部正常。保存为hello_agent.py：

from deepseek_harness import Agent agent = Agent( model="deepseek-chat", system_prompt="你是一个测试助手，请用最简短的话回答。", ) result = agent.run("你好，请说一句话证明你活着。") print(result.final_answer)

这段代码就三件事：初始化 Agent、指定模型、跑一句话。执行后如果正常，你会看到类似[step 1] model_call ok和total_steps=1的日志，然后输出一句简短回答。

这里有个第一次运行大概率会踩的坑：网络超时。还有少数版本默认的base_url指向 DeepSeek 官方 API，如果你用的是第三方兼容通道，需要在初始化时指定：

agent = Agent( model="deepseek-chat", base_url="https://你的兼容服务地址", api_key="sk-xxxx", )

这一步验证通过，说明环境没问题，可以进入真正的 Agent 开发了。

3. 核心配置与原理剖析：关键参数这样调，Agent 才会“听话”

3.1 Agent 的三件套：模型、工具集、执行循环

把最小例子跑通后，得理解它为什么“能干活”。DeepSeek Harness 的 Agent 模型核心就三个部件：模型、工具集、执行循环。

模型不用多说，默认接deepseek-chat，也可以用deepseek-reasoner。后者擅长复杂推理，但响应更慢、成本更高。我的经验是通用任务先上 chat，只有 Agent 需要多步数学或代码推理时才切 reasoner。

工具集是 Agent 的手脚。Agent 本身接触不到外部世界，一切外部动作——搜索网页、读写文件、执行命令——都要封装成一个个普通 Python 函数，然后注册给它。模型看不到你的函数代码，它只能看到函数名、参数名和 docstring 转换成的 JSON Schema。这也就是为什么工具函数的命名和说明这么重要：写得越清楚，模型越不容易用错。很多新手工具一多就频繁报错，绝大多数都是“给模型的说明书没写明白”。

执行循环是灵魂。它按“观察—思考—行动—再观察”的节奏反复运行，也就是常说的 ReAct 模式。模型先看任务和已有信息，推理出下一步动作，生成一个工具调用请求；Harness 帮你校验参数、执行函数、把结果塞回上下文，再让模型重新思考。直到模型认为任务完成、不再请求调用工具为止，循环结束。这就是 Agent 化与普通 API 调用的根本区别。

3.2 关键参数选型：temperature、max_tokens、system_prompt

Harness 里可配置参数不少，但初期最影响体验的是这几个。

temperature控制随机性。聊天场景你可以调到 0.7、0.8 让回答更有创造力，但 Agent 是执行任务，就该往低调，我一般 0.1~0.2。调高了容易“说多做少”，甚至自己编造一个不存在的工具名来调用。 Agent 要的是稳定，不是创意。

max_tokens控制单次输出的最大 token 数。Agent 不仅要输出答案，还要输出中间推理和工具调用的 JSON，太短就会被截断导致解析失败。我习惯 1024 起步，复杂场景 2048。如果发现模型每次生成 tool_call 都异常，先看这个值是不是设小了。

system_prompt是给 Agent 立规矩的地方。角色、工作范围、输出格式、禁忌都可以写在这里。很多 Agent “犯傻”不是模型笨，是提示词写得含糊。我见过最多的错误是没在提示词里写明“不要调用不存在的工具”，模型一旦遇到模糊指令，就开始自由发挥。

还有两个参数也值得关注。streaming在 Agent 场景我一般不开，因为 Agent 本来就是后台执行，流式输出反而增加日志噪音；tools列表可以静态传入，也可以事后用agent.register_tool()动态加，后者在搭复杂工作流时更灵活。

4. 实操全流程：搭建一个能搜索、能写笔记的 Agent（附完整代码）

4.1 需求拆解与模块设计

接下来是重头戏，我搭建了一个“本地笔记助手”。场景很实在：我每天会看不少技术博客，随手记笔记，但流程很碎。这个助手要做的是：给我一句话，它自己上网搜资料、整理成 markdown 笔记、写进指定目录。

拆解成 Agent 需要的能力，一共四件事：

• 搜索互联网资料。我用公开搜索接口实现，不需要复杂的登录授权。
• 读取本地 markdown 文件。目的是让 Agent 能参考现有笔记的排版风格，保持输出统一。
• 写入 markdown 文件。这是 Agent 的“交付动作”，让它真的把任务落地。
• 获取当前时间。写笔记日期信息时，Agent 需要知道“现在是几点”。

这里的设计原则是：工具要尽量贴近“一手交付”。如果最后一个环节还要你手动复制粘贴，那 Agent 的独立性就打折扣了。工具分得越细，Agent 越灵活；但也不是越细越好，太碎了反而会让模型在“选哪个工具”上犯难。

4.2 核心代码：工具定义与 Agent 装配

项目结构很简单：

note-agent/ ├── .env ├── agent.py └── tools/ └── note_tools.py

先看tools/note_tools.py，里面是一组普通 Python 函数：

import datetime from pathlib import Path import httpx def get_current_time() -> str: """返回当前日期和时间字符串，例如 2025-06-01 15:30:00。""" return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S") def search_web(query: str) -> str: """使用公开搜索接口搜索互联网，返回结果文本。query 为搜索关键词。""" url = "https://api.duckduckgo.com/" params = {"q": query, "format": "json", "no_html": 1} resp = httpx.get(url, params=params, timeout=10) data = resp.json() if not data.get("AbstractText"): return "未找到有效摘要，换一个关键词试试。" return data["AbstractText"][:2000] def read_markdown(path: str) -> str: """读取本地 markdown 文件内容，path 为文件路径。""" p = Path(path) if not p.exists(): return f"文件 {path} 不存在。" return p.read_text(encoding="utf-8")[:3000] def write_markdown(path: str, content: str) -> str: """将 content 写入指定 markdown 文件，path 为文件路径。""" p = Path(path) p.parent.mkdir(parents=True, exist_ok=True) p.write_text(content, encoding="utf-8") return f"已写入 {path}，共 {len(content)} 字符。"

每个函数的 docstring 我刻意写得很细，因为模型看到的不是函数体，而是“函数名+参数名+描述”组成的 JSON Schema。你给模型的说明书越清晰，它用错参数的概率就越低。search_web里我做了结果截断，避免一长串返回内容把上下文撑爆。

再看agent.py：

from dotenv import load_dotenv from deepseek_harness import Agent from tools import note_tools load_dotenv() agent = Agent( model="deepseek-chat", system_prompt=( "你是一个严谨的本地笔记助手。你的任务：根据用户指令，" "必要时先调用 search_web 获取资料，然后参考已有笔记风格，" "用 write_markdown 把整理好的 markdown 写入指定目录。" "不要编造数据，不要在没有搜索的情况下写自己不确认的内容。" "不要调用不存在的工具。" ), temperature=0.2, max_tokens=1024, ) for func in [note_tools.get_current_time, note_tools.search_web, note_tools.read_markdown, note_tools.write_markdown]: agent.register_tool(func) if __name__ == "__main__": task = input("请描述你要记录的笔记：") result = agent.run(task) print("最终结果：") print(result.final_answer)

运行后输入一句任务，比如：“帮我搜索一下 LangGraph 和 LangChain 的区别，整理成简短备忘，写入 docs/langgraph_vs_langchain.md”。Agent 会自己规划：先搜资料，再看一下现有笔记的风格，最后把内容写进文件。中间任何一步失败，日志里都能看到它断在哪一步。

4.3 实测运行：看 Agent 如何“自主决策”

我实测跑了一次，日志里清晰记录了这个过程。它先调用了get_current_time拿到时间，然后调search_web搜索关键词，发现返回的摘要信息偏短，又调read_markdown看了一眼 docs 目录下已有笔记的格式，最后用write_markdown写入文件。整个流程出现 4 次 tool call，耗时约 20 秒。

这个过程最有意思的地方在于“自我信息补充”：第一次搜索摘要不够长，模型没有硬着头皮瞎写，而是选择再读一个本地文件来获取格式参考。这种“发现信息不足就主动补料”的能力，正是 ReAct 循环的自然结果，也是 Agent 和普通 API 拼接最大的区别。你不需要在代码里写死“如果摘要太短就再读一次文件”，模型在循环里自己就判断出来了。

4.4 进阶一：把 Agent 嵌进 Spring AI 的多 Agent 项目

如果你做 Java 后端，想把类似能力嵌进项目，也有成熟路子。DeepSeek 的 API 兼容 OpenAI 协议，所以 Spring AI 里可以直接把端点指过去：

spring: ai: openai: base-url: https://api.deepseek.com api-key: ${DEEPSEEK_API_KEY} chat: options: model: deepseek-chat temperature: 0.2

多 Agent 场景下，Spring AI 提供了 ChatClient 组合编排能力，可以让一个主 Agent 负责拆解任务，子 Agent 各管搜索、摘要、写作，最后合并结果。如果你的业务是“任务复杂、需要多个角色协作”，这种 Multi Agent 模式值得投入时间研究，它本质上和 DeepSeek Harness 的执行循环是同一套思想，只是把单个 Agent 的循环扩展成了多个 Agent 之间的编排。

4.5 进阶二：用 MCP 和 LangGraph 扩展边界

再往外扩一点，MCP（Model Context Protocol，模型上下文协议）是当下特别值得跟的方向。它本质上是把“工具如何暴露给模型”这件事标准化。外部系统做成 MCP Server 后，Agent 就能统一对接数据库、设计工具、办公套件等，不需要每个系统写一套自定义接入。

DeepSeek Harness 的工具注册机制可以对接 MCP Server，注册一个“桥接工具”去调用标准化的 MCP 能力。当项目复杂到一定程度，比如任务不是线性而是有分支、有循环，可以再上 LangGraph 这类图式框架。我见过一种很务实的组合：LangGraph 负责全局状态切换，DeepSeek Harness 作为其中一个执行节点，专注处理局部任务。这种“框架嵌套”在生产环境里很常见，核心原则是不要为了用框架而用框架，哪里简单从哪里入手。

5. 高频问题排查实录：乱输出、工具报错、上下文爆炸怎么办

5.1 模型“胡乱冒字出来失真情况”从哪来

第一次跑多轮 Agent，我遇到的第一个大坑就是日志里出现一堆无意义字符、重复的 markdown 标记、甚至自言自语式的句子。这类乱输出通常有三个来源。

第一是 temperature 太高。模型一旦开始“放飞”，后面步骤就会越来越离谱，先把它压到 0.2 再试一轮。第二是 system_prompt 与工具返回内容冲突。比如你要求“全部用中文回答”，但搜索工具返回的是英文材料，模型夹在两种指令之间就容易产生混乱输出。第三是上下文历史污染。多轮对话后，旧消息里的错误输出会被模型当成材料接着引用，越滚越乱。Harness 里可以定期清理历史，或者把旧轮次压缩成摘要。

5.2 工具调用参数一直报错

第二个高频问题是工具调用的参数解析失败，日志里常见tool call args parse error或者missing required argument。原因通常出在“说明书”上：函数的参数名、类型、描述写得不够清楚，模型猜错字段；或者 temperature 太高，模型返回的 JSON 不规矩。

解决办法有三个层面：给工具 schema 开启严格模式，Harness 里叫strict tool calling；把函数 docstring 补到位，参数默认值也写清楚；在 system_prompt 里明确要求“必须先给出完整 JSON 参数再调用工具”。我在笔记助手项目里就遇到了write_markdown的 path 参数被模型拼错路径的情况，补齐 docstring 之后问题立刻消失。

5.3 Agent 越跑越慢、越来越贵

第三个问题：Agent 跑久了明显变慢。原因是每一步的工具结果都会拼进上下文，而上下文越长，模型推理越慢，费用也水涨船高。DeepSeek 模型窗口虽大，但塞满后延迟依然不可接受。

我常用的方案是三种：截断、摘要、滑动窗口。简单任务直接限制历史轮数，比如max_history_steps=8；复杂任务就在每轮结束后让模型把重要信息压缩成一段总结，下一轮把总结放在历史首位；更精细的做法是滑动窗口，只保留最近 N 轮完整对话和前面的摘要。工具函数的返回值也要控制长度，我在search_web和read_markdown里都截断了，这对控制上下文开销非常有效。

5.4 常见问题速查表

这张表我贴在了自己项目的 README 里，排查时直接对着找，比从头翻日志快得多。

最后再分享一点我自己的体会。从“会调模型 API”到“能写出一个不丢任务的 Agent”，最大的坎其实不是框架，而是思维方式的转变。DeepSeek Harness 把执行循环封装好了，但你要学会把任务拆解成“工具能处理的动作”，把每个工具描述得像操作说明书一样清晰。这类轻量框架很适合做这个思维的入门练习，因为所有中间过程都摊开在日志里，你能一眼看到模型在哪里走神、哪里开始胡编。我现在已经把笔记助手扩展到了日报场景：每天早上定时跑一次，自动收集数据、写简报、归档文件。顺着这个思路往下走，Agent 能替你干的活会超乎你预期。