DeepSeek Harness 学习日记：关于Agent接口，工具调用的底层实现

Agent核心接口-Agent是怎么干活的

本文助你理解三个问题：

Agent是什么（接口定义）
Agent怎么处理一个任务（Turn-step模型）
怎么中途干预Agent（Inbox机制）

什么是Agent

上一节我们知道了：插件通过ctx找到服务

现在进阶：Agent本身就是一个服务，通过ctx.agent管理

类比：

概念	类比
`ctx.agents`	公司里的"员工花名册"
一个 Agent 实例	一个员工
`agent.id`	员工工号
`agent.status`	员工状态（空闲/忙碌/已离职）
`agent.session`	员工的工作档案（记忆）
`agent.inbox`	员工的任务收件夹

java 复制代码

// 创建 Agent = 招一个员工
const handle = await ctx.agents.create({
  name: 'my-agent',
  model: 'deepseek-chat',
  // ...
})

const agent = handle.agent  // 拿到 Agent 句柄

// 查看状态
agent.status  // 'idle' | 'running'

// 销毁 Agent = 辞退员工
await handle.dispose()

Turn-Step模型（核心）

Agent运转的基本单元。用餐厅点餐类比：

Turn（轮次）= 从"收到消息"到"没有更多事要做"

Step（步骤）= 一次 LLM 调用 + 它触发的所有工具调用

场景：用户说"帮我查天气，然后根据天气推荐穿搭"

这不是一个简单的问答，而是：

Step 1: LLM 决定调用"查天气"工具 → 工具返回"北京 25°C 晴"

Step 2: LLM 拿到结果，决定调用"推荐穿搭"工具 → 返回"穿T恤+薄外套"

Step 3: LLM 觉得任务完成了，不再调用工具 → Turn 结束

一个 Turn 里有 3 个 Step

Inbox（收件夹）

Agent怎么知道有新任务，通过Inbox

三种往 Inbox 塞消息的方式：

followup（）；排队，唤醒处理；
steer（）；排队，立即处理；
inject（）；排队，不唤醒；

两类事件

dsh中有两类时间，作用不同：

持久化事件：写入日志，永久保存；可以重播、分叉；模型可见 ⟺ 已记录
实时事件：不写入日志，只在内存中；用于实时协调；模型不可见

Session Events = 历史记录（发生了什么）

Agent Events = 实时控制（正在发生什么）

核心变量不变

DSH有一个非常重要的设计原则：模型能看到的东西，必须能从日志重播得到

如果 LLM 看到了某个信息，但没有记录到日志：

→ 系统重启后，LLM 就不记得这个信息了

→ 无法重现之前的对话

→ 无法审计 Agent 为什么做了某个决定

所以：任何到达 LLM 的内容，必须写入 Session Log

学习感悟

我们常说的Agent loop循环，在dsh中就是Step循环

"Agent 的核心公式是 LLM + Tools + Planning + Memory。LLM 是大脑，Tools 是手脚，Planning 是决策循环，Memory 是记忆。

我研究过 DeepSeek Harness 的实现，它把这个公式落地成了一个 Turn-Step 模型：

Turn 是一次完整对话

Step 是 LLM 的一次决策+工具调用

多个 Step 串起来就是一个 Agent Loop，LLM 反复决策直到任务完成

它在八股的基础上还加了几个生产级特性：

Inbox 机制：可以中途给 Agent 塞新任务或紧急指令

Session Log 持久化：所有模型可见内容都记录日志，支持重播和分叉

工具执行管道：工具调用不是直接执行，而是经过多层审批/拦截"

总结

一句话概括

Agent 是有状态的工作单元，通过 Turn-Step 模型驱动 LLM 循环决策，支持中途干预。

核心知识点

Agent 是什么

Agent = 有 ID、状态、收件夹的工作单元

ctx.agents = Agent 注册表（员工花名册）

Turn-Step 模型

Turn（轮次）= 从收到消息到没有更多事要做

Step（步骤）= 一次 LLM 调用 + 它触发的工具调用

一个 Turn 可以包含多个 Step（LLM 反复决策直到完成）

Inbox 三种干预方式

方式	效果	场景
`followup()`	排队，唤醒处理	普通新任务
`steer()`	排队，紧急处理	立即打断
`inject()`	排队，不唤醒	注入上下文

两类事件

Session Events（持久化）：turn/start, step/end, tool/call, tool/result...

→ 写入日志，可重播、可审计

Agent Events（实时）：agent/created, agent/pre-step, agent/status...

→ 内存中，用于实时协调

核心不变量

"Model-visible means logged"

LLM 看到的任何内容，必须能从 Session Log 重播得到

面试怎么答

"dsh 用 Turn-Step 模型驱动 Agent：Turn 是一次完整对话，Step 是一次 LLM 调用+工具调用，多个 Step 串起来就是 Agent Loop。支持三种中途干预------followup 排队、steer 紧急插入、inject 静默注入。设计不变量是'模型可见即日志记录'------LLM 看到的必须写入 Session Log，保证可重播可审计。"

一页速记

Agent：有 ID / status / inbox / session 的工作单元

Turn-Step：Turn = 完整对话，Step = LLM调用 + 工具调用

Inbox：followup(排队) / steer(紧急) / inject(静默)

事件：Session Events(持久) / Agent Events(实时)

不变量：Model-visible ⟺ Logged