Skip to main content

graphrt_core/
tool_node.rs

1//! The generic `tool` node and [`NativeTools`], a [`ToolRuntime`] built from
2//! Rust closures.
3//!
4//! The `tool` node calls one tool of a provider registered in the
5//! [`ToolRegistry`] service:
6//!
7//! ```yaml
8//! - id: weather
9//!   type: tool
10//!   provider_id: builtin          # or e.g. "mcp:github"
11//!   tool_name: get_weather
12//!   tool_parameters:
13//!     city:  { type: variable, value: [start, city] }
14//!     units: { type: constant, value: metric }
15//!     note:  { type: mixed,    value: "asked by {{#sys.user_id#}}" }
16//! ```
17//!
18//! A simpler `arguments` map is also accepted: string values are templates
19//! (a lone `{{#a.b#}}` placeholder keeps its typed value), other values are
20//! constants.
21//!
22//! Outputs: `text` (string), `json` (structured result, or `null`; when the text
23//! looks like JSON but does not parse, metadata `json_error` says why), `files`
24//! (array, currently always empty), `is_error` (bool) and `error` (the tool's error
25//! text, or `null`). A tool-reported error fails the node unless
26//! `ignore_tool_errors` is set, in which case `is_error` / `error` let a downstream
27//! branch react. `variable` arguments that do not resolve are sent as `null` and
28//! listed in metadata `missing_arguments`.
29
30use 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
45/// Node kind handled by [`ToolNode`].
46pub const KIND: &str = "tool";
47
48/// Register the `tool` node kind.
49pub 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
53/// Catalog descriptor of the `tool` node.
54pub 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/// How one tool argument is produced.
95#[derive(Clone, Debug, PartialEq, Deserialize)]
96#[serde(tag = "type", rename_all = "lowercase")]
97enum ArgSource {
98    /// Text template, rendered against the pool.
99    Mixed { value: Template },
100    /// Value read from a selector (typed).
101    Variable { value: Selector },
102    /// Literal value.
103    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    /// Constant configuration parameters; lowest precedence.
117    #[serde(default)]
118    tool_configurations: IndexMap<String, Value>,
119    /// Shorthand: strings are templates, everything else a constant.
120    #[serde(default)]
121    arguments: IndexMap<String, Value>,
122    /// When true, a tool-reported error becomes a normal output instead of a node failure.
123    #[serde(default)]
124    ignore_tool_errors: bool,
125}
126
127/// Calls one tool from the [`ToolRegistry`] service.
128#[derive(Debug, Clone)]
129pub struct ToolNode {
130    provider: String,
131    tool: String,
132    /// Arguments in precedence order (later entries override earlier ones).
133    args: Vec<(String, ArgSource)>,
134    ignore_tool_errors: bool,
135}
136
137impl ToolNode {
138    /// Build from a node document.
139    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    /// Resolve arguments. Returns `(plaintext arguments for the call, masked copy for observability)`.
165    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                // Text templates: render twice so the observable copy keeps secrets masked.
171                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                        // A lone placeholder keeps the typed value (numbers stay numbers).
178                        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        // With `ignore_tool_errors`, the failure stays visible to the graph through the
205        // `is_error` / `error` outputs so a downstream branch can react to it.
206        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    /// Selectors of `variable` arguments that do not resolve (sent to the tool as `null`).
226    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
237/// Structured view of a text result when it looks like a JSON object or array.
238/// Returns the parse error when it looks like JSON but is not valid.
239fn 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/// A [`ToolRuntime`] whose tools are Rust closures.
271///
272/// ```
273/// use graphrt_core::tool::{ToolOutput, ToolSpec};
274/// use graphrt_core::tool_node::NativeTools;
275///
276/// let tools = NativeTools::new().with(
277///     ToolSpec {
278///         name: "echo".into(),
279///         description: "Echo the `text` argument".into(),
280///         parameters: serde_json::json!({
281///             "type": "object",
282///             "properties": { "text": { "type": "string" } },
283///             "required": ["text"]
284///         }),
285///     },
286///     |args| async move { Ok(ToolOutput::text(args["text"].as_str().unwrap_or_default())) },
287/// );
288/// ```
289#[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    /// Add (or replace) a tool.
306    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    /// Builder-style [`NativeTools::add`].
317    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
355/// Lightweight argument check: the arguments must be an object containing every
356/// property listed in the schema's `required` array. Full JSON Schema validation
357/// is left to the tool itself.
358fn 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        // Observability metadata never contains the secret.
453        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); // note, city, days, auth
459    }
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        // Looks like JSON but is truncated: `json` is null and the reason is recorded.
490        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}