Struct AgentSessionHandle 

pub struct AgentSessionHandle { /* private fields */ }

Lightweight handle for programmatic embedding.

This wraps AgentSession and exposes high-level request methods while still allowing access to the underlying session when needed.

Session-level event listeners can be registered via Self::subscribe or by providing callbacks on SessionOptions. These fire for every prompt, in addition to the per-prompt on_event callback.

Implementations

impl AgentSessionHandle

pub const fn from_session_with_listeners( session: AgentSession, listeners: EventListeners, ) -> Self

Create a handle from a pre-built AgentSession with custom listeners.

This is useful for tests and advanced embedding scenarios where the full create_agent_session() flow is not needed.

pub async fn prompt( &mut self, input: impl Into<String>, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<AssistantMessage>

Send one user prompt through the agent loop.

The on_event callback receives events for this prompt only. Session-level listeners registered via Self::subscribe or SessionOptions callbacks also fire for every event.

pub async fn prompt_with_abort( &mut self, input: impl Into<String>, abort_signal: AbortSignal, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<AssistantMessage>

Send one user prompt through the agent loop with an explicit abort signal.

pub fn new_abort_handle() -> (AbortHandle, AbortSignal)

Create a new abort handle/signal pair for prompt cancellation.

pub fn subscribe( &self, listener: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> SubscriptionId

Register a session-level event listener.

The listener fires for every AgentEvent across all future prompts until removed via Self::unsubscribe.

Returns a SubscriptionId that can be used to remove the listener.

pub fn unsubscribe(&self, id: SubscriptionId) -> bool

Remove a previously registered event listener.

Returns true if the listener was found and removed.

pub const fn listeners(&self) -> &EventListeners

Access the session-level event listeners.

pub const fn listeners_mut(&mut self) -> &mut EventListeners

Mutable access to session-level event listeners.

Allows updating typed hooks (on_tool_start, on_tool_end, on_stream_event) after session creation.

pub const fn has_extensions(&self) -> bool

Whether this session has extensions loaded.

pub fn extension_manager(&self) -> Option<&ExtensionManager>

Return a reference to the extension manager (if extensions are loaded).

pub const fn extension_region(&self) -> Option<&ExtensionRegion>

Return a reference to the extension region (if extensions are loaded).

The region wraps the extension manager with lifecycle management.

pub fn model(&self) -> (String, String)

Return the active provider/model pair.

pub async fn set_model(&mut self, provider: &str, model_id: &str) -> Result<()>

Update the active provider/model pair and persist it to session metadata.

pub const fn thinking_level(&self) -> Option<ThinkingLevel>

Return the currently configured thinking level.

pub const fn thinking(&self) -> Option<ThinkingLevel>

Alias for thinking level access, matching the SDK naming style.

pub async fn set_thinking_level(&mut self, level: ThinkingLevel) -> Result<()>

Update thinking level and persist it to session metadata.

pub async fn messages(&self) -> Result<Vec<Message>>

Return all model messages for the current session path.

pub async fn state(&self) -> Result<AgentSessionState>

Return a lightweight state snapshot.

pub async fn compact( &mut self, on_event: impl Fn(AgentEvent) + Send + Sync + 'static, ) -> Result<()>

Trigger an immediate compaction pass (if compaction is enabled).

pub const fn session(&self) -> &AgentSession

Access the underlying AgentSession.

pub const fn session_mut(&mut self) -> &mut AgentSession

Mutable access to the underlying AgentSession.

pub fn into_inner(self) -> AgentSession

Consume the handle and return the inner AgentSession.