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