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: RunEntry)

Append one host record without interpreting or validating its contents.

Source

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

Every appended RunEntry, in append order.

Source

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

The entries of one kind, in append order.

Source

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

The most recently appended entry of kind, if present.

Source

pub fn advertise_tools(&mut self, turn: usize, definitions: Vec<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: Vec<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) -> &[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_tool_choice(self, tool_choice: ToolChoice) -> Self

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

Source

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

Set the synthetic output-tool name for Tool output mode. When a model turn calls this tool, the run finalizes with the call’s arguments (serialized JSON) as the response.

Source

pub fn commit_output_tool_name(&mut self, name: impl Into<String>) -> bool

Commit the output-tool name once the driver has resolved it from the prepared request inside the run loop, where the agent’s tool set (and thus the resolved output mode) is known. Returns whether this call committed it: the name is pinned for the whole run, so the request the driver builds each turn stays consistent with the intercept (and a tool set that shifts mid-run cannot flip the mode); a later call with a different name is refused, not applied.

Source

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

The synthetic output-tool name committed for this run, if any. 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) -> &[Message]

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

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.

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 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.

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.

§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_tool_call_context( &self, tool_call: &ToolCall, is_streaming: bool, ) -> Option<InvalidToolCallContext>

The invalid-call context for a pending call whose arguments are not a JSON object, for the driver to offer its invalid-call hook before answering the call. None when the call’s arguments parsed or no AgentRunStep::CallTools is pending.

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 tool_results( &mut self, results: Vec<UserContent>, ) -> Result<(), PromptError>

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

Results may arrive in any order and are appended as one user message. Each must answer a pending call, with exactly one result per occurrence of its ID. Invalid or incomplete batches return a cancellation error.

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 while awaiting a model response, or after a 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<Message>>, ) -> Self

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

Applies the spec’s budget, invalid-call retries, output validation and tool choice; everything else in the spec is request-shaping the driver reads when it prepares each model call.

Source§

impl AgentRun

Source

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

with_history, rejecting a history that is not a canonical transcript. Use this when the history comes from outside the protocol (a memory backend, 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