Enum AgentEvent 

#[non_exhaustive]
pub enum AgentEvent {
    RunStarted {
        session_id: SessionId,
        prompt: ContentInput,
    },
    RunCompleted {
        session_id: SessionId,
        result: String,
        structured_output: Option<Value>,
        extraction_required: bool,
        usage: Usage,
        terminal_cause_kind: Option<TurnTerminalCauseKind>,
    },
    ExtractionSucceeded {
        session_id: SessionId,
        structured_output: Value,
        schema_warnings: Option<Vec<SchemaWarning>>,
    },
    ExtractionFailed {
        session_id: SessionId,
        last_output: String,
        attempts: u32,
        reason: String,
    },
    RunFailed {
        session_id: SessionId,
        error_class: AgentErrorClass,
        error: String,
        terminal_cause_kind: Option<TurnTerminalCauseKind>,
        error_report: Option<AgentErrorReport>,
    },
    HookStarted {
        hook_id: HookId,
        point: HookPoint,
    },
    HookCompleted {
        hook_id: HookId,
        point: HookPoint,
        duration_ms: u64,
    },
    HookFailed {
        hook_id: HookId,
        point: HookPoint,
        error: String,
    },
    HookDenied {
        hook_id: HookId,
        point: HookPoint,
        reason_code: HookReasonCode,
        message: String,
        payload: Option<Value>,
    },
    TurnStarted {
        turn_number: u32,
    },
    ReasoningDelta {
        delta: String,
    },
    ReasoningComplete {
        content: String,
    },
    TextDelta {
        delta: String,
    },
    TextComplete {
        content: String,
    },
    ServerToolContent {
        id: Option<String>,
        name: String,
        content: Value,
    },
    AssistantImageAppended {
        image: AssistantImageEvent,
    },
    ToolCallRequested {
        id: String,
        name: String,
        args: ToolCallArguments,
    },
    ToolResultReceived {
        id: String,
        name: String,
        content: Vec<ContentBlock>,
        is_error: bool,
    },
    TurnCompleted {
        stop_reason: StopReason,
        usage: Usage,
    },
    ToolExecutionStarted {
        id: String,
        name: String,
    },
    ToolExecutionCompleted {
        id: String,
        name: String,
        result: String,
        content: Vec<ContentBlock>,
        is_error: bool,
        duration_ms: u64,
    },
    ToolExecutionTimedOut {
        id: String,
        name: String,
        timeout_ms: u64,
    },
    CompactionStarted {
        input_tokens: u64,
        estimated_history_tokens: u64,
        message_count: usize,
    },
    CompactionCompleted {
        summary_tokens: u64,
        messages_before: usize,
        messages_after: usize,
    },
    CompactionFailed {
        error: String,
    },
    BudgetWarning {
        budget_type: BudgetType,
        used: u64,
        limit: u64,
        percent: f32,
    },
    Retrying {
        attempt: u32,
        max_attempts: u32,
        error: String,
        delay_ms: u64,
        retry: Option<LlmRetrySchedule>,
    },
    SkillsResolved {
        skills: Vec<SkillKey>,
        injection_bytes: usize,
    },
    SkillResolutionFailed {
        skill_key: Option<SkillKey>,
        reason: SkillResolutionFailureReason,
        reference: String,
        error: String,
    },
    InteractionComplete {
        interaction_id: InteractionId,
        result: String,
        structured_output: Option<Value>,
    },
    InteractionCallbackPending {
        interaction_id: InteractionId,
        tool_name: String,
        args: Value,
    },
    InteractionFailed {
        interaction_id: InteractionId,
        error: String,
    },
    StreamTruncated {
        reason: String,
    },
    ToolConfigChanged {
        payload: ToolConfigChangedPayload,
    },
    BackgroundJobCompleted {
        job_id: String,
        display_name: String,
        legacy_status: Option<String>,
        terminal_status: BackgroundJobTerminalStatus,
        detail: String,
    },
}

Events emitted during agent execution

These events form the streaming API for consumers.

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.

RunStarted

Agent run started

Fields

session_id: SessionId

prompt: ContentInput

RunCompleted

Agent run completed successfully

Fields

session_id: SessionId

result: String

structured_output: Option<Value>

Structured output from the completed run, when schema extraction produced a typed value.

extraction_required: bool

Whether a separate extraction terminal event is expected after this completed main run.

usage: Usage

terminal_cause_kind: Option<TurnTerminalCauseKind>

ExtractionSucceeded

Structured-output extraction succeeded after a completed main run.

Fields

session_id: SessionId

structured_output: Value

schema_warnings: Option<Vec<SchemaWarning>>

ExtractionFailed

Structured-output extraction failed after a completed main run.

Fields

session_id: SessionId

last_output: String

attempts: u32

reason: String

RunFailed

