Struct AgentRun 

pub struct AgentRun { /* private fields */ }

The sans-IO agent loop state machine. See the module docs for the driving protocol.

Implementations

impl AgentRun

pub fn new(prompt: impl Into<Message>) -> Self

Create a run for one prompt with no input history, no multi-turn depth and no invalid tool-call retries.

pub fn with_history(self, history: Vec<Message>) -> Self

Set the input chat history preceding the prompt.

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

Set the maximum multi-turn depth. Exceeding it makes AgentRun::next_step return PromptError::MaxTurnsError.

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

Set the retry budget for InvalidToolCallHookAction::Retry resolutions. Invalid tool-call retries also consume multi-turn depth.

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

Set the tool choice active for this run. Used to reject InvalidToolCallHookAction::Skip resolutions under ToolChoice::None and reported in invalid tool-call contexts.

pub fn usage(&self) -> Usage

Aggregated token usage across all completed model calls so far.

pub fn turn(&self) -> usize

Number of model calls emitted so far (including retries).

pub fn completion_calls(&self) -> &[CompletionCall]

Details for each completed model call so far.

pub fn messages(&self) -> &[Message]

Messages accumulated by this run (the prompt plus all assistant turns and tool results), excluding the input history.

pub fn full_history(&self) -> Vec<Message>

The full conversation: input history followed by Self::messages.

pub fn is_done(&self) -> bool

Whether the run reached AgentRunStep::Done.

pub fn response(&self) -> Option<&PromptResponse>

The final response once the run is done, without cloning it. AgentRun::next_step in the done state returns an owned clone (including the full accumulated message history); prefer this when only inspecting the result.

pub fn cancel_error(&self, reason: impl Into<String>) -> PromptError

Build the cancellation error a driver should return when one of its hooks terminates the run, carrying the current full history.

pub fn pending_invalid_tool_call(&self) -> Option<InvalidToolCallContext>

The invalid tool call currently awaiting AgentRun::resolve_invalid_tool_call, if any. Useful to re-derive the resolution context after deserializing a suspended run.

pub fn next_step(&mut self) -> Result<AgentRunStep, PromptError>

Advance the machine and return the next action for the driver.

Errors

• PromptError::MaxTurnsError when the multi-turn depth is exhausted.
• PromptError::PromptCancelled when the machine is driven out of protocol (for example, calling this while a model response is pending).

pub fn model_response( &mut self, turn: ModelTurn, ) -> Result<ModelTurnOutcome, PromptError>

Feed the model’s response for the pending AgentRunStep::CallModel.

Records the completion call and aggregates usage, then validates the turn’s tool calls against the advertised tool names. See ModelTurnOutcome for what the driver must do next.

pub fn resolve_invalid_tool_call( &mut self, action: InvalidToolCallHookAction, ) -> Result<ModelTurnOutcome, PromptError>

Answer a pending ModelTurnOutcome::NeedsResolution.

Applies the agent loop’s recovery semantics:

• InvalidToolCallHookAction::Fail fails the run with PromptError::UnknownToolCall.
• InvalidToolCallHookAction::Retry rolls the turn back with corrective feedback while budget remains, consuming multi-turn depth.
• InvalidToolCallHookAction::Repair renames the tool call; the repaired name is revalidated against the allowed tools.
• InvalidToolCallHookAction::Skip records a synthetic tool result and suppresses execution of every tool call in the turn. Rejected under ToolChoice::None.

pub fn tool_results( &mut self, results: Vec<UserContent>, ) -> Result<(), PromptError>

Feed the tool results for the pending AgentRunStep::CallTools.

Results may be in any order; they are appended as a single user message, matching what providers expect for parallel tool calls. Each result must be a tool result answering one of the pending calls, and every pending call must be answered — exactly what providers require to accept the next request.

pub fn record_streamed_completion_call( &mut self, usage: Usage, ) -> Result<CompletionCall, PromptError>

Record one provider completion call for a streamed turn.

Streamed turns learn usage from the provider’s final stream event — including for turns abandoned by invalid tool-call recovery, where the stream is drained for usage after the rollback — so recording is decoupled from turn ingestion. Valid while a model response is pending or between a turn rollback and the next AgentRunStep::CallModel; aggregates usage into the run total. Zero-valued usage means the provider reported no usage metrics.

pub fn streamed_invalid_tool_call_context( &self, partial: &PartialStreamedTurn, invalid: &StreamedInvalidToolCall, ) -> InvalidToolCallContext

The recovery-hook context for an invalid tool call surfaced mid-stream by a streamed::StreamedTurnAssembler.

pub fn resolve_streamed_invalid_tool_call( &mut self, partial: &PartialStreamedTurn, invalid: &StreamedInvalidToolCall, action: InvalidToolCallHookAction, ) -> Result<StreamedResolution, PromptError>

Resolve an invalid tool call surfaced mid-stream.

Applies the same recovery semantics as AgentRun::resolve_invalid_tool_call, but rollback messages are assembled from the partial streamed turn — exactly what the model has produced so far — and a successful retry or skip abandons the turn (see StreamedResolution) instead of finishing it.

pub fn streamed_turn(&mut self, turn: StreamedTurn) -> Result<(), PromptError>

Feed the assembled streamed turn for the pending AgentRunStep::CallModel.

Remaining tool calls are validated fail-fast — mid-stream resolution already had recovery-hook access — and the turn then advances through AgentRun::next_step exactly like a non-streamed one.

Trait Implementations

impl Clone for AgentRun

fn clone(&self) -> AgentRun

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentRun

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for AgentRun

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentRun

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.