Struct AgentRuntime 

pub struct AgentRuntime { /* private fields */ }

Top-level agent runtime. Manages runs across threads.

Provides methods for cancelling and sending decisions to active agent runs. Enforces one active run per thread.

Implementations

impl AgentRuntime

pub async fn cancel_and_wait_by_thread(&self, thread_id: &str) -> bool

Cancel an active run by thread ID and wait for it to finish.

Returns true only when the run slot is released before the wait timeout. Returns false when no active run exists or cancellation does not finish in time.

pub fn cancel_by_thread(&self, thread_id: &str) -> bool

Cancel an active run by thread ID.

pub fn cancel_by_run_id(&self, run_id: &str) -> bool

Cancel an active run by run ID.

pub fn cancel(&self, id: &str) -> bool

Cancel an active run by dual-index ID (run_id or thread_id). Ambiguous IDs are rejected.

pub fn send_decisions( &self, thread_id: &str, decisions: Vec<(String, ToolCallResume)>, ) -> bool

Send decisions to an active run by thread ID.

pub fn send_decision( &self, id: &str, tool_call_id: String, resume: ToolCallResume, ) -> bool

Send a decision by dual-index ID (run_id or thread_id). Ambiguous IDs are rejected.

pub fn send_messages(&self, id: &str, messages: Vec<Message>) -> bool

Send direct input messages to an active run by run ID or thread ID. Ambiguous IDs are rejected.

impl AgentRuntime

pub async fn run_to_completion( &self, request: RunRequest, ) -> Result<AgentRunResult, AgentLoopError>

Run an agent loop until it returns an AgentRunResult.

This is a convenience wrapper for one-shot CLI programs and examples that only need the final AgentRunResult. Use Self::run with an EventSink when streaming events to SSE, WebSocket, protocol adapters, or tests.

pub async fn run( &self, request: RunRequest, sink: Arc<dyn EventSink>, ) -> Result<AgentRunResult, AgentLoopError>

Run an agent loop.

This is the single production entry point. It:

1. Resolves the agent from the registry
2. Loads thread messages from storage (if configured)
3. Applies resume decisions (if present in request)
4. Creates a PhaseRuntime and StateStore
5. Registers the active run
6. Calls run_agent_loop internally
7. Unregisters the run when complete

Run an agent loop. Returns the result when the run completes.

Use cancel() / send_decisions() on AgentRuntime for external control of in-flight runs.

impl AgentRuntime

pub fn new(resolver: Arc<dyn AgentResolver>) -> AgentRuntime

pub fn new_with_execution_resolver( resolver: Arc<dyn ExecutionResolver>, ) -> AgentRuntime

pub fn with_registry_handle(self, handle: RegistryHandle) -> AgentRuntime

pub fn with_thread_run_store( self, store: Arc<dyn ThreadRunStore>, ) -> AgentRuntime

pub fn with_mailbox_store(self, store: Arc<dyn MailboxStore>) -> AgentRuntime

Wire the mailbox store used to subscribe to live-steering commands for each active run. If unset, runs never receive remote LiveRunCommands — this is the single-process / test default.

pub fn resolver(&self) -> &dyn AgentResolver

pub fn resolver_arc(&self) -> Arc<dyn AgentResolver>

Return a cloned Arc of the agent resolver.

pub fn execution_resolver(&self) -> &dyn ExecutionResolver

pub fn execution_resolver_arc(&self) -> Arc<dyn ExecutionResolver>

pub fn registry_handle(&self) -> Option<RegistryHandle>

pub fn registry_snapshot(&self) -> Option<RegistrySnapshot>

pub fn registry_version(&self) -> Option<u64>

pub fn registry_set(&self) -> Option<RegistrySet>

pub fn replace_registry_set(&self, registries: RegistrySet) -> Option<u64>

pub fn with_composite_registry( self, registry: Arc<CompositeAgentSpecRegistry>, ) -> AgentRuntime

pub fn composite_registry(&self) -> Option<&Arc<CompositeAgentSpecRegistry>>

Return the composite registry, if one was configured.

pub async fn initialize(&self) -> Result<(), RuntimeError>

Initialize the runtime — discover remote agents. Call this after build() to complete async initialization.

pub fn thread_run_store(&self) -> Option<&dyn ThreadRunStore>

Trait Implementations

impl RunDispatchExecutor for AgentRuntime

fn run<'life0, 'async_trait>( &'life0 self, request: RunRequest, sink: Arc<dyn EventSink>, ) -> Pin<Box<dyn Future<Output = Result<AgentRunResult, AgentLoopError>> + Send + 'async_trait>>

where 'life0: 'async_trait, AgentRuntime: 'async_trait,

Execute a run request and stream events into the provided sink.

fn run_with_thread_context<'life0, 'async_trait>( &'life0 self, request: RunRequest, sink: Arc<dyn EventSink>, thread_ctx: Option<ThreadContextSnapshot>, ) -> Pin<Box<dyn Future<Output = Result<AgentRunResult, AgentLoopError>> + Send + 'async_trait>>

where 'life0: 'async_trait, AgentRuntime: 'async_trait,

Execute a run with an optional mailbox-provided thread cache.

fn cancel(&self, id: &str) -> bool

Cancel an active run by run id or thread id.

fn cancel_and_wait_by_thread<'life0, 'life1, 'async_trait>( &'life0 self, thread_id: &'life1 str, ) -> Pin<Box<dyn Future<Output = bool> + Send + 'async_trait>>

where 'life0: 'async_trait, 'life1: 'async_trait, AgentRuntime: 'async_trait,

Cancel an active run by thread id and wait for it to unregister.

fn send_decision( &self, id: &str, tool_call_id: String, resume: ToolCallResume, ) -> bool

Forward one human/tool decision to an active run.

fn send_messages(&self, id: &str, messages: Vec<Message>) -> bool

Forward direct input messages to an active run.