Skip to main content

AgentRun

Struct AgentRun 

Source
pub struct AgentRun { /* private fields */ }
Expand description

The sans-IO agent loop state machine. See the module docs for the driving protocol. The persisted envelope is versioned: RUN_FORMAT is written on every serialization and checked on every deserialization, and an unknown key is refused. State written by another format is refused by name rather than loaded with defaults filled in.

Implementations§

Source§

impl AgentRun

Source

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

Create a run for one prompt with no input history, a one-model-call budget, and no invalid tool-call retries.

Source

pub fn initial_prompt(&self) -> Option<&Message>

The prompt this run will send on its first model call, while the run has not yet started. None once the first AgentRunStep::CallModel has been emitted (the prompt is then run history, no longer pending input).

Source

pub fn append_entry(&mut self, entry: Aside)

Append one host record without interpreting or validating its contents.

Source

pub fn entries(&self) -> &[Aside]

Every appended record, in append order.

Source

pub fn entries_of<'a>( &'a self, kind: &'a str, ) -> impl Iterator<Item = &'a Aside>

The records of one kind, in append order.

Source

pub fn last_entry_of(&self, kind: &str) -> Option<&Aside>

The most recently appended record of kind, if present.

Source

pub fn advertise_tools( &mut self, turn: usize, definitions: Vec<Arc<ToolDefinition>>, )

Record the tool definitions advertised to the model for turn (the turn of the AgentRunStep::CallModel being served). Replaces any earlier record; the run keeps only the latest turn’s advertisement.

Source

pub fn advertised_tools(&self) -> Option<&TurnTools>

The tools advertised for the most recent model call, if the driver recorded them. A CallTools step whose calls name tools outside this set means the driver and the run have desynchronized (a registry that changed under a resumed run, say); a driver that wants that guard checks here before dispatching.

Source

pub fn with_history( self, history: impl IntoIterator<Item = impl Into<Arc<Message>>>, ) -> Self

Set the input chat history preceding the prompt.

Source

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

Set the total model-call budget, including the initial call and every retry or continuation. A budget of zero emits no model calls. Exceeding the budget makes AgentRun::next_step return PromptError::MaxTurns.

Source

pub fn with_output_validation( self, output_schema: Option<Value>, max_output_retries: usize, ) -> Self

Set the output schema and retry budget for missing output-tool calls, output-tool arguments that are not a JSON object, or required fields. Validation checks only top-level required field presence; exhausting either the output or model-call budget finalizes best-effort, except that arguments that are not a JSON object fail the run.

Source

pub fn input_chat_history(&self) -> &[Arc<Message>]

The input chat history this run was created with, empty when none was set. This is the history preceding the initial prompt, not the run’s accumulated messages.

Source

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

Set the retry budget for InvalidToolCallAction::Retry resolutions. Invalid tool-call retries also consume the total model-call budget.

Source

pub fn max_consecutive_malformed_tool_calls( self, limit: impl Into<Option<usize>>, ) -> Self

Set how many consecutive turns may answer a tool call whose arguments are not a JSON object before the run fails. None, the default, sets no limit. See RunSpec::max_consecutive_malformed_tool_calls.

Source

pub fn with_unhandled_invalid_tool_call( self, policy: UnhandledInvalidToolCall, ) -> Self

Set what the run does with an invalid tool call no hook resolves. See UnhandledInvalidToolCall.

Source

pub fn with_output_tool_name(self, name: impl Into<String>) -> Self

Pin the synthetic output-tool name for Tool output mode up front.

This only seeds output_tool_name, which the driver passes to prepare_request as committed_output_tool for later turns. It does not by itself make a call to the tool finalize the run: a turn intercepts the call only when its TurnPolicy names the tool, as prepared.policy does when prepare_request resolved Tool output mode, or a hand-built TurnPolicy::new(.., Some(name)). Under a policy that does not name it, a call to the tool is an invalid (unknown) tool call.

Source

pub fn output_tool_name(&self) -> Option<&str>

