Struct AgentHandle 

pub struct AgentHandle { /* private fields */ }

Agent session handle — unified input/output/cancel interface

AgentHandle wraps a command queue, a Worker task, an event stream, and cancellation. All callers (CLI / UI / HTTP API) interact with agent-base through it.

Example

use agent_works::AgentHandle;
use agent_base::AgentRuntime;

let mut handle = AgentHandle::new(runtime);

// Send user input
handle.send_input("check disk space").await.unwrap();

// Receive events
while let Some(event) = handle.recv_event().await {
    // Handle event...
    if matches!(event, agent_base::RuntimeEvent::RunFinished { .. }
        | agent_base::RuntimeEvent::RunCancelled { .. }) {
        break;
    }
}

// Cancel current execution
handle.cancel();

Implementations

impl AgentHandle

pub fn new(runtime: AgentRuntime) -> Self

Create a new AgentHandle, spawning a background Worker

pub fn with_session(runtime: AgentRuntime, session_id: SessionId) -> Self

Create an AgentHandle with a default session_id The session_id will be used for all send_input calls unless overridden

pub async fn send_input(&self, input: &str) -> Result<(), SendError>

Send user input (async, with error return) Uses the default session_id if set via with_session(), otherwise creates a new session

pub async fn send_input_with_session( &self, input: &str, session_id: SessionId, ) -> Result<(), SendError>

Send user input with a specified session_id

pub async fn recv_event(&mut self) -> Option<RuntimeEvent>

Receive the next event (blocking)

pub fn try_recv_event(&mut self) -> Option<RuntimeEvent>

Try to receive an event (non-blocking)

pub fn cancel(&self)

Cancel current execution — delegates to runtime, always cancels the latest token

pub fn runtime(&self) -> &AgentRuntime

Get a reference to the underlying runtime