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
impl AgentRun
Sourcepub fn new(prompt: impl Into<Message>) -> Self
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.
Sourcepub fn initial_prompt(&self) -> Option<&Message>
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).
Sourcepub fn append_entry(&mut self, entry: RunEntry)
pub fn append_entry(&mut self, entry: RunEntry)
Append one host record without interpreting or validating its contents.
Sourcepub fn entries_of<'a>(
&'a self,
kind: &'a str,
) -> impl Iterator<Item = &'a RunEntry>
pub fn entries_of<'a>( &'a self, kind: &'a str, ) -> impl Iterator<Item = &'a RunEntry>
The entries of one kind, in append order.
Sourcepub fn last_entry_of(&self, kind: &str) -> Option<&RunEntry>
pub fn last_entry_of(&self, kind: &str) -> Option<&RunEntry>
The most recently appended entry of kind, if present.
Sourcepub fn advertise_tools(&mut self, turn: usize, definitions: Vec<ToolDefinition>)
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.
Sourcepub fn advertised_tools(&self) -> Option<&TurnTools>
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.
Sourcepub fn with_history(self, history: Vec<Message>) -> Self
pub fn with_history(self, history: Vec<Message>) -> Self
Set the input chat history preceding the prompt.
Sourcepub fn max_turns(self, max_turns: usize) -> Self
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.
Sourcepub fn with_output_validation(
self,
output_schema: Option<Value>,
max_output_retries: usize,
) -> Self
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.
Sourcepub fn input_chat_history(&self) -> &[Message]
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.
Sourcepub fn max_invalid_tool_call_retries(self, retries: usize) -> Self
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.
Sourcepub fn max_consecutive_malformed_tool_calls(
self,
limit: impl Into<Option<usize>>,
) -> Self
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.
Sourcepub fn with_unhandled_invalid_tool_call(
self,
policy: UnhandledInvalidToolCall,
) -> Self
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.
Sourcepub fn with_tool_choice(self, tool_choice: ToolChoice) -> Self
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.
Sourcepub fn with_output_tool_name(self, name: impl Into<String>) -> Self
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.
Sourcepub fn commit_output_tool_name(&mut self, name: impl Into<String>) -> bool
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.
Sourcepub fn output_tool_name(&self) -> Option<&str>
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.
Sourcepub fn previous_model(&self) -> Option<&ModelRef>
pub fn previous_model(&self) -> Option<&ModelRef>
Model of the preceding issued attempt, as recorded by the driver.
Sourcepub fn set_previous_model(&mut self, model: ModelRef)
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.
Sourcepub fn completion_calls(&self) -> &[CompletionCall]
pub fn completion_calls(&self) -> &[CompletionCall]
Every completion call the run made so far, in order.
Sourcepub fn messages(&self) -> &[Message]
pub fn messages(&self) -> &[Message]
Messages accumulated by this run (the prompt plus all assistant turns and tool results), excluding the input history.
Sourcepub fn accepted_turn_choice(&self) -> Option<Vec<AssistantContent>>
pub fn accepted_turn_choice(&self) -> Option<Vec<AssistantContent>>
Canonical content for the accepted model turn awaiting advancement.
Sourcepub fn replace_accepted_turn_choice(
&mut self,
choice: Vec<AssistantContent>,
) -> Result<(), PromptError>
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.
Sourcepub fn retry_model_turn(
&mut self,
request: RetryRequest,
) -> Result<(), PromptError>
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.
Sourcepub fn full_history(&self) -> Vec<Message>
pub fn full_history(&self) -> Vec<Message>
The full conversation: input history followed by Self::messages.
Sourcepub fn is_done(&self) -> bool
pub fn is_done(&self) -> bool
Whether the run reached AgentRunStep::Done.
Sourcepub fn response(&self) -> Option<&PromptResponse>
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.
Sourcepub fn cancel_error(&self, reason: impl Into<String>) -> PromptError
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.
Sourcepub fn pending_invalid_tool_call(&self) -> Option<InvalidToolCallContext>
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.
Sourcepub fn next_step(&mut self) -> Result<AgentRunStep, PromptError>
pub fn next_step(&mut self) -> Result<AgentRunStep, PromptError>
Advance the machine and return the next action for the driver.
§Errors
PromptError::MaxTurnswhen the total model-call budget is exhausted.PromptError::Cancelledwhen the machine is driven out of protocol (for example, calling this while a model response is pending).
Sourcepub fn model_response(
&mut self,
turn: ModelTurn,
) -> Result<ModelTurnOutcome, PromptError>
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.
Sourcepub fn malformed_tool_call_context(
&self,
tool_call: &ToolCall,
is_streaming: bool,
) -> Option<InvalidToolCallContext>
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.
Sourcepub fn resolve_invalid_tool_call(
&mut self,
action: InvalidToolCallAction,
) -> Result<ModelTurnOutcome, PromptError>
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:
InvalidToolCallAction::Failfails the run withPromptError::UnknownToolCall.InvalidToolCallAction::Retryrolls the turn back with corrective feedback while budget remains, consuming the total model-call budget.InvalidToolCallAction::Repairrenames the tool call; the repaired name is revalidated against the allowed tools.InvalidToolCallAction::Stopcancels the run withPromptError::cancelledand the supplied reason.InvalidToolCallAction::Skiprecords a synthetic tool result and suppresses execution of every tool call in the turn. Rejected underToolChoice::None.
Sourcepub fn resolve_unhandled_invalid_tool_call(
&mut self,
) -> Result<ModelTurnOutcome, PromptError>
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.
Sourcepub fn ignore_invalid_tool_call(
&mut self,
) -> Result<ModelTurnOutcome, PromptError>
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.
Sourcepub fn tool_results(
&mut self,
results: Vec<UserContent>,
) -> Result<(), PromptError>
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.
Sourcepub fn record_streamed_completion_call(
&mut self,
usage: Usage,
identity: ResponseIdentity,
finish_reason: Option<FinishReason>,
raw: Value,
) -> Result<CompletionCall, PromptError>
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.
Sourcepub fn streamed_invalid_tool_call_context(
&self,
partial: &PartialStreamedTurn,
invalid: &StreamedInvalidToolCall,
) -> InvalidToolCallContext
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.
Sourcepub fn resolve_streamed_invalid_tool_call(
&mut self,
partial: &PartialStreamedTurn,
invalid: &StreamedInvalidToolCall,
action: InvalidToolCallAction,
) -> Result<StreamedResolution, PromptError>
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.
Sourcepub fn ignore_streamed_invalid_tool_call(
&mut self,
) -> Result<StreamedResolution, PromptError>
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.
Sourcepub fn streamed_turn(&mut self, turn: StreamedTurn) -> Result<(), PromptError>
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
impl AgentRun
Sourcepub fn from_spec(
spec: &RunSpec,
prompt: impl Into<Message>,
history: Option<Vec<Message>>,
) -> Self
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
impl AgentRun
Sourcepub fn with_validated_history(
self,
history: Vec<Message>,
) -> Result<Self, TranscriptError>
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.