Agent Tools and ReAct Loop

Relevant source files

• agent/tools/code_exec.py
• agent/tools/exesql.py
• agent/tools/retrieval.py
• internal/agent/component/fixture_stubs.go
• internal/agent/component/invoke.go
• internal/agent/component/invoke_test.go
• internal/agent/component/production_chain_fixes_test.go
• internal/agent/component/tool_component_test.go
• internal/agent/component/universe_a_wrappers.go
• internal/agent/component/verify_p1_test.go
• internal/agent/runtime/state.go
• internal/agent/runtime/state_test.go
• internal/agent/sandbox/self_managed.go
• internal/agent/tool/arxiv.go
• internal/agent/tool/arxiv_test.go
• internal/agent/tool/email.go
• internal/agent/tool/github.go
• internal/agent/tool/github_test.go
• internal/agent/tool/google_scholar.go
• internal/agent/tool/google_scholar_test.go
• internal/agent/tool/keenable.go
• internal/agent/tool/keenable_test.go
• internal/agent/tool/pubmed.go
• internal/agent/tool/pubmed_test.go
• internal/agent/tool/registry.go
• internal/agent/tool/registry_test.go
• internal/agent/tool/wikipedia.go
• internal/agent/tool/wikipedia_test.go
• internal/agent/tool/yahoo_finance.go
• internal/agent/tool/yahoo_finance_test.go
• internal/harness/core/interrupt.go
• test/unit_test/agent/tools/test_exesql_ssrf.py
• web/src/components/canvas/background.tsx
• web/src/pages/agent/canvas/node/agent-node.tsx
• web/src/pages/agent/canvas/node/begin-node.tsx
• web/src/pages/agent/canvas/node/categorize-node.tsx
• web/src/pages/agent/canvas/node/index.tsx
• web/src/pages/agent/canvas/node/message-node.tsx
• web/src/pages/agent/canvas/node/node-wrapper.tsx
• web/src/pages/agent/canvas/node/note-node/index.tsx
• web/src/pages/agent/canvas/node/resize-icon.tsx
• web/src/pages/agent/canvas/node/retrieval-node.tsx
• web/src/pages/agent/canvas/node/switch-node.tsx
• web/src/pages/agent/form/exesql-form/index.tsx
• web/src/pages/agent/form/exesql-form/use-submit-form.ts
• web/src/pages/agent/form/retrieval-form/next.tsx
• web/src/pages/agent/form/string-transform-form/index.tsx
• web/src/pages/agent/form/switch-form/index.tsx
• web/src/pages/agent/form/tool-form/exesql-form/index.tsx
• web/src/pages/agent/form/tool-form/retrieval-form/index.tsx
• web/src/pages/agent/options.ts
• web/src/pages/next-chats/hooks/use-build-form-refs.ts

This document describes the Agent component's tool integration system and its implementation of the ReAct (Reasoning + Acting) pattern for multi-step problem-solving. The Agent component orchestrates iterative workflows where language models reason about tasks, invoke external tools, observe results, and synthesize final answers.

For general information about the Canvas workflow system and component architecture, see Canvas Engine and DSL (8.1) and Component System Architecture (8.2). For details on the base LLM component without tool use, see Built-in Components (8.3).

---

Agent Component Overview

The Agent component is a specialized LLM component that implements ReAct-style tool use. Unlike a standard LLM component that generates single-shot text responses, the Agent can analyze tasks, plan actions by selecting tools, and reflect on observations to determine next steps.

Agent vs. LLM Component

Feature	LLM Component	Agent Component
Tool access	None	Built-in, MCP, and Sub-Agents
Iterations	Single-shot	Multi-turn (max_rounds)
Tool Card UI	Not applicable	Renders as ToolCard in ToolNode web/src/pages/agent/canvas/node/tool-node.tsx81

The frontend manages tool configuration through specialized forms. The AgentNode component handles visual handles for tools (bottom-left at position 20) and sub-agents (bottom-right at position 180) web/src/pages/agent/canvas/node/agent-node.tsx71-90 It also visualizes the failure handling method, such as Goto which adds an error handle web/src/pages/agent/canvas/node/agent-node.tsx104-115

Sources: web/src/pages/agent/canvas/node/agent-node.tsx71-115 web/src/pages/agent/canvas/node/tool-node.tsx81-103

---

Tool Integration Architecture

The Agent architecture bridges the gap between high-level LLM reasoning and low-level code execution by mapping model tool-calls to specific Python/Go objects or remote MCP sessions.

Tool Registry and Mapping

Title: Natural Language Space to Code Entity Space: Tool Mapping

Sources: internal/agent/tool/registry.go33-68 internal/agent/component/universe_a_wrappers.go126-138 agent/tools/exesql.py70 agent/tools/code_exec.py29 agent/tools/retrieval.py82 web/src/pages/agent/canvas/node/retrieval-node.tsx20 web/src/pages/agent/canvas/node/switch-node.tsx64

Built-in Component Tools

Built-in tools are specialized modules that the Agent can invoke.

Key Tools:

