Struct Agent 

pub struct Agent { /* private fields */ }

Stateful wrapper around agent_loop with conversation state, cancellation, event subscription, and message queue management.

Implementations

impl Agent

pub fn new( provider: Box<dyn Provider>, tools: Vec<Box<dyn Tool>>, model: String, system: Option<String>, config: AgentLoopConfig, hooks: Box<dyn AgentHooks>, ) -> Self

Create a new Agent with the given provider, tools, model, and hooks.

pub async fn prompt( &mut self, text: impl Into<String>, ) -> Result<Vec<AgentMessage>, AgentError>

Send a user message and run the agent loop.

Resets the cancellation state if the agent was previously aborted, allowing a fresh conversation turn.

pub async fn prompt_with_content( &mut self, content: Vec<InputContent>, ) -> Result<Vec<AgentMessage>, AgentError>

Send a user message with arbitrary content (text + images) and run the agent loop.

pub async fn continue_( &mut self, text: impl Into<String>, ) -> Result<Vec<AgentMessage>, AgentError>

Continue the conversation with an additional user message.

Requires the last context message to be a user message or tool result.

pub fn abort(&self)

Cancel the current operation.

Equivalent to the first Ctrl+C. The running prompt or continue_ call will return AgentError::Cancelled.

pub fn add_tool(&mut self, tool: Box<dyn Tool>)

Add an additional tool to the agent’s tool set.

pub fn model(&self) -> &str

Return the active model spec.

pub fn set_model(&mut self, model: String)

Change the model used by subsequent provider requests.

pub fn provider(&self) -> &dyn Provider

Return the underlying provider metadata.

pub fn thinking_config(&self) -> ThinkingConfig

Return the thinking configuration used by subsequent provider requests.

pub fn set_thinking_config(&mut self, thinking: Option<ThinkingConfig>)

Change the thinking configuration used by subsequent provider requests.

pub fn set_max_tokens(&mut self, max_tokens: Option<u64>)

Change the maximum output tokens used by subsequent provider requests.

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

Set the initial conversation messages (for session resume).

Must be called before prompt or continue_. Replaces any existing messages in the agent’s internal buffer.

pub fn inject_message(&mut self, message: AgentMessage)

Inject a single message into the conversation buffer.

Used after compaction to insert a CompactionSummary so subsequent provider calls include the summary in their context window.

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

Replace the entire conversation buffer.

Used after compaction to install [summary, ...kept] so subsequent provider requests no longer carry the compacted messages.

pub fn emit_event(&self, event: AgentEvent)

Emit an AgentEvent to all subscribers outside of the agent loop.

Used by callers (e.g. harness) to surface lifecycle events that occur between loop invocations, such as compaction start/end.

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

Snapshot the current conversation buffer.

The harness uses this after a turn (and any subsequent compaction) to compute the next turn_offset and return the post-compaction message list to callers.

pub fn subscribe(&mut self, callback: Box<dyn Fn(&AgentEvent) + Send + Sync>)

Register an event subscriber that receives all AgentEvents.

pub fn cancel_token(&self) -> CancellationToken

Return a clonable cancellation token for external cancellation.

Cancelling this token cancels the currently running loop operation.

pub fn control_handle(&self) -> AgentControl

Return a clonable handle for cancellation and message queues.

pub fn steer(&self, message: String)

Add a steering message to be delivered before the next provider request.

Steering messages are high-priority and delivered after the current turn’s tool calls complete but before the next provider request.

pub fn follow_up(&self, message: String)

Add a follow-up message to be delivered when the agent would otherwise stop.

Follow-up messages are only delivered when the agent has no tool calls pending and no steering messages queued.

pub fn reset_cancel_if_cancelled(&mut self)

Reset cancellation state before handing out a control handle for a new turn.