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;