Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    AgentStart,
    AgentEnd {
        messages: Vec<Message>,
    },
    TurnStart,
    TurnEnd {
        message: Message,
        tool_results: Vec<ToolResult>,
    },
    MessageStart {
        message: Message,
    },
    MessageDelta {
        delta: String,
        tokens_generated: u32,
        tokens_per_sec: f64,
    },
    MessageEnd {
        message: Message,
    },
    GenerationStats {
        tokens_generated: u32,
        prompt_tokens: u32,
        tokens_per_sec: f64,
        time_to_first_token_ms: f64,
        generation_time_ms: f64,
    },
    ToolExecStart {
        tool_call_id: String,
        tool_name: String,
        args: Value,
    },
    ToolExecUpdate {
        tool_call_id: String,
        tool_name: String,
        partial: String,
    },
    ToolExecEnd {
        tool_call_id: String,
        tool_name: String,
        result: ToolResult,
    },
    ToolDenied {
        tool_call_id: String,
        tool_name: String,
        reason: String,
    },
    ContextBudget {
        used_tokens: u32,
        max_tokens: u32,
        messages_in_context: u32,
        messages_pruned: u32,
    },
    Warning {
        message: String,
    },
    Error {
        message: String,
    },
}

Events emitted by the agent loop. Mirrors pi-agent-core’s event system for UI reactivity.

This enum is #[non_exhaustive]: match it with a wildcard arm, as new event variants may be added in a minor release.

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

Agent begins processing a prompt.

AgentEnd

Agent finished all processing.

Fields

messages: Vec<Message>

All messages produced during this prompt() call.

TurnStart

A new turn begins (one LLM call + any tool executions).

TurnEnd

A turn completed.

Fields

message: Message

The assistant message produced by the turn.

tool_results: Vec<ToolResult>

Results of any tools the turn executed.

MessageStart

A message was added (user, assistant, or tool_result).

Fields

message: Message

The message that was added.

MessageDelta

Streaming delta for the current assistant message.

Fields

delta: String

The new token/chunk of text.

tokens_generated: u32

Tokens generated so far in this response.

tokens_per_sec: f64

Current generation speed.

MessageEnd

A message is complete.

Fields

message: Message

The completed message.

GenerationStats

Timing and token statistics for one completed LLM generation.

Emission guarantee. Exactly one GenerationStats is emitted for each LLM iteration that runs to completion within a single prompt() call - no more, no less - and always before that turn’s MessageEnd/TurnEnd and before the run’s closing AgentEnd. When tools fire, a prompt() spans several iterations; summing the tokens_generated / prompt_tokens of every GenerationStats in the run therefore yields the exact per-run totals, with no gaps and no double counting. A generation that is aborted or errors before completing produces no result and so emits no GenerationStats (the internal summarization pass likewise does not emit one). Consumers metering usage can rely on this contract; it is pinned by tests.

Fields

tokens_generated: u32

Tokens generated in the response.

prompt_tokens: u32

Tokens in the formatted prompt.

tokens_per_sec: f64

Average generation speed in tokens per second.

time_to_first_token_ms: f64

Time to the first emitted token, in milliseconds.

generation_time_ms: f64

Total generation time, in milliseconds.

ToolExecStart

A tool execution started.

Fields

tool_call_id: String

Id of the tool call being executed.

tool_name: String

Name of the tool being executed.

args: Value

Arguments passed to the tool.

ToolExecUpdate

Streaming progress from a tool execution.

Fields

tool_call_id: String

Id of the tool call reporting progress.

tool_name: String

Name of the tool reporting progress.

partial: String

Partial output emitted so far.

ToolExecEnd

A tool execution completed.

Fields

tool_call_id: String

Id of the completed tool call.

tool_name: String

Name of the completed tool.

result: ToolResult

The tool’s result.

ToolDenied

A tool call was refused by the approval hook and never executed.

Distinct from a ToolExecEnd carrying an error result: that signals a tool that ran and failed, whereas this signals a call that was blocked before execution. The same reason is also appended to the conversation as an error tool result so the model can adapt.

Fields

tool_call_id: String

Id of the denied tool call.

tool_name: String

Name of the denied tool.

reason: String

Human-readable reason the call was refused.

ContextBudget

Context budget info after formatting.

Fields

used_tokens: u32

Tokens used by the prepared prompt.

max_tokens: u32

Maximum context tokens available.

messages_in_context: u32

Number of messages kept in the prompt.

messages_pruned: u32

Number of messages pruned to fit.

Warning

Non-fatal warning during processing.

Fields

message: String

Human-readable warning text.

Error

Fatal error that stopped processing.

Fields

message: String

Human-readable error text.

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.