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