Skip to main content

objectiveai_sdk/agent/script/
agent.rs

1//! Script Agent types and validation logic.
2
3use schemars::JsonSchema;
4use serde::{Deserialize, Serialize};
5use twox_hash::XxHash3_128;
6
7/// The base configuration for a Script Agent (without computed ID).
8#[derive(
9    Clone,
10    Debug,
11    PartialEq,
12    Serialize,
13    Deserialize,
14    JsonSchema,
15    arbitrary::Arbitrary,
16)]
17#[schemars(rename = "agent.script.AgentBase")]
18pub struct AgentBase {
19    /// The upstream provider marker.
20    pub upstream: super::Upstream,
21
22    /// The output mode for vector completions. Ignored for agent completions.
23    pub output_mode: super::OutputMode,
24
25    /// The code this agent runs on the CLIENT — a required
26    /// `type`-tagged enum, flattened so `type` + its payload (e.g.
27    /// `python`) sit directly on the agent object.
28    #[serde(flatten)]
29    #[schemars(schema_with = "crate::flatten_schema::<super::Script>")]
30    pub script: super::Script,
31
32    /// MCP servers the agent can connect to.
33    #[serde(skip_serializing_if = "Option::is_none")]
34    #[schemars(extend("omitempty" = true))]
35    pub mcp_servers: Option<super::super::McpServers>,
36
37    /// Laboratories provisioned for the agent — each becomes a
38    /// client-side laboratory MCP server whose id DERIVES from the
39    /// agent's full id plus the spec (see
40    /// [`laboratories::derived_id`](super::super::laboratory::laboratories::derived_id)).
41    #[serde(skip_serializing_if = "Option::is_none")]
42    #[schemars(extend("omitempty" = true))]
43    pub laboratories: Option<super::super::Laboratories>,
44
45
46
47    /// Plugins this agent uses — each IS one MCP server (the
48    /// next-iteration plugin shape; see [`super::super::plugin`]).
49    #[serde(default, skip_serializing_if = "Vec::is_empty")]
50    #[schemars(extend("omitempty" = true))]
51    pub plugins: Vec<super::super::Plugin>,
52}
53
54impl AgentBase {
55    /// Normalizes the configuration for deterministic ID computation.
56    /// The script code itself is never normalized — whitespace is
57    /// significant.
58    pub fn prepare(&mut self) {
59        self.mcp_servers = match self.mcp_servers.take() {
60            Some(mcp_servers) => {
61                super::super::mcp::mcp_servers::prepare(mcp_servers)
62            }
63            None => None,
64        };
65        self.laboratories = match self.laboratories.take() {
66            Some(laboratories) => {
67                super::super::laboratory::laboratories::prepare(laboratories)
68            }
69            None => None,
70        };
71        self.plugins =
72            super::super::plugin::prepare(std::mem::take(&mut self.plugins));
73    }
74
75    /// Validates the configuration.
76    pub fn validate(&self) -> Result<(), String> {
77        self.script.validate()?;
78        if let Some(mcp_servers) = &self.mcp_servers {
79            super::super::mcp::mcp_servers::validate(mcp_servers)?;
80        }
81        if let Some(laboratories) = &self.laboratories {
82            super::super::laboratory::laboratories::validate(laboratories)?;
83        }
84        super::super::plugin::validate(&self.plugins)?;
85        Ok(())
86    }
87
88    /// Returns the messages as-is.
89    pub fn merged_messages(
90        &self,
91        messages: Vec<super::super::completions::message::Message>,
92    ) -> Vec<super::super::completions::message::Message> {
93        messages
94    }
95
96    /// Computes the deterministic content-addressed ID.
97    pub fn id(&self) -> String {
98        let mut hasher = XxHash3_128::with_seed(0);
99        hasher.write(serde_json::to_string(self).unwrap().as_bytes());
100        format!("{:0>22}", base62::encode(hasher.finish_128()))
101    }
102
103    pub const fn model() -> &'static str {
104        "script"
105    }
106}
107
108/// A validated Script Agent with its computed content-addressed ID.
109#[derive(Clone, Debug, PartialEq, Serialize, Deserialize, JsonSchema)]
110#[schemars(rename = "agent.script.Agent")]
111pub struct Agent {
112    /// The deterministic content-addressed ID (22-character base62 string).
113    pub id: String,
114    /// The normalized configuration.
115    #[serde(flatten)]
116    pub base: AgentBase,
117}
118
119impl TryFrom<AgentBase> for Agent {
120    type Error = String;
121    fn try_from(mut base: AgentBase) -> Result<Self, Self::Error> {
122        base.prepare();
123        base.validate()?;
124        let id = base.id();
125        Ok(Agent { id, base })
126    }
127}