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