Skip to main content

objectiveai_sdk/agent/
agent.rs

1//! Core Agent types — unified enum dispatching to per-upstream implementations.
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5
6// ── Pre-validation types (no computed ID) ──────────────────────────
7
8/// The base inline configuration for an Agent (without computed ID or metadata).
9///
10/// This is an untagged enum that dispatches to the per-upstream AgentBase.
11/// Deserialization tries each variant in order until one matches.
12#[derive(
13    Clone,
14    Debug,
15    PartialEq,
16    Serialize,
17    Deserialize,
18    JsonSchema,
19    arbitrary::Arbitrary,
20)]
21#[serde(untagged)]
22#[schemars(rename = "agent.InlineAgentBase")]
23pub enum InlineAgentBase {
24    #[schemars(title = "Openrouter")]
25    Openrouter(super::openrouter::AgentBase),
26    #[schemars(title = "ClaudeAgentSdk")]
27    ClaudeAgentSdk(super::claude_agent_sdk::AgentBase),
28    #[schemars(title = "CodexSdk")]
29    CodexSdk(super::codex_sdk::AgentBase),
30    #[schemars(title = "Mock")]
31    Mock(super::mock::AgentBase),
32    #[schemars(title = "Script")]
33    Script(super::script::AgentBase),
34}
35
36impl InlineAgentBase {
37    pub fn as_ref(&self) -> InlineAgentRef<'_> {
38        match self {
39            InlineAgentBase::Openrouter(b) => InlineAgentRef::Openrouter(b),
40            InlineAgentBase::ClaudeAgentSdk(b) => {
41                InlineAgentRef::ClaudeAgentSdk(b)
42            }
43            InlineAgentBase::CodexSdk(b) => InlineAgentRef::CodexSdk(b),
44            InlineAgentBase::Mock(b) => InlineAgentRef::Mock(b),
45            InlineAgentBase::Script(b) => InlineAgentRef::Script(b),
46        }
47    }
48
49    pub fn model(&self) -> &str {
50        self.as_ref().model()
51    }
52
53    pub fn upstream(&self) -> super::Upstream {
54        self.as_ref().upstream()
55    }
56
57    pub fn output_mode(&self) -> super::OutputMode {
58        self.as_ref().output_mode()
59    }
60
61    pub fn mcp_servers(&self) -> Option<&super::McpServers> {
62        self.as_ref().mcp_servers()
63    }
64
65    pub fn laboratories(&self) -> Option<&super::Laboratories> {
66        self.as_ref().laboratories()
67    }
68
69    pub fn plugins(&self) -> &[super::Plugin] {
70        self.as_ref().plugins()
71    }
72
73    pub fn prepare(&mut self) {
74        match self {
75            InlineAgentBase::Openrouter(b) => b.prepare(),
76            InlineAgentBase::ClaudeAgentSdk(b) => b.prepare(),
77            InlineAgentBase::CodexSdk(b) => b.prepare(),
78            InlineAgentBase::Mock(b) => b.prepare(),
79            InlineAgentBase::Script(b) => b.prepare(),
80        }
81    }
82
83    pub fn validate(&self) -> Result<(), String> {
84        match self {
85            InlineAgentBase::Openrouter(b) => b.validate(),
86            InlineAgentBase::ClaudeAgentSdk(b) => b.validate(),
87            InlineAgentBase::CodexSdk(b) => b.validate(),
88            InlineAgentBase::Mock(b) => b.validate(),
89            InlineAgentBase::Script(b) => b.validate(),
90        }
91    }
92
93    pub fn id(&self) -> String {
94        match self {
95            InlineAgentBase::Openrouter(b) => b.id(),
96            InlineAgentBase::ClaudeAgentSdk(b) => b.id(),
97            InlineAgentBase::CodexSdk(b) => b.id(),
98            InlineAgentBase::Mock(b) => b.id(),
99            InlineAgentBase::Script(b) => b.id(),
100        }
101    }
102
103    /// Validates and converts to an [`InlineAgent`] with computed ID.
104    pub fn convert(self) -> Result<InlineAgent, String> {
105        match self {
106            InlineAgentBase::Openrouter(b) => {
107                Ok(InlineAgent::Openrouter(b.try_into()?))
108            }
109            InlineAgentBase::ClaudeAgentSdk(b) => {
110                Ok(InlineAgent::ClaudeAgentSdk(b.try_into()?))
111            }
112            InlineAgentBase::CodexSdk(b) => {
113                Ok(InlineAgent::CodexSdk(b.try_into()?))
114            }
115            InlineAgentBase::Mock(b) => Ok(InlineAgent::Mock(b.try_into()?)),
116            InlineAgentBase::Script(b) => {
117                Ok(InlineAgent::Script(b.try_into()?))
118            }
119        }
120    }
121}
122
123/// A remote agent base definition with metadata.
124///
125/// Like [`InlineAgentBase`] but includes a description field for remote storage.
126#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
127#[schemars(rename = "agent.RemoteAgentBase")]
128pub struct RemoteAgentBase {
129    pub description: String,
130    #[serde(flatten)]
131    #[schemars(schema_with = "crate::flatten_schema::<InlineAgentBase>")]
132    pub inner: InlineAgentBase,
133}
134
135impl RemoteAgentBase {
136    pub fn as_ref(&self) -> InlineAgentRef<'_> {
137        self.inner.as_ref()
138    }
139
140    pub fn model(&self) -> &str {
141        self.inner.model()
142    }
143
144    pub fn upstream(&self) -> super::Upstream {
145        self.inner.upstream()
146    }
147
148    pub fn output_mode(&self) -> super::OutputMode {
149        self.inner.output_mode()
150    }
151
152    pub fn mcp_servers(&self) -> Option<&super::McpServers> {
153        self.inner.mcp_servers()
154    }
155
156    pub fn laboratories(&self) -> Option<&super::Laboratories> {
157        self.inner.laboratories()
158    }
159
160    pub fn plugins(&self) -> &[super::Plugin] {
161        self.inner.plugins()
162    }
163
164    pub fn prepare(&mut self) {
165        self.inner.prepare()
166    }
167
168    pub fn validate(&self) -> Result<(), String> {
169        self.inner.validate()
170    }
171
172    pub fn id(&self) -> String {
173        self.inner.id()
174    }
175
176    /// Validates and converts to a [`RemoteAgent`] with computed ID.
177    pub fn convert(self) -> Result<RemoteAgent, String> {
178        Ok(RemoteAgent {
179            description: self.description,
180            inner: self.inner.convert()?,
181        })
182    }
183}
184
185/// An Agent base definition, either remote (with metadata) or inline.
186#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
187#[serde(untagged)]
188#[schemars(rename = "agent.AgentBase")]
189pub enum AgentBase {
190    #[schemars(title = "Remote")]
191    Remote(RemoteAgentBase),
192    #[schemars(title = "Inline")]
193    Inline(InlineAgentBase),
194}
195
196impl AgentBase {
197    pub fn as_ref(&self) -> InlineAgentRef<'_> {
198        match self {
199            AgentBase::Remote(r) => r.as_ref(),
200            AgentBase::Inline(i) => i.as_ref(),
201        }
202    }
203
204    pub fn model(&self) -> &str {
205        match self {
206            AgentBase::Remote(r) => r.model(),
207            AgentBase::Inline(i) => i.model(),
208        }
209    }
210
211    pub fn upstream(&self) -> super::Upstream {
212        match self {
213            AgentBase::Remote(r) => r.upstream(),
214            AgentBase::Inline(i) => i.upstream(),
215        }
216    }
217
218    pub fn output_mode(&self) -> super::OutputMode {
219        match self {
220            AgentBase::Remote(r) => r.output_mode(),
221            AgentBase::Inline(i) => i.output_mode(),
222        }
223    }
224
225    pub fn mcp_servers(&self) -> Option<&super::McpServers> {
226        match self {
227            AgentBase::Remote(r) => r.mcp_servers(),
228            AgentBase::Inline(i) => i.mcp_servers(),
229        }
230    }
231
232    pub fn laboratories(&self) -> Option<&super::Laboratories> {
233        match self {
234            AgentBase::Remote(r) => r.laboratories(),
235            AgentBase::Inline(i) => i.laboratories(),
236        }
237    }
238
239    pub fn plugins(&self) -> &[super::Plugin] {
240        match self {
241            AgentBase::Remote(r) => r.plugins(),
242            AgentBase::Inline(i) => i.plugins(),
243        }
244    }
245
246    pub fn prepare(&mut self) {
247        match self {
248            AgentBase::Remote(r) => r.prepare(),
249            AgentBase::Inline(i) => i.prepare(),
250        }
251    }
252
253    pub fn validate(&self) -> Result<(), String> {
254        match self {
255            AgentBase::Remote(r) => r.validate(),
256            AgentBase::Inline(i) => i.validate(),
257        }
258    }
259
260    pub fn id(&self) -> String {
261        match self {
262            AgentBase::Remote(r) => r.id(),
263            AgentBase::Inline(i) => i.id(),
264        }
265    }
266
267    /// Validates and converts to an [`Agent`] with computed ID.
268    pub fn convert(self) -> Result<Agent, String> {
269        match self {
270            AgentBase::Remote(r) => Ok(Agent::Remote(r.convert()?)),
271            AgentBase::Inline(i) => Ok(Agent::Inline(i.convert()?)),
272        }
273    }
274}
275
276// ── Ref types ──────────────────────────────────────────────────────
277
278/// A borrowed reference into an [`InlineAgentBase`] variant.
279#[derive(Clone, Copy, Debug)]
280pub enum InlineAgentRef<'a> {
281    Openrouter(&'a super::openrouter::AgentBase),
282    ClaudeAgentSdk(&'a super::claude_agent_sdk::AgentBase),
283    CodexSdk(&'a super::codex_sdk::AgentBase),
284    Mock(&'a super::mock::AgentBase),
285    Script(&'a super::script::AgentBase),
286}
287
288impl<'a> InlineAgentRef<'a> {
289    pub fn to_owned(self) -> InlineAgentBase {
290        match self {
291            InlineAgentRef::Openrouter(b) => {
292                InlineAgentBase::Openrouter(b.clone())
293            }
294            InlineAgentRef::ClaudeAgentSdk(b) => {
295                InlineAgentBase::ClaudeAgentSdk(b.clone())
296            }
297            InlineAgentRef::CodexSdk(b) => InlineAgentBase::CodexSdk(b.clone()),
298            InlineAgentRef::Mock(b) => InlineAgentBase::Mock(b.clone()),
299            InlineAgentRef::Script(b) => InlineAgentBase::Script(b.clone()),
300        }
301    }
302
303    pub fn model(&self) -> &'a str {
304        match self {
305            InlineAgentRef::Openrouter(b) => &b.model,
306            InlineAgentRef::ClaudeAgentSdk(b) => &b.model,
307            InlineAgentRef::CodexSdk(b) => &b.model,
308            InlineAgentRef::Mock(_) => super::mock::AgentBase::model(),
309            InlineAgentRef::Script(_) => super::script::AgentBase::model(),
310        }
311    }
312
313    pub fn upstream(&self) -> super::Upstream {
314        match self {
315            InlineAgentRef::Openrouter(_) => super::Upstream::Openrouter,
316            InlineAgentRef::ClaudeAgentSdk(_) => {
317                super::Upstream::ClaudeAgentSdk
318            }
319            InlineAgentRef::CodexSdk(_) => super::Upstream::CodexSdk,
320            InlineAgentRef::Mock(_) => super::Upstream::Mock,
321            InlineAgentRef::Script(_) => super::Upstream::Script,
322        }
323    }
324
325    pub fn output_mode(&self) -> super::OutputMode {
326        match self {
327            InlineAgentRef::Openrouter(b) => b.output_mode.into(),
328            InlineAgentRef::ClaudeAgentSdk(b) => b.output_mode.into(),
329            InlineAgentRef::CodexSdk(b) => b.output_mode.into(),
330            InlineAgentRef::Mock(b) => b.output_mode.into(),
331            InlineAgentRef::Script(b) => b.output_mode.into(),
332        }
333    }
334
335    pub fn mcp_servers(&self) -> Option<&'a super::McpServers> {
336        match self {
337            InlineAgentRef::Openrouter(b) => b.mcp_servers.as_ref(),
338            InlineAgentRef::ClaudeAgentSdk(b) => b.mcp_servers.as_ref(),
339            InlineAgentRef::CodexSdk(b) => b.mcp_servers.as_ref(),
340            InlineAgentRef::Mock(b) => b.mcp_servers.as_ref(),
341            InlineAgentRef::Script(b) => b.mcp_servers.as_ref(),
342        }
343    }
344
345    pub fn laboratories(&self) -> Option<&'a super::Laboratories> {
346        match self {
347            InlineAgentRef::Openrouter(b) => b.laboratories.as_ref(),
348            InlineAgentRef::ClaudeAgentSdk(b) => b.laboratories.as_ref(),
349            InlineAgentRef::CodexSdk(b) => b.laboratories.as_ref(),
350            InlineAgentRef::Mock(b) => b.laboratories.as_ref(),
351            InlineAgentRef::Script(b) => b.laboratories.as_ref(),
352        }
353    }
354
355    pub fn plugins(&self) -> &'a [super::Plugin] {
356        match self {
357            InlineAgentRef::Openrouter(b) => &b.plugins,
358            InlineAgentRef::ClaudeAgentSdk(b) => &b.plugins,
359            InlineAgentRef::CodexSdk(b) => &b.plugins,
360            InlineAgentRef::Mock(b) => &b.plugins,
361            InlineAgentRef::Script(b) => &b.plugins,
362        }
363    }
364
365    pub fn top_logprobs(&self) -> Option<u64> {
366        match self {
367            InlineAgentRef::Openrouter(b) => b.top_logprobs,
368            InlineAgentRef::ClaudeAgentSdk(_) => None,
369            InlineAgentRef::CodexSdk(_) => None,
370            InlineAgentRef::Mock(b) => b.top_logprobs,
371            InlineAgentRef::Script(_) => None,
372        }
373    }
374
375    pub fn merged_messages(
376        &self,
377        messages: Vec<super::completions::message::Message>,
378    ) -> Vec<super::completions::message::Message> {
379        match self {
380            InlineAgentRef::Openrouter(b) => b.merged_messages(messages),
381            InlineAgentRef::ClaudeAgentSdk(b) => b.merged_messages(messages),
382            InlineAgentRef::CodexSdk(b) => b.merged_messages(messages),
383            InlineAgentRef::Mock(b) => b.merged_messages(messages),
384            InlineAgentRef::Script(b) => b.merged_messages(messages),
385        }
386    }
387}
388
389// ── Post-validation types (with computed ID) ───────────────────────
390
391/// A validated inline Agent with its computed content-addressed ID.
392///
393/// This is an untagged enum that dispatches to the per-upstream Agent.
394#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
395#[serde(untagged)]
396#[schemars(rename = "agent.InlineAgent")]
397pub enum InlineAgent {
398    #[schemars(title = "Openrouter")]
399    Openrouter(super::openrouter::Agent),
400    #[schemars(title = "ClaudeAgentSdk")]
401    ClaudeAgentSdk(super::claude_agent_sdk::Agent),
402    #[schemars(title = "CodexSdk")]
403    CodexSdk(super::codex_sdk::Agent),
404    #[schemars(title = "Mock")]
405    Mock(super::mock::Agent),
406    #[schemars(title = "Script")]
407    Script(super::script::Agent),
408}
409
410impl InlineAgent {
411    pub fn id(&self) -> &str {
412        match self {
413            InlineAgent::Openrouter(a) => &a.id,
414            InlineAgent::ClaudeAgentSdk(a) => &a.id,
415            InlineAgent::CodexSdk(a) => &a.id,
416            InlineAgent::Mock(a) => &a.id,
417            InlineAgent::Script(a) => &a.id,
418        }
419    }
420
421    pub fn base(&self) -> InlineAgentRef<'_> {
422        match self {
423            InlineAgent::Openrouter(a) => InlineAgentRef::Openrouter(&a.base),
424            InlineAgent::ClaudeAgentSdk(a) => {
425                InlineAgentRef::ClaudeAgentSdk(&a.base)
426            }
427            InlineAgent::CodexSdk(a) => InlineAgentRef::CodexSdk(&a.base),
428            InlineAgent::Mock(a) => InlineAgentRef::Mock(&a.base),
429            InlineAgent::Script(a) => InlineAgentRef::Script(&a.base),
430        }
431    }
432
433    pub fn into_base(self) -> InlineAgentBase {
434        match self {
435            InlineAgent::Openrouter(a) => InlineAgentBase::Openrouter(a.base),
436            InlineAgent::ClaudeAgentSdk(a) => {
437                InlineAgentBase::ClaudeAgentSdk(a.base)
438            }
439            InlineAgent::CodexSdk(a) => InlineAgentBase::CodexSdk(a.base),
440            InlineAgent::Mock(a) => InlineAgentBase::Mock(a.base),
441            InlineAgent::Script(a) => InlineAgentBase::Script(a.base),
442        }
443    }
444
445    pub fn top_logprobs(&self) -> Option<u64> {
446        self.base().top_logprobs()
447    }
448}
449
450/// A validated remote Agent with metadata and computed content-addressed ID.
451#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
452#[schemars(rename = "agent.RemoteAgent")]
453pub struct RemoteAgent {
454    pub description: String,
455    #[serde(flatten)]
456    #[schemars(schema_with = "crate::flatten_schema::<InlineAgent>")]
457    pub inner: InlineAgent,
458}
459
460impl RemoteAgent {
461    pub fn id(&self) -> &str {
462        self.inner.id()
463    }
464
465    pub fn base(&self) -> InlineAgentRef<'_> {
466        self.inner.base()
467    }
468
469    pub fn into_base(self) -> RemoteAgentBase {
470        RemoteAgentBase {
471            description: self.description,
472            inner: self.inner.into_base(),
473        }
474    }
475
476    pub fn top_logprobs(&self) -> Option<u64> {
477        self.inner.top_logprobs()
478    }
479}
480
481/// A validated Agent, either remote (with metadata) or inline.
482#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
483#[serde(untagged)]
484#[schemars(rename = "agent.Agent")]
485pub enum Agent {
486    #[schemars(title = "Remote")]
487    Remote(RemoteAgent),
488    #[schemars(title = "Inline")]
489    Inline(InlineAgent),
490}
491
492impl Agent {
493    pub fn id(&self) -> &str {
494        match self {
495            Agent::Remote(a) => a.inner.id(),
496            Agent::Inline(a) => a.id(),
497        }
498    }
499
500    pub fn base(&self) -> InlineAgentRef<'_> {
501        match self {
502            Agent::Remote(a) => a.inner.base(),
503            Agent::Inline(a) => a.base(),
504        }
505    }
506
507    pub fn into_base(self) -> AgentBase {
508        match self {
509            Agent::Remote(a) => AgentBase::Remote(RemoteAgentBase {
510                description: a.description,
511                inner: a.inner.into_base(),
512            }),
513            Agent::Inline(a) => AgentBase::Inline(a.into_base()),
514        }
515    }
516
517    pub fn top_logprobs(&self) -> Option<u64> {
518        self.base().top_logprobs()
519    }
520}
521
522// ── WithFallbacks types ────────────────────────────────────────────
523
524/// An [`InlineAgentBase`] with optional fallbacks (no description).
525#[derive(
526    Clone,
527    Debug,
528    PartialEq,
529    Serialize,
530    Deserialize,
531    JsonSchema,
532    arbitrary::Arbitrary,
533)]
534#[schemars(rename = "agent.InlineAgentBaseWithFallbacks")]
535pub struct InlineAgentBaseWithFallbacks {
536    /// The primary agent configuration.
537    #[serde(flatten)]
538    #[schemars(schema_with = "crate::flatten_schema::<InlineAgentBase>")]
539    pub inner: InlineAgentBase,
540    /// Fallback agents to try if the primary fails.
541    #[serde(skip_serializing_if = "Option::is_none")]
542    #[schemars(extend("omitempty" = true))]
543    pub fallbacks: Option<Vec<InlineAgentBase>>,
544}
545
546impl InlineAgentBaseWithFallbacks {
547    /// Validates and converts to an [`InlineAgentWithFallbacks`] with computed IDs.
548    pub fn convert(self) -> Result<InlineAgentWithFallbacks, String> {
549        let inner = self.inner.convert()?;
550        let fallbacks = match self.fallbacks {
551            Some(fallbacks) if !fallbacks.is_empty() => {
552                let mut converted = Vec::with_capacity(fallbacks.len());
553                for fallback in fallbacks {
554                    converted.push(fallback.convert()?);
555                }
556                Some(converted)
557            }
558            _ => None,
559        };
560        Ok(InlineAgentWithFallbacks { inner, fallbacks })
561    }
562}
563
564/// A validated [`InlineAgent`] with optional fallbacks (no description).
565#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
566#[schemars(rename = "agent.InlineAgentWithFallbacks")]
567pub struct InlineAgentWithFallbacks {
568    /// The primary agent configuration.
569    #[serde(flatten)]
570    #[schemars(schema_with = "crate::flatten_schema::<InlineAgent>")]
571    pub inner: InlineAgent,
572    /// Fallback agents to try if the primary fails.
573    #[serde(skip_serializing_if = "Option::is_none")]
574    #[schemars(extend("omitempty" = true))]
575    pub fallbacks: Option<Vec<InlineAgent>>,
576}
577
578impl InlineAgentWithFallbacks {
579    /// Returns the concatenated IDs of the primary agent and all fallbacks.
580    ///
581    /// Used by swarms to compute their content-addressed ID.
582    pub fn full_id(&self) -> String {
583        match &self.fallbacks {
584            Some(fallbacks) => {
585                let id = self.inner.id();
586                let mut full_id =
587                    String::with_capacity(id.len() + fallbacks.len() * 22);
588                full_id.push_str(id);
589                for fallback in fallbacks {
590                    full_id.push_str(fallback.id());
591                }
592                full_id
593            }
594            None => self.inner.id().to_owned(),
595        }
596    }
597
598    /// Returns an iterator over the IDs of the primary agent and all fallbacks.
599    pub fn ids(&self) -> impl Iterator<Item = &str> + Send {
600        std::iter::once(self.inner.id()).chain(
601            self.fallbacks.as_ref().into_iter().flat_map(|fallbacks| {
602                fallbacks.iter().map(|fallback| fallback.id())
603            }),
604        )
605    }
606}
607
608/// A remote agent base definition with description and optional fallbacks.
609#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
610#[schemars(rename = "agent.RemoteAgentBaseWithFallbacks")]
611pub struct RemoteAgentBaseWithFallbacks {
612    pub description: String,
613    #[serde(flatten)]
614    #[schemars(
615        schema_with = "crate::flatten_schema::<InlineAgentBaseWithFallbacks>"
616    )]
617    pub inner: InlineAgentBaseWithFallbacks,
618}
619
620impl RemoteAgentBaseWithFallbacks {
621    /// Validates and converts to a [`RemoteAgentWithFallbacks`].
622    pub fn convert(self) -> Result<RemoteAgentWithFallbacks, String> {
623        Ok(RemoteAgentWithFallbacks {
624            description: self.description,
625            inner: self.inner.convert()?,
626        })
627    }
628}
629
630/// A validated remote agent with description and optional fallbacks.
631#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
632#[schemars(rename = "agent.RemoteAgentWithFallbacks")]
633pub struct RemoteAgentWithFallbacks {
634    pub description: String,
635    #[serde(flatten)]
636    #[schemars(
637        schema_with = "crate::flatten_schema::<InlineAgentWithFallbacks>"
638    )]
639    pub inner: InlineAgentWithFallbacks,
640}
641
642impl RemoteAgentWithFallbacks {
643    /// Returns the concatenated IDs of the primary agent and all fallbacks.
644    pub fn full_id(&self) -> String {
645        self.inner.full_id()
646    }
647
648    /// Returns an iterator over the IDs of the primary agent and all fallbacks.
649    pub fn ids(&self) -> impl Iterator<Item = &str> + Send {
650        self.inner.ids()
651    }
652}
653
654/// A validated agent with optional fallbacks, either remote (with description) or inline.
655#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
656#[serde(untagged)]
657#[schemars(rename = "agent.AgentWithFallbacks")]
658pub enum AgentWithFallbacks {
659    #[schemars(title = "Remote")]
660    Remote(RemoteAgentWithFallbacks),
661    #[schemars(title = "Inline")]
662    Inline(InlineAgentWithFallbacks),
663}
664
665impl AgentWithFallbacks {
666    /// Returns the inner `InlineAgentWithFallbacks` regardless of variant.
667    pub fn inline(&self) -> &InlineAgentWithFallbacks {
668        match self {
669            AgentWithFallbacks::Remote(a) => &a.inner,
670            AgentWithFallbacks::Inline(a) => a,
671        }
672    }
673
674    /// Returns the primary agent.
675    pub fn agent(&self) -> &InlineAgent {
676        &self.inline().inner
677    }
678
679    /// Returns the fallback agents.
680    pub fn fallbacks(&self) -> Option<&Vec<InlineAgent>> {
681        self.inline().fallbacks.as_ref()
682    }
683
684    /// Returns the concatenated IDs of the primary agent and all fallbacks.
685    pub fn full_id(&self) -> String {
686        self.inline().full_id()
687    }
688
689    /// Returns an iterator over the IDs of the primary agent and all fallbacks.
690    pub fn ids(&self) -> impl Iterator<Item = &str> + Send {
691        self.inline().ids()
692    }
693
694    pub fn id(&self) -> &str {
695        self.agent().id()
696    }
697
698    pub fn base(&self) -> InlineAgentRef<'_> {
699        self.agent().base()
700    }
701
702    pub fn top_logprobs(&self) -> Option<u64> {
703        self.agent().top_logprobs()
704    }
705}
706
707// ── InlineAgentBaseWithFallbacksOrRemote ─────────────────────────────────
708
709/// An agent specification that is either an inline agent base with fallbacks
710/// or a remote path reference.
711///
712/// Used in swarm definitions to allow agents to be specified inline
713/// (with optional fallbacks) or resolved from a remote source via a
714/// hashmap during conversion.
715#[derive(
716    Clone,
717    Debug,
718    PartialEq,
719    Serialize,
720    Deserialize,
721    JsonSchema,
722    arbitrary::Arbitrary,
723)]
724#[serde(untagged)]
725#[schemars(rename = "agent.InlineAgentBaseWithFallbacksOrRemote")]
726pub enum InlineAgentBaseWithFallbacksOrRemote {
727    #[schemars(title = "AgentBase")]
728    AgentBase(InlineAgentBaseWithFallbacks),
729    #[schemars(title = "Remote")]
730    Remote(crate::RemotePath),
731}
732
733/// Like [`InlineAgentBaseWithFallbacksOrRemote`] but with optional commit.
734/// Used in request types where commit resolution happens server-side.
735#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
736#[serde(untagged)]
737#[schemars(rename = "agent.InlineAgentBaseWithFallbacksOrRemoteCommitOptional")]
738pub enum InlineAgentBaseWithFallbacksOrRemoteCommitOptional {
739    #[schemars(title = "AgentBase")]
740    AgentBase(InlineAgentBaseWithFallbacks),
741    #[schemars(title = "Remote")]
742    Remote(crate::RemotePathCommitOptional),
743}
744
745// ── WithCount types (for swarm agent slots) ────────────────────────
746
747fn default_count() -> u64 {
748    1
749}
750
751/// An [`InlineAgentBaseWithFallbacksOrRemote`] with a count
752/// (pre-validation swarm agent slot).
753#[derive(
754    Clone,
755    Debug,
756    PartialEq,
757    Serialize,
758    Deserialize,
759    JsonSchema,
760    arbitrary::Arbitrary,
761)]
762#[schemars(rename = "agent.InlineAgentBaseWithFallbacksOrRemoteWithCount")]
763pub struct InlineAgentBaseWithFallbacksOrRemoteWithCount {
764    /// Number of instances of this agent in the swarm. Defaults to 1.
765    #[serde(default = "default_count")]
766    #[arbitrary(with = crate::arbitrary_util::arbitrary_u64)]
767    pub count: u64,
768    /// The agent configuration.
769    #[serde(flatten)]
770    #[schemars(
771        schema_with = "crate::flatten_schema::<InlineAgentBaseWithFallbacksOrRemote>"
772    )]
773    pub inner: InlineAgentBaseWithFallbacksOrRemote,
774}
775
776/// An [`AgentWithFallbacks`] with a count (post-validation swarm agent slot).
777#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
778#[schemars(rename = "agent.AgentWithFallbacksWithCount")]
779pub struct AgentWithFallbacksWithCount {
780    /// Number of instances of this agent in the swarm. Defaults to 1.
781    #[serde(default = "default_count")]
782    pub count: u64,
783    /// The validated agent configuration.
784    #[serde(flatten)]
785    #[schemars(schema_with = "crate::flatten_schema::<AgentWithFallbacks>")]
786    pub inner: AgentWithFallbacks,
787}