Skip to main content

rig_agent/run/
spec.rs

1//! Serializable request settings, turn budgets, and output policies for runs.
2//! Live models, tools, and hooks remain owned by the driver.
3//!
4//! ```
5//! use rig_agent::run::spec::RunSpec;
6//! let spec = RunSpec::new();
7//! assert_eq!(spec.effective_max_turns(), 1);
8//! ```
9
10use rig_core::completion::{Document, GenerationOptions, ProviderOptions};
11use rig_core::message::ToolChoice;
12use serde::{Deserialize, Serialize};
13
14use super::output::OutputMode;
15
16/// Protocol-facing run configuration. See the [module docs](self).
17/// [`Default`] equals [`RunSpec::new`], and a field missing from serialized
18/// input takes its value from there.
19#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
20#[serde(default)]
21pub struct RunSpec {
22    /// System prompt.
23    pub preamble: Option<String>,
24    /// Documents always attached to the request.
25    pub static_context: Vec<Document>,
26    /// Provider-specific request parameters, merged into every request.
27    pub additional_params: Option<serde_json::Value>,
28    /// Portable generation options every request carries. Omitted from the
29    /// serialized spec while they hold their defaults.
30    #[serde(skip_serializing_if = "GenerationOptions::is_default")]
31    pub options: GenerationOptions,
32    /// Typed per-provider options every request carries. Omitted from the
33    /// serialized spec while empty.
34    #[serde(skip_serializing_if = "ProviderOptions::is_empty")]
35    pub provider_options: ProviderOptions,
36    /// Maximum tokens the model may generate per call.
37    pub max_tokens: Option<u64>,
38    /// Sampling temperature.
39    pub temperature: Option<f64>,
40    /// Tool choice applied to every model call.
41    pub tool_choice: Option<ToolChoice>,
42    /// Total model-call budget for the run. `None` means the protocol default
43    /// of one call.
44    pub max_turns: Option<usize>,
45    /// How many times an invalid model tool call may be retried with feedback.
46    pub max_invalid_tool_call_retries: usize,
47    /// How many consecutive turns may call a tool with arguments that are not
48    /// a JSON object. Each such call is answered with feedback; a turn whose
49    /// calls all parse resets the count. Past `Some(n)` such turns in a row,
50    /// the run fails. `None`, the default, sets no limit.
51    pub max_consecutive_malformed_tool_calls: Option<usize>,
52    /// JSON schema the final answer must satisfy, when structured output is
53    /// requested.
54    pub output_schema: Option<rig_core::schemars::Schema>,
55    /// How structured output is obtained.
56    pub output_mode: OutputMode,
57    /// Name of the synthetic output tool when output is collected through a
58    /// tool call; `None` lets the driver pick.
59    pub output_tool_name: Option<String>,
60    /// Description of that synthetic tool.
61    pub output_tool_description: Option<String>,
62    /// Whether the driver may augment the preamble with structured-output
63    /// instructions.
64    pub augment_output_preamble: bool,
65    /// What the run does with a model tool call that cannot be dispatched as
66    /// written when no hook resolves it.
67    pub unhandled_invalid_tool_call: UnhandledInvalidToolCall,
68    /// Whether a finish reason outside the normalized vocabulary ends a turn
69    /// as a normal stop. Carried into every prepared request. Defaults to
70    /// `false`.
71    pub accept_unknown_finish_reasons: bool,
72}
73
74/// Policy applied when every [`on_invalid_tool_call`] hook declines to resolve
75/// a call to an unknown or disallowed tool. Defaults to failure; ignoring drops
76/// the call and continues.
77///
78/// [`on_invalid_tool_call`]: crate::agent::AgentHook::on_invalid_tool_call
79#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
80#[serde(rename_all = "snake_case")]
81pub enum UnhandledInvalidToolCall {
82    /// Fail the run.
83    #[default]
84    Fail,
85    /// Drop the call and continue the turn.
86    Ignore,
87}
88
89impl RunSpec {
90    /// Create a spec with a one-call budget, no preamble, tool choice, or schema,
91    /// and output-preamble augmentation enabled.
92    pub fn new() -> Self {
93        Self {
94            preamble: None,
95            static_context: Vec::new(),
96            additional_params: None,
97            options: GenerationOptions::default(),
98            provider_options: ProviderOptions::default(),
99            max_tokens: None,
100            temperature: None,
101            tool_choice: None,
102            max_turns: None,
103            max_invalid_tool_call_retries: 0,
104            max_consecutive_malformed_tool_calls: None,
105            output_schema: None,
106            output_mode: OutputMode::default(),
107            output_tool_name: None,
108            output_tool_description: None,
109            augment_output_preamble: true,
110            unhandled_invalid_tool_call: UnhandledInvalidToolCall::default(),
111            accept_unknown_finish_reasons: false,
112        }
113    }
114
115    /// The turn budget the protocol will use.
116    pub fn effective_max_turns(&self) -> usize {
117        self.max_turns.unwrap_or(1)
118    }
119}
120
121impl Default for RunSpec {
122    fn default() -> Self {
123        Self::new()
124    }
125}
126
127impl RunSpec {
128    /// How many times a run re-prompts for structured output that failed
129    /// validation before giving up. The default a run built from a spec
130    /// carries; drivers that construct runs by hand pass it explicitly.
131    pub const DEFAULT_OUTPUT_RETRIES: usize = 1;
132}
133
134#[cfg(test)]
135mod tests;