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_lazily_described(KIND, descriptor, |doc| {
51        ToolNode::from_doc(doc).map(|n| Arc::new(n) as Arc<dyn Node>)
52    });
53}
54
55/// Catalog descriptor of the `tool` node.
56pub 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/// How one tool argument is produced.
97#[derive(Clone, Debug, PartialEq, Deserialize)]
98#[serde(tag = "type", rename_all = "lowercase")]
99enum ArgSource {
100    /// Text template, rendered against the pool.
101    Mixed { value: Template },
102    /// Value read from a selector (typed).
103    Variable { value: Selector },
104    /// Literal value.
105    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    /// Constant configuration parameters; lowest precedence.
119    #[serde(default)]
120    tool_configurations: IndexMap<String, Value>,
121    /// Shorthand: strings are templates, everything else a constant.
122    #[serde(default)]
123    arguments: IndexMap<String, Value>,
124    /// When true, a tool-reported error becomes a normal output instead of a node failure.
125    #[serde(default)]
126    ignore_tool_errors: bool,
127}
128
129/// Calls one tool from the [`ToolRegistry`] service.
130#[derive(Debug, Clone)]
131pub struct ToolNode {
132    provider: String,
133    tool: String,
134    /// Arguments in precedence order (later entries override earlier ones).
135    args: Vec<(String, ArgSource)>,
136    ignore_tool_errors: bool,
137}
138
139impl ToolNode {
140    /// Build from a node document.
141    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    /// Resolve arguments. Returns `(plaintext arguments for the call, masked copy for observability)`.
167    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                // Text templates: render twice so the observable copy keeps secrets masked.
173                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                        // A lone placeholder keeps the typed value (numbers stay numbers).
180                        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        // With `ignore_tool_errors`, the failure stays visible to the graph through the
207        // `is_error` / `error` outputs so a downstream branch can react to it.
208        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    /// Selectors of `variable` arguments that do not resolve (sent to the tool as `null`).
228    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
239/// Structured view of a text result when it looks like a JSON object or array.
240/// Returns the parse error when it looks like JSON but is not valid.
241fn 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/// A [`ToolRuntime`] whose tools are Rust closures.
273///
274/// ```
275/// use graphrt_core::tool::{ToolOutput, ToolSpec};
276/// use graphrt_core::tool_node::NativeTools;
277///
278/// let tools = NativeTools::new().with(
279///     ToolSpec {
280///         name: "echo".into(),
281///         description: "Echo the `text` argument".into(),
282///         parameters: serde_json::json!({
283///             "type": "object",
284///             "properties": { "text": { "type": "string" } },
285///             "required": ["text"]
286///         }),
287///     },
288///     |args| async move { Ok(ToolOutput::text(args["text"].as_str().unwrap_or_default())) },
289/// );
290/// ```
291#[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    /// Add (or replace) a tool.
308    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    /// Builder-style [`NativeTools::add`].
319    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
357/// Lightweight argument check: the arguments must be an object containing every
358/// property listed in the schema's `required` array. Full JSON Schema validation
359/// is left to the tool itself.
360fn 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        // Observability metadata never contains the secret.
455        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); // note, city, days, auth
461    }
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        // Looks like JSON but is truncated: `json` is null and the reason is recorded.
492        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}