Skip to main content

graphrt_llm/nodes/
agent.rs

1//! `agent` node: a tool-calling loop.
2//!
3//! Each iteration calls the model with the available tools, runs the tool
4//! calls it requests (concurrently when `parallel_tool_calls` is on) and feeds
5//! the results back, until the model answers without calling tools. On the
6//! last allowed iteration the tools stay declared (providers require that when
7//! the history contains tool calls) but the model may not call them
8//! (`tool_choice: none`), so the run always ends with an answer.
9//!
10//! Streaming: only the final answer is streamed on field `text`, so the
11//! streamed text always equals the `text` output. Turns that may still call
12//! tools are buffered; text the model writes alongside tool calls is reported
13//! as an `agent_thought` progress event instead.
14//!
15//! Tool-call arguments that are not a JSON object are not executed; the model
16//! receives an error result explaining the problem so it can retry the call.
17//!
18//! Tools come from the [`ToolRegistry`] service and are referenced as
19//! `provider/name` (or `provider/*` for every tool of a provider). Tools listed
20//! in `require_approval` pause the run before they execute; other calls of the
21//! same turn run immediately. The host resumes with `{"approved": true|false}`
22//! for every pending call, or per call with `{"approvals": {"<call id>": true}}`,
23//! optionally with a `reason`. Calls without a decision (including when the
24//! resume input is missing or not understood) keep the run paused.
25//!
26//! Tool results may carry images (see `docs/tool-images.md`): they are checked
27//! against the limits of [`check_images`] (invalid ones are dropped with a
28//! note to the model) and follow the result text in the `tool` message.
29//! `keep_tool_images` (default 3, `null` for all) bounds how many image-bearing
30//! results keep their images.
31//!
32//! Progress events: `agent_step`, `agent_thought`, `tool_call`, `tool_result`,
33//! `tool_denied`. Outputs: `text`, `tool_calls`
34//! (`[{name, provider, tool, arguments, result, is_error, images}]`), `iterations`,
35//! `stopped_reason` (`completed`, `max_iterations` or `length`), `usage`.
36
37use std::collections::{HashMap, HashSet};
38use std::sync::Arc;
39
40use futures::future::BoxFuture;
41use graphrt_core::dsl::NodeDoc;
42use graphrt_core::event::Usage;
43use graphrt_core::node::{ConfigError, NodeOutcome, NodeResult, PauseRequest, parse_config};
44use graphrt_core::template::Template;
45use graphrt_core::tool::{ToolImage, ToolOutput, ToolRegistry, ToolRuntime, ToolSpec, check_images};
46use graphrt_core::value::Value;
47use graphrt_core::{Node, NodeContext, NodeError, NodeOutput, Selector};
48use serde::{Deserialize, Serialize};
49use serde_json::{Value as Json, json};
50
51use super::common::{
52    FinishCheck, MemoryConfig, ModelConfig, StreamField, StreamMode, VisionConfig, check_finish, invoke, model_for,
53    usage_value,
54};
55use crate::types::{ContentPart, FinishReason, Message, Role, ToolCall, ToolChoice};
56
57/// Upper bound for `max_iterations`.
58pub const MAX_ITERATIONS_LIMIT: u32 = 100;
59
60/// Reference to a tool: `"provider/name"` or `{provider, name}`.
61#[derive(Clone, Debug, Deserialize)]
62#[serde(untagged)]
63pub enum ToolRef {
64    Path(String),
65    Pair { provider: String, name: String },
66}
67
68impl ToolRef {
69    fn split(&self) -> Option<(String, String)> {
70        match self {
71            ToolRef::Path(p) => {
72                let (provider, name) = p.split_once('/')?;
73                if provider.is_empty() || name.is_empty() {
74                    return None;
75                }
76                Some((provider.to_owned(), name.to_owned()))
77            }
78            ToolRef::Pair { provider, name } if !provider.is_empty() && !name.is_empty() => {
79                Some((provider.clone(), name.clone()))
80            }
81            ToolRef::Pair { .. } => None,
82        }
83    }
84}
85
86fn default_query() -> Template {
87    Template::parse("{{#sys.query#}}")
88}
89
90fn default_max_iterations() -> u32 {
91    10
92}
93
94fn default_true() -> bool {
95    true
96}
97
98fn default_max_tool_output() -> usize {
99    32_000
100}
101
102fn default_keep_tool_images() -> Option<usize> {
103    Some(3)
104}
105
106/// Configuration of the `agent` node.
107#[derive(Clone, Debug, Deserialize)]
108pub struct AgentConfig {
109    pub model: ModelConfig,
110    /// System prompt.
111    #[serde(default)]
112    pub instruction: Option<Template>,
113    /// User message (default `{{#sys.query#}}`).
114    #[serde(default = "default_query")]
115    pub query: Template,
116    #[serde(default)]
117    pub tools: Vec<ToolRef>,
118    /// Maximum model calls. Default 10.
119    #[serde(default = "default_max_iterations")]
120    pub max_iterations: u32,
121    /// Tool calls beyond this number in one turn are rejected with an error result.
122    #[serde(default)]
123    pub max_tool_calls_per_turn: Option<usize>,
124    #[serde(default = "default_true")]
125    pub parallel_tool_calls: bool,
126    #[serde(default)]
127    pub memory: Option<MemoryConfig>,
128    #[serde(default)]
129    pub vision: VisionConfig,
130    /// Tools that need host approval: `provider/name`, a tool name, or `*` for all.
131    #[serde(default)]
132    pub require_approval: Vec<String>,
133    /// Tool results longer than this (in characters) are truncated. Default 32 000.
134    #[serde(default = "default_max_tool_output")]
135    pub max_tool_output_chars: usize,
136    /// Keep the images of only the last N image-bearing tool results in the
137    /// conversation (older ones become a text placeholder). Default 3, since
138    /// images are resent on every turn; `null` keeps every image.
139    #[serde(default = "default_keep_tool_images")]
140    pub keep_tool_images: Option<usize>,
141}
142
143/// A tool bound for one run.
144#[derive(Clone, Debug)]
145struct BoundTool {
146    /// Name exposed to the model (unique, provider-safe characters).
147    exposed: String,
148    provider: String,
149    name: String,
150    runtime: Arc<dyn ToolRuntime>,
151    spec: ToolSpec,
152}
153
154/// One executed (or rejected) tool call.
155#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
156struct ToolLogEntry {
157    id: String,
158    name: String,
159    provider: String,
160    tool: String,
161    /// Parsed arguments, or the raw text when the model sent malformed JSON.
162    arguments: Json,
163    result: String,
164    is_error: bool,
165    /// Images sent to the model with the result.
166    #[serde(default)]
167    images: usize,
168}
169
170/// Persistable loop state, used to pause for tool approval.
171#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
172struct AgentState {
173    messages: Vec<Message>,
174    iteration: u32,
175    log: Vec<ToolLogEntry>,
176    usage: Usage,
177    /// Calls awaiting approval.
178    pending: Vec<ToolCall>,
179}
180
181/// Why the loop ended.
182#[derive(Clone, Debug, PartialEq, Eq)]
183enum StopReason {
184    /// The model answered without calling tools.
185    Completed,
186    /// The iteration limit forced a final answer without tools.
187    MaxIterations,
188    /// The final answer was cut off by the output token limit.
189    Length,
190    /// The provider ended the turn with a reason graphrt does not recognize.
191    Unrecognized(String),
192}
193
194impl StopReason {
195    fn as_str(&self) -> String {
196        match self {
197            StopReason::Completed => "completed".into(),
198            StopReason::MaxIterations => "max_iterations".into(),
199            StopReason::Length => "length".into(),
200            StopReason::Unrecognized(reason) => format!("finish:{reason}"),
201        }
202    }
203}
204
205/// The `agent` node.
206#[derive(Debug)]
207pub struct AgentNode {
208    config: AgentConfig,
209    refs: Vec<(String, String)>,
210}
211
212impl AgentNode {
213    pub fn from_doc(doc: &NodeDoc) -> Result<Self, ConfigError> {
214        let config: AgentConfig = parse_config(doc)?;
215        if config.max_iterations == 0 || config.max_iterations > MAX_ITERATIONS_LIMIT {
216            return Err(ConfigError::new(doc, format!("max_iterations must be between 1 and {MAX_ITERATIONS_LIMIT}")));
217        }
218        let refs = config
219            .tools
220            .iter()
221            .map(|r| {
222                r.split()
223                    .ok_or_else(|| ConfigError::new(doc, format!("invalid tool reference {r:?}; use `provider/name`")))
224            })
225            .collect::<Result<Vec<_>, _>>()?;
226        Ok(Self { config, refs })
227    }
228
229    /// Resolve tool references against the registry, assigning unique exposed names.
230    async fn bind_tools(&self, ctx: &NodeContext) -> Result<Vec<BoundTool>, NodeError> {
231        if self.refs.is_empty() {
232            return Ok(Vec::new());
233        }
234        let registry = ctx.require_service::<ToolRegistry>("tool registry (graphrt_core::tool::ToolRegistry)")?;
235        let mut listings: HashMap<String, Vec<ToolSpec>> = HashMap::new();
236        let mut bound: Vec<BoundTool> = Vec::new();
237        let mut used: HashSet<String> = HashSet::new();
238        for (provider, name) in &self.refs {
239            let runtime = registry
240                .get(provider)
241                .cloned()
242                .ok_or_else(|| NodeError::fatal("tool_not_found", format!("unknown tool provider `{provider}`")))?;
243            if !listings.contains_key(provider) {
244                let specs = runtime.list().await.map_err(|e| NodeError::new("tool", e.to_string()))?;
245                listings.insert(provider.clone(), specs);
246            }
247            let specs = listings.get(provider).map(Vec::as_slice).unwrap_or_default();
248            let selected: Vec<&ToolSpec> = if name == "*" {
249                specs.iter().collect()
250            } else {
251                let spec = specs.iter().find(|s| &s.name == name).ok_or_else(|| {
252                    NodeError::fatal("tool_not_found", format!("provider `{provider}` has no tool `{name}`"))
253                })?;
254                vec![spec]
255            };
256            for spec in selected {
257                if bound.iter().any(|b| &b.provider == provider && b.name == spec.name) {
258                    continue;
259                }
260                let exposed = unique_name(&spec.name, provider, &mut used);
261                bound.push(BoundTool {
262                    exposed: exposed.clone(),
263                    provider: provider.clone(),
264                    name: spec.name.clone(),
265                    runtime: Arc::clone(&runtime),
266                    spec: ToolSpec {
267                        name: exposed,
268                        description: spec.description.clone(),
269                        parameters: spec.parameters.clone(),
270                    },
271                });
272            }
273        }
274        Ok(bound)
275    }
276
277    fn needs_approval(&self, tool: &BoundTool) -> bool {
278        self.config.require_approval.iter().any(|r| {
279            r == "*" || *r == tool.exposed || *r == tool.name || *r == format!("{}/{}", tool.provider, tool.name)
280        })
281    }
282
283    fn call_needs_approval(&self, tools: &[BoundTool], call: &ToolCall) -> bool {
284        tools.iter().any(|t| t.exposed == call.name && self.needs_approval(t))
285    }
286
287    fn initial_state(&self, ctx: &NodeContext) -> Result<AgentState, NodeError> {
288        let cfg = &self.config;
289        let pool = &ctx.pool;
290        let mut messages = Vec::new();
291        if let Some(instruction) = &cfg.instruction {
292            let text = instruction.render(pool);
293            if !text.trim().is_empty() {
294                messages.push(Message::system(text));
295            }
296        }
297        if let Some(memory) = &cfg.memory {
298            messages.extend(memory.history(pool)?);
299        }
300        let query = cfg.query.render(pool);
301        let images = cfg.vision.image_parts(pool)?;
302        if query.trim().is_empty() && images.is_empty() {
303            if messages.iter().all(|m| m.role == Role::System) {
304                return Err(NodeError::invalid_input("agent query is empty"));
305            }
306        } else {
307            let mut user = Message::user(query);
308            user.content.extend(images);
309            messages.push(user);
310        }
311        Ok(AgentState { messages, ..AgentState::default() })
312    }
313
314    /// Apply the host's decisions to the pending calls. Returns the calls that
315    /// still have no decision.
316    async fn apply_decisions(
317        &self,
318        ctx: &NodeContext,
319        state: &mut AgentState,
320        tools: &[BoundTool],
321        input: Option<&Value>,
322    ) -> Vec<ToolCall> {
323        let decisions = Approvals::from_input(input);
324        let mut approved = Vec::new();
325        let mut undecided = Vec::new();
326        for call in std::mem::take(&mut state.pending) {
327            match decisions.decision(&call.id) {
328                Some(true) => approved.push(call),
329                Some(false) => self.deny(ctx, state, tools, &call, decisions.reason.as_deref()),
330                None => undecided.push(call),
331            }
332        }
333        self.run_calls(ctx, state, tools, approved).await;
334        undecided
335    }
336
337    async fn execute(&self, ctx: NodeContext) -> NodeResult {
338        let cfg = &self.config;
339        let tools = self.bind_tools(&ctx).await?;
340        let model = model_for(&ctx, &cfg.model)?;
341
342        let mut state = match &ctx.resume {
343            Some(resume) => {
344                let mut state: AgentState = serde_json::from_value(resume.state.clone())
345                    .map_err(|e| NodeError::fatal("invalid_resume_state", e.to_string()))?;
346                let undecided = self.apply_decisions(&ctx, &mut state, &tools, resume.input.as_ref()).await;
347                if !undecided.is_empty() {
348                    state.pending = undecided;
349                    return self.pause(&state);
350                }
351                state
352            }
353            None => self.initial_state(&ctx)?,
354        };
355
356        let (final_text, stop) = loop {
357            state.iteration += 1;
358            let final_turn = state.iteration >= cfg.max_iterations;
359            let offer_tools = !tools.is_empty();
360            let can_call_tools = offer_tools && !final_turn;
361            if let Some(keep) = cfg.keep_tool_images {
362                prune_tool_images(&mut state.messages, keep);
363            }
364            let mut request = cfg.model.request(state.messages.clone(), &ctx.pool)?;
365            if offer_tools {
366                // Tools stay declared on the final turn: the history may contain tool calls,
367                // which providers only accept alongside tool definitions.
368                request.tools = tools.iter().map(|t| t.spec.clone()).collect();
369                request.tool_choice = Some(if can_call_tools { ToolChoice::Auto } else { ToolChoice::None });
370            }
371            ctx.progress(
372                "agent_step",
373                Value::from_json(json!({"iteration": state.iteration, "tools_enabled": can_call_tools})),
374            );
375
376            // A turn that may call tools is buffered: its text is only the answer if no tools are called.
377            let mode = if can_call_tools { StreamMode::Off } else { StreamMode::Raw };
378            let response = invoke(&ctx, model.as_ref(), request, mode).await?;
379            state.usage.add(&response.usage);
380            // A content-filtered or malformed turn is an error, never an empty "completed" answer.
381            let finish = check_finish(&response)?;
382
383            if !can_call_tools || response.tool_calls.is_empty() {
384                if can_call_tools && !response.text.is_empty() {
385                    ctx.chunk_shared(StreamField::Text.shared(), response.text.clone());
386                }
387                let stop = if response.finish_reason == Some(FinishReason::Length) {
388                    StopReason::Length
389                } else if let FinishCheck::Unknown(reason) = finish {
390                    StopReason::Unrecognized(reason)
391                } else if offer_tools && final_turn {
392                    StopReason::MaxIterations
393                } else {
394                    StopReason::Completed
395                };
396                state.messages.push(Message::assistant(response.text.clone()));
397                break (response.text, stop);
398            }
399
400            if !response.text.trim().is_empty() {
401                ctx.progress(
402                    "agent_thought",
403                    Value::from_json(json!({"iteration": state.iteration, "text": response.text})),
404                );
405            }
406            // Malformed arguments are never replayed to the provider: the history keeps `{}`
407            // and the tool result explains the problem to the model.
408            let mut assistant = response.to_message();
409            for call in &mut assistant.tool_calls {
410                if call.arguments_json().is_err() {
411                    call.arguments = "{}".to_owned();
412                }
413            }
414            state.messages.push(assistant);
415
416            let mut calls = response.tool_calls;
417            if let Some(limit) = cfg.max_tool_calls_per_turn {
418                if calls.len() > limit {
419                    for call in calls.split_off(limit) {
420                        self.record(
421                            &mut state,
422                            &tools,
423                            &call,
424                            ToolOutput::error("rejected: too many tool calls in one turn"),
425                        );
426                    }
427                }
428            }
429            let mut runnable = Vec::with_capacity(calls.len());
430            for call in calls {
431                match call.arguments_json() {
432                    Ok(_) => runnable.push(call),
433                    Err(e) => {
434                        let message = format!("error: {e}. Call the tool again with a valid JSON object.");
435                        self.record(&mut state, &tools, &call, ToolOutput::error(message));
436                    }
437                }
438            }
439            let (gated, free): (Vec<ToolCall>, Vec<ToolCall>) =
440                runnable.into_iter().partition(|c| self.call_needs_approval(&tools, c));
441            self.run_calls(&ctx, &mut state, &tools, free).await;
442            if !gated.is_empty() {
443                state.pending = gated;
444                return self.pause(&state);
445            }
446        };
447
448        let log: Vec<Value> = state
449            .log
450            .iter()
451            .map(|e| {
452                Value::from_json(json!({
453                    "name": e.name, "provider": e.provider, "tool": e.tool,
454                    "arguments": e.arguments, "result": e.result, "is_error": e.is_error, "images": e.images,
455                }))
456            })
457            .collect();
458        Ok(NodeOutput::new()
459            .with("text", final_text)
460            .with("tool_calls", Value::from(log))
461            .with("iterations", i64::from(state.iteration))
462            .with("stopped_reason", stop.as_str())
463            .with("usage", usage_value(&state.usage))
464            .usage(state.usage)
465            .into())
466    }
467
468    fn pause(&self, state: &AgentState) -> NodeResult {
469        let calls: Vec<Json> =
470            state.pending.iter().map(|c| json!({"id": c.id, "name": c.name, "arguments": log_arguments(c)})).collect();
471        let saved = serde_json::to_value(state)
472            .map_err(|e| NodeError::fatal("agent_state", format!("cannot save agent state: {e}")))?;
473        Ok(NodeOutcome::Paused(PauseRequest {
474            kind: "tool_approval".to_owned(),
475            data: Value::from_json(json!({"calls": calls})),
476            state: saved,
477        }))
478    }
479
480    fn deny(
481        &self,
482        ctx: &NodeContext,
483        state: &mut AgentState,
484        tools: &[BoundTool],
485        call: &ToolCall,
486        reason: Option<&str>,
487    ) {
488        let text = match reason {
489            Some(r) if !r.is_empty() => format!("The user did not approve this tool call: {r}"),
490            _ => "The user did not approve this tool call.".to_owned(),
491        };
492        ctx.progress("tool_denied", Value::from_json(json!({"id": call.id, "name": call.name})));
493        self.record(state, tools, call, ToolOutput::error(text));
494    }
495
496    /// Append a tool result to the conversation and the log.
497    fn record(&self, state: &mut AgentState, tools: &[BoundTool], call: &ToolCall, output: ToolOutput) {
498        let bound = tools.iter().find(|t| t.exposed == call.name);
499        let mut text = truncate(&output.text, self.config.max_tool_output_chars);
500        let images = match check_images(&output.images) {
501            Ok(()) => output.images,
502            Err(e) => {
503                let note = format!("[images dropped: {e}]");
504                text = if text.is_empty() { note } else { format!("{text}\n{note}") };
505                Vec::new()
506            }
507        };
508        let image_count = images.len();
509        state.messages.push(Message::tool_with_images(
510            call.id.clone(),
511            text.clone(),
512            images.iter().map(ToolImage::to_url),
513        ));
514        state.log.push(ToolLogEntry {
515            id: call.id.clone(),
516            name: call.name.clone(),
517            provider: bound.map(|b| b.provider.clone()).unwrap_or_default(),
518            tool: bound.map(|b| b.name.clone()).unwrap_or_default(),
519            arguments: log_arguments(call),
520            result: text,
521            is_error: output.is_error,
522            images: image_count,
523        });
524    }
525
526    async fn run_calls(&self, ctx: &NodeContext, state: &mut AgentState, tools: &[BoundTool], calls: Vec<ToolCall>) {
527        if calls.is_empty() {
528            return;
529        }
530        for call in &calls {
531            ctx.progress(
532                "tool_call",
533                Value::from_json(json!({"id": call.id, "name": call.name, "arguments": log_arguments(call)})),
534            );
535        }
536        let outputs: Vec<ToolOutput> = if self.config.parallel_tool_calls {
537            futures::future::join_all(calls.iter().map(|c| call_tool(tools, c))).await
538        } else {
539            let mut out = Vec::with_capacity(calls.len());
540            for c in &calls {
541                out.push(call_tool(tools, c).await);
542            }
543            out
544        };
545        for (call, output) in calls.iter().zip(outputs) {
546            ctx.progress(
547                "tool_result",
548                Value::from_json(
549                    json!({"id": call.id, "name": call.name, "is_error": output.is_error, "images": output.images.len()}),
550                ),
551            );
552            self.record(state, tools, call, output);
553        }
554    }
555}
556
557/// Replace the images of all but the last `keep` image-bearing tool results
558/// with a text placeholder, so a screenshot loop does not resend every
559/// screenshot on every turn.
560fn prune_tool_images(messages: &mut [Message], keep: usize) {
561    let mut seen = 0;
562    for message in messages.iter_mut().rev().filter(|m| m.role == Role::Tool) {
563        let count = message.images().count();
564        if count == 0 {
565            continue;
566        }
567        seen += 1;
568        if seen <= keep {
569            continue;
570        }
571        let note = if count == 1 {
572            "[1 image removed from history]".to_owned()
573        } else {
574            format!("[{count} images removed from history]")
575        };
576        let text = message.text();
577        let text = if text.is_empty() { note } else { format!("{text}\n{note}") };
578        message.content = vec![ContentPart::Text { text }];
579    }
580}
581
582/// Arguments as shown in logs and approval requests: the parsed object, or the
583/// raw text when it is not valid JSON (so nothing is hidden from the reader).
584fn log_arguments(call: &ToolCall) -> Json {
585    match call.arguments_json() {
586        Ok(map) => Json::Object(map),
587        Err(_) => Json::String(call.arguments.clone()),
588    }
589}
590
591async fn call_tool(tools: &[BoundTool], call: &ToolCall) -> ToolOutput {
592    let Some(tool) = tools.iter().find(|t| t.exposed == call.name) else {
593        return ToolOutput::error(format!("error: unknown tool `{}`", call.name));
594    };
595    let arguments = match call.arguments_json() {
596        Ok(map) => Json::Object(map),
597        Err(e) => return ToolOutput::error(format!("error: {e}")),
598    };
599    match tool.runtime.call(&tool.name, arguments).await {
600        Ok(output) => output,
601        Err(e) => ToolOutput::error(format!("error: {e}")),
602    }
603}
604
605/// Host decision for paused tool calls.
606#[derive(Debug, Default)]
607struct Approvals {
608    all: Option<bool>,
609    per_call: HashMap<String, bool>,
610    reason: Option<String>,
611}
612
613impl Approvals {
614    /// Recognized forms: `true`/`false`, `{"approved": bool}`,
615    /// `{"approvals": {"<call id>": bool}}` (both may be combined, per-call wins),
616    /// plus an optional `reason`. Anything else decides nothing.
617    fn from_input(input: Option<&Value>) -> Self {
618        let mut out = Self::default();
619        match input {
620            Some(Value::Bool(b)) => out.all = Some(*b),
621            Some(Value::Object(map)) => {
622                out.all = map.get("approved").and_then(Value::as_bool);
623                if let Some(Value::Object(per)) = map.get("approvals") {
624                    for (id, v) in per.iter() {
625                        if let Some(b) = v.as_bool() {
626                            out.per_call.insert(id.clone(), b);
627                        }
628                    }
629                }
630                out.reason = map.get("reason").and_then(Value::as_str).map(str::to_owned);
631            }
632            _ => {}
633        }
634        out
635    }
636
637    /// `Some(true)` approved, `Some(false)` denied, `None` no decision yet.
638    fn decision(&self, id: &str) -> Option<bool> {
639        self.per_call.get(id).copied().or(self.all)
640    }
641}
642
643/// Model-safe tool name: `[A-Za-z0-9_-]{1,64}`, unique within the run.
644fn unique_name(name: &str, provider: &str, used: &mut HashSet<String>) -> String {
645    let clean = |s: &str| -> String {
646        let mut out: String = s
647            .chars()
648            .map(|c| if c.is_ascii_alphanumeric() || c == '_' || c == '-' { c } else { '_' })
649            .take(64)
650            .collect();
651        if out.is_empty() {
652            out.push_str("tool");
653        }
654        out
655    };
656    let mut candidate = clean(name);
657    if used.contains(&candidate) {
658        candidate = clean(&format!("{provider}_{name}"));
659    }
660    let base = candidate.clone();
661    let mut n = 2;
662    while used.contains(&candidate) {
663        let suffix = format!("_{n}");
664        let keep = 64usize.saturating_sub(suffix.len());
665        candidate = format!("{}{suffix}", base.chars().take(keep).collect::<String>());
666        n += 1;
667    }
668    used.insert(candidate.clone());
669    candidate
670}
671
672fn truncate(text: &str, max_chars: usize) -> String {
673    if max_chars == 0 || text.chars().count() <= max_chars {
674        return text.to_owned();
675    }
676    let mut out: String = text.chars().take(max_chars).collect();
677    out.push_str("\n[truncated]");
678    out
679}
680
681impl Node for AgentNode {
682    fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
683        Box::pin(self.execute(ctx))
684    }
685
686    fn inputs(&self) -> Vec<Selector> {
687        let cfg = &self.config;
688        let mut out: Vec<Selector> = cfg.query.selectors().cloned().collect();
689        if let Some(i) = &cfg.instruction {
690            out.extend(i.selectors().cloned());
691        }
692        if let Some(memory) = &cfg.memory {
693            out.extend(memory.selectors());
694        }
695        out.extend(cfg.vision.selectors());
696        out.extend(cfg.model.selectors());
697        out
698    }
699}
700
701/// Factory for the node registry.
702pub fn factory(doc: &NodeDoc) -> Result<Arc<dyn Node>, ConfigError> {
703    Ok(Arc::new(AgentNode::from_doc(doc)?))
704}
705
706#[cfg(test)]
707mod tests {
708    use super::*;
709    use crate::mock::MockModel;
710    use crate::registry::ModelRegistry;
711    use crate::types::Role;
712    use graphrt_core::event::Event;
713    use graphrt_core::node::Resume;
714    use graphrt_core::tool::ToolError;
715    use graphrt_core::{Services, VariablePool};
716    use std::sync::Mutex;
717
718    /// Tools: `add {a, b}` and `fail {}`.
719    #[derive(Debug, Default)]
720    struct MathTools {
721        calls: Mutex<Vec<String>>,
722    }
723
724    impl ToolRuntime for MathTools {
725        fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>> {
726            Box::pin(async {
727                Ok(vec![
728                    ToolSpec {
729                        name: "add".into(),
730                        description: "add numbers".into(),
731                        parameters: json!({"type": "object"}),
732                    },
733                    ToolSpec {
734                        name: "fail".into(),
735                        description: "always fails".into(),
736                        parameters: json!({"type": "object"}),
737                    },
738                ])
739            })
740        }
741
742        fn call<'a>(&'a self, name: &'a str, arguments: Json) -> BoxFuture<'a, Result<ToolOutput, ToolError>> {
743            self.calls.lock().unwrap().push(name.to_owned());
744            Box::pin(async move {
745                match name {
746                    "add" => {
747                        let a = arguments["a"].as_i64().unwrap_or(0);
748                        let b = arguments["b"].as_i64().unwrap_or(0);
749                        Ok(ToolOutput::text((a + b).to_string()))
750                    }
751                    _ => Err(ToolError { tool: name.to_owned(), message: "broken".into() }),
752                }
753            })
754        }
755    }
756
757    /// Tools: `screenshot {}` (one PNG), `bad_image {}` (an unsupported type).
758    #[derive(Debug, Default)]
759    struct ScreenTools;
760
761    impl ToolRuntime for ScreenTools {
762        fn list(&self) -> BoxFuture<'_, Result<Vec<ToolSpec>, ToolError>> {
763            let spec = |name: &str| ToolSpec { name: name.into(), description: "d".into(), parameters: json!({}) };
764            Box::pin(async move { Ok(vec![spec("screenshot"), spec("bad_image")]) })
765        }
766
767        fn call<'a>(&'a self, name: &'a str, _arguments: Json) -> BoxFuture<'a, Result<ToolOutput, ToolError>> {
768            Box::pin(async move {
769                Ok(match name {
770                    "screenshot" => ToolOutput::text("800x600").with_image(ToolImage::png("aGVsbG8=")),
771                    _ => ToolOutput::text("odd")
772                        .with_image(ToolImage::Base64 { media_type: "image/bmp".into(), data_base64: "aGVs".into() }),
773                })
774            })
775        }
776    }
777
778    struct Setup {
779        model: Arc<MockModel>,
780        tools: Arc<MathTools>,
781        events: Arc<Mutex<Vec<Event>>>,
782    }
783
784    fn setup(responses: Vec<Vec<crate::ChatDelta>>) -> Setup {
785        Setup {
786            model: Arc::new(MockModel::new(responses)),
787            tools: Arc::new(MathTools::default()),
788            events: Arc::default(),
789        }
790    }
791
792    fn ctx(s: &Setup) -> NodeContext {
793        let mut tool_registry = ToolRegistry::new();
794        tool_registry.add("math", Arc::clone(&s.tools) as Arc<dyn ToolRuntime>);
795        tool_registry.add("screen", Arc::new(ScreenTools) as Arc<dyn ToolRuntime>);
796        let services = Services::new()
797            .with(ModelRegistry::new().with("openai", Arc::clone(&s.model) as Arc<dyn crate::ChatModel>))
798            .with(tool_registry);
799        let mut pool = VariablePool::new();
800        pool.insert("sys", "query", Value::from("what is 2+3?"));
801        let events = Arc::clone(&s.events);
802        NodeContext::for_test("agent", pool)
803            .with_services(Arc::new(services))
804            .with_sink(Arc::new(move |e| events.lock().unwrap().push(e)))
805    }
806
807    fn agent(extra: Json) -> AgentNode {
808        let mut config = json!({
809            "model": {"provider": "openai", "name": "gpt"},
810            "instruction": "You are a calculator.",
811            "tools": ["math/*"],
812        });
813        if let (Some(c), Json::Object(e)) = (config.as_object_mut(), extra) {
814            c.extend(e);
815        }
816        AgentNode::from_doc(&NodeDoc::new("agent", "agent", config)).unwrap()
817    }
818
819    fn completed(r: NodeResult) -> NodeOutput {
820        match r.unwrap() {
821            NodeOutcome::Completed(o) => o,
822            NodeOutcome::Paused(p) => panic!("unexpected pause: {p:?}"),
823        }
824    }
825
826    #[tokio::test]
827    async fn loops_until_answer() {
828        let s = setup(vec![
829            MockModel::tool_calls(&[("c1", "add", r#"{"a":2,"b":3}"#), ("c2", "fail", "{}")]),
830            MockModel::text("The answer is 5."),
831        ]);
832        let out = completed(agent(json!({})).run(ctx(&s)).await);
833        assert_eq!(out.outputs["text"], Value::from("The answer is 5."));
834        assert_eq!(out.outputs["iterations"], Value::Int(2));
835        let log = out.outputs["tool_calls"].as_array().unwrap().to_vec();
836        assert_eq!(log.len(), 2);
837        assert_eq!(log[0].get_path(&["result"]), Some(Value::from("5")));
838        assert_eq!(log[1].get_path(&["is_error"]), Some(Value::Bool(true)));
839        assert_eq!(out.usage.unwrap().total_tokens, 4);
840
841        let requests = s.model.requests();
842        assert_eq!(requests[0].tools.len(), 2);
843        let second = &requests[1].messages;
844        assert_eq!(second[0].role, Role::System);
845        assert_eq!(second[2].tool_calls.len(), 2);
846        assert_eq!(second[3].tool_call_id.as_deref(), Some("c1"));
847        assert_eq!(second[3].text(), "5");
848        assert!(second[4].text().contains("broken"));
849
850        let progress: Vec<String> = s
851            .events
852            .lock()
853            .unwrap()
854            .iter()
855            .filter_map(|e| match e {
856                Event::NodeProgress { name, .. } => Some(name.clone()),
857                _ => None,
858            })
859            .collect();
860        assert_eq!(progress, ["agent_step", "tool_call", "tool_call", "tool_result", "tool_result", "agent_step"]);
861    }
862
863    #[tokio::test]
864    async fn tool_images_reach_the_model() {
865        let s = setup(vec![MockModel::tool_calls(&[("c1", "screenshot", "{}")]), MockModel::text("a login form")]);
866        let out = completed(agent(json!({"tools": ["screen/*"]})).run(ctx(&s)).await);
867        let requests = s.model.requests();
868        let result = &requests[1].messages[3];
869        assert_eq!(result.role, Role::Tool);
870        assert_eq!(result.text(), "800x600");
871        assert_eq!(
872            result.images().cloned().collect::<Vec<_>>(),
873            vec![ContentPart::Image { url: "data:image/png;base64,aGVsbG8=".into(), detail: None }]
874        );
875        let log = out.outputs["tool_calls"].as_array().unwrap().to_vec();
876        assert_eq!(log[0].get_path(&["images"]), Some(Value::Int(1)));
877        let reported = s.events.lock().unwrap().iter().find_map(|e| match e {
878            Event::NodeProgress { name, data, .. } if name == "tool_result" => data.get_path(&["images"]),
879            _ => None,
880        });
881        assert_eq!(reported, Some(Value::Int(1)));
882    }
883
884    #[tokio::test]
885    async fn invalid_tool_images_are_dropped_with_a_note() {
886        let s = setup(vec![MockModel::tool_calls(&[("c1", "bad_image", "{}")]), MockModel::text("ok")]);
887        completed(agent(json!({"tools": ["screen/*"]})).run(ctx(&s)).await);
888        let result = &s.model.requests()[1].messages[3];
889        assert_eq!(result.images().count(), 0);
890        assert!(
891            result.text().starts_with("odd\n[images dropped: image #0: image media type `image/bmp`"),
892            "{}",
893            result.text()
894        );
895    }
896
897    #[tokio::test]
898    async fn keep_tool_images_prunes_older_screenshots() {
899        let s = setup(vec![
900            MockModel::tool_calls(&[("c1", "screenshot", "{}")]),
901            MockModel::tool_calls(&[("c2", "screenshot", "{}")]),
902            MockModel::tool_calls(&[("c3", "screenshot", "{}")]),
903            MockModel::text("done"),
904        ]);
905        completed(agent(json!({"tools": ["screen/*"], "keep_tool_images": 2})).run(ctx(&s)).await);
906        let last = s.model.requests().last().cloned().unwrap();
907        let results: Vec<&Message> = last.messages.iter().filter(|m| m.role == Role::Tool).collect();
908        assert_eq!(results.iter().map(|m| m.images().count()).collect::<Vec<_>>(), [0, 1, 1]);
909        assert_eq!(results[0].text(), "800x600\n[1 image removed from history]");
910        // The second request still had every image (only two existed).
911        let second = &s.model.requests()[2];
912        assert_eq!(second.messages.iter().map(|m| m.images().count()).sum::<usize>(), 2);
913    }
914
915    fn four_screenshots() -> Vec<Vec<crate::ChatDelta>> {
916        vec![
917            MockModel::tool_calls(&[("c1", "screenshot", "{}")]),
918            MockModel::tool_calls(&[("c2", "screenshot", "{}")]),
919            MockModel::tool_calls(&[("c3", "screenshot", "{}")]),
920            MockModel::tool_calls(&[("c4", "screenshot", "{}")]),
921            MockModel::text("done"),
922        ]
923    }
924
925    fn images_per_tool_result(s: &Setup) -> Vec<usize> {
926        let last = s.model.requests().last().cloned().unwrap();
927        last.messages.iter().filter(|m| m.role == Role::Tool).map(|m| m.images().count()).collect()
928    }
929
930    #[tokio::test]
931    async fn keep_tool_images_defaults_to_the_last_three() {
932        let s = setup(four_screenshots());
933        completed(agent(json!({"tools": ["screen/*"]})).run(ctx(&s)).await);
934        assert_eq!(images_per_tool_result(&s), [0, 1, 1, 1]);
935    }
936
937    #[tokio::test]
938    async fn keep_tool_images_null_keeps_every_image() {
939        let s = setup(four_screenshots());
940        completed(agent(json!({"tools": ["screen/*"], "keep_tool_images": null})).run(ctx(&s)).await);
941        assert_eq!(images_per_tool_result(&s), [1, 1, 1, 1]);
942    }
943
944    #[tokio::test]
945    async fn last_iteration_keeps_tools_but_forbids_calls() {
946        let s = setup(vec![MockModel::tool_calls(&[("c1", "add", r#"{"a":1,"b":1}"#)]), MockModel::text("2")]);
947        let out = completed(agent(json!({"max_iterations": 2})).run(ctx(&s)).await);
948        assert_eq!(out.outputs["text"], Value::from("2"));
949        assert_eq!(out.outputs["stopped_reason"], Value::from("max_iterations"));
950        let requests = s.model.requests();
951        assert_eq!(requests[0].tool_choice, Some(ToolChoice::Auto));
952        assert!(!requests[1].tools.is_empty(), "tool definitions stay for the history's tool calls");
953        assert_eq!(requests[1].tool_choice, Some(ToolChoice::None));
954    }
955
956    #[tokio::test]
957    async fn only_the_final_answer_is_streamed() {
958        let mut first = vec![crate::ChatDelta::Text("Let me check.".into())];
959        first.extend(MockModel::tool_calls(&[("c1", "add", r#"{"a":2,"b":3}"#)]));
960        let s = setup(vec![first, MockModel::text("It is 5.")]);
961        let out = completed(agent(json!({})).run(ctx(&s)).await);
962        assert_eq!(out.outputs["stopped_reason"], Value::from("completed"));
963        let events = s.events.lock().unwrap();
964        let streamed: String = events
965            .iter()
966            .filter_map(|e| match e {
967                Event::NodeChunk { field, chunk, .. } if field.as_ref() == "text" => Some(chunk.clone()),
968                _ => None,
969            })
970            .collect();
971        assert_eq!(streamed, "It is 5.");
972        assert_eq!(out.outputs["text"], Value::from(streamed.as_str()));
973        let thought = events.iter().find_map(|e| match e {
974            Event::NodeProgress { name, data, .. } if name == "agent_thought" => data.get_path(&["text"]),
975            _ => None,
976        });
977        assert_eq!(thought, Some(Value::from("Let me check.")));
978    }
979
980    #[tokio::test]
981    async fn malformed_arguments_are_reported_back_to_the_model() {
982        let s = setup(vec![MockModel::tool_calls(&[("c1", "add", r#"{"a":2,"#)]), MockModel::text("sorry")]);
983        let out = completed(agent(json!({})).run(ctx(&s)).await);
984        assert!(s.tools.calls.lock().unwrap().is_empty(), "malformed calls never run");
985        let log = out.outputs["tool_calls"].as_array().unwrap().to_vec();
986        assert_eq!(log[0].get_path(&["arguments"]), Some(Value::from(r#"{"a":2,"#)));
987        assert_eq!(log[0].get_path(&["is_error"]), Some(Value::Bool(true)));
988        let second = &s.model.requests()[1];
989        assert_eq!(second.messages[2].tool_calls[0].arguments, "{}", "history never replays malformed JSON");
990        assert!(second.messages[3].text().contains("invalid JSON arguments"));
991    }
992
993    #[tokio::test]
994    async fn per_turn_limit_rejects_extra_calls() {
995        let s = setup(vec![
996            MockModel::tool_calls(&[("c1", "add", r#"{"a":1,"b":1}"#), ("c2", "add", r#"{"a":2,"b":2}"#)]),
997            MockModel::text("ok"),
998        ]);
999        let out =
1000            completed(agent(json!({"max_tool_calls_per_turn": 1, "parallel_tool_calls": false})).run(ctx(&s)).await);
1001        assert_eq!(s.tools.calls.lock().unwrap().len(), 1);
1002        let log = out.outputs["tool_calls"].as_array().unwrap().to_vec();
1003        assert_eq!(log[0].get_path(&["is_error"]), Some(Value::Bool(true)));
1004    }
1005
1006    #[tokio::test]
1007    async fn approval_pauses_and_resumes() {
1008        let s = setup(vec![MockModel::tool_calls(&[("c1", "add", r#"{"a":2,"b":2}"#)]), MockModel::text("4")]);
1009        let node = agent(json!({"tools": [{"provider": "math", "name": "add"}], "require_approval": ["math/add"]}));
1010        let paused = match node.run(ctx(&s)).await.unwrap() {
1011            NodeOutcome::Paused(p) => p,
1012            NodeOutcome::Completed(_) => panic!("expected pause"),
1013        };
1014        assert_eq!(paused.kind, "tool_approval");
1015        assert_eq!(paused.data.get_path(&["calls", "0", "name"]), Some(Value::from("add")));
1016        assert!(s.tools.calls.lock().unwrap().is_empty(), "nothing runs before approval");
1017
1018        // The saved state survives serialization (snapshots store it as JSON).
1019        let state: Json = serde_json::from_str(&paused.state.to_string()).unwrap();
1020        let resumed =
1021            ctx(&s).with_resume(Some(Resume { state, input: Some(Value::from_json(json!({"approved": true}))) }));
1022        let out = completed(node.run(resumed).await);
1023        assert_eq!(out.outputs["text"], Value::from("4"));
1024        assert_eq!(s.tools.calls.lock().unwrap().as_slice(), ["add"]);
1025    }
1026
1027    #[tokio::test]
1028    async fn denied_calls_are_reported_to_the_model() {
1029        let s = setup(vec![MockModel::tool_calls(&[("c1", "add", "{}")]), MockModel::text("fine")]);
1030        let node = agent(json!({"require_approval": ["*"]}));
1031        let NodeOutcome::Paused(p) = node.run(ctx(&s)).await.unwrap() else { panic!("expected pause") };
1032        let input = Value::from_json(json!({"approvals": {"c1": false}, "reason": "not now"}));
1033        let out = completed(node.run(ctx(&s).with_resume(Some(Resume { state: p.state, input: Some(input) }))).await);
1034        assert_eq!(out.outputs["text"], Value::from("fine"));
1035        assert!(s.tools.calls.lock().unwrap().is_empty());
1036        let last_request = s.model.requests().pop().unwrap();
1037        assert!(last_request.messages.iter().any(|m| m.text().contains("not now")));
1038    }
1039
1040    #[tokio::test]
1041    async fn only_gated_calls_wait_for_approval() {
1042        let s = setup(vec![
1043            MockModel::tool_calls(&[("c1", "add", r#"{"a":1,"b":1}"#), ("c2", "fail", "{}")]),
1044            MockModel::text("done"),
1045        ]);
1046        let node = agent(json!({"require_approval": ["math/fail"]}));
1047        let NodeOutcome::Paused(p) = node.run(ctx(&s)).await.unwrap() else { panic!("expected pause") };
1048        assert_eq!(s.tools.calls.lock().unwrap().as_slice(), ["add"], "ungated calls run immediately");
1049        assert_eq!(p.data.get_path(&["calls", "0", "id"]), Some(Value::from("c2")));
1050        assert!(p.data.get_path(&["calls", "1"]).is_none());
1051
1052        // No decision (or one that is not understood) keeps the run paused.
1053        for input in [None, Some(Value::from("yes")), Some(Value::from_json(json!({"approved": "true"})))] {
1054            let resumed = ctx(&s).with_resume(Some(Resume { state: p.state.clone(), input }));
1055            assert!(matches!(node.run(resumed).await.unwrap(), NodeOutcome::Paused(_)));
1056        }
1057        assert_eq!(s.tools.calls.lock().unwrap().len(), 1);
1058
1059        let input = Value::from_json(json!({"approvals": {"c2": true}}));
1060        let out = completed(node.run(ctx(&s).with_resume(Some(Resume { state: p.state, input: Some(input) }))).await);
1061        assert_eq!(out.outputs["text"], Value::from("done"));
1062        assert_eq!(s.tools.calls.lock().unwrap().as_slice(), ["add", "fail"]);
1063    }
1064
1065    #[tokio::test]
1066    async fn per_call_decisions_can_arrive_in_steps() {
1067        let s = setup(vec![
1068            MockModel::tool_calls(&[("c1", "add", r#"{"a":1,"b":1}"#), ("c2", "add", r#"{"a":2,"b":2}"#)]),
1069            MockModel::text("ok"),
1070        ]);
1071        let node = agent(json!({"require_approval": ["*"], "parallel_tool_calls": false}));
1072        let NodeOutcome::Paused(p) = node.run(ctx(&s)).await.unwrap() else { panic!("expected pause") };
1073        let input = Value::from_json(json!({"approvals": {"c1": true}}));
1074        let NodeOutcome::Paused(p2) =
1075            node.run(ctx(&s).with_resume(Some(Resume { state: p.state, input: Some(input) }))).await.unwrap()
1076        else {
1077            panic!("c2 is still undecided")
1078        };
1079        assert_eq!(s.tools.calls.lock().unwrap().len(), 1);
1080        assert_eq!(p2.data.get_path(&["calls", "0", "id"]), Some(Value::from("c2")));
1081        let input = Value::from_json(json!({"approved": false}));
1082        let out = completed(node.run(ctx(&s).with_resume(Some(Resume { state: p2.state, input: Some(input) }))).await);
1083        assert_eq!(out.outputs["text"], Value::from("ok"));
1084        assert_eq!(s.tools.calls.lock().unwrap().len(), 1, "c2 was denied");
1085    }
1086
1087    #[test]
1088    fn inputs_cover_templates_and_memory() {
1089        let node = agent(json!({"query": "{{#start.q#}}", "instruction": "{{#env.persona#}}", "memory": {}}));
1090        let inputs: Vec<String> = node.inputs().iter().map(ToString::to_string).collect();
1091        for expected in ["start.q", "env.persona", "sys.history", "sys.query"] {
1092            assert!(inputs.iter().any(|i| i == expected), "missing {expected} in {inputs:?}");
1093        }
1094    }
1095
1096    #[tokio::test]
1097    async fn unknown_provider_is_fatal() {
1098        let s = setup(vec![]);
1099        let err = agent(json!({"tools": ["nope/x"]})).run(ctx(&s)).await.unwrap_err();
1100        assert!(!err.retryable);
1101        assert_eq!(err.kind, "tool_not_found");
1102    }
1103
1104    #[test]
1105    fn config_validation_and_names() {
1106        let bad = NodeDoc::new("a", "agent", json!({"model": {"provider": "p", "name": "m"}, "tools": ["no-slash"]}));
1107        assert!(AgentNode::from_doc(&bad).is_err());
1108        let bad = NodeDoc::new("a", "agent", json!({"model": {"provider": "p", "name": "m"}, "max_iterations": 0}));
1109        assert!(AgentNode::from_doc(&bad).is_err());
1110        let mut used = HashSet::new();
1111        assert_eq!(unique_name("search", "web", &mut used), "search");
1112        assert_eq!(unique_name("search", "docs", &mut used), "docs_search");
1113        assert_eq!(unique_name("search", "docs", &mut used), "docs_search_2");
1114        assert_eq!(unique_name("a.b/c", "p", &mut used), "a_b_c");
1115    }
1116}