1use 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
57pub const MAX_ITERATIONS_LIMIT: u32 = 100;
59
60#[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#[derive(Clone, Debug, Deserialize)]
108pub struct AgentConfig {
109 pub model: ModelConfig,
110 #[serde(default)]
112 pub instruction: Option<Template>,
113 #[serde(default = "default_query")]
115 pub query: Template,
116 #[serde(default)]
117 pub tools: Vec<ToolRef>,
118 #[serde(default = "default_max_iterations")]
120 pub max_iterations: u32,
121 #[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 #[serde(default)]
132 pub require_approval: Vec<String>,
133 #[serde(default = "default_max_tool_output")]
135 pub max_tool_output_chars: usize,
136 #[serde(default = "default_keep_tool_images")]
140 pub keep_tool_images: Option<usize>,
141}
142
143#[derive(Clone, Debug)]
145struct BoundTool {
146 exposed: String,
148 provider: String,
149 name: String,
150 runtime: Arc<dyn ToolRuntime>,
151 spec: ToolSpec,
152}
153
154#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
156struct ToolLogEntry {
157 id: String,
158 name: String,
159 provider: String,
160 tool: String,
161 arguments: Json,
163 result: String,
164 is_error: bool,
165 #[serde(default)]
167 images: usize,
168}
169
170#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
172struct AgentState {
173 messages: Vec<Message>,
174 iteration: u32,
175 log: Vec<ToolLogEntry>,
176 usage: Usage,
177 pending: Vec<ToolCall>,
179}
180
181#[derive(Clone, Debug, PartialEq, Eq)]
183enum StopReason {
184 Completed,
186 MaxIterations,
188 Length,
190 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#[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 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 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 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 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 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 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 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
557fn 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
582fn 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#[derive(Debug, Default)]
607struct Approvals {
608 all: Option<bool>,
609 per_call: HashMap<String, bool>,
610 reason: Option<String>,
611}
612
613impl Approvals {
614 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 fn decision(&self, id: &str) -> Option<bool> {
639 self.per_call.get(id).copied().or(self.all)
640 }
641}
642
643fn 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
701pub 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 #[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 #[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 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 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 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}