Struct Agent 

pub struct Agent { /* private fields */ }

Stateful wrapper around the agent loop.

Implementations

impl Agent

pub fn new(options: AgentOptions) -> Self

Creates an agent; a leading system message is added for the prompt and tools unless the transcript already starts with one.

pub fn subscribe(&self, listener: Arc<dyn AgentListener>) -> Subscription

Registers a listener; dropping the returned Subscription removes it.

pub fn state(&self) -> AgentState

Snapshot of the state.

pub fn with_state<R>(&self, f: impl FnOnce(&AgentState) -> R) -> R

Runs f on the state under the lock (avoids cloning the transcript).

pub fn messages(&self) -> Vec<AgentMessage>

Copy of the transcript.

pub fn set_messages(&self, messages: Vec<AgentMessage>)

Replaces the transcript (copy-on-set).

pub fn append_message(&self, message: AgentMessage)

Appends one message to the transcript.

pub fn replace_last_message(&self, message: AgentMessage)

Replaces the last transcript message (in-place message_end replacement).

pub fn set_tools(&self, tools: Vec<Arc<dyn AgentTool>>)

Replaces the executable tools.

pub fn model(&self) -> Model

Current model.

pub fn set_model(&self, model: Model)

Sets the model of the next request.

pub fn thinking_level(&self) -> ThinkingLevel

Current thinking level.

pub fn set_thinking_level(&self, level: ThinkingLevel)

Sets the thinking level of the next request.

pub fn system_prompt(&self) -> String

S t a t e . s y s t e m P r o m p t.

pub fn is_streaming(&self) -> bool

Whether a run is active.

pub fn set_hooks(&self, hooks: AgentHooks)

Replaces the hooks.

pub fn update_stream_options(&self, f: impl FnOnce(&mut StreamOptions))

Updates the base stream options (sessionId, transport, budgets, …).

pub fn set_tool_execution(&self, mode: ToolExecution)

Sets the batch scheduling.

pub fn steering_mode(&self) -> QueueMode

Steering drain mode.

pub fn set_steering_mode(&self, mode: QueueMode)

Sets the steering drain mode.

pub fn follow_up_mode(&self) -> QueueMode

Follow-up drain mode.

pub fn set_follow_up_mode(&self, mode: QueueMode)

Sets the follow-up drain mode.

pub fn steer(&self, message: AgentMessage)

Queues a message injected after the current turn.

pub fn follow_up(&self, message: AgentMessage)

Queues a message delivered when the agent would otherwise stop.

pub fn update_queue<R>( &self, steering: bool, edit: impl FnOnce(&mut Vec<AgentMessage>) -> R, ) -> R

Edits the steering (steering = true) or follow-up queue in place, atomically with respect to draining (single-item queue edits).

pub fn clear_steering_queue(&self)

Clears the steering queue.

pub fn clear_follow_up_queue(&self)

Clears the follow-up queue.

pub fn clear_all_queues(&self)

Clears both queues.

pub fn has_queued_messages(&self) -> bool

Whether either queue has messages.

pub fn peek_queued_messages(&self) -> Vec<AgentMessage>

Messages the next turn would take, without consuming them.

pub fn steering_queue(&self) -> Vec<AgentMessage>

Every queued steering message (in order).

pub fn follow_up_queue(&self) -> Vec<AgentMessage>

Every queued follow-up message (in order).

pub fn signal(&self) -> Option<CancellationToken>

Abort signal of the active run.

pub fn abort(&self)

Aborts the active run, if any.

pub fn recover_orphaned_run(&self)

Clears a run orphaned by a crashed driver task (X-PANIC): a panic’s unwind dropped the run future before finish_run ran, leaving the run “active” and the session forever busy. Discards streaming state and pending tool calls; the transcript is kept — callers rebuild from the session log. No-op when no run is active.

pub async fn wait_for_idle(&self)

Resolves once no run is active and every agent_end listener has returned.

pub fn reset(&self) -> Result<(), AgentError>

Clears the transcript (keeping the replayed system baseline) and both queues.

Errors

AgentError::ResetWhileBusy while a run is active.

pub async fn prompt_text( &self, text: impl Into<String>, images: Vec<ImageContent>, ) -> Result<(), AgentError>

A user message with text and images.

Errors

AgentError::PromptWhileBusy while a run is active.

pub async fn prompt( &self, messages: Vec<AgentMessage>, ) -> Result<(), AgentError>

Starts a run with messages; resolves when the run is idle.

Errors

AgentError::PromptWhileBusy while a run is active.

pub async fn continue_run(&self) -> Result<(), AgentError>

Continues from the transcript; after an assistant message the queues are drained instead.

Errors

AgentError::ContinueWhileBusy, AgentError::NoMessages, AgentError::CannotContinue.

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Agent

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

Formats the value using the given formatter.