Struct AgentHandle 

pub struct AgentHandle { /* private fields */ }

Agent execution handle returned by AgentSupervisor::spawn().

Wraps Arc<Agent> with lifecycle state management. Thread-safe: status tracked via atomic, cancel via shared flag.

Implementations

impl AgentHandle

pub fn agent_id(&self) -> &str

Agent identifier.

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

Parent agent ID (for delegation lineage).

pub fn created_at_ms(&self) -> u64

Creation timestamp (ms since epoch).

pub fn metrics(&self) -> MetricsSnapshot

Current metrics snapshot.

pub fn is_running(&self) -> bool

Whether the agent is currently running.

pub fn status(&self) -> AgentStatus

Current lifecycle status.

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

Run the agent with a prompt.

Transitions Created/Suspended → Running → Created (on success) or Failed (on error).

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

Continue the conversation with a follow-up prompt.

Equivalent to run() — the underlying agent maintains conversation history.

pub fn cancel(&self)

Request cancellation of the current run.

pub async fn suspend(&self) -> SdkResult<AgentSnapshot>

Suspend the agent and create a checkpoint snapshot.

Transitions Created/Running → Suspended.

pub fn terminate(&self) -> SdkResult<()>

Terminate the agent permanently (terminal state).

pub fn snapshot(&self) -> SdkResult<AgentSnapshot>

Take a snapshot without changing state.

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

Switch model mid-conversation.

The new provider is re-credentialed via the resolver; the old api_key parameter was removed in 0.55.0 (issues #39/#40).

pub fn set_system_prompt(&self, prompt: String)

Update system prompt for future runs.

pub fn add_tool(&self, tool: impl AgentTool + 'static)

Register a tool at runtime.

pub fn routing(&self) -> &RoutingControl

Get the runtime routing control for this agent.

Allows dynamic enabling/disabling of routing, model exclusion, and fallback model management.

pub fn disable_routing(&self)

Convenience: disable routing.

pub fn enable_routing(&self)

Convenience: enable routing.

pub fn exclude_route_model(&self, model_id: &str)

Convenience: exclude a model from routing.

Trait Implementations

impl Clone for AgentHandle

fn clone(&self) -> AgentHandle

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentHandle

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

Formats the value using the given formatter.