Struct Agent 

pub struct Agent { /* private fields */ }

Agent runtime.

Manages provider, tool registry, state, and compaction, providing an agentic loop for prompt execution, model switching, tool calls, and fallback.

Supports session continuation, tokio-native event streaming, and deferred model switching (changes are queued while a loop is running and applied after it completes).

Implementations

impl Agent

pub fn new( provider: Arc<dyn Provider>, config: AgentConfig, tools: Arc<ToolRegistry>, ) -> Self

Create a new agent with the given provider, config, and tool registry.

Uses the global oxi_ai::get_provider() / resolve_model_from_id() for model switching. For isolated instances, use new_with_resolver.

pub fn new_with_resolver( provider: Arc<dyn Provider>, config: AgentConfig, tools: Arc<ToolRegistry>, resolver: Arc<dyn ProviderResolver>, ) -> Self

Create an agent with a custom provider/model resolver.

This is the preferred constructor for SDK usage where provider and model registries must be isolated from global state.

pub fn new_empty(provider: Arc<dyn Provider>, config: AgentConfig) -> Self

Create an agent with an empty tool registry.

pub fn model_id(&self) -> String

Get the current model ID

pub fn get_config(&self) -> AgentConfig

Get the agent configuration (full clone)

pub fn resolver(&self) -> &Arc<dyn ProviderResolver>

Get a reference to the provider resolver.

pub fn switch_model( &self, model_id: &str, api_key: Option<String>, ) -> Result<()>

Switch the model used for future LLM calls.

Switch model mid-conversation.

If the agent is currently running, the switch is deferred: the new model and provider are stored in pending_model_switch and applied automatically when the current loop finishes. This ensures the running loop completes with a consistent provider/model without interruption.

If the agent is idle, the switch takes effect immediately.

If the new model uses a different provider API, the conversation history is automatically transformed for cross-provider compatibility (e.g. thinking blocks are converted to <thinking> tags).

Arguments

• model_id - New model ID in provider/model format
• api_key - Optional API key for the new provider (will be passed to StreamOptions)

Returns

Ok(()) on success, or an error if the model/provider is unknown

pub fn switch_to_model( &self, model: &Model, api_key: Option<String>, ) -> Result<()>

Switch the model using a pre-resolved Model object.

This is useful when the caller has already looked up the model and optionally created the provider.

Like switch_model, if the agent is currently running, the switch is deferred until the current loop completes.

pub fn refresh_api_key(&self, api_key: Option<String>)

Refresh only the API key without changing model or provider. Useful when the user stores a key after the session was already created.

pub fn tools(&self) -> Arc<ToolRegistry>

Get a handle to the tool registry.

pub fn state(&self) -> AgentState

Get a snapshot of the current agent state.

pub fn update_state(&self, f: impl FnOnce(&mut AgentState))

Update agent state in-place. Used by compaction to replace messages.

pub fn reset(&self)

Reset agent state for a new conversation

pub fn add_tool<T: AgentTool + 'static>(&self, tool: T)

Register a tool that the agent can invoke during a run.

pub fn set_system_prompt(&self, prompt: String)

Update the system prompt for future interactions.

pub fn compaction_manager(&self) -> &CompactionManager

Get the compaction manager

pub async fn run(&self, prompt: String) -> Result<(Response, Vec<AgentEvent>)>

Run the agent with a prompt, collecting all events into a vector.

Convenience wrapper around run_with_channel that gathers every AgentEvent produced during the run.

pub async fn run_with_channel( &self, prompt: String, tx: Sender<AgentEvent>, ) -> Result<Response>

Run the agent, delivering events through the provided channel.

Delegates to the agent loop which implements the same 2-level agentic loop matching pi-mono’s architecture:

AgentLoop.run_messages()
  Outer loop (follow-up messages):
    Inner loop (tool calls + steering):
      1. Inject pending messages (steering)
      2. Compaction check
      3. Stream LLM response (with accumulated partial messages)
      4. Execute tool calls if any
      5. Emit turn_end
      6. Check shouldStopAfterTurn
      7. Poll steering messages
    Check follow-up messages
    Exit

pub fn set_hooks(&self, hooks: AgentHooks)

Set hooks for the agent loop.

pub fn cancel(&self)

Request cancellation of the current agent run.

Sets a shared cancel_flag that is propagated to the AgentLoop’s external_stop on every event AND polled every ~500ms by the streaming loop’s periodic check. This ensures cancellation is detected quickly even when the provider stream is completely hung (no events arriving).

pub fn reset_cancel(&self)

Reset the cancellation flag before starting a new run.

pub async fn run_streaming<F>( &self, prompt: String, on_event: F, ) -> Result<Response>

where F: FnMut(AgentEvent) + Send,

Run the agent, invoking on_event for each AgentEvent produced.

Blocking convenience wrapper suitable for callers that prefer a callback-based API over a channel.

pub fn export_state(&self) -> Result<Value>

Export the agent state as a JSON value.

The serialized state includes conversation messages, token counts, iteration progress, and stop reason. Use import_state to restore.

pub fn import_state(&self, value: Value) -> Result<()>

Import agent state from a JSON value.

Restores conversation history, token counts, and iteration progress. Typically used together with export_state for session persistence.

pub async fn continue_with( &self, prompt: String, ) -> Result<(Response, Vec<AgentEvent>)>

Continue the current session with a new prompt.

Unlike run(), which can be used on a fresh agent, continue_with preserves the existing conversation state and appends the new prompt. This enables multi-turn interactions within the same session.

pub async fn run_tokio_stream( &self, prompt: String, ) -> Result<(Receiver<AgentEvent>, JoinHandle<Result<Response>>)>

Run the agent with tokio-native event streaming.

Returns a tokio::sync::mpsc::Receiver for events and a JoinHandle for the response. This is the preferred API for async runtimes (WebSocket/SSE gateways, tokio-based servers).

Example

let (rx, handle) = agent.run_tokio_stream("Explain Rust".into()).await?;
while let Some(event) = rx.recv().await {
    println!("Event: {:?}", event.type_name());
}
let response = handle.await??;