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