use serde::de::DeserializeOwned;
use serde_json::Value;
use std::collections::HashMap;
use std::future::Future;
use std::pin::Pin;
use std::sync::Arc;
use crate::error::{ConductorError, Result};
use super::credentials::Credentials;
use super::def::AgentDef;
use super::guardrail::Guardrail;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolType {
Worker,
Http,
Mcp,
AgentTool,
Human,
Api,
GenerateImage,
GenerateAudio,
GenerateVideo,
GeneratePdf,
RagIndex,
RagSearch,
PullWorkflowMessages,
}
impl ToolType {
#[must_use]
pub fn as_str(&self) -> &'static str {
match self {
ToolType::Worker => "worker",
ToolType::Http => "http",
ToolType::Mcp => "mcp",
ToolType::AgentTool => "agent_tool",
ToolType::Human => "human",
ToolType::Api => "api",
ToolType::GenerateImage => "generate_image",
ToolType::GenerateAudio => "generate_audio",
ToolType::GenerateVideo => "generate_video",
ToolType::GeneratePdf => "generate_pdf",
ToolType::RagIndex => "rag_index",
ToolType::RagSearch => "rag_search",
ToolType::PullWorkflowMessages => "pull_workflow_messages",
}
}
}
#[derive(Debug, Clone, Default)]
pub struct ToolContext {
pub session_id: String,
pub execution_id: String,
pub agent_name: String,
pub metadata: HashMap<String, Value>,
pub dependencies: HashMap<String, Value>,
state: Arc<std::sync::Mutex<HashMap<String, Value>>>,
}
impl ToolContext {
#[must_use]
pub fn get_state(&self, key: &str) -> Option<Value> {
self.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.get(key)
.cloned()
}
pub fn set_state(&self, key: impl Into<String>, value: Value) {
self.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.insert(key.into(), value);
}
#[must_use]
pub fn state_snapshot(&self) -> HashMap<String, Value> {
self.state
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.clone()
}
pub(super) fn with_initial_state(mut self, state: HashMap<String, Value>) -> Self {
self.state = Arc::new(std::sync::Mutex::new(state));
self
}
}
pub type ToolHandler = Arc<
dyn Fn(Value, Credentials, ToolContext) -> Pin<Box<dyn Future<Output = Result<Value>> + Send>>
+ Send
+ Sync,
>;
#[derive(Clone)]
pub struct ToolDef {
pub name: String,
pub description: String,
pub input_schema: Value,
pub output_schema: Value,
pub tool_type: ToolType,
pub approval_required: bool,
pub stateful: bool,
pub timeout_seconds: Option<u64>,
pub max_calls: Option<u32>,
pub config: HashMap<String, Value>,
pub credentials: Vec<String>,
pub sub_agent: Option<Box<AgentDef>>,
pub handler: Option<ToolHandler>,
pub guardrails: Vec<Guardrail>,
}
impl std::fmt::Debug for ToolDef {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("ToolDef")
.field("name", &self.name)
.field("description", &self.description)
.field("input_schema", &self.input_schema)
.field("output_schema", &self.output_schema)
.field("tool_type", &self.tool_type)
.field("approval_required", &self.approval_required)
.field("stateful", &self.stateful)
.field("timeout_seconds", &self.timeout_seconds)
.field("max_calls", &self.max_calls)
.field("config", &self.config)
.field("credentials", &self.credentials)
.field("sub_agent", &self.sub_agent)
.field("handler", &self.handler.as_ref().map(|_| "Fn(..)"))
.field("guardrails", &self.guardrails)
.finish()
}
}
impl ToolDef {
fn base(name: impl Into<String>, description: impl Into<String>, tool_type: ToolType) -> Self {
Self {
name: name.into(),
description: description.into(),
input_schema: Value::Null,
output_schema: Value::Null,
tool_type,
approval_required: false,
stateful: false,
timeout_seconds: None,
max_calls: None,
config: HashMap::new(),
credentials: Vec::new(),
sub_agent: None,
handler: None,
guardrails: Vec::new(),
}
}
pub fn function<T, F, Fut>(
name: impl Into<String>,
description: impl Into<String>,
input_schema: Value,
handler: F,
) -> Self
where
T: DeserializeOwned,
F: Fn(T) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<Value>> + Send + 'static,
{
let mut tool = Self::base(name, description, ToolType::Worker);
tool.input_schema = input_schema;
let handler = Arc::new(handler);
tool.handler = Some(Arc::new(
move |raw: Value, _credentials: Credentials, _context: ToolContext| {
let handler = Arc::clone(&handler);
Box::pin(async move {
let args: T = serde_json::from_value(raw)?;
handler(args).await
})
},
));
tool
}
pub fn function_with_credentials<T, F, Fut>(
name: impl Into<String>,
description: impl Into<String>,
input_schema: Value,
handler: F,
) -> Self
where
T: DeserializeOwned,
F: Fn(T, &Credentials) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<Value>> + Send + 'static,
{
let mut tool = Self::base(name, description, ToolType::Worker);
tool.input_schema = input_schema;
let handler = Arc::new(handler);
tool.handler = Some(Arc::new(
move |raw: Value, credentials: Credentials, _context: ToolContext| {
let handler = Arc::clone(&handler);
Box::pin(async move {
let args: T = serde_json::from_value(raw)?;
handler(args, &credentials).await
})
},
));
tool
}
pub fn function_with_context<T, F, Fut>(
name: impl Into<String>,
description: impl Into<String>,
input_schema: Value,
handler: F,
) -> Self
where
T: DeserializeOwned,
F: Fn(T, ToolContext) -> Fut + Send + Sync + 'static,
Fut: Future<Output = Result<Value>> + Send + 'static,
{
let mut tool = Self::base(name, description, ToolType::Worker);
tool.input_schema = input_schema;
let handler = Arc::new(handler);
tool.handler = Some(Arc::new(
move |raw: Value, _credentials: Credentials, context: ToolContext| {
let handler = Arc::clone(&handler);
Box::pin(async move {
let args: T = serde_json::from_value(raw)?;
handler(args, context).await
})
},
));
tool
}
pub fn http(
name: impl Into<String>,
description: impl Into<String>,
url: impl Into<String>,
method: &str,
headers: HashMap<String, String>,
credentials: Vec<String>,
) -> Result<Self> {
let url = url.into();
validate_credential_placeholders(&headers, &credentials)?;
validate_credential_placeholders(
&HashMap::from([("url".to_owned(), url.clone())]),
&credentials,
)?;
let mut tool = Self::base(name, description, ToolType::Http);
tool.credentials = credentials;
tool.input_schema = serde_json::json!({"type": "object", "properties": {}});
tool.config.insert("url".to_owned(), Value::String(url));
tool.config
.insert("method".to_owned(), Value::String(method.to_uppercase()));
tool.config
.insert("headers".to_owned(), serde_json::to_value(&headers)?);
tool.config.insert(
"accept".to_owned(),
Value::Array(vec![Value::String("application/json".to_owned())]),
);
tool.config.insert(
"contentType".to_owned(),
Value::String("application/json".to_owned()),
);
Ok(tool)
}
#[expect(clippy::too_many_arguments)]
pub fn http_templated(
name: impl Into<String>,
description: impl Into<String>,
input_schema: Value,
url: impl Into<String>,
method: &str,
path_template: Option<String>,
query_params: Option<Vec<String>>,
headers: HashMap<String, String>,
credentials: Vec<String>,
) -> Result<Self> {
let url = url.into();
validate_credential_placeholders(&headers, &credentials)?;
validate_credential_placeholders(
&HashMap::from([("url".to_owned(), url.clone())]),
&credentials,
)?;
let mut tool = Self::base(name, description, ToolType::Http);
tool.input_schema = input_schema;
tool.credentials = credentials;
tool.config.insert("url".to_owned(), Value::String(url));
tool.config
.insert("method".to_owned(), Value::String(method.to_uppercase()));
if let Some(path_template) = path_template {
tool.config
.insert("pathTemplate".to_owned(), Value::String(path_template));
}
if let Some(query_params) = query_params {
tool.config.insert(
"queryParams".to_owned(),
Value::Array(query_params.into_iter().map(Value::String).collect()),
);
}
if !headers.is_empty() {
tool.config
.insert("headers".to_owned(), serde_json::to_value(&headers)?);
}
Ok(tool)
}
pub fn mcp(
server_url: impl Into<String>,
name: impl Into<String>,
description: impl Into<String>,
headers: HashMap<String, String>,
tool_names: Option<Vec<String>>,
max_tools: u32,
credentials: Vec<String>,
) -> Result<Self> {
let server_url = server_url.into();
validate_credential_placeholders(&headers, &credentials)?;
validate_credential_placeholders(
&HashMap::from([("server_url".to_owned(), server_url.clone())]),
&credentials,
)?;
let mut tool = Self::base(name, description, ToolType::Mcp);
tool.credentials = credentials;
tool.config
.insert("server_url".to_owned(), Value::String(server_url));
tool.config
.insert("headers".to_owned(), serde_json::to_value(&headers)?);
if let Some(tool_names) = tool_names {
tool.config.insert(
"tool_names".to_owned(),
Value::Array(tool_names.into_iter().map(Value::String).collect()),
);
}
tool.config
.insert("max_tools".to_owned(), Value::from(max_tools));
Ok(tool)
}
#[must_use]
pub fn agent(agent: AgentDef) -> Self {
let mut tool = Self::base(
agent.name.clone(),
format!("Delegate to agent '{}'", agent.name),
ToolType::AgentTool,
);
tool.input_schema = serde_json::json!({
"type": "object",
"properties": { "request": { "type": "string" } },
"required": ["request"]
});
tool.sub_agent = Some(Box::new(agent));
tool
}
pub fn human(name: impl Into<String>, description: impl Into<String>) -> Self {
let mut tool = Self::base(name, description, ToolType::Human);
tool.input_schema = serde_json::json!({
"type": "object",
"properties": { "question": { "type": "string" } },
"required": ["question"]
});
tool
}
pub fn api(
url: impl Into<String>,
name: impl Into<String>,
description: impl Into<String>,
headers: HashMap<String, String>,
tool_names: Option<Vec<String>>,
max_tools: u32,
credentials: Vec<String>,
) -> Result<Self> {
let url = url.into();
validate_credential_placeholders(&headers, &credentials)?;
validate_credential_placeholders(
&HashMap::from([("url".to_owned(), url.clone())]),
&credentials,
)?;
let mut tool = Self::base(name, description, ToolType::Api);
tool.credentials = credentials;
tool.config.insert("url".to_owned(), Value::String(url));
if !headers.is_empty() {
tool.config
.insert("headers".to_owned(), serde_json::to_value(&headers)?);
}
if let Some(tool_names) = tool_names {
tool.config.insert(
"tool_names".to_owned(),
Value::Array(tool_names.into_iter().map(Value::String).collect()),
);
}
tool.config
.insert("max_tools".to_owned(), Value::from(max_tools));
Ok(tool)
}
pub fn image(
name: impl Into<String>,
description: impl Into<String>,
llm_provider: impl Into<String>,
model: impl Into<String>,
input_schema: Option<Value>,
defaults: HashMap<String, Value>,
) -> Self {
Self::media_tool(
ToolType::GenerateImage,
"GENERATE_IMAGE",
name,
description,
llm_provider,
model,
input_schema.unwrap_or_else(|| {
serde_json::json!({
"type": "object",
"properties": {
"prompt": {"type": "string", "description": "Text description of the image to generate."},
"style": {"type": "string", "description": "Image style: 'vivid' or 'natural'."},
"width": {"type": "integer", "description": "Image width in pixels.", "default": 1024},
"height": {"type": "integer", "description": "Image height in pixels.", "default": 1024},
"size": {"type": "string", "description": "Image size (e.g. '1024x1024'). Alternative to width/height."},
"n": {"type": "integer", "description": "Number of images to generate.", "default": 1},
"outputFormat": {"type": "string", "description": "Output format: 'png', 'jpg', or 'webp'.", "default": "png"},
"weight": {"type": "number", "description": "Image weight parameter."},
},
"required": ["prompt"],
})
}),
defaults,
)
}
pub fn audio(
name: impl Into<String>,
description: impl Into<String>,
llm_provider: impl Into<String>,
model: impl Into<String>,
input_schema: Option<Value>,
defaults: HashMap<String, Value>,
) -> Self {
Self::media_tool(
ToolType::GenerateAudio,
"GENERATE_AUDIO",
name,
description,
llm_provider,
model,
input_schema.unwrap_or_else(|| {
serde_json::json!({
"type": "object",
"properties": {
"text": {"type": "string", "description": "Text to convert to speech."},
"voice": {
"type": "string",
"description": "Voice to use.",
"enum": ["alloy", "echo", "fable", "onyx", "nova", "shimmer"],
"default": "alloy",
},
"speed": {"type": "number", "description": "Speech speed multiplier (0.25 to 4.0).", "default": 1.0},
"responseFormat": {"type": "string", "description": "Audio format: 'mp3', 'wav', 'opus', 'aac', or 'flac'.", "default": "mp3"},
"n": {"type": "integer", "description": "Number of audio outputs to generate.", "default": 1},
},
"required": ["text"],
})
}),
defaults,
)
}
pub fn video(
name: impl Into<String>,
description: impl Into<String>,
llm_provider: impl Into<String>,
model: impl Into<String>,
input_schema: Option<Value>,
defaults: HashMap<String, Value>,
) -> Self {
Self::media_tool(
ToolType::GenerateVideo,
"GENERATE_VIDEO",
name,
description,
llm_provider,
model,
input_schema.unwrap_or_else(|| {
serde_json::json!({
"type": "object",
"properties": {
"prompt": {"type": "string", "description": "Text description of the video scene."},
"inputImage": {"type": "string", "description": "Base64-encoded or URL image for image-to-video generation."},
"duration": {"type": "integer", "description": "Video duration in seconds.", "default": 5},
"width": {"type": "integer", "description": "Video width in pixels.", "default": 1280},
"height": {"type": "integer", "description": "Video height in pixels.", "default": 720},
"fps": {"type": "integer", "description": "Frames per second.", "default": 24},
"outputFormat": {"type": "string", "description": "Video format (e.g. 'mp4').", "default": "mp4"},
"style": {"type": "string", "description": "Video style (e.g. 'cinematic', 'natural')."},
"motion": {"type": "string", "description": "Movement intensity (e.g. 'slow', 'normal', 'extreme')."},
"seed": {"type": "integer", "description": "Seed for reproducibility."},
"guidanceScale": {"type": "number", "description": "Prompt adherence strength (1.0 to 20.0)."},
"aspectRatio": {"type": "string", "description": "Aspect ratio (e.g. '16:9', '1:1')."},
"negativePrompt": {"type": "string", "description": "Description of what to exclude from the video."},
"personGeneration": {"type": "string", "description": "Controls for human figure generation."},
"resolution": {"type": "string", "description": "Quality level (e.g. '720p', '1080p')."},
"generateAudio": {"type": "boolean", "description": "Whether to generate audio with the video."},
"size": {"type": "string", "description": "Video size specification (e.g. '1280x720')."},
"n": {"type": "integer", "description": "Number of videos to generate.", "default": 1},
"maxDurationSeconds": {"type": "integer", "description": "Maximum duration ceiling in seconds."},
"maxCostDollars": {"type": "number", "description": "Maximum cost limit in dollars."},
},
"required": ["prompt"],
})
}),
defaults,
)
}
pub fn pdf(
name: impl Into<String>,
description: impl Into<String>,
input_schema: Option<Value>,
defaults: HashMap<String, Value>,
) -> Self {
let mut tool = Self::base(name, description, ToolType::GeneratePdf);
tool.input_schema = input_schema.unwrap_or_else(|| {
serde_json::json!({
"type": "object",
"properties": {
"markdown": {"type": "string", "description": "Markdown text to convert to PDF."},
"pageSize": {"type": "string", "description": "Page size: A4, LETTER, LEGAL, A3, or A5.", "default": "A4"},
"theme": {"type": "string", "description": "Style preset: 'default' or 'compact'.", "default": "default"},
"baseFontSize": {"type": "number", "description": "Base font size in points.", "default": 11},
},
"required": ["markdown"],
})
});
let mut config = HashMap::from([(
"taskType".to_owned(),
Value::String("GENERATE_PDF".to_owned()),
)]);
config.extend(defaults);
tool.config = config;
tool
}
#[expect(clippy::too_many_arguments)]
fn media_tool(
tool_type: ToolType,
task_type: &str,
name: impl Into<String>,
description: impl Into<String>,
llm_provider: impl Into<String>,
model: impl Into<String>,
input_schema: Value,
defaults: HashMap<String, Value>,
) -> Self {
let mut tool = Self::base(name, description, tool_type);
tool.input_schema = input_schema;
let mut config = HashMap::from([
("taskType".to_owned(), Value::String(task_type.to_owned())),
("llmProvider".to_owned(), Value::String(llm_provider.into())),
("model".to_owned(), Value::String(model.into())),
]);
config.extend(defaults);
tool.config = config;
tool
}
#[expect(clippy::too_many_arguments)]
pub fn rag_index(
name: impl Into<String>,
description: impl Into<String>,
vector_db: impl Into<String>,
index: impl Into<String>,
embedding_model_provider: impl Into<String>,
embedding_model: impl Into<String>,
namespace: Option<String>,
chunk_size: Option<u32>,
chunk_overlap: Option<u32>,
dimensions: Option<u32>,
input_schema: Option<Value>,
) -> Self {
let mut tool = Self::base(name, description, ToolType::RagIndex);
tool.input_schema = input_schema.unwrap_or_else(|| {
serde_json::json!({
"type": "object",
"properties": {
"text": {"type": "string", "description": "The text content to index."},
"docId": {"type": "string", "description": "Unique document identifier."},
"metadata": {"type": "object", "description": "Optional metadata to store with the document."},
},
"required": ["text", "docId"],
})
});
tool.config.insert(
"taskType".to_owned(),
Value::String("LLM_INDEX_TEXT".to_owned()),
);
tool.config
.insert("vectorDB".to_owned(), Value::String(vector_db.into()));
tool.config.insert(
"namespace".to_owned(),
Value::String(namespace.unwrap_or_else(|| "default_ns".to_owned())),
);
tool.config
.insert("index".to_owned(), Value::String(index.into()));
tool.config.insert(
"embeddingModelProvider".to_owned(),
Value::String(embedding_model_provider.into()),
);
tool.config.insert(
"embeddingModel".to_owned(),
Value::String(embedding_model.into()),
);
if let Some(chunk_size) = chunk_size {
tool.config
.insert("chunkSize".to_owned(), Value::from(chunk_size));
}
if let Some(chunk_overlap) = chunk_overlap {
tool.config
.insert("chunkOverlap".to_owned(), Value::from(chunk_overlap));
}
if let Some(dimensions) = dimensions {
tool.config
.insert("dimensions".to_owned(), Value::from(dimensions));
}
tool
}
#[expect(clippy::too_many_arguments)]
pub fn rag_search(
name: impl Into<String>,
description: impl Into<String>,
vector_db: impl Into<String>,
index: impl Into<String>,
embedding_model_provider: impl Into<String>,
embedding_model: impl Into<String>,
namespace: Option<String>,
max_results: Option<u32>,
dimensions: Option<u32>,
input_schema: Option<Value>,
) -> Self {
let mut tool = Self::base(name, description, ToolType::RagSearch);
tool.input_schema = input_schema.unwrap_or_else(|| {
serde_json::json!({
"type": "object",
"properties": {
"query": {"type": "string", "description": "The search query."},
},
"required": ["query"],
})
});
tool.config.insert(
"taskType".to_owned(),
Value::String("LLM_SEARCH_INDEX".to_owned()),
);
tool.config
.insert("vectorDB".to_owned(), Value::String(vector_db.into()));
tool.config.insert(
"namespace".to_owned(),
Value::String(namespace.unwrap_or_else(|| "default_ns".to_owned())),
);
tool.config
.insert("index".to_owned(), Value::String(index.into()));
tool.config.insert(
"embeddingModelProvider".to_owned(),
Value::String(embedding_model_provider.into()),
);
tool.config.insert(
"embeddingModel".to_owned(),
Value::String(embedding_model.into()),
);
tool.config.insert(
"maxResults".to_owned(),
Value::from(max_results.unwrap_or(5)),
);
if let Some(dimensions) = dimensions {
tool.config
.insert("dimensions".to_owned(), Value::from(dimensions));
}
tool
}
pub fn wait_for_message(
name: impl Into<String>,
description: impl Into<String>,
batch_size: u32,
blocking: bool,
) -> Self {
let mut tool = Self::base(name, description, ToolType::PullWorkflowMessages);
tool.input_schema = serde_json::json!({"type": "object", "properties": {}});
tool.config
.insert("batchSize".to_owned(), Value::from(batch_size));
if !blocking {
tool.config
.insert("blocking".to_owned(), Value::Bool(false));
}
tool
}
#[must_use]
pub fn with_output_schema(mut self, schema: Value) -> Self {
self.output_schema = schema;
self
}
#[must_use]
pub fn with_approval_required(mut self, approval_required: bool) -> Self {
self.approval_required = approval_required;
self
}
#[must_use]
pub fn with_stateful(mut self, stateful: bool) -> Self {
self.stateful = stateful;
self
}
#[must_use]
pub fn with_timeout_seconds(mut self, timeout_seconds: u64) -> Self {
self.timeout_seconds = Some(timeout_seconds);
self
}
#[must_use]
pub fn with_max_calls(mut self, max_calls: u32) -> Self {
self.max_calls = Some(max_calls);
self
}
#[must_use]
pub fn with_credentials(mut self, credentials: Vec<String>) -> Self {
self.credentials = credentials;
self
}
#[must_use]
pub fn with_guardrail(mut self, guardrail: Guardrail) -> Self {
self.guardrails.push(guardrail);
self
}
#[must_use]
pub fn with_guardrails(mut self, guardrails: impl IntoIterator<Item = Guardrail>) -> Self {
self.guardrails.extend(guardrails);
self
}
}
fn validate_credential_placeholders(
headers: &HashMap<String, String>,
credentials: &[String],
) -> Result<()> {
for value in headers.values() {
for placeholder in extract_placeholders(value) {
if !credentials.iter().any(|c| c == placeholder) {
return Err(ConductorError::agent(format!(
"undeclared credential placeholder '${{{placeholder}}}': add '{placeholder}' \
to `credentials` or remove the placeholder"
)));
}
}
}
Ok(())
}
fn extract_placeholders(value: &str) -> Vec<&str> {
let mut placeholders = Vec::new();
let mut rest = value;
while let Some(start) = rest.find("${") {
let after_open = &rest[start + 2..];
if let Some(end) = after_open.find('}') {
placeholders.push(&after_open[..end]);
rest = &after_open[end + 1..];
} else {
break;
}
}
placeholders
}
#[cfg(test)]
mod tests {
use super::*;
#[derive(serde::Deserialize)]
struct Args {
n: i32,
}
#[tokio::test]
async fn test_function_tool_roundtrip() {
let tool = ToolDef::function::<Args, _, _>(
"double",
"doubles a number",
serde_json::json!({"type": "object"}),
|args: Args| async move { Ok(Value::from(args.n * 2)) },
);
let handler = tool.handler.clone().unwrap();
let result = handler(
serde_json::json!({"n": 21}),
Credentials::default(),
ToolContext::default(),
)
.await
.unwrap();
assert_eq!(result, Value::from(42));
}
#[tokio::test]
async fn test_function_with_credentials_tool_reads_credential() {
let tool = ToolDef::function_with_credentials::<Args, _, _>(
"double_with_token",
"doubles a number, using a token",
serde_json::json!({"type": "object"}),
|args: Args, creds: &Credentials| {
let token = creds.get("API_KEY").unwrap().to_owned();
async move { Ok(Value::from(format!("{token}:{}", args.n * 2))) }
},
)
.with_credentials(vec!["API_KEY".to_owned()]);
assert_eq!(tool.credentials, vec!["API_KEY".to_owned()]);
let mut values = HashMap::new();
values.insert("API_KEY".to_owned(), "secret".to_owned());
let creds = Credentials::new(values);
let handler = tool.handler.clone().unwrap();
let result = handler(serde_json::json!({"n": 21}), creds, ToolContext::default())
.await
.unwrap();
assert_eq!(result, Value::from("secret:42"));
}
#[test]
fn test_tool_context_set_and_get_state() {
let ctx = ToolContext::default();
assert_eq!(ctx.get_state("repo"), None);
ctx.set_state("repo", Value::String("conductor".to_owned()));
assert_eq!(
ctx.get_state("repo"),
Some(Value::String("conductor".to_owned()))
);
}
#[test]
fn test_tool_context_state_snapshot_reflects_mutations() {
let ctx = ToolContext::default();
ctx.set_state("a", Value::from(1));
ctx.set_state("b", Value::from(2));
let snapshot = ctx.state_snapshot();
assert_eq!(snapshot.get("a"), Some(&Value::from(1)));
assert_eq!(snapshot.get("b"), Some(&Value::from(2)));
}
#[test]
fn test_tool_context_clone_shares_the_same_state() {
let ctx = ToolContext::default();
let cloned = ctx.clone();
ctx.set_state("shared", Value::from(true));
assert_eq!(cloned.get_state("shared"), Some(Value::from(true)));
}
#[test]
fn test_tool_context_with_initial_state_seeds_snapshot() {
let mut seed = HashMap::new();
seed.insert("repo".to_owned(), Value::String("conductor".to_owned()));
let ctx = ToolContext::default().with_initial_state(seed);
assert_eq!(
ctx.get_state("repo"),
Some(Value::String("conductor".to_owned()))
);
}
#[tokio::test]
async fn test_function_with_context_tool_reads_and_writes_state() {
#[derive(serde::Deserialize)]
struct Args {
n: i32,
}
let tool = ToolDef::function_with_context::<Args, _, _>(
"increment",
"increments a running total",
serde_json::json!({"type": "object"}),
|args: Args, ctx: ToolContext| async move {
let previous = ctx.get_state("total").and_then(|v| v.as_i64()).unwrap_or(0);
let total = previous + i64::from(args.n);
ctx.set_state("total", Value::from(total));
Ok(Value::from(total))
},
);
let handler = tool.handler.clone().unwrap();
let ctx = ToolContext::default();
let result = handler(
serde_json::json!({"n": 5}),
Credentials::default(),
ctx.clone(),
)
.await
.unwrap();
assert_eq!(result, Value::from(5));
assert_eq!(ctx.get_state("total"), Some(Value::from(5)));
}
#[test]
fn test_http_tool_rejects_undeclared_placeholder() {
let mut headers = HashMap::new();
headers.insert("Authorization".to_owned(), "Bearer ${API_KEY}".to_owned());
let result = ToolDef::http("t", "d", "https://example.com", "get", headers, vec![]);
result.unwrap_err();
}
#[test]
fn test_http_tool_accepts_declared_placeholder() {
let mut headers = HashMap::new();
headers.insert("Authorization".to_owned(), "Bearer ${API_KEY}".to_owned());
let result = ToolDef::http(
"t",
"d",
"https://example.com",
"get",
headers,
vec!["API_KEY".to_owned()],
);
assert!(result.is_ok());
let tool = result.unwrap();
assert_eq!(
tool.config.get("method"),
Some(&Value::String("GET".to_owned()))
);
}
#[test]
fn test_http_tool_defaults_to_empty_object_input_schema() {
let tool = ToolDef::http(
"t",
"d",
"https://example.com",
"get",
HashMap::new(),
vec![],
)
.unwrap();
assert_eq!(
tool.input_schema,
serde_json::json!({"type": "object", "properties": {}})
);
}
#[test]
fn test_mcp_tool_always_emits_max_tools_defaulting_to_64() {
let tool = ToolDef::mcp(
"https://mcp.example.com",
"t",
"d",
HashMap::new(),
None,
64,
vec![],
)
.unwrap();
assert_eq!(tool.config.get("max_tools"), Some(&Value::from(64)));
assert!(!tool.config.contains_key("tool_names"));
}
#[test]
fn test_mcp_tool_emits_tool_names_when_given() {
let tool = ToolDef::mcp(
"https://mcp.example.com",
"t",
"d",
HashMap::new(),
Some(vec!["search".to_owned(), "fetch".to_owned()]),
32,
vec![],
)
.unwrap();
assert_eq!(
tool.config.get("tool_names"),
Some(&Value::from(vec!["search", "fetch"]))
);
assert_eq!(tool.config.get("max_tools"), Some(&Value::from(32)));
}
#[test]
fn test_agent_tool_holds_sub_agent() {
let sub = AgentDef::new("researcher").unwrap();
let tool = ToolDef::agent(sub);
assert_eq!(tool.tool_type, ToolType::AgentTool);
assert!(tool.sub_agent.is_some());
}
#[test]
fn test_api_tool_wire_shape() {
let mut headers = HashMap::new();
headers.insert(
"Authorization".to_owned(),
"Bearer ${STRIPE_KEY}".to_owned(),
);
let tool = ToolDef::api(
"https://api.stripe.com/openapi.json",
"stripe",
"Stripe API tools",
headers,
None,
20,
vec!["STRIPE_KEY".to_owned()],
)
.unwrap();
assert_eq!(tool.tool_type, ToolType::Api);
assert_eq!(
tool.config.get("url"),
Some(&Value::String(
"https://api.stripe.com/openapi.json".to_owned()
))
);
assert_eq!(tool.config.get("max_tools"), Some(&Value::from(20_u32)));
assert!(!tool.config.contains_key("tool_names"));
assert_eq!(tool.credentials, vec!["STRIPE_KEY".to_owned()]);
}
#[test]
fn test_api_tool_rejects_undeclared_placeholder() {
let mut headers = HashMap::new();
headers.insert("Authorization".to_owned(), "Bearer ${MISSING}".to_owned());
let result = ToolDef::api(
"https://api.example.com/openapi.json",
"t",
"d",
headers,
None,
64,
vec![],
);
result.unwrap_err();
}
#[test]
fn test_api_tool_includes_tool_names_when_given() {
let tool = ToolDef::api(
"https://api.example.com/openapi.json",
"t",
"d",
HashMap::new(),
Some(vec!["listUsers".to_owned(), "getUser".to_owned()]),
64,
vec![],
)
.unwrap();
assert_eq!(
tool.config.get("tool_names"),
Some(&serde_json::json!(["listUsers", "getUser"]))
);
}
#[test]
fn test_image_tool_default_schema_and_config() {
let tool = ToolDef::image("gen_image", "d", "openai", "dall-e-3", None, HashMap::new());
assert_eq!(tool.tool_type, ToolType::GenerateImage);
assert_eq!(
tool.config.get("taskType"),
Some(&Value::String("GENERATE_IMAGE".to_owned()))
);
assert_eq!(
tool.config.get("llmProvider"),
Some(&Value::String("openai".to_owned()))
);
assert_eq!(
tool.config.get("model"),
Some(&Value::String("dall-e-3".to_owned()))
);
assert!(tool.input_schema["properties"]["prompt"].is_object());
assert_eq!(tool.input_schema["required"], serde_json::json!(["prompt"]));
}
#[test]
fn test_image_tool_merges_extra_defaults() {
let mut defaults = HashMap::new();
defaults.insert("n".to_owned(), Value::from(2));
let tool = ToolDef::image("t", "d", "openai", "dall-e-3", None, defaults);
assert_eq!(tool.config.get("n"), Some(&Value::from(2)));
}
#[test]
fn test_image_tool_custom_input_schema_overrides_default() {
let custom = serde_json::json!({"type": "object", "properties": {}});
let tool = ToolDef::image(
"t",
"d",
"openai",
"dall-e-3",
Some(custom.clone()),
HashMap::new(),
);
assert_eq!(tool.input_schema, custom);
}
#[test]
fn test_audio_tool_default_schema_and_config() {
let tool = ToolDef::audio("tts", "d", "openai", "tts-1", None, HashMap::new());
assert_eq!(tool.tool_type, ToolType::GenerateAudio);
assert_eq!(
tool.config.get("taskType"),
Some(&Value::String("GENERATE_AUDIO".to_owned()))
);
assert!(tool.input_schema["properties"]["voice"].is_object());
assert_eq!(tool.input_schema["required"], serde_json::json!(["text"]));
}
#[test]
fn test_video_tool_default_schema_and_config() {
let tool = ToolDef::video("vid", "d", "openai", "sora-2", None, HashMap::new());
assert_eq!(tool.tool_type, ToolType::GenerateVideo);
assert_eq!(
tool.config.get("taskType"),
Some(&Value::String("GENERATE_VIDEO".to_owned()))
);
assert!(tool.input_schema["properties"]["duration"].is_object());
assert_eq!(tool.input_schema["required"], serde_json::json!(["prompt"]));
}
#[test]
fn test_pdf_tool_default_schema_and_config() {
let tool = ToolDef::pdf(
"generate_pdf",
"Generate a PDF document from markdown text.",
None,
HashMap::new(),
);
assert_eq!(tool.tool_type, ToolType::GeneratePdf);
assert_eq!(
tool.config.get("taskType"),
Some(&Value::String("GENERATE_PDF".to_owned()))
);
assert!(!tool.config.contains_key("llmProvider"));
assert!(tool.input_schema["properties"]["markdown"].is_object());
}
#[test]
fn test_pdf_tool_merges_extra_defaults() {
let mut defaults = HashMap::new();
defaults.insert("pageSize".to_owned(), Value::String("LETTER".to_owned()));
let tool = ToolDef::pdf("t", "d", None, defaults);
assert_eq!(
tool.config.get("pageSize"),
Some(&Value::String("LETTER".to_owned()))
);
}
#[test]
fn test_rag_index_tool_default_namespace_and_schema() {
let tool = ToolDef::rag_index(
"index_document",
"d",
"pgvectordb",
"product_docs",
"openai",
"text-embedding-3-small",
None,
None,
None,
None,
None,
);
assert_eq!(tool.tool_type, ToolType::RagIndex);
assert_eq!(
tool.config.get("taskType"),
Some(&Value::String("LLM_INDEX_TEXT".to_owned()))
);
assert_eq!(
tool.config.get("namespace"),
Some(&Value::String("default_ns".to_owned()))
);
assert_eq!(
tool.config.get("vectorDB"),
Some(&Value::String("pgvectordb".to_owned()))
);
assert_eq!(
tool.input_schema["required"],
serde_json::json!(["text", "docId"])
);
assert!(!tool.config.contains_key("chunkSize"));
}
#[test]
fn test_rag_index_tool_optional_fields_when_given() {
let tool = ToolDef::rag_index(
"t",
"d",
"pgvectordb",
"docs",
"openai",
"text-embedding-3-small",
Some("custom_ns".to_owned()),
Some(500),
Some(50),
Some(1536),
None,
);
assert_eq!(
tool.config.get("namespace"),
Some(&Value::String("custom_ns".to_owned()))
);
assert_eq!(tool.config.get("chunkSize"), Some(&Value::from(500)));
assert_eq!(tool.config.get("chunkOverlap"), Some(&Value::from(50)));
assert_eq!(tool.config.get("dimensions"), Some(&Value::from(1536)));
}
#[test]
fn test_rag_search_tool_default_max_results_and_namespace() {
let tool = ToolDef::rag_search(
"search_kb",
"d",
"pgvectordb",
"product_docs",
"openai",
"text-embedding-3-small",
None,
None,
None,
None,
);
assert_eq!(tool.tool_type, ToolType::RagSearch);
assert_eq!(
tool.config.get("taskType"),
Some(&Value::String("LLM_SEARCH_INDEX".to_owned()))
);
assert_eq!(tool.config.get("maxResults"), Some(&Value::from(5)));
assert_eq!(
tool.config.get("namespace"),
Some(&Value::String("default_ns".to_owned()))
);
assert_eq!(tool.input_schema["required"], serde_json::json!(["query"]));
}
#[test]
fn test_rag_search_tool_custom_max_results() {
let tool = ToolDef::rag_search(
"t",
"d",
"pgvectordb",
"docs",
"openai",
"text-embedding-3-small",
None,
Some(10),
None,
None,
);
assert_eq!(tool.config.get("maxResults"), Some(&Value::from(10)));
}
#[test]
fn test_wait_for_message_tool_blocking_default() {
let tool = ToolDef::wait_for_message("wait_for_message", "d", 1, true);
assert_eq!(tool.tool_type, ToolType::PullWorkflowMessages);
assert_eq!(tool.config.get("batchSize"), Some(&Value::from(1)));
assert!(!tool.config.contains_key("blocking"));
assert_eq!(
tool.input_schema,
serde_json::json!({"type": "object", "properties": {}})
);
}
#[test]
fn test_wait_for_message_tool_non_blocking_emits_false() {
let tool = ToolDef::wait_for_message("t", "d", 5, false);
assert_eq!(tool.config.get("batchSize"), Some(&Value::from(5)));
assert_eq!(tool.config.get("blocking"), Some(&Value::Bool(false)));
}
#[test]
fn test_tool_type_as_str_matches_wire_strings() {
assert_eq!(ToolType::Api.as_str(), "api");
assert_eq!(ToolType::GenerateImage.as_str(), "generate_image");
assert_eq!(ToolType::GenerateAudio.as_str(), "generate_audio");
assert_eq!(ToolType::GenerateVideo.as_str(), "generate_video");
assert_eq!(ToolType::GeneratePdf.as_str(), "generate_pdf");
assert_eq!(ToolType::RagIndex.as_str(), "rag_index");
assert_eq!(ToolType::RagSearch.as_str(), "rag_search");
assert_eq!(
ToolType::PullWorkflowMessages.as_str(),
"pull_workflow_messages"
);
}
}