Events

Events 是 SDK 用来观察 tool 执行过程的轻量 hook。

当你的应用需要展示“Agent 正在调用 web_search”、记录工具耗时、把状态流式推送到 UI，或把执行过程接入 telemetry 时，可以使用 Events。它不是基础 Agent 的必需配置。如果你只想运行 Agent 并拿到最终回答，优先从 duclaw-cli/sdk 使用 createAgent()。

Events 放在低层 core 入口里，因为它属于运行时组合能力：

import {
  createCoreAgent,
  createRuntimeEventBus,
  createToolExecutor,
  createToolRegistry,
  type RuntimeEvent,
  type RuntimeEventBus,
} from "duclaw-cli/sdk/core";

Event 类型

内置 tool executor 会发出这些事件：

Event	触发时机
toolUse.started	工具调用即将开始
toolUse.completed	工具调用成功完成
toolUse.failed	工具调用抛出错误
toolUse.blocked	hook 或策略阻止了工具调用

每个 event 包含：

字段	含义
eventId	这个 runtime event 的稳定 id
type	上面列出的 event 类型之一
occurredAt	ISO 时间戳
toolName	工具名称，例如 web_search
toolCallId	可用时为模型产生的 tool-use id
inputSummary	工具输入的 JSON 摘要
durationMs	工具调用结束后的耗时
resultSummary	成功调用的截断结果文本
errorSummary	失败或被阻止时的错误原因
requestContext	请求元数据，例如 requestId

订阅 Events

const eventBus = createRuntimeEventBus();

eventBus.subscribe("toolUse.completed", (event) => {
  console.log(`${event.toolName} finished in ${event.durationMs}ms`);
});

subscribe() 会返回一个取消订阅函数：

const unsubscribe = eventBus.subscribe("toolUse.failed", (event) => {
  console.error(event.toolName, event.errorSummary);
});

unsubscribe();

接入 Core

const registry = createToolRegistry();
const toolExecutor = createToolExecutor(registry, { eventBus });

const agent = createCoreAgent({
  systemPrompt,
  llm,
  storage,
  tools: Array.from(registry.values()),
  toolExecutor,
});

duclaw-cli/sdk 中友好的 createAgent() facade 会帮你创建 tool executor。只有当宿主应用需要自己接管这些运行时 wiring 时，才从 duclaw-cli/sdk/core 使用 createCoreAgent()。

何时使用 Events

当宿主应用需要这些能力时，使用 RuntimeEventBus：

• 在 Web 或桌面 UI 中渲染实时 tool activity；
• 持久化 execution traces 方便调试；
• 统计工具耗时和失败率；
• 通过 WebSocket 或 SSE 转发状态更新；
• 把 SDK runs 接入产品 telemetry。

简单脚本、测试或命令行示例里，如果最终的 agent.run() 结果已经够用，就不需要接入 Events。