The synthetic output-tool name pinned for this run, if any: set up front, or by the first model turn whose policy names one. The driver passes this back when preparing later turns so Tool output mode stays pinned even if the per-turn tool set changes.

Source

pub fn usage(&self) -> Usage

Aggregated token usage across all completed model calls so far.

Source

pub fn turn(&self) -> usize

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

Source

pub fn previous_model(&self) -> Option<&ModelRef>

Model of the preceding issued attempt, as recorded by the driver.

Source

pub fn set_previous_model(&mut self, model: ModelRef)

Record the model an attempt is about to be issued to; the driver calls this immediately before the model turn is driven.

Source

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

Every completion call the run made so far, in order.

Source

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

Messages accumulated by this run (the prompt plus all assistant turns and tool results), excluding the input history. While tools run, the last turn’s calls are still unanswered here: this is the view to display, and Self::full_history the one to resume from.

Source

pub fn projection_start(&self) -> usize

Where a driver starts to project messages: the end, or the message holding a pending AgentRunStep::CallTools batch, so a resumed run announces the calls whose results it streams.

Source

pub fn accepted_turn_choice(&self) -> Option<Vec<AssistantContent>>

Canonical content for the accepted model turn awaiting advancement.

Source

pub fn replace_accepted_turn_choice( &mut self, choice: Vec<AssistantContent>, ) -> Result<(), PromptError>

Replace accepted content before it enters history. Returns a cancellation error without an accepted turn or if either turn contains tool calls.

Source

pub fn retry_model_turn( &mut self, request: RetryRequest, ) -> Result<(), PromptError>

Reject the accepted, tool-free model turn and prepare another model call.

RetryRequest::Repeat discards the rejected assistant response and reuses the same prompt and preceding history with fresh request preparation. RetryRequest::Feedback records the rejected response followed by corrective user feedback. Canonical empty assistant turns are omitted from history, matching normal turn advancement. Both modes preserve completion-call and usage accounting, and the next call consumes the existing total model-call budget.

Tool-bearing turns cannot be retried through this operation because preserving them without matching tool results would create invalid provider-visible history. Use tool-call hooks to steer those turns.

Source

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

The full conversation: input history followed by Self::messages, with a tool batch the host has not finished answering closed: its results so far, then the other calls closed by close_pending (a pre-resolved result stands), so it resumes as a canonical transcript.

Source

pub fn is_done(&self) -> bool

Whether the run reached AgentRunStep::Done.

Source

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.

Source

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

Self::full_history closed for cancellation by repair: mid tool batch, the results so far follow it with the rest closed, and every call still unanswered in the unchecked input history is closed as well.

Source

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 Self::canonical_history.

Source

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.

Source

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

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

Idempotent while awaiting a model response or tool results: the step is emitted again, a model call without consuming a turn and a tool step with only its unanswered calls. A persisted run resumes from here in any non-terminal state except a pending invalid tool-call resolution.

A re-issued AgentRunStep::CallModel is the same attempt: it carries the same turn, and the run cannot tell its response from a late one of the attempt it replaces. Before re-issuing, the driver drops (or drains) the previous model call or stream, so nothing of it reaches Self::model_response, Self::record_streamed_completion_call or Self::streamed_turn. Re-issues are not budgeted: they consume no turn of Self::max_turns, and an attempt that never reached model_response or record_streamed_completion_call is not in Self::usage. A driver that re-issues in a loop bounds it itself.

§Errors
Source

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.

Source

pub fn malformed_context( &self, call: &MalformedCall, is_streaming: bool, ) -> InvalidToolCallContext

The invalid-call context for a malformed pending call, for the driver to offer its invalid-call hook before answering the call. Outside a AgentRunStep::CallTools step the context lists no tools.

Source

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

Answer a pending ModelTurnOutcome::NeedsResolution.

Applies the agent loop’s recovery semantics:

Source

pub fn resolve_unhandled_invalid_tool_call( &mut self, ) -> Result<ModelTurnOutcome, PromptError>

