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