rig_agent/agent/typed.rs
1//! Typed run outputs with optional retries for execution or deserialization failures.
2//! Native prompting parses final text; extractors require an output-tool call.
3//!
4//! ```no_run
5//! # async fn example(agent: rig_agent::Agent) -> Result<(), rig_agent::completion::StructuredOutputError> {
6//! let response = agent.prompt_typed::<Vec<String>>("List three colors.").retries(1).await?;
7//! assert_eq!(response.output.len(), 3);
8//! # Ok(())
9//! # }
10//! ```
11
12use std::{future::IntoFuture, marker::PhantomData};
13
14use schemars::{JsonSchema, schema_for};
15use serde::de::DeserializeOwned;
16use serde::{Deserialize, Serialize};
17
18use rig_core::wasm_compat::{WasmBoxedFuture, WasmCompatSend};
19use tracing_futures::Instrument;
20
21use super::{
22 Agent,
23 hook::AgentHook,
24 run::{OutputMode, spec::UnhandledInvalidToolCall},
25 runner::AgentRunner,
26};
27use crate::{
28 completion::{Message, StructuredOutputError, Usage},
29 run::response::{CompletionCall, PromptResponse},
30 tool::ToolContext,
31};
32
33/// A typed run's response: the deserialized value plus the run's usage and
34/// completion calls.
35#[derive(Debug, Clone, Serialize, Deserialize)]
36pub struct TypedPromptResponse<T> {
37 /// The parsed structured output.
38 pub output: T,
39 /// Usage accumulated across every attempt, including attempts that
40 /// received a billed response but failed to produce a parseable value.
41 pub usage: Usage,
42 /// Successfully completed completion requests made by the accepted attempt.
43 ///
44 /// `usage` remains the aggregate across the whole run. Use the last
45 /// entry's usage to inspect the final completion request's prompt/context
46 /// length. An entry whose counters are all `None` means the provider
47 /// reported no usage metrics for that request.
48 #[serde(default, skip_serializing_if = "Vec::is_empty")]
49 pub completion_calls: Vec<CompletionCall>,
50 /// How the accepted attempt's conversation-memory append settled; see
51 /// [`PromptResponse::memory_append`](crate::agent::PromptResponse::memory_append).
52 #[serde(default, skip_serializing_if = "Option::is_none")]
53 pub memory_append: Option<crate::run::MemoryAppend>,
54}
55
56impl<T> TypedPromptResponse<T> {
57 /// A response of `output` with the run's `usage`.
58 pub fn new(output: T, usage: Usage) -> Self {
59 Self {
60 output,
61 usage,
62 completion_calls: Vec::new(),
63 memory_append: None,
64 }
65 }
66
67 /// Attach completion call details to this response.
68 pub fn with_completion_calls(mut self, completion_calls: Vec<CompletionCall>) -> Self {
69 self.completion_calls = completion_calls;
70 self
71 }
72
73 /// Returns successfully completed completion requests made by this agent run.
74 ///
75 /// An entry whose counters are all `None` means the provider reported no
76 /// usage metrics for that request.
77 pub fn completion_calls(&self) -> &[CompletionCall] {
78 &self.completion_calls
79 }
80
81 /// Number of completion requests this agent run made.
82 pub fn requests(&self) -> usize {
83 self.completion_calls.len()
84 }
85}
86
87/// How a [`TypedRun`] recovers `T` from the accepted [`PromptResponse`].
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
89pub(crate) enum TypedOutput {
90 /// Parse the model's final text; tolerate prose or fences around the JSON.
91 Native,
92 /// The value is the arguments of the run's output tool call; the model not
93 /// calling it is an empty response.
94 OutputTool,
95}
96
97/// A run that deserializes its accepted output as `T`.
98///
99/// Configure it with the same setters as [`AgentRunner`], then `.await` it for
100/// a [`TypedPromptResponse<T>`]. With a [`retries`](Self::retries) budget, a
101/// failed attempt (run error, empty output, unparseable output) is retried
102/// from scratch; usage accumulates across attempts.
103#[must_use = "a typed run does nothing until awaited"]
104pub struct TypedRun<T> {
105 runner: AgentRunner,
106 retries: u64,
107 output: TypedOutput,
108 _t: PhantomData<T>,
109}
110
111/// The setters that forward verbatim to the inner [`AgentRunner`].
112macro_rules! forward_runner_setters {
113 () => {
114 /// Attach a per-call [`ToolContext`] for this run.
115 ///
116 /// Every tool the agent executes during this run can read the
117 /// caller-provided values (auth tokens, session IDs, conversation state, …)
118 /// through the tool's [`ToolContext`](crate::tool::ToolContext),
119 /// without the model ever seeing them.
120 pub fn tool_context(mut self, context: ToolContext) -> Self {
121 self.runner = self.runner.tool_context(context);
122 self
123 }
124
125 /// Add chat history to the run.
126 pub fn history<H, Item>(mut self, history: H) -> Self
127 where
128 H: IntoIterator<Item = Item>,
129 Item: Into<Message>,
130 {
131 self.runner = self.runner.history(history);
132 self
133 }
134
135 /// Override the agent preamble for this run.
136 pub fn preamble(mut self, preamble: impl Into<String>) -> Self {
137 self.runner = self.runner.preamble(preamble);
138 self
139 }
140
141 /// Remove the agent's configured preamble for this run.
142 pub fn without_preamble(mut self) -> Self {
143 self.runner = self.runner.without_preamble();
144 self
145 }
146
147 /// Append one static context document for this run.
148 pub fn document(mut self, document: crate::completion::Document) -> Self {
149 self.runner = self.runner.document(document);
150 self
151 }
152
153 /// Append static context documents for this run.
154 pub fn documents(
155 mut self,
156 documents: impl IntoIterator<Item = crate::completion::Document>,
157 ) -> Self {
158 self.runner = self.runner.documents(documents);
159 self
160 }
161
162 /// Override the model temperature for this run.
163 pub fn temperature(mut self, temperature: f64) -> Self {
164 self.runner = self.runner.temperature(temperature);
165 self
166 }
167
168 /// Remove the agent's configured temperature for this run.
169 pub fn without_temperature(mut self) -> Self {
170 self.runner = self.runner.without_temperature();
171 self
172 }
173
174 /// Override the maximum completion token count for this run.
175 pub fn max_tokens(mut self, max_tokens: u64) -> Self {
176 self.runner = self.runner.max_tokens(max_tokens);
177 self
178 }
179
180 /// Remove the agent's configured maximum token count for this run.
181 pub fn without_max_tokens(mut self) -> Self {
182 self.runner = self.runner.without_max_tokens();
183 self
184 }
185
186 /// Shallow-merge object fields into the provider-specific parameters
187 /// for this run. Later fields win.
188 pub fn merge_additional_params(
189 mut self,
190 params: serde_json::Map<String, serde_json::Value>,
191 ) -> Self {
192 self.runner = self.runner.merge_additional_params(params);
193 self
194 }
195
196 /// Replace all provider-specific parameters for this run.
197 pub fn replace_additional_params(mut self, params: serde_json::Value) -> Self {
198 self.runner = self.runner.replace_additional_params(params);
199 self
200 }
201
202 /// Remove the agent's configured provider-specific parameters for this run.
203 pub fn without_additional_params(mut self) -> Self {
204 self.runner = self.runner.without_additional_params();
205 self
206 }
207
208 /// Override the tool-choice policy for this run.
209 pub fn tool_choice(mut self, tool_choice: rig_core::message::ToolChoice) -> Self {
210 self.runner = self.runner.tool_choice(tool_choice);
211 self
212 }
213
214 /// Remove the agent's configured tool-choice policy for this run.
215 pub fn without_tool_choice(mut self) -> Self {
216 self.runner = self.runner.without_tool_choice();
217 self
218 }
219
220 /// Opt in or out of recording sensitive request, response, and tool
221 /// content on GenAI telemetry spans for this run.
222 ///
223 /// Defaults to the agent's setting, which defaults to `false`. Enabling
224 /// this can expose prompts, retrieved context, tool results, model
225 /// responses, and other sensitive or high-cardinality data through
226 /// OpenTelemetry span attributes. Structural metadata and token usage
227 /// remain available when disabled.
228 pub fn record_content_telemetry(mut self, enabled: bool) -> Self {
229 self.runner = self.runner.record_content_telemetry(enabled);
230 self
231 }
232
233 /// Set the conversation id used to load and persist memory for this run.
234 ///
235 /// Overrides any default conversation id set on the agent. If memory is not
236 /// configured on the agent, this has no effect.
237 pub fn conversation(mut self, id: impl Into<rig_core::id::ConversationId>) -> Self {
238 self.runner = self.runner.conversation(id);
239 self
240 }
241
242 /// Disable conversation memory for this run.
243 ///
244 /// History will neither be loaded from nor saved to the agent's memory backend.
245 pub fn without_memory(mut self) -> Self {
246 self.runner = self.runner.without_memory();
247 self
248 }
249
250 /// Set the retry budget for invalid tool-call recovery.
251 ///
252 /// Invalid tool-call retries also consume the total model-call budget.
253 pub fn max_invalid_tool_call_retries(mut self, retries: usize) -> Self {
254 self.runner = self.runner.max_invalid_tool_call_retries(retries);
255 self
256 }
257
258 /// Set the default model candidate for this run.
259 ///
260 /// This does not suppress registered model-selection hooks, which may
261 /// replace this candidate before each model call (including retries).
262 pub fn using_model(mut self, model: impl Into<$crate::agent::ModelRef>) -> Self {
263 self.runner = self.runner.using_model(model);
264 self
265 }
266
267 /// Erase and set a typed default model for this run.
268 pub fn using_model_value(
269 mut self,
270 model: impl Into<rig_core::DynModel<rig_core::operation::Completion>>,
271 ) -> Self {
272 self.runner = self.runner.using_model_value(model);
273 self
274 }
275
276 /// Set the total model-call budget, including the initial call and every
277 /// retry or continuation. Zero emits no model calls; one permits only the
278 /// initial call. Exceeding the budget returns a
279 /// [`StructuredOutputError::PromptError`] wrapping a `MaxTurnsError`.
280 pub fn max_turns(mut self, max_turns: usize) -> Self {
281 self.runner = self.runner.max_turns(max_turns);
282 self
283 }
284
285 /// Append a hook to this run's hook stack (on top of any the agent
286 /// already carries). See the [`hook`](crate::agent::hook) module docs.
287 pub fn add_hook<H>(mut self, hook: H) -> Self
288 where
289 H: AgentHook + 'static,
290 {
291 self.runner = self.runner.add_hook(hook);
292 self
293 }
294
295 /// Execute up to `concurrency` of a turn's tool calls at once. See
296 /// [`AgentRunner::tool_concurrency`] for ordering guarantees.
297 pub fn tool_concurrency(mut self, concurrency: usize) -> Self {
298 self.runner = self.runner.tool_concurrency(concurrency);
299 self
300 }
301 };
302}
303
304impl<T> TypedRun<T>
305where
306 T: JsonSchema + DeserializeOwned + WasmCompatSend,
307{
308 /// A native-mode typed run: the schema for `T` is the run's structured
309 /// output schema and the model's final text is parsed as `T`.
310 pub(crate) fn native(agent: &Agent, prompt: impl Into<Message>) -> Self {
311 let mut runner = AgentRunner::from_agent(agent, prompt);
312 runner.config.output_schema = Some(schema_for!(T));
313 // Native typed prompting parses final text rather than requiring an output call.
314 runner.config.output_mode = OutputMode::Native;
315 Self::from_runner(runner, TypedOutput::Native)
316 }
317
318 /// An output-tool typed run over an already configured runner: the value
319 /// is the arguments of the run's output tool call. Unhandled invalid tool
320 /// calls are ignored rather than failing the run.
321 pub(crate) fn output_tool(runner: AgentRunner) -> Self {
322 Self::from_runner(
323 runner.unhandled_invalid_tool_call(UnhandledInvalidToolCall::Ignore),
324 TypedOutput::OutputTool,
325 )
326 }
327
328 pub(crate) fn from_runner(runner: AgentRunner, output: TypedOutput) -> Self {
329 Self {
330 runner,
331 retries: 0,
332 output,
333 _t: PhantomData,
334 }
335 }
336
337 /// Retry a failed attempt up to `retries` more times. An attempt fails when
338 /// the run errors, produces no output, or produces output that does not
339 /// parse as `T`. Usage accumulates across attempts.
340 pub fn retries(mut self, retries: u64) -> Self {
341 self.retries = retries;
342 self
343 }
344
345 forward_runner_setters!();
346
347 async fn send(
348 self,
349 ambient: tracing::Span,
350 ) -> Result<TypedPromptResponse<T>, StructuredOutputError> {
351 let mut usage = Usage::default();
352 let mut last_error = None;
353
354 for attempt in 0..=self.retries {
355 if self.retries > 0 {
356 tracing::debug!(
357 "Attempting to extract structured output. Retries left: {}",
358 self.retries - attempt
359 );
360 }
361 let (result, error_usage) = self
362 .runner
363 .clone()
364 .run_with_error_usage(ambient.clone())
365 .await;
366 let outcome = match result {
367 Ok(response) => {
368 usage += response.usage;
369 recover_output(&response, self.output).map(|output| TypedPromptResponse {
370 output,
371 usage,
372 completion_calls: response.completion_calls,
373 memory_append: response.memory_append,
374 })
375 }
376 Err(err) => {
377 usage += error_usage;
378 Err(StructuredOutputError::PromptError(err))
379 }
380 };
381 match outcome {
382 Ok(response) => return Ok(response),
383 Err(err) => {
384 if attempt < self.retries {
385 tracing::warn!(
386 "Attempt {attempt} to extract structured output failed: {err:?}. Retrying..."
387 );
388 }
389 last_error = Some(err);
390 }
391 }
392 }
393
394 Err(last_error.unwrap_or(StructuredOutputError::EmptyResponse))
395 }
396}
397
398/// Recover `T` from an accepted response according to the run's output mode.
399fn recover_output<T: DeserializeOwned>(
400 response: &PromptResponse,
401 output: TypedOutput,
402) -> Result<T, StructuredOutputError> {
403 match output {
404 TypedOutput::Native => {
405 if response.output.is_empty() {
406 return Err(StructuredOutputError::EmptyResponse);
407 }
408 Ok(deserialize_structured_output(&response.output)?)
409 }
410 TypedOutput::OutputTool => {
411 let submissions = response.output_tool_calls();
412 // A whole JSON answer is the run's output too: the protocol accepts
413 // schema-valid text, and a model that rejects forced tool choice
414 // answers in native structured output instead of calling the tool.
415 if submissions == 0
416 && let Ok(value) = serde_json::from_str::<T>(response.output.trim())
417 {
418 return Ok(value);
419 }
420 if submissions == 0 {
421 tracing::warn!(
422 "The submit tool was not called. If this happens more than once, please ensure the model you are using is powerful enough to reliably call tools."
423 );
424 return Err(StructuredOutputError::EmptyResponse);
425 }
426 if submissions > 1 {
427 tracing::warn!(
428 "Multiple submit calls detected, using the first one. Providers / agents should only ensure one submit call."
429 );
430 }
431 Ok(serde_json::from_str(&response.output)?)
432 }
433 }
434}
435
436/// Deserialize final text directly, then try one value starting at the first
437/// object or array delimiter. Returns a parse error if neither attempt yields `T`.
438pub(crate) fn deserialize_structured_output<T: DeserializeOwned>(
439 text: &str,
440) -> Result<T, serde_json::Error> {
441 let trimmed = text.trim();
442 match serde_json::from_str::<T>(trimmed) {
443 Ok(value) => Ok(value),
444 Err(direct_err) => {
445 let Some(start) = trimmed.find(['{', '[']) else {
446 return Err(direct_err);
447 };
448 serde_json::Deserializer::from_str(&trimmed[start..])
449 .into_iter::<T>()
450 .next()
451 .unwrap_or(Err(direct_err))
452 }
453 }
454}
455
456impl<T> IntoFuture for TypedRun<T>
457where
458 T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static,
459{
460 type Output = Result<TypedPromptResponse<T>, StructuredOutputError>;
461 type IntoFuture = WasmBoxedFuture<'static, Self::Output>;
462
463 fn into_future(self) -> Self::IntoFuture {
464 // Captured in the synchronous part of the call, like `run()`: a
465 // typed run belongs to the span it was started in, not to the task
466 // that first polls it.
467 let ambient = tracing::Span::current();
468 let run_under = ambient.clone();
469 Box::pin(self.send(run_under).instrument(ambient))
470 }
471}