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 via continue_with and tokio-native event streaming via run_tokio_stream.

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 switch_model(&self, model_id: &str) -> Result<()>

Switch the model used for future LLM calls.

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

Returns

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

pub fn switch_to_model(&self, model: &Model) -> 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.

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 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 [AgentLoop] 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 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??;