Agent run failed

Fields

session_id: SessionId

error_class: AgentErrorClass

error: String

Display projection of error_report.message.

terminal_cause_kind: Option<TurnTerminalCauseKind>

error_report: Option<AgentErrorReport>

HookStarted

Hook invocation started.

Fields

hook_id: HookId

point: HookPoint

HookCompleted

Hook invocation completed.

Fields

hook_id: HookId

point: HookPoint

duration_ms: u64

HookFailed

Hook invocation failed.

Fields

hook_id: HookId

point: HookPoint

error: String

HookDenied

Hook denied an action.

Fields

hook_id: HookId

point: HookPoint

reason_code: HookReasonCode

message: String

payload: Option<Value>

TurnStarted

New turn started (calling LLM)

Fields

turn_number: u32

ReasoningDelta

Streaming reasoning/thinking from the model

Fields

delta: String

ReasoningComplete

Reasoning/thinking complete for this block

Fields

content: String

TextDelta

Streaming text from the model

Fields

delta: String

TextComplete

Text generation complete for this turn

Fields

content: String

ServerToolContent

Provider-executed tool content surfaced during a model turn.

Fields

id: Option<String>

name: String

content: Value

AssistantImageAppended

Canonical assistant image block appended to transcript history.

Fields

image: AssistantImageEvent

ToolCallRequested

Model requested a tool call

Fields

id: String

name: String

args: ToolCallArguments

ToolResultReceived

Tool result received (injected into conversation)

Fields

id: String

name: String

content: Vec<ContentBlock>

is_error: bool

TurnCompleted

Turn completed

Fields

stop_reason: StopReason

usage: Usage

ToolExecutionStarted

Starting tool execution

Fields

id: String

name: String

ToolExecutionCompleted

Tool execution completed

Fields

id: String

name: String

result: String

Legacy text projection retained for existing event consumers.

content: Vec<ContentBlock>

Canonical typed tool-result content.

is_error: bool

duration_ms: u64

ToolExecutionTimedOut

Tool execution timed out

Fields

id: String

name: String

timeout_ms: u64

CompactionStarted

Context compaction started.

Fields

input_tokens: u64

Input tokens from the last LLM call that triggered compaction.

estimated_history_tokens: u64

Estimated total history tokens before compaction.

message_count: usize

Number of messages before compaction.

CompactionCompleted

Context compaction completed successfully.

Fields

summary_tokens: u64

Tokens consumed by the summary.

messages_before: usize

Messages before compaction.

messages_after: usize

Messages after compaction.

CompactionFailed

Context compaction failed (non-fatal — agent continues with uncompacted history).

Fields

error: String

BudgetWarning

Budget warning (approaching limits)

Fields

budget_type: BudgetType

used: u64

limit: u64

percent: f32

Retrying

Retrying after error

Fields

attempt: u32

max_attempts: u32

error: String

delay_ms: u64

retry: Option<LlmRetrySchedule>

SkillsResolved

Skills resolved for this turn.

Fields

skills: Vec<SkillKey>

injection_bytes: usize

SkillResolutionFailed

A skill reference could not be resolved.

Fields

skill_key: Option<SkillKey>

Canonical structured skill identity/reference, when resolution had one.

reason: SkillResolutionFailureReason

Structured reason for the failure. Legacy payloads deserialize as unknown.

reference: String

Legacy display mirror for consumers still reading string references.

error: String

Legacy display mirror for consumers still reading string errors.

InteractionComplete

An interaction completed successfully (terminal event for tap subscribers).

Fields

interaction_id: InteractionId

result: String

structured_output: Option<Value>

Structured output from the completed interaction, when schema extraction produced a typed value.

InteractionCallbackPending

An interaction reached an external callback boundary and is waiting for tool results before the session can continue.

Fields

interaction_id: InteractionId

tool_name: String

args: Value

InteractionFailed

An interaction failed (terminal event for tap subscribers).

Fields

interaction_id: InteractionId

error: String

StreamTruncated

Some streaming events were dropped due to channel backpressure. Best-effort marker — the terminal event is authoritative.

Fields

reason: String

ToolConfigChanged

Live tool configuration changed for this session.

Fields

payload: ToolConfigChangedPayload

BackgroundJobCompleted

A background shell job completed (or failed/cancelled/timed out).

Fields

job_id: String

display_name: String

legacy_status: Option<String>

Legacy display mirror for consumers still rendering string status.

terminal_status: BackgroundJobTerminalStatus

detail: String

Implementations

impl AgentEvent

pub fn background_job_completed( job_id: impl Into<String>, display_name: impl Into<String>, terminal_status: BackgroundJobTerminalStatus, detail: impl Into<String>, ) -> Self

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 JsonSchema for AgentEvent

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

fn json_schema(generator: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

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.