Skip to main content

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}