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;