1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
//! Per-call accounting, final run responses, and prompting errors.
//!
//! ```
//! use rig_agent::run::response::PromptResponse;
//! let response = PromptResponse::new("done", Default::default());
//! assert_eq!(response.output(), "done");
//! ```
use rig_core::completion::{FinishReason, ResponseIdentity, Usage};
use rig_core::error::ProviderError;
use rig_core::message::{AssistantContent, Message};
use rig_core::tool::validate::Problem;
use serde::{Deserialize, Serialize};
/// One completion call of a run: what was asked and what came back.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CompletionCall {
/// Zero-based index of the completion request within this agent run.
pub call_index: usize,
/// Token usage reported for this completion request.
///
/// A counter the provider did not report is `None`; a reported zero is
/// `Some(0)`. Every counter is `None` when no usage was reported at all.
pub usage: Usage,
/// The response and transport request ids this call reported.
#[serde(flatten)]
pub identity: ResponseIdentity,
/// Why this call stopped generating, or `None` if unreported.
/// Retained per call so callers can identify which attempt was truncated.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub finish_reason: Option<FinishReason>,
/// This attempt's provider response payload, as defined by
/// [`rig_core::completion::CompletionResponse::raw`]. A stream without a
/// terminal response produces no completion-call entry.
pub raw: serde_json::Value,
}
impl CompletionCall {
/// Create details for one completion request in an agent run, carrying
/// the provider's own response `raw` (see [`Self::raw`]); identity and
/// finish reason start unset.
pub fn new(call_index: usize, usage: Usage, raw: serde_json::Value) -> Self {
Self {
call_index,
usage,
identity: ResponseIdentity::default(),
finish_reason: None,
raw,
}
}
}
/// Final run output and accounting, returned by awaited runs and terminal
/// `MultiTurnStreamItem::FinalResponse` stream items.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct PromptResponse {
/// Aggregated token usage across the whole run.
pub usage: Usage,
/// Successfully completed completion requests made by this agent run.
///
/// `usage` remains the aggregate across the whole run. Use the last
/// entry's usage to inspect the final completion request's prompt/context
/// length. An entry whose counters are all `None` means the provider
/// reported no usage metrics for that request.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub completion_calls: Vec<CompletionCall>,
/// The run's transcript: the prompt, every accepted assistant turn, every
/// committed tool result and the corrective feedback of any retried turn,
/// excluding the input history the run started from: what a caller keeping
/// the conversation appends to it. Empty only for a response built without
/// a run behind it.
#[serde(default)]
pub messages: Vec<Message>,
/// Structured assistant content for the final turn: its text,
/// reasoning, images, and other parts. In output-tool mode the model's
/// prose and tool calls are replaced by one text part holding the
/// serialized structured output. [`output`](Self::output) is derived
/// from it.
pub content: Vec<AssistantContent>,
/// Number of synthetic output-tool calls in the turn that finalized this
/// response. Kept crate-private because it is runner bookkeeping rather
/// than provider-facing response content.
#[serde(skip)]
pub(crate) output_tool_calls: usize,
}
impl std::fmt::Display for PromptResponse {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.output().fmt(f)
}
}
impl PromptResponse {
/// A response whose final turn is the single text part `output`, with the
/// run's `usage`.
pub fn new(output: impl Into<String>, usage: Usage) -> Self {
Self::from_content(vec![AssistantContent::text(output)], usage)
}
/// A response whose final turn is `content`.
pub(crate) fn from_content(content: Vec<AssistantContent>, usage: Usage) -> Self {
Self {
content,
usage,
completion_calls: Vec::new(),
messages: Vec::new(),
output_tool_calls: 0,
}
}
/// Record how many times the output tool was called.
pub(crate) fn with_output_tool_calls(mut self, count: usize) -> Self {
self.output_tool_calls = count;
self
}
/// How many times the output tool was called.
pub fn output_tool_calls(&self) -> usize {
self.output_tool_calls
}
/// The concatenated text parts of [`content`](Self::content). In
/// output-tool mode this is the serialized structured output.
pub fn output(&self) -> String {
AssistantContent::concat_text(&self.content)
}
/// Aggregated token usage across the whole run.
pub fn usage(&self) -> Usage {
self.usage
}
/// The run's transcript (see the [field](Self::messages)).
pub fn messages(&self) -> &[Message] {
&self.messages
}
/// The structured assistant content for the final turn (see the
/// [field](Self::content)).
pub fn content(&self) -> &[AssistantContent] {
&self.content
}
/// Returns successfully completed completion requests made by this agent run.
///
/// An entry whose counters are all `None` means the provider reported no
/// usage metrics for that request.
pub fn completion_calls(&self) -> &[CompletionCall] {
&self.completion_calls
}
/// Number of completion requests this agent run made.
pub fn requests(&self) -> usize {
self.completion_calls.len()
}
}
/// Replace calls and prose in a finished output-tool turn with final output text,
/// retaining reasoning and images. Call only after finalization, when remaining
/// calls are output-tool calls. Persisted history retains prose independently;
/// returns `None` if no call is present.
pub(crate) fn finalize_output_tool_choice(
choice: &[AssistantContent],
output: &str,
) -> Option<Vec<AssistantContent>> {
let finalized_via_output_tool = choice
.iter()
.any(|item| matches!(item, AssistantContent::ToolCall(_)));
if !finalized_via_output_tool {
return None;
}
let mut items: Vec<AssistantContent> = choice
.iter()
.filter(|item| {
!matches!(
item,
AssistantContent::ToolCall(_) | AssistantContent::Text(_)
)
})
.cloned()
.collect();
items.push(AssistantContent::text(output.to_string()));
Some(items)
}
use thiserror::Error;
/// Why an agent run failed, whether it was awaited or streamed.
///
/// Variants that wrap another error display it unchanged and forward its
/// source.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum PromptError {
/// A provider completion failed.
#[error(transparent)]
Provider(ProviderError),
/// Structured effect failure from a handler, a hook, or a stream item. A
/// relayed provider failure arrives as its report.
#[error(transparent)]
Report(#[from] rig_core::error::ErrorReport),
/// The run's conversation could not be loaded from its memory store,
/// before any model call, or the finished run could not be saved there
/// ([`AgentBuilder::memory`](crate::AgentBuilder::memory)). The run did
/// not succeed. A failed save may already have set aside a torn last
/// line the log ended in (to `recovered/` in the store) and stored the
/// blobs of the run's images; its own append stored nothing or, cut
/// short, a cut last line, which the next save sets aside. A remote
/// store that applied the append before failing to answer may hold all
/// of it.
#[error("the conversation memory failed: {error}")]
Memory {
/// Why the store refused or failed, such as
/// [`SessionError::Changed`](rig_memory::SessionError::Changed) when
/// another run saved to the log after this one loaded it.
#[source]
error: rig_memory::SessionError,
/// The finished run whose save failed; `None` when the load did.
response: Option<Box<PromptResponse>>,
},
/// The run exhausted its total model-call budget.
#[error("reached the max turns limit of {max_turns}")]
MaxTurns {
/// Configured total model-call budget.
max_turns: usize,
/// Canonical history available when the budget was exhausted.
chat_history: Vec<Message>,
/// Prompt for the call that could not be dispatched.
prompt: Message,
},
/// The run was cancelled.
#[error("the run was cancelled: {reason}")]
Cancelled {
/// The run's history at cancellation, every tool call answered
/// (closed by [`repair`](rig_core::conversation::pairing::repair)).
chat_history: Vec<Message>,
/// Human-readable cancellation reason.
reason: String,
},
/// The final answer missed the run's output schema, as
/// [`rig_core::tool::validate::validate`] checks it, once the
/// output-retry budget was spent. The message names the problems and the
/// answer's first 200 characters; the fields keep all of them.
#[error("{}", schema_mismatch_message(.output, .output_tool.as_deref(), .problems))]
OutputSchemaMismatch {
/// The whole answer: the text, or the output tool call's arguments,
/// re-serialized from their parsed JSON (key order and spacing may
/// differ from the model's), or their raw text when they are not a
/// JSON object.
output: String,
/// The output tool the model called, or `None` for a text answer.
output_tool: Option<String>,
/// Every problem found. Within an object, the problems of its fields
/// come first, in the parsed answer's key order (sorted by key unless
/// the build enables serde_json's `preserve_order`), then its missing
/// required fields, in the schema's `required` order.
problems: Vec<Problem>,
/// Canonical history at failure, without the refused answer.
chat_history: Vec<Message>,
},
/// The model attempted to call a tool unavailable for the current turn.
#[error(
"model attempted to call unknown or disallowed tool `{tool_name}`. Available tools: {available_tools:?}. Allowed tools for this turn: {allowed_tools:?}"
)]
UnknownToolCall {
/// Tool name emitted by the model.
tool_name: String,
/// Tools registered on the runtime.
available_tools: Vec<String>,
/// Exact immutable set allowed for this turn.
allowed_tools: Vec<String>,
/// Canonical history available at failure.
chat_history: Vec<Message>,
},
}
/// The problems as one line, `; `-separated.
pub(crate) fn join_problems(problems: &[Problem]) -> String {
problems
.iter()
.map(ToString::to_string)
.collect::<Vec<_>>()
.join("; ")
}
fn schema_mismatch_message(
output: &str,
output_tool: Option<&str>,
problems: &[Problem],
) -> String {
let problems = join_problems(problems);
let excerpt = match output.char_indices().nth(200) {
Some((end, _)) => format!("{}…", output.get(..end).unwrap_or_default()),
None => output.to_owned(),
};
let answer = match output_tool {
Some(name) => format!("the output tool `{name}` call"),
None => "the answer".to_owned(),
};
format!("{answer} does not satisfy the output schema ({problems}): {excerpt}")
}
/// A relayed failure is the report the origin sent.
impl From<ProviderError> for PromptError {
fn from(error: ProviderError) -> Self {
match error {
ProviderError::Relayed(report) => Self::Report(*report),
error => Self::Provider(error),
}
}
}
/// Forward provider response accessors through wrapped errors and optional reports.
macro_rules! forward_provider_response_helpers {
($err:ident, $variant:ident, $inner:literal $(, report = $report:ident)?) => {
impl $err {
#[doc = concat!("Returns the provider response body exposed by a wrapped ", $inner, ".")]
pub fn provider_response_body(&self) -> Option<&str> {
match self {
Self::$variant(error) => error.provider_response_body(),
$(Self::$report(report) => report.provider_response_body(),)?
_ => None,
}
}
#[doc = concat!("Parses the provider response body of a wrapped ", $inner, " as JSON when present.")]
pub fn provider_response_json(
&self,
) -> Result<Option<serde_json::Value>, serde_json::Error> {
match self {
Self::$variant(error) => error.provider_response_json(),
$(Self::$report(report) => report.provider_response_json(),)?
_ => Ok(None),
}
}
#[doc = concat!("Returns the provider transport request id exposed by a wrapped ", $inner, ", or carried by a wire report.")]
pub fn provider_request_id(&self) -> Option<&str> {
match self {
Self::$variant(error) => error.provider_request_id(),
$(Self::$report(report) => report.provider_request_id(),)?
_ => None,
}
}
#[doc = concat!("Returns the HTTP status exposed by a wrapped ", $inner, ", or carried by a wire report.")]
pub fn provider_response_status(&self) -> Option<http::StatusCode> {
match self {
Self::$variant(error) => error.provider_response_status(),
$(Self::$report(report) => report.provider_response_status(),)?
_ => None,
}
}
#[doc = concat!("Returns the response headers exposed by a wrapped ", $inner, " or report.")]
pub fn provider_response_headers(&self) -> Option<&http::HeaderMap> {
match self {
Self::$variant(error) => error.provider_response_headers(),
$(Self::$report(report) => report.provider_response_headers(),)?
_ => None,
}
}
}
};
}
pub(crate) use forward_provider_response_helpers;
forward_provider_response_helpers!(PromptError, Provider, "completion error", report = Report);
impl PromptError {
/// Build a [`PromptError::Cancelled`]. A driver gets the history from
/// [`AgentRun::cancel_error`](super::AgentRun::cancel_error), or closes
/// its own with [`repair`](rig_core::conversation::pairing::repair).
pub fn cancelled(chat_history: Vec<Message>, reason: impl Into<String>) -> Self {
Self::Cancelled {
chat_history,
reason: reason.into(),
}
}
}