Skip to content

AgentEvent ​

Category: Core

Source: agent_event.dart

Events emitted by the agent loop that the surface (UI, ACP, web) subscribes to.

Status: part of the proposed core data model — see docs/plans/2026-04-29-harness-layers.md. Originally lived in agent/agent_core.dart. This is the current agent-event vocabulary; the richer [SessionEvent] hierarchy in session_event.dart is the proposed future contract.

Classes ​

sealed AgentEvent ​

Events emitted by the agent that the UI subscribes to.

AgentTextDelta ​

A delta of generated text forwarded to the UI.

Constructor ​

dart
AgentTextDelta(this.delta)

Properties ​

PropertyTypeDescription
deltaString

AgentThinkingDelta ​

A delta of streaming reasoning/"thinking" content forwarded to the UI. Only emitted by reasoning-capable models. Renderers should style this distinctly from [AgentTextDelta] (typically dim + italic) so users see the reasoning as an aside, not as the final answer.

Constructor ​

dart
AgentThinkingDelta(this.delta)

Properties ​

PropertyTypeDescription
deltaString

AgentToolCallPending ​

Notification that a tool call is being prepared.

Constructor ​

dart
AgentToolCallPending({required this.id, required this.name})

Properties ​

PropertyTypeDescription
idToolCallId
nameString

AgentToolCall ​

A fully-formed tool call ready for execution.

Constructor ​

dart
AgentToolCall(this.call)

Properties ​

PropertyTypeDescription
callToolCall

AgentToolResult ​

The result of an executed tool call.

Constructor ​

dart
AgentToolResult(this.result)

Properties ​

PropertyTypeDescription
resultToolResult

AgentDone ​

Signals that the agent has finished its response.

AgentUsage ​

Token usage reported by the LLM for one call. Forwarded as an [AgentEvent] so [AgentRunner], surfaces, and the session log can aggregate per-call costs without poking inside [AgentCore].

Constructor ​

dart
AgentUsage(this.usage)

Properties ​

PropertyTypeDescription
usageUsageInfo

AgentError ​

An error encountered during the agent loop.

Constructor ​

dart
AgentError(this.error)

Properties ​

PropertyTypeDescription
errorObject

AgentNotice ​

Non-fatal informational message addressed to the user via the transcript surface. Use for soft-degradation announcements — e.g. "tools disabled for this session because the model doesn't support them" — where the agent loop kept running but the user should know something changed.

Every new surface (TUI, ACP, JSON, print) must learn to render this — it's not optional. The fallback behaviour is to skip the notice silently, which masks soft degradation from users.

Constructor ​

dart
AgentNotice(this.message, {this.kind = 'info'})

Properties ​

PropertyTypeDescription
messageStringSingle-line human-readable text. No leading marker glyph — surfaces add their own (TUI uses markerInfo/markerWarn, --print uses ! on stderr).
kindStringinfo (default) for "FYI" messages, warning for soft-degradation announcements the user should react to. Forward-compatible string rather than an enum so adding new kinds doesn't break compile.

Released under the MIT License.