Struct Agent 

pub struct Agent { /* private fields */ }

The primary concrete agent: pairs a chat client with instructions, default options, tools, context providers, and middleware.

Cheaply cloneable (the client, context providers, and middleware are shared via Arc), which is what makes Agent::as_tool possible.

Implementations

impl Agent

pub fn builder(client: impl ChatClient + 'static) -> AgentBuilder

Start building an agent from a chat client. The client is automatically wrapped with FunctionInvokingChatClient so local tools are executed.

pub fn instructions(&self) -> Option<&str>

The agent’s default instructions.

pub async fn run_stream( &self, messages: impl IntoMessages, session: Option<AgentSession>, options: Option<AgentRunOptions>, ) -> Result<AgentRunStream>

Run and stream incremental updates — an ergonomic wrapper over the object-safe SupportsAgentRun::run_stream trait method (the real streaming implementation), accepting impl IntoMessages.

The session’s context providers (including any history provider) are driven when the stream completes; because provider storage is shared via Arc, updates are visible on the original session once the returned stream is fully consumed. Pass per-run AgentRunOptions to override the agent’s defaults for this call only.

pub async fn run_stream_once( &self, messages: impl IntoMessages, ) -> Result<AgentRunStream>

Ergonomic streaming run with a fresh session and no per-run options (mirrors Agent::run_once).

pub async fn run_once( &self, messages: impl IntoMessages, ) -> Result<AgentResponse>

Ergonomic run without an explicit session.

impl Agent

pub fn description(&self) -> Option<&str>

The agent description, if any.

pub fn create_session_with_service_id( &self, service_session_id: impl Into<String>, ) -> AgentSession

Create a new service-managed session bound to service_session_id, mirroring Python’s get_new_thread(service_thread_id=…) (_agents.py:1078-1082).

The agent’s own context providers are NOT copied onto the returned session; see the note on Agent::create_session.

pub fn session_from_dict(&self, state: &Value) -> Result<AgentSession>

Reconstruct a session from state (as produced by AgentSession::to_dict), mirroring Python’s BaseAgent.deserialize_thread (_agents.py:378-392).

Conversation history is not part of this state (see AgentSession::to_dict); reattach a crate::history::HistoryProvider (e.g. via crate::history::InMemoryHistoryProvider::from_dict) to context_providers separately when restoring a conversation. The agent’s own context providers are NOT copied onto the returned session; see the note on Agent::create_session.

pub fn as_tool(&self, options: AsToolOptions) -> ToolDefinition

Wrap this agent as a ToolDefinition usable by another agent’s .tool(...). Mirrors Python BaseAgent.as_tool.

The tool takes a single string argument (default name "task") and, on each call, runs this agent and returns the response text. By default each call runs statelessly (a fresh session per call); with AsToolOptions::propagate_session the parent agent’s session is forwarded instead (as an AgentSession::child). Set AsToolOptions::stream_callback to observe the sub-agent’s streamed updates, and AsToolOptions::approval_mode to gate calls behind human approval.

A run that ends with pending user-input requests (function-approval requests from the sub-agent’s own tools) cannot be satisfied from within a tool call and surfaces as a tool error — mirroring upstream’s UserInputRequiredException.

let research_tool = researcher.as_tool(AsToolOptions::new().name("research"));
let coordinator = Agent::builder(coordinator_client)
    .tool(research_tool)
    .build();

Trait Implementations

impl Clone for Agent

fn clone(&self) -> Agent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl SupportsAgentRun for Agent

fn run<'life0, 'life1, 'async_trait>( &'life0 self, messages: Vec<Message>, session: Option<&'life1 mut AgentSession>, ) -> Pin<Box<dyn Future<Output = Result<AgentResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run the agent to completion.

fn run_with_options<'life0, 'life1, 'async_trait>( &'life0 self, messages: Vec<Message>, session: Option<&'life1 mut AgentSession>, options: AgentRunOptions, ) -> Pin<Box<dyn Future<Output = Result<AgentResponse>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run the agent to completion, applying per-run AgentRunOptions over the agent’s build-time defaults.

fn run_stream<'life0, 'async_trait>( &'life0 self, messages: Vec<Message>, session: Option<AgentSession>, options: Option<AgentRunOptions>, ) -> Pin<Box<dyn Future<Output = Result<AgentRunStream>> + Send + 'async_trait>>

where Self: 'async_trait, 'life0: 'async_trait,

Run the agent and stream incremental AgentResponseUpdates.

fn id(&self) -> &str

A stable identifier for this agent.

fn name(&self) -> Option<&str>

The optional human-readable name.

fn create_session(&self) -> AgentSession

A fresh session for a new conversation.

fn display_name(&self) -> String

The display name: name if set, else id.