Struct AgentRunner 

pub struct AgentRunner { /* 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 AgentRunner

pub async fn stream(self) -> StreamingResult

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 AgentRunner

pub fn from_agent(agent: &Agent, 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 + '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 (model selections and ToolCall/ToolResult rewrites chain, CompletionCall request patches accumulate and merge, while model-turn steering and observe-only/recovery events use their event-specific terminal action). See the hook module docs.

impl AgentRunner

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 using_model(self, model: ModelHandle) -> Self

Set the default model candidate for this run.

This does not suppress registered model-selection hooks, which may replace the candidate before each model call (including retries). Append an unconditional selecting hook last when the run must always use one model.

pub fn using_model_value<M>(self, model: M) -> Self

where M: CompletionModel + 'static,

Erase and set a typed default model for this run.

pub fn tool_context(self, context: ToolContext) -> Self

Set the typed context cloned for every tool dispatch in this run.

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 preamble(self, preamble: impl Into<String>) -> Self

Override the agent preamble for this run.

pub fn without_preamble(self) -> Self

Remove the agent’s configured preamble for this run.

pub fn document(self, document: Document) -> Self

Append one static context document for this run.

pub fn documents(self, documents: impl IntoIterator<Item = Document>) -> Self

Append static context documents for this run.

pub fn temperature(self, temperature: f64) -> Self

Override the model temperature for this run.

pub fn without_temperature(self) -> Self

Remove the agent’s configured temperature for this run.

pub fn max_tokens(self, max_tokens: u64) -> Self

Override the maximum completion token count for this run.

pub fn without_max_tokens(self) -> Self

Remove the agent’s configured maximum token count for this run.

pub fn merge_additional_params(self, params: Map<String, Value>) -> Self

Shallow-merge object fields into the provider-specific parameters for this run. Later fields win. A non-object baseline is replaced by the supplied object. A later completion-call hook patch has final precedence: object values shallow-merge, while a non-object on either side causes wholesale replacement by the hook value.

pub fn replace_additional_params(self, params: Value) -> Self

Replace all provider-specific parameters for this run. A later completion-call hook patch has final precedence: object values shallow-merge, while a non-object on either side causes wholesale replacement by the hook value.

pub fn without_additional_params(self) -> Self

Remove the agent’s configured provider-specific parameters for this run. A later completion-call hook may still supply its own parameters.

pub fn tool_choice(self, tool_choice: ToolChoice) -> Self

Override the tool-choice policy for this run.

pub fn without_tool_choice(self) -> Self

Remove the agent’s configured tool-choice policy for this run.

pub fn record_content_telemetry(self, enabled: bool) -> Self

Opt in or out of recording sensitive request, response, and tool content on GenAI telemetry spans for this run.

Defaults to the agent’s setting, which defaults to false. Enabling this can expose prompts, retrieved context, tool results, model responses, and other sensitive or high-cardinality data through OpenTelemetry span attributes, which can increase observability backend storage and query costs. Only enable it when content telemetry is acceptable for this run. Structural metadata and token usage remain available when disabled.

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 ToolExecutionCommitted 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; at 1 the tools of a turn run strictly sequentially in call order, failing fast on the first terminating error.

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 AgentRunner

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.