docs/sdk/reference/events.mdx
The SDK exposes multiple event surfaces.
Direct AgentRuntime usage emits low-level runtime events through agent.subscribe(listener).
const unsubscribe = agent.subscribe((event) => {
console.log(event.type)
})
Common runtime events include model events, tool execution events, run lifecycle events, and failure events. Runtime results use AgentRunResult.status rather than finishReason.
Core/host-facing agent events are emitted through AgentConfig.onEvent and core adapters.
| Event | Description |
|---|---|
content_start | Text/reasoning/tool content begins |
content_update | Tool progress update |
content_end | Text/reasoning/tool content completes |
iteration_start | Loop iteration begins |
iteration_end | Loop iteration completes |
usage | Token/cost usage update |
notice | Runtime status/recovery notice |
done | Agent completed/aborted/failed |
error | Error occurred |
interface AgentDoneEvent {
type: "done"
reason: "completed" | "max_iterations" | "aborted" | "mistake_limit" | "error"
text: string
iterations: number
usage?: LegacyAgentUsage
}
interface AgentUsageEvent {
type: "usage"
inputTokens: number
outputTokens: number
cacheReadTokens?: number
cacheWriteTokens?: number
cost?: number
totalInputTokens: number
totalOutputTokens: number
totalCacheReadTokens?: number
totalCacheWriteTokens?: number
totalCost?: number
}
ClineCore.subscribe(listener, options?) emits session-level events from the runtime host.
const unsubscribe = cline.subscribe((event) => {
console.log(event.type, event.sessionId)
}, { sessionId })