Agent 执行：控制接口、循环驱动与事件记录

agent 提供运行控制接口，agent-loop 驱动请求准入、模型调用和工具结算，Session 保存可重放事件。取消与空闲等待属于运行控制，历史与工具能力通过独立服务供循环使用。

运行对象与持久事件的职责分离

箭头表示标注的调用或依赖关系；点击组件定位正文。完整关系见下方文字说明。

文字关系说明与章节链接

agent →（驱动实现）→ agent-loop；agent-loop →（模型服务）→ llm；agent →（关联记录）→ Session；agent-loop →（工具分派）→ tools；tools →（调用已注册工具）→ tool-fs / ctx.fs。

agent · agent-loop · llm · Session · tools · tool-fs / ctx.fs

agent 接口由 agent-loop 驱动

dsh-agent 提供运行中的 Agent 与 create、resume 等生命周期入口；dsh-agent-loop 提供可替换的执行循环。

dsh-agent · 接口摘录，省略上下文 · ctx.agents.create · packages/core/agent/README.md

// 应用通过已注册工厂创建 Agent 与 Session，返回负责销毁的 AgentHandle。
const handle = await ctx.agents.create({
  sessionId,
  agentOptions: { provider: 'deepseek', model: 'deepseek-chat' },
})

消息进入 inbox 后唤醒驱动器，循环开始 turn，领取排队输入，调用 dsh-system-prompt 组装系统内容，并经过 pre-step 扩展点。dsh-session 持有这次对话的事件记录。Agent 是有取消、状态和拥有者的运行对象，Session 是记录，两者不能互相代称。

dsh-agent · 接口摘录，省略上下文 · agent.followup · packages/core/agent/README.md · agent/pre-step · packages/core/agent/README.md

// 用户或插件递交后续输入并唤醒下一轮；消息先进入 inbox，再由循环接纳。
handle.agent.followup({
  content: [{ type: 'text', text: '解释项目启动方式。' }],
  source: { kind: 'user' },
})

// 监听者在进入步骤前拒绝或替换输入；接纳成功前取消不把待接纳内容写入历史。
'agent/pre-step'

请求准备与准入确定本次输入

AgentLoop 开始 step，通过 request/prepareCall 解析请求，最后交给 dsh-llm 路由到所选模型提供者。在准备阶段被取消，尚未接纳的系统内容和用户消息不会进入历史。

接纳阶段同步记录必要输入并冻结本次请求，使随后发送给提供者的内容可以从日志重建。已安装的 session-checkpoint-policy 再在相关外部动作前落实持久化检查点。这个分界决定一条排队消息是否真正参与了模型请求。

工具分派连接注册表与能力提供者

模型返回读取请求后，AgentLoop 把工具名与参数交给 dsh-tools。读文件工具 dsh-tool-fs 解释路径、起始位置与读取限制，调用 ctx.fs；本地提供者 dsh-fs-local 执行实际文件访问，输出再经工具校验和呈现形成模型可读结果。

因此模型决定调用什么，工具定义调用语义，文件提供者决定如何访问执行环境。并行工具由有界池调度，屏障约束不适合并行的工作，结果按模型调用顺序进入后续处理。

响应、取消与空闲以结算为界

文件结果进入记录后，下一次模型步骤才能依据正文解释项目；需要更多信息时模型继续调用工具。成功输出提交为 assistant/message，失败、重试或取消后的已结算尝试提交为 assistant/attempt；瞬时流片段不是同等持久的对话消息。

取消触发工具和请求停止，循环要等拥有的工作收敛并完成停止检查点才转为空闲。进程在流结算前丢失，不能保证恢复用户曾看见的每一个片段。

dsh-agent · 接口摘录，省略上下文 · agent.cancel · packages/core/agent/README.md · agent.whenIdle() · packages/core/agent/README.md

// 控制方取消当前工作，默认清除待处理 inbox；取消不等同于销毁运行 Agent。
agent.cancel

// 调用方等待 Agent 回到空闲，确保已拥有的工作完成收敛。
await handle.agent.whenIdle()

辅助示例

“读 README 并解释启动方式”依次经过 inbox→AgentLoop→system-prompt 与 Session→ctx.llm→模型工具调用→core/tools→tool-fs→fs-local。文件正文返回后，循环再次请求模型形成解释。若文件不存在，文件工具产生失败结果供模型处理；若用户取消，取消信号沿实际执行链传播，而不是只把界面按钮改成已停止。

设计取舍

把决策、调度、工具语义、执行提供者和记录分开，使同一个循环可以使用本地或其他文件提供者；代价是一次请求涉及多个组件。排错应定位消息接纳、模型调用、工具执行或持久化中的具体失败点，不能把所有问题都归为模型没有理解。

Agent 执行：控制接口、循环驱动与事件记录 ​

agent 接口由 agent-loop 驱动 ​

请求准备与准入确定本次输入 ​

工具分派连接注册表与能力提供者 ​

响应、取消与空闲以结算为界 ​