• ExeSQL: Executes SQL queries across multiple database types (MySQL, Postgres, OceanBase, Trino, etc.) agent/tools/exesql.py70 It performs safety checks to prevent access to the core rag_flow database agent/tools/exesql.py60-64 and guards against SSRF via assert_host_is_safe agent/tools/exesql.py124
• CodeExec: Provides a sandbox for executing arbitrary code (Python/Node.js). It enforces output contracts and type validation for business results agent/tools/code_exec.py183-199 It uses select_business_output to isolate the primary result from system metadata agent/tools/code_exec.py64-74
• Retrieval: Searches configured datasets or memories agent/tools/retrieval.py82 It supports similarity_threshold, top_n, and meta_data_filter agent/tools/retrieval.py37-72 The _retrieve_kb method handles resolving dataset IDs from variables and applying metadata filters agent/tools/retrieval.py90-137
• Switch: Implements conditional logic within workflows using logical operators (IF/ELSEIF) and criteria matching web/src/pages/agent/form/switch-form/index.tsx153-200 It allows routing based on variable values and operators like "equal", "contains", etc. web/src/pages/agent/canvas/node/switch-node.tsx32-43

Sources: agent/tools/exesql.py70-128 agent/tools/code_exec.py64-199 agent/tools/retrieval.py37-137 web/src/pages/agent/form/switch-form/index.tsx153-200 web/src/pages/agent/canvas/node/switch-node.tsx32-43

Go Tool Registry (internal/agent/tool/)

The Go port implements a centralized tool registry in internal/agent/tool/registry.go internal/agent/tool/registry.go33 This registry uses a Factory pattern internal/agent/tool/registry.go31 to build Eino-compatible BaseTool instances. The registry includes 20+ built-in tools.

Registered Tools include:

• Search: arxiv, duckduckgo, google, google_scholar, wikipedia, searxng, tavily, bgpt internal/agent/tool/registry.go33-60
• Developer: code_exec (Sandbox execution) internal/agent/tool/registry.go37 execute_sql / exesql (Database access) internal/agent/tool/registry.go42-43 github internal/agent/tool/registry.go44
• RAG: retrieval / search_my_dataset internal/agent/tool/registry.go52-54
• Financial: yahoo_finance, akshare, tushare, wencai, jin10 internal/agent/tool/registry.go34-67
• Others: email internal/agent/tool/registry.go41 deepl internal/agent/tool/registry.go39 qweather internal/agent/tool/registry.go51 pubmed internal/agent/tool/registry.go50

Sources: internal/agent/tool/registry.go33-68 internal/agent/tool/registry.go70-117

---

ReAct Loop and Execution Flow

The Agent's reasoning process follows the ReAct pattern, iteratively calling tools until a final answer is produced.

Visual Workflow Integration

Title: Agent Tool Connectivity in Canvas

Sources: web/src/pages/agent/canvas/node/agent-node.tsx71-90 web/src/pages/agent/canvas/node/retrieval-node.tsx36-48 internal/agent/component/universe_a_wrappers.go167-183 internal/agent/runtime/state.go27-40

Execution Logic

1. Tool Discovery: The system registers components like Retrieval and CodeExec in the component registry internal/agent/component/universe_a_wrappers.go17-20
2. Input Resolution: Components resolve variables (e.g., kb_ids or query) from the canvas context. In Go, retrievalComponent applies defaults and normalizes legacy inputs internal/agent/component/universe_a_wrappers.go168-169
3. Tool Invocation: The Invoke method internal/agent/component/universe_a_wrappers.go167 executes the underlying tool. For instance, retrievalComponent calls inner.InvokableRun with marshaled JSON arguments internal/agent/component/universe_a_wrappers.go175
4. Result Formalization: Raw tool outputs are rendered into "formalized content" suitable for LLM prompts. In Go, parseToolEnvelope handles the envelope extraction internal/agent/component/universe_a_wrappers.go182
5. State Management: Concurrent access to canvas state during tool execution is managed via CanvasState with its RWMutex internal/agent/runtime/state.go27-40

Sources: internal/agent/component/universe_a_wrappers.go17-183 agent/tools/retrieval.py90-105 internal/agent/runtime/state.go27-40

---

Tool Parameter and Output Management

Output Schema

Tools generally provide two types of outputs to satisfy both the LLM and the workflow:

• formalized_content: A string representation of the result, often in Markdown or a concise text format, intended for inclusion in the LLM's context agent/tools/retrieval.py44 internal/agent/component/universe_a_wrappers.go162
• chunks / json: The raw structured data for downstream components. For Retrieval, this includes id, document_id, and score internal/agent/component/universe_a_wrappers.go163 web/src/pages/agent/form/retrieval-form/next.tsx148

Metadata Filtering

The Retrieval tool supports complex metadata filtering. It uses DocMetadataService.get_flatted_meta_by_kbs agent/tools/retrieval.py137 to fetch available metadata and applies filters using a variable reference pattern agent/tools/retrieval.py145 The frontend provides a MetadataFilter component that supports variable referencing web/src/pages/agent/form/retrieval-form/next.tsx182

Sources: agent/tools/retrieval.py44-137 internal/agent/component/universe_a_wrappers.go160-165 web/src/pages/agent/form/retrieval-form/next.tsx141-182