值得从DeepSeek的Harness中借鉴的五种代理工程模式
以事件日志为真相、分级循环警告、显式截断、权限检查的代码模式以及新代理交接:构建可调试代理系统的五种模式。
来源: 5 Agent-Engineering Patterns I Learned From DeepSeek’s Open-Source Harness
智能体在编写代码、调用工具、搜索文件以及处理长时间任务方面的能力不断提升。但在这一切背后,还有一个更为隐蔽的问题:究竟是什么阻止了智能体变得混乱、难以预测,甚至几乎无法调试?仔细研究 DeepSeek 开源智能体框架中的工程设计选择,可以发现五种值得借鉴的理念,即便你从不使用该框架也是如此。这些并非 DeepSeek 独有的技巧,而是适用于所有智能体系统的通用设计思路。
1. 将事件日志作为事实来源
大多数智能体系统会将对话内容存储在列表中,再将该列表传递给模型:
messages = [...]
在其他地方,有名记录员记录下了发生的事情:
logger.info({
"messages": messages,
"tool_calls": tool_calls,
"tokens": tokens
})
这似乎合情合理,但它会导致对同一事件出现两种描述,而这正是存在风险的地方。假设该应用程序在发送消息之前对其进行了修改,比如插入了额外的指令:
messages.append({
"role": "system",
"content": "Remember to be concise."
})
如果事件日志从未记录过那次编辑,说明模型处理了某些日志中完全没有记载的内容。六小时后,该智能体做出了异常行为,你便查看日志试图找出原因。其解释可能是一条并未出现在任何记录历史中的系统消息。
更好的方法
应将事件日志视为唯一的权威来源。它记录着所有事实,比如用户的请求、每次工具调用、每个结果以及助手的回复:
events = [
UserMessage("Fix the authentication bug"),
ToolCall("grep", {"query": "auth"}),
ToolResult("Found 12 matches"),
AssistantMessage("I'll inspect the middleware")
]
模型的上下文由此类事件生成,而非以独立列表的形式保存:
def build_context(events):
return [
event.to_message()
for event in events
if event.visible_to_model
]
关键在于并不存在任何私有的、隐藏的消息数组。每次都需要自行计算。将两种结构进行比较,更优的那种是从日志通过上下文构建器一直传递到请求的。
Event Log
↓
Context Builder
↓
LLM Request
应避免使用会分割日志的架构,其中一个分支负责处理日志,另一个分支则负责处理传给模型的消息:
Event Log ─────────→ Logs
\
→ Messages ─→ LLM
这一小小的结构改动让调试变得容易多了。
进一步验证
在开发过程中,你可以添加一个检查机制,从日志中重新构建预期的上下文,并将其与实际即将发送的内容进行比较:
expected = build_context(event_log)
actual = request.messages
if actual != expected:
raise RuntimeError(
"log-reconstruction desync"
)
有了这样的机制,上下文漂移就不再是一个令人困惑的生产环境缺陷,而只是一次失败的测试。此外还有额外的好处:可观测性大幅提升。如果轨迹视图能够显示模型调用、工具调用、工具结果、令牌使用情况以及时间信息,就无需再另行拼凑事件经过,因为这些信息早已存在——智能体在重建自身上下文时就需要它们。这样一来,单一的真实数据源便能承担两项功能。
2. 不要立即强制终止智能体循环
每位智能体开发者迟早都会遇到这种情况:模型反复执行相同的搜索操作:
grep "authentication"
grep "authentication"
grep "authentication"
grep "authentication"
...
问题很明确,显而易见的解决办法也同样简单:拒绝重复来电。
if previous_call == current_call:
raise LoopError()
问题在于,重复操作有时是必要的。网络请求可能会失败,文件也可能已更改,此时确实需要重新尝试。与其阻止模型,不如向它发出警告。
想象一个随重复次数增加而增强的压力系统:
3 repeats → gentle reminder
5 repeats → stronger reminder
8 repeats → very strong reminder
第一级可能会指出相同的工具调用正在重复,并建议重新查看上一个结果:
if repeat_count >= 3:
inject(
"You are repeating the same tool call. "
"Re-read the last result and consider another approach."
)
第二级更为严格,要求代理停止当前操作并重新评估:
if repeat_count >= 5:
inject(
"You have repeated this exact operation several times. "
"Stop and reassess the approach."
)
到第三步时,消息提示这似乎是一个循环,需要改变处理方式,或者应当结束当前工作:
if repeat_count >= 8:
inject(
"This appears to be a loop. "
"Change your approach or wrap up."
)
注意安全带没有做什么。它从不返回类似这样的直接拒绝信息:
return False
控制权仍在模型手中。训练集仅提供更多信息,由模型自行决策,这是两者之间的重要区别。
统计真正的重复
一个优秀的检测器不会被夹在其中的无关调用所迷惑。以下序列仍应被视为重复:
grep foo
todo update
grep foo
否则,模型可能在相同的调用之间进行无意义的工作,从而重置自身的计数器。参数也应进行标准化处理,这样这两者就视为相同的操作:
{"query": "foo", "path": "src"}
以及:
{"path": "src", "query": "foo"}
字典中的键顺序不应有影响。被拒绝的调用也应被统计在内。如果模型持续尝试此类操作:
run dangerous command
→ denied
run dangerous command
→ denied
run dangerous command
→ denied
正是在那时,它才需要意识到或许应该停止尝试。
一般模式
软弱的应对方式是对不良行为的直接反应:
Bad behavior → hard block
更强大的模型能够检测到这种行为,增强反馈机制,从而帮助模型恢复:
Bad behavior
↓
Detect
↓
Increase feedback
↓
Let model recover
这其实是个看似简单的想法,几乎适用于所有能调用工具的智能体框架。
3. 告诉模型它没有看到的内容
这听起来很显然,但仍有许多工具会犯错。假设某个仓库中存有如下内容:
4,000 files
而搜索工具只返回了这些内容:
100 files
如果响应仅仅是那百个文件,模型可能会认为恰好有一百个文件匹配。但实际上该工具的意思是“这里有百个文件,因为我已经停止搜索了”,这两种含义截然不同。
明确说明截断情况
更好的响应应说明发生了什么以及其余内容存放在何处:
Showing 100 of 4,000 results.
The result set was truncated.
Full results:
~/.agent/search-results/results.txt
该模型现在知道了三件事:存在更多结果,它当前拥有的是其中的一部分,且如有需要可以获取完整列表。这样的状态要安全得多。
抽样方法优于直接取前N个
假设共有4,000个文件,而只能存储100个。简单的做法就是直接截取一部分:
results[:100]
排序后的结果可能存在风险,因为同一个目录或同一命名规则下可能会产生上百个文件。将样本分散在完整列表中能提供更多有用信息:
def sample_results(results, limit=100):
step = len(results) / limit
return [
results[int(i * step)]
for i in range(limit)
]
具体的算法不如原则重要:绝不能让模型将真实存在的事物与工具显示的内容混为一谈。
错误同样需要重视
工具的错误也可能误导智能体。假设某个命令被安全策略阻止,仅给出这样的简单提示是不足的:
Permission denied
因为模型可能会判定自己的语法有误,然后一次又一次地尝试。一个好得多的提示应该是明确的:
Policy denial.
This command was intentionally blocked by the sandbox.
The command itself may be valid, but this operation is not permitted.
Do not retry using another method to bypass the policy.
这不仅仅是一条更友好的消息,更是对智能体的指导。你的工具不仅能执行操作,还能与另一个推理系统进行交互。工具的输出应当回答一个问题:模型需要了解什么信息才能做出正确的下一步决策?
4. 代码执行不得绕过权限限制
现代智能体系统中的另一种模式是代码模式。与其允许每轮只调用一个工具,不如为模型提供一个编程环境:
files = search("authentication")
for file in files:
content = read_file(file)
print(analyze(content))
这非常强大。通常的循环会一轮又一轮地在模型调用和工具调用之间切换:
LLM
↓
search
↓
LLM
↓
read
↓
LLM
↓
read
↓
LLM
↓
read
代码模式允许模型运行一个会进行多次调用的程序,并返回总结结果:
LLM
↓
run_code(...)
↓
50 tool calls
↓
summary
这可以大幅减少往返次数和上下文使用量,但也会引发一个严重的安全问题。
谁来检查程序内部的调用?
在常规架构中,每个模型操作在到达工具之前都会先经过权限验证层:
Model
↓
Permission Layer
↓
Tool
若粗心添加代码执行功能,代码便可能直接接触到相关工具:
Model
↓
Code
↓
Tool
如果是这样的话,你就相当于在权限系统周围构建了一个后门,这显然是不好的。正确的设计应确保程序的每一次调用都遵循相同的安全路径:
Model
↓
run_code
↓
Program
↓
Permission Layer
↓
Tool
每次工具调用仍需经过相同的处理流程。从概念上讲,文件读取函数在执行任何操作之前都会先检查权限:
def read_file(path):
permission = check_permission(
operation="read",
path=path
)
if not permission.allowed:
raise PermissionError(
"File access denied"
)
return actual_read(path)
代码解释器不会收到该函数的特殊版本,它得到的与其他人使用的完全相同。
将拒绝处理转化为普通程序错误
还有一个更微妙的细节。如果程序试图执行其未被允许的操作:
try:
delete_file("/important/file")
except PermissionError as e:
print(e)
它应该会收到一个普通的、可捕获的错误。不应让其无限期地悬而未决:
hang forever
它不应悄无声息地返回空结果:
return None
它不应表现得好像什么都没发生一样:
pretend nothing happened
程序必须能够识别出操作失败这一情况,这在模型需要即时编写程序时尤为重要。代码模式之所以强大,正是因为它能让模型拥有更多控制权,因此权限边界必须更加严格而非宽松。
5. 有时最好的上下文策略就是不使用上下文
这是更多智能体构建者应当尝试的理念。长时间运行的智能体会积累大量对话历史。起初这会有帮助,但随后就会变成负担。最终你会面临一系列轮次不断为庞大的上下文提供数据的情况:
Round 1
↓
Round 2
↓
Round 3
↓
Round 4
↓
Round 5
↓
Huge context
现在,模型把注意力集中在重读自己的过往记录上,而非解决任务。总结是一种解决办法,但还有另一种:结束对话并保留工作空间。
以一个需要进行五轮的编程任务为例。在第一轮中,第一个智能体会检查代码库,进行修改,保存自己的工作成果,并撰写交接说明:
Agent A
→ inspect repository
→ make changes
→ save work
→ write handoff
第二轮从一个全新的智能体开始,它会读取工作空间及交接信息,然后继续执行任务:
Agent B
→ read workspace
→ read handoff
→ continue
没有冗长的历史记录,没有过时的推理方式,也没有堆积如山的工具杂音。它只有当前的状态。