1use std::fmt;
31use std::future::Future;
32use std::sync::Arc;
33
34use futures::future::BoxFuture;
35use indexmap::IndexMap;
36use serde::Deserialize;
37
38use crate::dsl::NodeDoc;
39use crate::node::{ConfigError, Node, NodeContext, NodeError, NodeOutput, NodeResult, Registry, parse_config};
40use crate::pool::{Selector, VariablePool};
41use crate::template::Template;
42use crate::tool::{ToolError, ToolOutput, ToolRegistry, ToolRuntime, ToolSpec};
43use crate::value::Value;
44
45pub const KIND: &str = "tool";
47
48pub fn register(registry: &mut Registry) {
50 registry.register_described(descriptor(), |doc| ToolNode::from_doc(doc).map(|n| Arc::new(n) as Arc<dyn Node>));
51}
52
53pub fn descriptor() -> crate::catalog::NodeDescriptor {
55 use crate::catalog::schema::{nested, object, selector};
56 use crate::catalog::{NodeCategory, NodeDescriptor, OutputDescriptor};
57 use crate::value::ValueType;
58
59 let parameter = serde_json::json!({
60 "oneOf": [
61 nested(serde_json::json!({ "type": { "const": "mixed" }, "value": { "type": "string" } }), &["type", "value"]),
62 nested(serde_json::json!({ "type": { "const": "variable" }, "value": selector() }), &["type", "value"]),
63 nested(serde_json::json!({ "type": { "const": "constant" }, "value": {} }), &["type"])
64 ]
65 });
66 NodeDescriptor::new(KIND, "Tool", NodeCategory::Integration)
67 .describe(
68 "Calls one tool from a registered tool provider (native tools, MCP servers, plugins). \
69 Arguments: `tool_parameters` (mixed template / variable / constant) override `arguments` \
70 (strings are templates) which override `tool_configurations` (constants).",
71 )
72 .icon("wrench")
73 .source("builtin")
74 .schema(object(
75 serde_json::json!({
76 "provider_id": { "type": "string", "minLength": 1 },
77 "provider": { "type": "string", "minLength": 1 },
78 "provider_name": { "type": "string", "minLength": 1 },
79 "tool_name": { "type": "string", "minLength": 1 },
80 "tool_parameters": { "type": "object", "additionalProperties": parameter },
81 "tool_configurations": { "type": "object" },
82 "arguments": { "type": "object" },
83 "ignore_tool_errors": { "type": "boolean", "default": false }
84 }),
85 &["tool_name"],
86 ))
87 .output(OutputDescriptor::new("text", ValueType::String).describe("Text result"))
88 .output(OutputDescriptor::new("json", ValueType::Any).describe("Structured result, or the text parsed as JSON"))
89 .output(OutputDescriptor::new("files", ValueType::ArrayFile))
90 .output(OutputDescriptor::new("is_error", ValueType::Boolean))
91 .output(OutputDescriptor::new("error", ValueType::String).describe("Error text when the tool reported one"))
92}
93
94#[derive(Clone, Debug, PartialEq, Deserialize)]
96#[serde(tag = "type", rename_all = "lowercase")]
97enum ArgSource {
98 Mixed { value: Template },
100 Variable { value: Selector },
102 Constant {
104 #[serde(default)]
105 value: Value,
106 },
107}
108
109#[derive(Debug, Deserialize)]
110struct ToolNodeConfig {
111 #[serde(alias = "provider", alias = "provider_name")]
112 provider_id: String,
113 tool_name: String,
114 #[serde(default)]
115 tool_parameters: IndexMap<String, ArgSource>,
116 #[serde(default)]
118 tool_configurations: IndexMap<String, Value>,
119 #[serde(default)]
121 arguments: IndexMap<String, Value>,
122 #[serde(default)]
124 ignore_tool_errors: bool,
125}
126
127#[derive(Debug, Clone)]
129pub struct ToolNode {
130 provider: String,
131 tool: String,
132 args: Vec<(String, ArgSource)>,
134 ignore_tool_errors: bool,
135}
136
137impl ToolNode {
138 pub fn from_doc(doc: &NodeDoc) -> Result<Self, ConfigError> {
140 let cfg: ToolNodeConfig = parse_config(doc)?;
141 if cfg.provider_id.trim().is_empty() {
142 return Err(ConfigError::new(doc, "`provider_id` must not be empty"));
143 }
144 if cfg.tool_name.trim().is_empty() {
145 return Err(ConfigError::new(doc, "`tool_name` must not be empty"));
146 }
147 let mut args: Vec<(String, ArgSource)> = Vec::new();
148 for (k, v) in cfg.tool_configurations {
149 args.push((k, ArgSource::Constant { value: v }));
150 }
151 for (k, v) in cfg.arguments {
152 let source = match v {
153 Value::String(s) => ArgSource::Mixed { value: Template::parse(&s) },
154 other => ArgSource::Constant { value: other },
155 };
156 args.push((k, source));
157 }
158 for (k, v) in cfg.tool_parameters {
159 args.push((k, v));
160 }
161 Ok(Self { provider: cfg.provider_id, tool: cfg.tool_name, args, ignore_tool_errors: cfg.ignore_tool_errors })
162 }
163
164 fn resolve_args(&self, pool: &VariablePool) -> (serde_json::Value, Value) {
166 let mut exposed = serde_json::Map::new();
167 let mut masked: IndexMap<String, Value> = IndexMap::new();
168 for (name, source) in &self.args {
169 match source {
170 ArgSource::Mixed { value } if !matches!(value.parts(), [crate::template::Part::Var(_)]) => {
172 exposed.insert(name.clone(), serde_json::Value::String(value.render_exposed(pool)));
173 masked.insert(name.clone(), Value::from(value.render(pool)));
174 }
175 _ => {
176 let value = match source {
177 ArgSource::Mixed { value } => value.resolve(pool),
179 ArgSource::Variable { value } => pool.get_or_null(value),
180 ArgSource::Constant { value } => value.clone(),
181 };
182 exposed.insert(name.clone(), value.to_json_exposed());
183 masked.insert(name.clone(), value);
184 }
185 }
186 }
187 (serde_json::Value::Object(exposed), Value::from(masked))
188 }
189
190 async fn execute(&self, ctx: NodeContext) -> NodeResult {
191 let registry = ctx.require_service::<ToolRegistry>("tool registry")?;
192 let runtime = registry
193 .get(&self.provider)
194 .ok_or_else(|| NodeError::fatal("tool", format!("unknown tool provider `{}`", self.provider)))?
195 .clone();
196 let (arguments, masked_args) = self.resolve_args(&ctx.pool);
197 let missing = self.missing_variables(&ctx.pool);
198 let output = runtime.call(&self.tool, arguments).await.map_err(|e| NodeError::new("tool", e.to_string()))?;
199 if output.is_error && !self.ignore_tool_errors {
200 return Err(NodeError::fatal("tool_error", output.text));
201 }
202 let (json, json_error) =
203 if output.data.is_null() { parse_json_text(&output.text) } else { (output.data, None) };
204 let error = if output.is_error { Value::from(output.text.as_str()) } else { Value::Null };
207 let mut result = NodeOutput::new()
208 .with("text", output.text)
209 .with("json", json)
210 .with("files", Value::array([]))
211 .with("is_error", output.is_error)
212 .with("error", error)
213 .meta("provider", self.provider.as_str())
214 .meta("tool", self.tool.as_str())
215 .meta("arguments", masked_args);
216 if let Some(e) = json_error {
217 result = result.meta("json_error", e);
218 }
219 if !missing.is_empty() {
220 result = result.meta("missing_arguments", Value::array(missing.into_iter().map(Value::from)));
221 }
222 Ok(result.into())
223 }
224
225 fn missing_variables(&self, pool: &VariablePool) -> Vec<String> {
227 self.args
228 .iter()
229 .filter_map(|(_, source)| match source {
230 ArgSource::Variable { value } if pool.get(value).is_none() => Some(value.to_string()),
231 _ => None,
232 })
233 .collect()
234 }
235}
236
237fn parse_json_text(text: &str) -> (Value, Option<String>) {
240 let trimmed = text.trim_start();
241 if trimmed.starts_with('{') || trimmed.starts_with('[') {
242 return match serde_json::from_str::<serde_json::Value>(text) {
243 Ok(json) => (Value::from_json(json), None),
244 Err(e) => (Value::Null, Some(e.to_string())),
245 };
246 }
247 (Value::Null, None)
248}
249
250impl Node for ToolNode {
251 fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
252 Box::pin(self.execute(ctx))
253 }
254
255 fn inputs(&self) -> Vec<Selector> {
256 let mut out = Vec::new();
257 for (_, source) in &self.args {
258 match source {
259 ArgSource::Mixed { value } => out.extend(value.selectors().cloned()),
260 ArgSource::Variable { value } => out.push(value.clone()),
261 ArgSource::Constant { .. } => {}
262 }
263 }
264 out
265 }
266}
267
268type ToolFn = Arc<dyn Fn(serde_json::Value) -> BoxFuture<'static, Result<ToolOutput, ToolError>> + Send + Sync>;
269
270#[derive(Clone, Default)]
290pub struct NativeTools {
291 tools: IndexMap<String, (ToolSpec, ToolFn)>,
292}
293
294impl fmt::Debug for NativeTools {
295 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
296 f.debug_struct("NativeTools").field("tools", &self.tools.keys().collect::<Vec<_>>()).finish()
297 }
298}
299
300impl NativeTools {
301 pub fn new() -> Self {
302 Self::default()
303 }
304
305 pub fn add<F, Fut>(&mut self, spec: ToolSpec, handler: F) -> &mut Self
307 where
308 F: Fn(serde_json::Value) -> Fut + Send + Sync + 'static,
309 Fut: Future<Output = Result<ToolOutput, ToolError>> + Send + 'static,
310 {
311 let handler: ToolFn = Arc::new(move |args| Box::pin(handler(args)));
312 self.tools.insert(spec.name.clone(), (spec, handler));
313 self
314 }
315
316 pub fn with<F, Fut>(mut self, spec: ToolSpec, handler: F) -> Self
318 where
319 F: Fn(serde_json::Value) -> Fut + Send + Sync + 'static,
320 Fut: Future<Output = Result<ToolOutput, ToolError>> + Send + 'static,
321 {
322 self.add(spec, handler);
323 self
324 }
325
326 pub fn len(&self) -> usize {
327 self.tools.len()
328 }
329
330 pub fn is_empty(&self) -> bool {
331 self.tools.is_empty()
332 }
333}
334
335impl ToolRuntime for NativeTools {
336 fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>> {
337 let specs = self.tools.values().map(|(spec, _)| spec.clone()).collect();
338 Box::pin(futures::future::ready(Ok(specs)))
339 }
340
341 fn call<'a>(&'a self, name: &'a str, arguments: serde_json::Value) -> BoxFuture<'a, Result<ToolOutput, ToolError>> {
342 let Some((spec, handler)) = self.tools.get(name) else {
343 return Box::pin(futures::future::ready(Err(ToolError {
344 tool: name.to_owned(),
345 message: "unknown tool".to_owned(),
346 })));
347 };
348 if let Err(message) = check_required(&spec.parameters, &arguments) {
349 return Box::pin(futures::future::ready(Err(ToolError { tool: name.to_owned(), message })));
350 }
351 handler(arguments)
352 }
353}
354
355fn check_required(schema: &serde_json::Value, arguments: &serde_json::Value) -> Result<(), String> {
359 let Some(args) = arguments.as_object() else {
360 return Err("arguments must be a JSON object".to_owned());
361 };
362 let required = schema.get("required").and_then(serde_json::Value::as_array);
363 let missing: Vec<&str> = required
364 .into_iter()
365 .flatten()
366 .filter_map(serde_json::Value::as_str)
367 .filter(|key| args.get(*key).is_none_or(serde_json::Value::is_null))
368 .collect();
369 if missing.is_empty() { Ok(()) } else { Err(format!("missing required arguments: {}", missing.join(", "))) }
370}
371
372#[cfg(test)]
373mod tests {
374 use std::sync::Mutex;
375
376 use super::*;
377 use crate::node::{NodeOutcome, Services};
378
379 #[derive(Debug, Default)]
380 struct Recorder {
381 calls: Mutex<Vec<(String, serde_json::Value)>>,
382 reply: Option<ToolOutput>,
383 }
384
385 impl ToolRuntime for Recorder {
386 fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>> {
387 Box::pin(futures::future::ready(Ok(Vec::new())))
388 }
389 fn call<'a>(
390 &'a self,
391 name: &'a str,
392 arguments: serde_json::Value,
393 ) -> BoxFuture<'a, Result<ToolOutput, ToolError>> {
394 self.calls.lock().unwrap().push((name.to_owned(), arguments));
395 let reply = self.reply.clone().unwrap_or_else(|| ToolOutput::text("{\"ok\":true}"));
396 Box::pin(futures::future::ready(Ok(reply)))
397 }
398 }
399
400 fn doc(config: serde_json::Value) -> NodeDoc {
401 NodeDoc::new("t", KIND, config)
402 }
403
404 fn pool() -> VariablePool {
405 let mut p = VariablePool::new();
406 p.insert("start", "city", Value::from("Jakarta"));
407 p.insert("start", "days", Value::Int(3));
408 p.insert("env", "TOKEN", Value::Secret(Arc::from("s3cret")));
409 p
410 }
411
412 fn ctx_with(runtime: Arc<dyn ToolRuntime>) -> NodeContext {
413 let mut reg = ToolRegistry::new();
414 reg.add("mock", runtime);
415 NodeContext::for_test("t", pool()).with_services(Arc::new(Services::new().with(reg)))
416 }
417
418 fn completed(r: NodeResult) -> NodeOutput {
419 match r {
420 Ok(NodeOutcome::Completed(o)) => o,
421 other => panic!("unexpected {other:?}"),
422 }
423 }
424
425 #[tokio::test]
426 async fn resolves_all_argument_kinds() {
427 let rec = Arc::new(Recorder::default());
428 let node = ToolNode::from_doc(&doc(serde_json::json!({
429 "provider_id": "mock",
430 "tool_name": "weather",
431 "tool_configurations": {"units": "imperial", "lang": "en"},
432 "arguments": {"note": "for {{#start.city#}}", "raw": 5},
433 "tool_parameters": {
434 "city": {"type": "variable", "value": ["start", "city"]},
435 "days": {"type": "mixed", "value": "{{#start.days#}}"},
436 "units": {"type": "constant", "value": "metric"},
437 "auth": {"type": "mixed", "value": "Bearer {{#env.TOKEN#}}"}
438 }
439 })))
440 .unwrap();
441 let out = completed(node.run(ctx_with(rec.clone())).await);
442 let calls = rec.calls.lock().unwrap();
443 let (name, args) = &calls[0];
444 assert_eq!(name, "weather");
445 assert_eq!(args["city"], "Jakarta");
446 assert_eq!(args["days"], 3);
447 assert_eq!(args["units"], "metric", "tool_parameters override configurations");
448 assert_eq!(args["lang"], "en");
449 assert_eq!(args["note"], "for Jakarta");
450 assert_eq!(args["raw"], 5);
451 assert_eq!(args["auth"], "Bearer s3cret", "tool receives the plaintext secret");
452 let meta = serde_json::to_string(&out.metadata).unwrap();
454 assert!(!meta.contains("s3cret"));
455 assert_eq!(out.outputs["text"], Value::from("{\"ok\":true}"));
456 assert_eq!(out.outputs["json"].get_path(&["ok"]), Some(Value::Bool(true)));
457 assert_eq!(out.outputs["files"], Value::array([]));
458 assert_eq!(node.inputs().len(), 4); }
460
461 #[tokio::test]
462 async fn tool_error_fails_unless_ignored() {
463 let rec = Arc::new(Recorder { reply: Some(ToolOutput::error("boom")), ..Recorder::default() });
464 let cfg = serde_json::json!({"provider": "mock", "tool_name": "x"});
465 let node = ToolNode::from_doc(&doc(cfg)).unwrap();
466 let err = node.run(ctx_with(rec.clone())).await.unwrap_err();
467 assert_eq!(err.kind, "tool_error");
468 assert!(!err.retryable);
469
470 let cfg = serde_json::json!({"provider": "mock", "tool_name": "x", "ignore_tool_errors": true});
471 let node = ToolNode::from_doc(&doc(cfg)).unwrap();
472 let out = completed(node.run(ctx_with(rec)).await);
473 assert_eq!(out.outputs["text"], Value::from("boom"));
474 assert_eq!(out.outputs["is_error"], Value::Bool(true));
475 assert_eq!(out.outputs["error"], Value::from("boom"));
476 }
477
478 #[tokio::test]
479 async fn successful_call_has_no_error_output() {
480 let rec = Arc::new(Recorder { reply: Some(ToolOutput::text("{\"a\": 1")), ..Recorder::default() });
481 let node = ToolNode::from_doc(&doc(serde_json::json!({
482 "provider": "mock", "tool_name": "x",
483 "tool_parameters": {"city": {"type": "variable", "value": ["start", "nope"]}}
484 })))
485 .unwrap();
486 let out = completed(node.run(ctx_with(rec)).await);
487 assert_eq!(out.outputs["is_error"], Value::Bool(false));
488 assert_eq!(out.outputs["error"], Value::Null);
489 assert_eq!(out.outputs["json"], Value::Null);
491 assert!(out.metadata.contains_key("json_error"));
492 assert_eq!(out.metadata["missing_arguments"], Value::array([Value::from("start.nope")]));
493 }
494
495 #[tokio::test]
496 async fn missing_provider_or_registry_is_fatal() {
497 let node = ToolNode::from_doc(&doc(serde_json::json!({"provider_id": "nope", "tool_name": "x"}))).unwrap();
498 let err = node.run(ctx_with(Arc::new(Recorder::default()))).await.unwrap_err();
499 assert!(!err.retryable);
500 let err = node.run(NodeContext::for_test("t", pool())).await.unwrap_err();
501 assert_eq!(err.kind, "missing_service");
502 }
503
504 #[test]
505 fn rejects_invalid_config() {
506 assert!(ToolNode::from_doc(&doc(serde_json::json!({"tool_name": "x"}))).is_err());
507 assert!(ToolNode::from_doc(&doc(serde_json::json!({"provider_id": " ", "tool_name": "x"}))).is_err());
508 let bad_param = serde_json::json!({"provider_id": "p", "tool_name": "x",
509 "tool_parameters": {"a": {"type": "variable", "value": ["only"]}}});
510 assert!(ToolNode::from_doc(&doc(bad_param)).is_err());
511 }
512
513 #[test]
514 fn registers_kind() {
515 let mut r = Registry::new();
516 register(&mut r);
517 assert!(r.contains(KIND));
518 }
519
520 fn echo_spec() -> ToolSpec {
521 ToolSpec {
522 name: "echo".into(),
523 description: "echo".into(),
524 parameters: serde_json::json!({"type": "object", "required": ["text"]}),
525 }
526 }
527
528 #[tokio::test]
529 async fn native_tools_dispatch_and_validate() {
530 let tools = NativeTools::new().with(echo_spec(), |args| async move {
531 Ok(ToolOutput::text(args["text"].as_str().unwrap_or_default().to_uppercase()))
532 });
533 assert_eq!(tools.len(), 1);
534 assert_eq!(tools.list().await.unwrap()[0].name, "echo");
535 let out = tools.call("echo", serde_json::json!({"text": "hi"})).await.unwrap();
536 assert_eq!(out.text, "HI");
537 let err = tools.call("echo", serde_json::json!({})).await.unwrap_err();
538 assert!(err.message.contains("text"));
539 assert!(tools.call("echo", serde_json::json!("str")).await.is_err());
540 assert!(tools.call("nope", serde_json::json!({})).await.is_err());
541 }
542
543 #[tokio::test]
544 async fn tool_node_with_native_tools() {
545 let tools = NativeTools::new().with(echo_spec(), |args| async move {
546 Ok(ToolOutput { text: "done".into(), data: Value::from_json(args), is_error: false })
547 });
548 let node = ToolNode::from_doc(&doc(serde_json::json!({
549 "provider_id": "mock", "tool_name": "echo", "arguments": {"text": "{{#start.city#}}"}
550 })))
551 .unwrap();
552 let out = completed(node.run(ctx_with(Arc::new(tools))).await);
553 assert_eq!(out.outputs["json"].get_path(&["text"]), Some(Value::from("Jakarta")));
554 }
555}