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: Aside)
pub fn append_entry(&mut self, entry: Aside)
Append one host record without interpreting or validating its contents.
Sourcepub fn advertise_tools(
&mut self,
turn: usize,
definitions: Vec<Arc<ToolDefinition>>,
)
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.
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: impl IntoIterator<Item = impl Into<Arc<Message>>>,
) -> Self
pub fn with_history( self, history: impl IntoIterator<Item = impl Into<Arc<Message>>>, ) -> Self
Set the input chat history preceding the prompt. It is not checked: a
history from outside the run (another store, a run resumed in another
process) goes through rig_core::conversation::pairing::validate first.
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 answers that miss it: text
that does not satisfy it, an output-tool call whose arguments are not
a JSON object or do not satisfy it. The answer must be JSON (the whole
text, else one value past leading prose or a fence) that fits the
schema as rig_core::tool::validate::validate checks it, which
covers types, required fields and the other keywords it lists.
Exhausting either the output or model-call budget on such an answer
fails the run with PromptError::OutputSchemaMismatch.
Sourcepub fn input_chat_history(&self) -> &[Arc<Message>]
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.
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_output_tool_name(self, name: impl Into<String>) -> Self
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.
Sourcepub fn output_tool_name(&self) -> Option<&str>
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.
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) -> &[Arc<Message>]
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.
Sourcepub fn projection_start(&self) -> usize
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.
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,
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.
Sourcepub fn is_done(&self) -> bool
pub fn is_done(&self) -> bool
Whether the run reached AgentRunStep::Done.
Sourcepub fn canonical_history(&self) -> Vec<Message>
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.
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 Self::canonical_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.
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
PromptError::MaxTurnswhen the total model-call budget is exhausted.PromptError::OutputSchemaMismatchwhen the final answer misses the output schema and no output retry is left (Self::with_output_validation).PromptError::Cancelledwhen the machine is driven out of protocol (for example, calling this while an invalid tool-call resolution 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_context(
&self,
call: &MalformedCall,
is_streaming: bool,
) -> InvalidToolCallContext
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.
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 under a turn whose policyforbids_calls.
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 answer(&mut self, answer: ToolAnswer) -> Result<(), PromptError>
pub fn answer(&mut self, answer: ToolAnswer) -> Result<(), PromptError>
Apply one ToolAnswer for the pending AgentRunStep::CallTools.
See answer_all.
Sourcepub fn answer_all(
&mut self,
answers: impl IntoIterator<Item = ToolAnswer>,
) -> Result<(), PromptError>
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 once
every answer is checked; the run keeps the other answers, and the
first such answer in call order wins.
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 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.
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<Arc<Message>>>,
) -> Self
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.