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::{Agent, runner::AgentRunner};
22use crate::{
23    completion::{Message, StructuredOutputError, Usage},
24    run::response::{CompletionCall, PromptResponse},
25    run::{OutputMode, spec::UnhandledInvalidToolCall},
26};
27
28/// A typed run's response: the deserialized value plus the accepted attempt's
29/// transcript, the run's usage, and completion calls.
30#[derive(Debug, Clone, Serialize, Deserialize)]
31pub struct TypedPromptResponse<T> {
32    /// The parsed structured output.
33    pub output: T,
34    /// Usage accumulated across every attempt, including attempts that
35    /// received a billed response but failed to produce a parseable value.
36    pub usage: Usage,
37    /// Successfully completed completion requests made by the accepted attempt.
38    ///
39    /// `usage` remains the aggregate across the whole run. Use the last
40    /// entry's usage to inspect the final completion request's prompt/context
41    /// length. An entry whose counters are all `None` means the provider
42    /// reported no usage metrics for that request.
43    #[serde(default, skip_serializing_if = "Vec::is_empty")]
44    pub completion_calls: Vec<CompletionCall>,
45    /// The accepted attempt's transcript; see
46    /// [`PromptResponse::messages`](crate::agent::PromptResponse::messages).
47    /// Append it to caller-owned history to continue the conversation.
48    #[serde(default)]
49    pub messages: Vec<Message>,
50}
51
52impl<T> TypedPromptResponse<T> {
53    /// A response of `output` with the run's `usage`.
54    pub fn new(output: T, usage: Usage) -> Self {
55        Self {
56            output,
57            usage,
58            completion_calls: Vec::new(),
59            messages: Vec::new(),
60        }
61    }
62
63    /// Attach completion call details to this response.
64    pub fn with_completion_calls(mut self, completion_calls: Vec<CompletionCall>) -> Self {
65        self.completion_calls = completion_calls;
66        self
67    }
68
69    /// Returns successfully completed completion requests made by this agent run.
70    ///
71    /// An entry whose counters are all `None` means the provider reported no
72    /// usage metrics for that request.
73    pub fn completion_calls(&self) -> &[CompletionCall] {
74        &self.completion_calls
75    }
76
77    /// Number of completion requests this agent run made.
78    pub fn requests(&self) -> usize {
79        self.completion_calls.len()
80    }
81}
82
83/// How a [`TypedRun`] recovers `T` from the accepted [`PromptResponse`].
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
85enum OutputSource {
86    /// Parse the model's final text; tolerate prose or fences around the JSON.
87    Native,
88    /// The value is the arguments of the run's output tool call; the model not
89    /// calling it is an empty response.
90    OutputTool,
91}
92
93/// The typed-output state of a [`TypedRun`]: how `T` is recovered from the
94/// accepted response and how many failed attempts are retried.
95#[derive(Debug)]
96pub struct TypedOutput<T> {
97    source: OutputSource,
98    retries: usize,
99    _t: PhantomData<fn() -> T>,
100}
101
102/// A run that deserializes its accepted output as `T`.
103///
104/// Configure it with the same setters as [`AgentRunner`], then `.await` it for
105/// a [`TypedPromptResponse<T>`]. With a [`retries`](AgentRunner::retries) budget, a
106/// failed attempt (run error, empty output, unparseable output) is retried
107/// from scratch; usage accumulates across attempts.
108pub type TypedRun<T> = AgentRunner<TypedOutput<T>>;
109
110impl<T> TypedRun<T>
111where
112    T: JsonSchema + DeserializeOwned + WasmCompatSend,
113{
114    /// A native-mode typed run: the schema for `T` is the run's structured
115    /// output schema and the model's final text is parsed as `T`.
116    pub(crate) fn native(agent: &Agent, prompt: impl Into<Message>) -> Self {
117        let mut runner = AgentRunner::from_agent(agent, prompt);
118        runner.config.spec_mut().output_schema = Some(schema_for!(T));
119        // Native typed prompting parses final text rather than requiring an output call.
120        runner.config.spec_mut().output_mode = OutputMode::Native;
121        Self::from_runner(runner, OutputSource::Native)
122    }
123
124    /// An output-tool typed run over an already configured runner: the value
125    /// is the arguments of the run's output tool call. Unhandled invalid tool
126    /// calls are ignored rather than failing the run.
127    pub(crate) fn output_tool(runner: AgentRunner) -> Self {
128        Self::from_runner(
129            runner.unhandled_invalid_tool_call(UnhandledInvalidToolCall::Ignore),
130            OutputSource::OutputTool,
131        )
132    }
133
134    fn from_runner(runner: AgentRunner, source: OutputSource) -> Self {
135        let output = TypedOutput {
136            source,
137            retries: 0,
138            _t: PhantomData,
139        };
140        runner.replace_output(output).0
141    }
142
143    /// Retry a failed attempt up to `retries` more times. An attempt fails when
144    /// the run errors, produces no output, or produces output that does not
145    /// parse as `T`. Usage accumulates across attempts.
146    pub fn retries(mut self, retries: usize) -> Self {
147        self.output.retries = retries;
148        self
149    }
150
151    async fn send(
152        self,
153        ambient: tracing::Span,
154    ) -> Result<TypedPromptResponse<T>, StructuredOutputError> {
155        let (
156            runner,
157            TypedOutput {
158                source, retries, ..
159            },
160        ) = self.replace_output(());
161        let mut usage = Usage::default();
162        let mut last_error = None;
163
164        for attempt in 0..=retries {
165            if retries > 0 {
166                tracing::debug!(
167                    "Attempting to extract structured output. Retries left: {}",
168                    retries - attempt
169                );
170            }
171            let (result, error_usage) = runner.clone().run_with_error_usage(ambient.clone()).await;
172            let outcome = match result {
173                Ok(response) => {
174                    usage += response.usage;
175                    recover_output(&response, source).map(|output| TypedPromptResponse {
176                        output,
177                        usage,
178                        completion_calls: response.completion_calls,
179                        messages: response.messages,
180                    })
181                }
182                Err(err) => {
183                    usage += error_usage;
184                    Err(StructuredOutputError::Prompt(err))
185                }
186            };
187            match outcome {
188                Ok(response) => return Ok(response),
189                Err(err) => {
190                    if attempt < retries {
191                        tracing::warn!(
192                            "Attempt {attempt} to extract structured output failed: {err:?}. Retrying..."
193                        );
194                    }
195                    last_error = Some(err);
196                }
197            }
198        }
199
200        Err(last_error.unwrap_or(StructuredOutputError::EmptyResponse))
201    }
202}
203
204/// Recover `T` from an accepted response according to the run's output mode.
205fn recover_output<T: DeserializeOwned>(
206    response: &PromptResponse,
207    source: OutputSource,
208) -> Result<T, StructuredOutputError> {
209    let output = response.output();
210    match source {
211        OutputSource::Native => {
212            if output.is_empty() {
213                return Err(StructuredOutputError::EmptyResponse);
214            }
215            deserialize_structured_output(&output)
216                .map_err(|error| deserialization_error(&output, error))
217        }
218        OutputSource::OutputTool => {
219            let submissions = response.output_tool_calls();
220            // A whole JSON answer is the run's output too: the protocol accepts
221            // schema-valid text, and a model that rejects forced tool choice
222            // answers in native structured output instead of calling the tool.
223            if submissions == 0
224                && let Ok(value) = serde_json::from_str::<T>(output.trim())
225            {
226                return Ok(value);
227            }
228            if submissions == 0 {
229                tracing::warn!(
230                    "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."
231                );
232                return Err(StructuredOutputError::EmptyResponse);
233            }
234            if submissions > 1 {
235                tracing::warn!(
236                    "Multiple submit calls detected, using the first one. Providers / agents should only ensure one submit call."
237                );
238            }
239            serde_json::from_str(&output).map_err(|error| deserialization_error(&output, error))
240        }
241    }
242}
243
244fn deserialization_error(output: &str, error: serde_json::Error) -> StructuredOutputError {
245    StructuredOutputError::Deserialization {
246        output: output.to_string(),
247        error,
248    }
249}
250
251/// Deserialize final text directly, then try one value starting at the first
252/// object or array delimiter. Returns a parse error if neither attempt yields `T`.
253pub(crate) fn deserialize_structured_output<T: DeserializeOwned>(
254    text: &str,
255) -> Result<T, serde_json::Error> {
256    let trimmed = text.trim();
257    match serde_json::from_str::<T>(trimmed) {
258        Ok(value) => Ok(value),
259        Err(direct_err) => {
260            let Some(start) = trimmed.find(['{', '[']) else {
261                return Err(direct_err);
262            };
263            serde_json::Deserializer::from_str(&trimmed[start..])
264                .into_iter::<T>()
265                .next()
266                .unwrap_or(Err(direct_err))
267        }
268    }
269}
270
271impl<T> IntoFuture for TypedRun<T>
272where
273    T: JsonSchema + DeserializeOwned + WasmCompatSend + 'static,
274{
275    type Output = Result<TypedPromptResponse<T>, StructuredOutputError>;
276    type IntoFuture = WasmBoxedFuture<'static, Self::Output>;
277
278    fn into_future(self) -> Self::IntoFuture {
279        // Captured in the synchronous part of the call, like `run()`: a
280        // typed run belongs to the span it was started in, not to the task
281        // that first polls it.
282        let ambient = tracing::Span::current();
283        let run_under = ambient.clone();
284        Box::pin(self.send(run_under).instrument(ambient))
285    }
286}