Apply the configured unhandled-call policy after hooks decline resolution. Fail reports the invalid call; Ignore removes it without suppressing response hooks or sibling calls. Errors without a pending invalid call.

Source

pub fn ignore_invalid_tool_call( &mut self, ) -> Result<ModelTurnOutcome, PromptError>

Resolve the pending invalid tool call by ignoring it: the turn proceeds as if the model had not made the call.

Source

pub fn answer(&mut self, answer: ToolAnswer) -> Result<(), PromptError>

Apply one ToolAnswer for the pending AgentRunStep::CallTools. See answer_all.

Source

pub fn answer_all( &mut self, answers: impl IntoIterator<Item = ToolAnswer>, ) -> Result<(), PromptError>

Apply answers for the pending AgentRunStep::CallTools, all or none. The run builds each result; once every call is answered they are committed as one user message in call order.

§Errors

A protocol violation, storing nothing, for an answer whose call is not open. A malformed call’s Stop, Fail or Repair ends the run; it is applied after the other answers, which the run keeps, and the first such answer in call order wins.

Source

pub fn record_streamed_completion_call( &mut self, usage: Usage, identity: ResponseIdentity, finish_reason: Option<FinishReason>, raw: Value, ) -> Result<CompletionCall, PromptError>

Record a streamed attempt’s terminal metadata and aggregate its usage. All arguments must come from that attempt’s final event; do not record a stream that ended without one. All-None counters mean unreported usage.

Allowed once per model attempt: while awaiting its response, or after its streamed rollback before the next model step. Other states and duplicate records return a cancellation error. Abandoned streams must still be drained for usage.

Source

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.

Source

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

Resolve an invalid tool call surfaced mid-stream.

Uses buffered-turn recovery policy with rollback messages from the partial turn. Retry and skip abandon the stream; repair changes only the name and rejects malformed arguments. Errors without a pending model step.

Source

pub fn ignore_streamed_invalid_tool_call( &mut self, ) -> Result<StreamedResolution, PromptError>

Resolve a streamed call as ignored. The driver must apply the returned resolution to the assembler so the call does not enter the turn. Errors without a pending model step.

Source

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

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

Rejects remaining disallowed tool names without further recovery. Requires a pending model step and exactly one prior call to AgentRun::record_streamed_completion_call for this attempt; otherwise returns a protocol error. Accepted turns await AgentRun::next_step.

Source§

impl AgentRun

Source

pub fn from_spec( spec: &RunSpec, prompt: impl Into<Message>, history: Option<Vec<Arc<Message>>>, ) -> Self

Build a run from a RunSpec, a prompt and an optional prior history.

Applies the spec’s budget, invalid-call retries and output validation; everything else in the spec is request-shaping the driver reads when it prepares each model call. spec.tool_choice reaches invalid-call validation only through the turn’s TurnPolicy: pass prepared.policy from prepare_request to ModelTurn::from_policy or ModelTurn::new.

Source§

impl AgentRun

Source

pub fn with_validated_history( self, history: Vec<Message>, ) -> Result<Self, PairingError>

with_history, rejecting a history that is not a canonical transcript. Use this when the history comes from outside the protocol (a store of its own, a resumed run from another process); with_history stays unchecked for callers that built the history themselves.

Trait Implementations§

Source§

impl Clone for AgentRun

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for AgentRun

Source§

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

Formats the value using the given formatter. Read more
Source§

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

Source§

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>
where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer. Read more
Source§

impl Serialize for AgentRun

Source§

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

Serialize this value into the given Serde serializer. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> DeserializeOwned for T
where T: for<'de> Deserialize<'de>,

Source§

impl<T> DynClone for T
where T: Clone,

Source§

fn __clone_box(&self, _: Private) -> *mut ()

Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoToolOutput for T
where T: Serialize + 'static,

Source§

fn into_tool_output(self) -> Result<ToolOutput, ToolExecutionError>

Convert this value without routing structured data through a string.
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WasmCompatSend for T
where T: Send,

Source§

impl<T> WasmCompatSync for T
where T: Sync,

Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more