Struct AgentRunner 

#[non_exhaustive]
pub struct AgentRunner<M>
where
    M: CompletionModel,
{ /* private fields */ }

A hook-aware driver over AgentRun.

Construct one from an Agent with Agent::runner, attach hooks with add_hook, then call run (blocking) or stream (incremental). Hooks are held in a HookStack, an ordered, runtime-composable list; run() and stream() share the same loop and fire the same events, so they behave identically apart from the streamed delta events the medium adds.

Implementations

impl<M> AgentRunner<M>

where M: CompletionModel + 'static, <M as CompletionModel>::StreamingResponse: WasmCompatSend + GetTokenUsage,

pub async fn stream(self) -> StreamingResult<M::StreamingResponse>

Drive the agent loop, streaming assistant content, tool activity, and a final response. Hooks fire at every observable point, including streamed text and tool-call deltas. Returns the stream after loading any configured conversation memory.

Shares the drive loop, run construction, tool execution and fail-closed hook handling with the blocking run via drive_agent, so the two behave identically apart from the streamed delta events.

impl<M> AgentRunner<M>

where M: CompletionModel,

pub fn from_agent(agent: &Agent<M>, prompt: impl Into<Message>) -> Self

Build a runner from an agent, seeding it with the agent’s default hook stack. Prefer Agent::runner.

pub fn add_hook<H>(self, hook: H) -> Self

where H: AgentHook<M> + 'static,

Append a hook to the stack (on top of any the agent already carries). Hooks run in registration order; how their results compose is event-dependent (CompletionCall request patches accumulate and merge, ToolCall/ToolResult rewrites chain, and only observe-only/recovery events use first-non-Flow::Continue-wins). See the hook module docs.

impl<M> AgentRunner<M>

where M: CompletionModel,

pub fn max_turns(self, max_turns: usize) -> Self

Set the total model-call budget, including the initial call and every retry or continuation. Zero emits no model calls; one permits only the initial call. Exceeding the budget returns PromptError::MaxTurnsError.

pub fn tool_extensions(self, extensions: ToolCallExtensions) -> Self

Set the per-call runtime ToolCallExtensions for this run.

The extensions are threaded to every tool the agent executes, so tools can read caller-provided values (auth tokens, session IDs, conversation state, …) via Tool::call_with_extensions without the model ever seeing them. Replaces any extensions already set.

pub fn history<I, T>(self, history: I) -> Self

where I: IntoIterator<Item = T>, T: Into<Message>,

Set the chat history preceding the prompt. Passing explicit history bypasses conversation memory for this run.

pub fn tool_concurrency(self, concurrency: usize) -> Self

Execute up to concurrency tools at once (1 by default). Applies to both the blocking run and the streaming stream paths.

The resulting message history is the same in both paths regardless of concurrency: final tool results are persisted in tool-call order. At the default concurrency of 1 the two paths are fully in lock-step; with concurrency > 1 the tools run in parallel, so a ToolCall/ToolResult hook may fire in completion order rather than call order — the per-tool side effects interleave even though the final history does not.

For the streaming path: the driver emits all of a turn’s ToolCall stream items eagerly (in call order) when the model turn commits, then — only after the whole tool batch settles successfully — surfaces the per-tool ToolExecutionStart and ToolResult stream items in call order (never completion order), for the tools whose body actually ran. The persisted message history is unchanged.

A concurrency of 0 is clamped to 1; 0 and 1 both run a turn’s tools sequentially (the buffer_unordered path is used only at concurrency > 1).

pub fn conversation(self, id: impl Into<String>) -> Self

Set the conversation id used to load and persist memory for this run.

pub fn without_memory(self) -> Self

Disable conversation memory for this run (no load, no save).

pub fn max_invalid_tool_call_retries(self, retries: usize) -> Self

Set the retry budget for invalid tool-call recovery. Invalid tool-call retries also consume the total model-call budget.

impl<M> AgentRunner<M>

where M: CompletionModel,

pub async fn run(self) -> Result<PromptResponse, PromptError>

Drive the agent loop to completion, returning the aggregated PromptResponse. Hooks fire at every observable point; the first hook to terminate cancels the run.