Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    AgentStart,
    AgentEnd {
        messages: Arc<Vec<AgentMessage>>,
    },
    TurnStart,
    TurnEnd {
        assistant_message: AssistantMessage,
        tool_results: Vec<ToolResultMessage>,
        reason: TurnEndReason,
        snapshot: TurnSnapshot,
    },
    BeforeLlmCall {
        system_prompt: String,
        messages: Vec<LlmMessage>,
        model: ModelSpec,
    },
    MessageStart,
    MessageUpdate {
        delta: AssistantMessageDelta,
    },
    MessageEnd {
        message: AssistantMessage,
    },
    ToolExecutionStart {
        id: String,
        name: String,
        arguments: Value,
    },
    ToolExecutionUpdate {
        id: String,
        name: String,
        partial: AgentToolResult,
    },
    ToolApprovalRequested {
        id: String,
        name: String,
        arguments: Value,
    },
    ToolApprovalResolved {
        id: String,
        name: String,
        approved: bool,
    },
    ToolExecutionEnd {
        id: String,
        name: String,
        result: AgentToolResult,
        is_error: bool,
    },
    ContextCompacted {
        report: CompactionReport,
    },
    ModelFallback {
        from_model: ModelSpec,
        to_model: ModelSpec,
    },
    ModelCycled {
        old: ModelSpec,
        new: ModelSpec,
        reason: String,
    },
    StateChanged {
        delta: StateDelta,
    },
    CacheAction {
        hint: CacheHint,
        prefix_tokens: usize,
    },
    McpServerConnected {
        server_name: String,
    },
    McpServerDisconnected {
        server_name: String,
        reason: String,
    },
    McpToolsDiscovered {
        server_name: String,
        tool_count: usize,
    },
    McpToolCallStarted {
        server_name: String,
        tool_name: String,
    },
    McpToolCallCompleted {
        server_name: String,
        tool_name: String,
        is_error: bool,
    },
    TransferInitiated {
        signal: TransferSignal,
    },
    Custom(Emission),
}

Fine-grained lifecycle event emitted by the agent loop.

Consumers subscribe to these events for observability, UI updates, and logging. The harness never calls back into application logic for display concerns.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

AgentStart

Emitted once when the loop begins.

AgentEnd

Emitted once when the loop exits, carrying the final message context.

Fields

messages: Arc<Vec<AgentMessage>>

TurnStart

Emitted at the beginning of each assistant turn.

TurnEnd

Emitted at the end of each turn with the assistant message and tool results.

Fields

assistant_message: AssistantMessage

tool_results: Vec<ToolResultMessage>

reason: TurnEndReason

snapshot: TurnSnapshot

Full context snapshot at the turn boundary for replay/auditing.

BeforeLlmCall

Emitted after context transform, before the LLM streaming call. Allows plugins to observe/log the final prompt.

Fields

system_prompt: String

messages: Vec<LlmMessage>

model: ModelSpec

MessageStart

Emitted when a message begins streaming.

MessageUpdate

Emitted for each incremental delta during assistant streaming.

Fields

delta: AssistantMessageDelta

MessageEnd

Emitted when a message is complete.

Fields

message: AssistantMessage

ToolExecutionStart

Emitted when a tool call begins execution.

Fields

id: String

name: String

arguments: Value

ToolExecutionUpdate

Emitted for intermediate partial results from a streaming tool.

Fields

id: String

The tool call ID so observers can attribute concurrent updates.

name: String

The tool name (matches ToolExecutionStart.name, including any plugin namespace prefix) so observers can attribute concurrent updates without inspecting tool output content.

partial: AgentToolResult

The partial tool result payload.

ToolApprovalRequested

Emitted when a tool call is pending approval.

Fields

id: String

name: String

arguments: Value

ToolApprovalResolved

Emitted when a tool call approval decision is made.

Fields

id: String

name: String

approved: bool

ToolExecutionEnd

Emitted when a tool call completes.

Fields

id: String

name: String

The tool name (matches ToolExecutionStart.name, including any plugin namespace prefix) so observers can correlate end events with the tool that produced them.

result: AgentToolResult

is_error: bool

ContextCompacted

Emitted when context compaction drops messages.

Fields

report: CompactionReport

ModelFallback

Emitted when the agent falls back to a different model after exhausting retries on the current one.

Fields

from_model: ModelSpec

to_model: ModelSpec

ModelCycled

Emitted when the agent switches to a different model during a retry cycle.

Fields

old: ModelSpec

new: ModelSpec

reason: String

StateChanged

Emitted when session state delta is flushed (non-empty only). Fired immediately before TurnEnd.

Fields

delta: StateDelta

CacheAction

Emitted when context caching acts on a turn (write or read).

Fields

hint: CacheHint

prefix_tokens: usize

McpServerConnected

Emitted when an MCP server connects successfully.

Fields

server_name: String

McpServerDisconnected

Emitted when an MCP server disconnects.

Fields

server_name: String

reason: String

McpToolsDiscovered

Emitted when tools are discovered from an MCP server.

Fields

server_name: String

tool_count: usize

McpToolCallStarted

Emitted when an MCP tool call begins execution.

Fields

server_name: String

tool_name: String

McpToolCallCompleted

Emitted when an MCP tool call completes.

Fields

server_name: String

tool_name: String

is_error: bool

TransferInitiated

Emitted when a tool signals a transfer to another agent.

Contains the enriched TransferSignal with conversation history. Emitted immediately before the TurnEnd event with TurnEndReason::Transfer.

Fields

signal: TransferSignal

Custom(Emission)

A custom event emitted via Agent::emit.

Trait Implementations

impl Clone for AgentEvent

fn clone(&self) -> AgentEvent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentEvent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentEvent

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentEvent

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.