pub struct AgentHandle<R: Runtime + 'static> { /* private fields */ }Expand description
Handle to a running agent.
Wraps the agent’s lifecycle: creation, chat, and shutdown.
Call shutdown() for a clean, error-reported shutdown.
If the handle is dropped without calling shutdown(), a best-effort
background shutdown is spawned via tokio::spawn — the Python agent
will be cleaned up, but errors are only logged, not returned.
Most methods take &self — interior mutability is used where needed
so multiple concurrent operations can share a single handle.
§Mutex choice
This type uses std::sync::Mutex rather than tokio::sync::Mutex
because every lock acquisition is a brief, synchronous operation (pointer
swap or clone) that never spans an .await point. For these
microsecond critical sections, std::sync::Mutex is both simpler and
lower-overhead than the async alternative.
Implementations§
Source§impl<R: Runtime> AgentHandle<R>
impl<R: Runtime> AgentHandle<R>
Sourcepub async fn new(
runtime: Arc<R>,
config: AgentConfig,
registry: Option<Arc<ToolRegistry>>,
hook_runner: Option<Arc<Hooks>>,
policy_handler: Option<Arc<dyn AskUserHandler>>,
) -> Result<Self, Error>
pub async fn new( runtime: Arc<R>, config: AgentConfig, registry: Option<Arc<ToolRegistry>>, hook_runner: Option<Arc<Hooks>>, policy_handler: Option<Arc<dyn AskUserHandler>>, ) -> Result<Self, Error>
Sourcepub async fn chat(
&self,
content: impl Into<Content>,
) -> Result<ChatResponseHandle, Error>
pub async fn chat( &self, content: impl Into<Content>, ) -> Result<ChatResponseHandle, Error>
Send a message and receive a streaming response.
Accepts any type that converts into Content: &str, String,
Image, Document,
Audio, Video, or a
Vec<ContentPrimitive> for multimodal input.
Automatically backs off on quota limits (HTTP 429).
§Errors
Returns a Error on chat failure (Python error, timeout, etc.).
Sourcepub async fn chat_text(
&self,
message: impl Into<Content>,
) -> Result<String, Error>
pub async fn chat_text( &self, message: impl Into<Content>, ) -> Result<String, Error>
Send a message and return the final text response.
This is a convenience wrapper around chat that drains
the streaming response into a single String. If tools were associated
with the agent at creation time, the Python runtime handles tool
execution automatically.
§Errors
Returns Error if the chat turn fails or stream errors occur.
Sourcepub fn conversation_id(&self) -> Option<String>
pub fn conversation_id(&self) -> Option<String>
Return the current conversation ID, if one has been set.
Returns a cloned String because the underlying value is behind a
Mutex (interior mutability for &self access).
Sourcepub fn set_conversation_id(&self, id: String)
pub fn set_conversation_id(&self, id: String)
Set the conversation ID (called when the SDK assigns one).
Takes &self rather than &mut self so the handle can be shared
across concurrent tasks.
Sourcepub fn is_started(&self) -> bool
pub fn is_started(&self) -> bool
Check whether the agent has been started and is not yet shut down.
Sourcepub const fn config(&self) -> &AgentConfig
pub const fn config(&self) -> &AgentConfig
Return a reference to the agent’s configuration.
Sourcepub async fn wait_for_idle(&self) -> Result<(), Error>
pub async fn wait_for_idle(&self) -> Result<(), Error>
Sourcepub async fn turn_count(&self) -> Result<u32, Error>
pub async fn turn_count(&self) -> Result<u32, Error>
Sourcepub async fn total_usage(&self) -> Result<UsageMetadata, Error>
pub async fn total_usage(&self) -> Result<UsageMetadata, Error>
Sourcepub async fn last_turn_usage(&self) -> Result<UsageMetadata, Error>
pub async fn last_turn_usage(&self) -> Result<UsageMetadata, Error>
Sourcepub async fn clear_history(&self) -> Result<(), Error>
pub async fn clear_history(&self) -> Result<(), Error>
Sourcepub async fn disconnect(&self) -> Result<(), Error>
pub async fn disconnect(&self) -> Result<(), Error>
Sourcepub fn get_last_structured_output(&self) -> Option<Value>
pub fn get_last_structured_output(&self) -> Option<Value>
Return the structured output from the last chat response, if any.
Only populated after a chat() round-trip when the
agent was configured with a response_schema and the model returned
a valid JSON payload.
Sourcepub fn get_last_usage(&self) -> Option<UsageMetadata>
pub fn get_last_usage(&self) -> Option<UsageMetadata>
Return the usage metadata from the last chat response, if any.
Sourcepub async fn signal_idle(&self) -> Result<(), Error>
pub async fn signal_idle(&self) -> Result<(), Error>
Sourcepub async fn shutdown(&self) -> Result<(), Error>
pub async fn shutdown(&self) -> Result<(), Error>
Gracefully shut down the agent.
This sends a ShutdownAgent command to the Python runtime, which
calls __aexit__() on the SDK agent. The handle remains usable
for read-only queries (e.g. is_started())
after shutdown.
§Errors
Returns a Error if shutdown fails. The is_shutdown
flag is always set so the Drop impl will not emit a warning.