1use 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
50pub const MAX_ITERATIONS_LIMIT: u32 = 100;
52
53#[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#[derive(Clone, Debug, Deserialize)]
97pub struct AgentConfig {
98 pub model: ModelConfig,
99 #[serde(default)]
101 pub instruction: Option<Template>,
102 #[serde(default = "default_query")]
104 pub query: Template,
105 #[serde(default)]
106 pub tools: Vec<ToolRef>,
107 #[serde(default = "default_max_iterations")]
109 pub max_iterations: u32,
110 #[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 #[serde(default)]
121 pub require_approval: Vec<String>,
122 #[serde(default = "default_max_tool_output")]
124 pub max_tool_output_chars: usize,
125}
126
127#[derive(Clone, Debug)]
129struct BoundTool {
130 exposed: String,
132 provider: String,
133 name: String,
134 runtime: Arc<dyn ToolRuntime>,
135 spec: ToolSpec,
136}
137
138#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
140struct ToolLogEntry {
141 id: String,
142 name: String,
143 provider: String,
144 tool: String,
145 arguments: Json,
147 result: String,
148 is_error: bool,
149}
150
151#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
153struct AgentState {
154 messages: Vec<Message>,
155 iteration: u32,
156 log: Vec<ToolLogEntry>,
157 usage: Usage,
158 pending: Vec<ToolCall>,
160}
161
162#[derive(Clone, Debug, PartialEq, Eq)]
164enum StopReason {
165 Completed,
167 MaxIterations,
169 Length,
171 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#[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 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 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 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 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 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 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 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
519fn 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#[derive(Debug, Default)]
544struct Approvals {
545 all: Option<bool>,
546 per_call: HashMap<String, bool>,
547 reason: Option<String>,
548}
549
550impl Approvals {
551 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 fn decision(&self, id: &str) -> Option<bool> {
576 self.per_call.get(id).copied().or(self.all)
577 }
578}
579
580fn 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
638pub 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 #[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 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 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}