rig_agent/run/output.rs
1//! Structured-output enforcement modes for agent requests.
2//!
3//! ```
4//! use rig_agent::run::output::OutputMode;
5//! let mode = OutputMode::default();
6//! assert_eq!(mode, OutputMode::Auto);
7//! ```
8
9use serde::{Deserialize, Serialize};
10
11/// Select how requests convey an agent's output schema.
12///
13/// Whatever the mode, and whether or not the provider enforces the schema, a
14/// run ends only on an answer that is JSON fitting the schema, as
15/// [`rig_core::tool::validate::validate`] checks it: it asks the model again
16/// while its output-retry budget lasts, then fails.
17#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
18pub enum OutputMode {
19 /// Resolve to tool output when a schema and function tools are present,
20 /// tool choice permits it, and native output cannot compose with tools.
21 /// Otherwise use native output.
22 #[default]
23 Auto,
24 /// Offer the schema as a synthetic final-answer tool instead of a native
25 /// constraint. A text answer that satisfies the schema is also accepted.
26 Tool,
27 /// Send a native structured-output constraint on every turn.
28 /// Enforcement and compatibility with tool calls depend on provider
29 /// capabilities; a provider that drops the constraint is checked by the run.
30 Native,
31 /// Put the schema in the system prompt and return final text verbatim.
32 /// Prose or a markdown fence around the JSON may be present.
33 Prompted,
34}