Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    Token(String),
    ThinkStart,
    ThinkEnd {
        prompt_tokens: usize,
        completion_tokens: usize,
    },
    ToolCall {
        name: String,
        args: Value,
    },
    ToolResult {
        name: String,
        output: String,
    },
    ToolError {
        name: String,
        error: String,
    },
    PlanGenerated {
        steps: Vec<String>,
    },
    StepStart {
        step_index: usize,
        description: String,
    },
    StepEnd {
        step_index: usize,
        success: bool,
    },
    GuardTriggered {
        guard: String,
        blocked: bool,
    },
    MemoryRecalled {
        count: usize,
    },
    ContextCompressed {
        before_count: usize,
        after_count: usize,
        before_tokens: usize,
        after_tokens: usize,
    },
    HandoffStart {
        from: String,
        to: String,
    },
    HandoffEnd {
        to: String,
    },
    ReflectionStart {
        iteration: usize,
    },
    ReflectionEnd {
        iteration: usize,
        score: f64,
        passed: bool,
    },
    CritiqueGenerated {
        score: f64,
        passed: bool,
        feedback: String,
    },
    Refining {
        iteration: usize,
    },
    Chart {
        spec: Value,
    },
    Error {
        source: String,
        message: String,
    },
    FinalAnswer(String),
    Cancelled,
}

Events produced during Agent execution

Cover each phase of the Agent lifecycle for progress bars, logs, UI updates, etc.

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.

Token(String)

LLM is generating a token (streaming)

ThinkStart

LLM reasoning started

ThinkEnd

LLM reasoning ended

Fields

prompt_tokens: usize

Number of prompt tokens consumed

completion_tokens: usize

Number of completion tokens consumed

ToolCall

Preparing to invoke a tool

Fields

name: String

Tool name

args: Value

Tool arguments (JSON format)

ToolResult

Tool execution completed

Fields

name: String

Tool name

output: String

Tool execution result (string format)

ToolError

Tool execution error

Fields

name: String

Tool name

error: String

Error message

PlanGenerated

Plan-and-Execute engine generated a plan

Fields

steps: Vec<String>

List of plan step descriptions

StepStart

Plan step execution started

Fields

step_index: usize

Step index (0-based)

description: String

Step description

StepEnd

Plan step execution ended

Fields

step_index: usize

Step index (0-based)

success: bool

Whether the step executed successfully

GuardTriggered

A guard was triggered

Fields

guard: String

Guard name

blocked: bool

Whether the action was blocked

MemoryRecalled

Long-term memory was recalled

Fields

count: usize

Number of recalled memory entries

ContextCompressed

Context was auto-compressed to fit within token limits

Fields

before_count: usize

Message count before compression

after_count: usize

Message count after compression

before_tokens: usize

Estimated token count before compression

after_tokens: usize

Estimated token count after compression

HandoffStart

Agent-to-agent handoff started

Fields

from: String

Source agent name

to: String

Target agent name

HandoffEnd

Agent-to-agent handoff ended

Fields

to: String

Target agent name

ReflectionStart

Reflection iteration started

Fields

iteration: usize

Current iteration number (starting from 1)

ReflectionEnd

Reflection iteration ended

Fields

iteration: usize

Iteration number (starting from 1)

score: f64

Reflection score (0.0-1.0)

passed: bool

Whether reflection passed

CritiqueGenerated

Evaluator produced a critique

Fields

score: f64

Critique score (0.0-1.0)

passed: bool

Whether the evaluation passed

feedback: String

Evaluation feedback text

Refining

Refining answer based on reflection

Fields

iteration: usize

Current iteration number (starting from 1)

Chart

Chart generation (vega-lite JSON spec)

Fields

spec: Value

Error

Generic Agent error (non-tool errors, e.g. LLM call failure, guard rejection, etc.)

Fields

source: String

Error source (e.g. “llm”, “guard”, “config”)

message: String

Error message

FinalAnswer(String)

Final answer

Cancelled

Cancelled

Implementations

impl AgentEvent

pub fn prompt_tokens(&self) -> Option<usize>

Return prompt token count for ThinkEnd.

pub fn completion_tokens(&self) -> Option<usize>

Return completion token count for ThinkEnd.

pub fn total_tokens(&self) -> Option<usize>

Return total token usage for ThinkEnd.

pub fn tokens_used(&self) -> Option<usize>

Compatibility helper for older call sites that tracked a single token count.

pub fn phase(&self) -> AgentPhase

Return the lifecycle phase of this event

Used for frontend phase-routed rendering, state machine derivation, and similar scenarios.

Example

use echo_core::agent::{AgentEvent, AgentPhase};

let event = AgentEvent::ThinkStart;
assert_eq!(event.phase(), AgentPhase::Thinking);

let event = AgentEvent::FinalAnswer("done".into());
assert_eq!(event.phase(), AgentPhase::Terminal);

pub fn is_checkpoint(&self) -> bool

Whether this is a persistable snapshot point (phase boundary event)

When these events occur, the Agent state is at a “stable point” — no in-flight LLM calls or tool executions, suitable for checkpoint save, resume-from-checkpoint, or Time Travel debugging.

Example

use echo_core::agent::AgentEvent;

assert!(AgentEvent::ThinkEnd { prompt_tokens: 100, completion_tokens: 50 }.is_checkpoint());
assert!(AgentEvent::FinalAnswer("done".into()).is_checkpoint());
assert!(!AgentEvent::Token("hello".into()).is_checkpoint());

Trait Implementations

impl Debug for AgentEvent

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

Formats the value using the given formatter.