Agent Tools and ReAct Loop

Relevant source files

• agent/canvas.py
• agent/component/agent_with_tools.py
• agent/component/base.py
• agent/component/categorize.py
• agent/component/llm.py
• agent/tools/base.py
• api/apps/api_app.py
• api/apps/canvas_app.py
• api/db/services/canvas_service.py
• api/db/services/conversation_service.py
• common/mcp_tool_call_conn.py
• rag/advanced_rag/__init__.py
• rag/prompts/generator.py
• web/src/components/knowledge-base-item.tsx
• web/src/interfaces/request/flow.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 extends the base LLM component (8.3) to orchestrate 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 and Component System Architecture. For details on the base LLM component without tool use, see Built-in Components.

---

Agent Component Overview

The Agent component is a specialized LLM component that implements ReAct-style tool use. Unlike a standard LLM component that generates text responses, the Agent can:

1. Analyze tasks into subtasks requiring tool assistance
2. Plan actions by selecting appropriate tools from its toolbox
3. Execute tools with parsed parameters
4. Reflect on results to determine next steps
5. Synthesize answers after iterative tool use

The Agent component is defined in agent/component/agent_with_tools.py83-428 with parameter configuration in agent/component/agent_with_tools.py38-80

Agent vs. LLM Component

Feature	LLM Component	Agent Component
Base class	ComponentBase	LLM + ToolBase
Output	Text generation	Text + tool use results
Iterations	Single-shot	Multi-turn (max_rounds)
Tool access	None	Built-in, MCP, plugins
Prompt structure	System + user messages	Task analysis + planning prompts
Use case	Direct Q&A	Complex multi-step tasks

Sources: agent/component/agent_with_tools.py83-118 agent/component/llm.py82-91

---

Tool Integration Architecture

Diagram 1: Tool Integration Architecture

Sources: agent/component/agent_with_tools.py86-117 agent/tools/base.py50-75

Built-in Component Tools

Built-in tools are RAGFlow components configured as tools. Any component implementing ToolBase can be used as a tool by the Agent. During initialization, the Agent loads tool configurations and instantiates component objects:

The _load_tool_obj() method (agent/component/agent_with_tools.py119-130) creates a unique component ID by appending the agent's ID as a prefix (e.g., agent_0-->wikipedia_search_0), enabling hierarchical tool tracing.

Common Built-in Tools:

• Retrieval: Knowledge base search (see 8.3)
• Wikipedia: Wikipedia article search
• BaiduSearch: Baidu web search
• DuckDuckGoSearch: DuckDuckGo web search
• GoogleSearch: Google web search
• ArXiv: Academic paper search
• PubMed: Medical literature search
• SQL: Database query execution

Sources: agent/component/agent_with_tools.py119-130

MCP (Model Context Protocol) Tools

MCP tools are external tools hosted by MCP servers following the Model Context Protocol. The Agent connects to MCP servers and dynamically fetches available tools:

MCP servers can be SSE-based or Streamable HTTP. The MCPToolCallSession (common/mcp_tool_call_conn.py42-226) manages the connection lifecycle and provides a synchronous interface to async MCP operations:

• Connection: Establishes transport (SSE or Streamable HTTP) with server
• Tool Discovery: Calls list_tools() to fetch available tools
• Tool Invocation: Calls call_tool(name, arguments) with timeout
• Error Handling: Wraps MCP errors and timeouts

Sources: agent/component/agent_with_tools.py108-114 common/mcp_tool_call_conn.py42-226

Tool Metadata Schema

All tools expose metadata in OpenAI function calling format:

Tool parameters are defined via ToolParamBase (agent/tools/base.py77-123) which auto-generates metadata from the meta dictionary:

Sources: agent/tools/base.py77-123

---

ReAct Loop Implementation

The ReAct (Reasoning + Acting) pattern enables multi-turn problem solving through iterative planning, tool use, and reflection. The Agent component implements this in _react_with_tools_streamly_async_simple() (agent/component/agent_with_tools.py278-419).

Diagram 2: ReAct Loop Flow

Sources: agent/component/agent_with_tools.py278-419

Task Analysis

Before entering the ReAct loop, the Agent builds a comprehensive task description that includes:

1. Agent prompt: System-level instructions for the agent's role
2. User request: The current query (potentially optimized for multi-turn)
3. User-defined prompts: Custom prompt overrides (task_analysis, plan_generation, reflection)

For multi-turn conversations (history > 3 messages), the Agent optimizes the user request by calling full_question() (rag/prompts/generator.py224-256), which reformulates the latest query considering conversation context.

Sources: agent/component/agent_with_tools.py283-305 rag/prompts/generator.py224-256

Planning: next_step_async

The next_step_async() function (rag/prompts/generator.py395-414) is the core planning mechanism. It uses a specialized prompt to ask the LLM: "What's the next tool to call?"

Planning Prompt Structure (NEXT_STEP template):

The LLM responds with a JSON array of tool calls:

If the LLM determines it has sufficient information, it calls the special complete_task function:

Sources: rag/prompts/generator.py395-414 agent/component/agent_with_tools.py376-382

Tool Execution

When the LLM selects tools, the Agent executes them in parallel using asyncio.gather():

Each tool is invoked through the LLMToolPluginCallSession (agent/tools/base.py50-75), which:

1. Validates the tool exists in the registry
2. Invokes the tool's invoke() or invoke_async() method
3. Logs the call with parameters and results via callback
4. Returns the tool output (string or structured data)

The callback function logs all tool invocations to Redis for tracing:

Sources: agent/component/agent_with_tools.py394-409 agent/tools/base.py50-75 agent/canvas.py779-801

Reflection: build_observation

After tools execute, the Agent constructs an "Observation" message summarizing results:

This observation is appended to the conversation history as a user message, allowing the LLM to "see" tool results in the next planning iteration:

Example observation:

Observation:
[retrieval_0 result]
ID: 123
Title: RAGFlow Documentation
Content: RAGFlow is an open-source RAG engine...

[wikipedia_search_0 result]
Docker is a platform for developing...

Sources: agent/component/agent_with_tools.py355-410

Completion and Citation

When the LLM calls complete_task, the Agent generates the final answer:

If citation is enabled (cite=True) and retrieval chunks exist, the Agent either:

1. Inline citation: Appends citation_prompt() to system prompt before generation
2. Post-generation citation: Generates answer first, then calls _gen_citations_async() to insert [ID:xxx] references

Sources: agent/component/agent_with_tools.py320-353

---

Tool Calling Session

Diagram 3: Tool Calling Session Flow

The LLMToolPluginCallSession class (agent/tools/base.py50-75) provides a unified interface for invoking heterogeneous tools:

Key responsibilities:

1. Tool dispatch: Routes calls to appropriate handler (MCP, Component, Plugin)
2. Async/sync bridging: Wraps sync tools with thread_pool_exec() for non-blocking execution
3. Timeout handling: MCP tools have 60-second default timeout
4. Result capture: Returns tool output for reflection
5. Trace logging: Invokes callback with timing information

Sources: agent/tools/base.py50-75

---

Multi-turn Conversation and Memory

The Agent maintains conversation state across multiple ReAct iterations through the hist variable, which accumulates:

1. System message: Agent prompt + citations (index 0)
2. User messages: Original query + observations from tool results
3. Assistant messages: LLM's reasoning and tool call decisions

History Management

To prevent context overflow, the Agent implements history truncation strategies:

Strategy 1: Recent message window (agent/component/agent_with_tools.py335-336)

Keeps system message, initial user query, and last 10 messages.

Strategy 2: Multi-turn optimization (agent/component/agent_with_tools.py283-287)

Reformulates the query to be self-contained using full_question() prompt.

Memory Integration

The Canvas maintains a memory list (agent/canvas.py316) storing tool call summaries:

Memory summaries are generated by tool_call_summary() (rag/prompts/generator.py448-456):

This creates concise summaries of tool interactions for long-term context.

Sources: agent/component/agent_with_tools.py283-336 agent/canvas.py316-827 rag/prompts/generator.py448-456

---

Streaming Output with Tools

The Agent supports real-time streaming of tool use and final answers through async generators:

Streaming Events

When connected to the Canvas SSE endpoint (api/apps/canvas_app.py132-186), the Agent emits structured events:

Tool Execution Events:

Message Streaming:

Tool Trace:

The frontend can retrieve full execution traces via /canvas/trace?canvas_id=xxx&message_id=yyy (api/apps/canvas_app.py551-562).

Sources: agent/component/agent_with_tools.py256-276 api/apps/canvas_app.py132-562

---

Configuration and Parameters

The AgentParam class (agent/component/agent_with_tools.py38-80) extends LLMParam with tool-specific configuration:

Parameter	Type	Description	Default
llm_id	string	LLM model identifier	Required
sys_prompt	string	System-level instructions	""
tools	list	Built-in component tool configs	[]
mcp	list	MCP server configurations	[]
max_rounds	int	Maximum ReAct iterations	5
cite	bool	Enable citation insertion	true
max_tokens	int	Max generation length	0 (unlimited)
temperature	float	Sampling temperature	0
description	string	Tool description override	""
custom_header	dict	Custom HTTP headers for MCP	{}

Tool Configuration Schema:

MCP Configuration Schema:

Sources: agent/component/agent_with_tools.py38-80

---

Error Handling and Cancellation

The Agent implements comprehensive error handling at multiple levels:

Tool-level Errors

Tool execution errors are caught and returned as string results:

The Agent treats tool errors as observations and continues the ReAct loop, allowing the LLM to recover by trying alternative tools.

ReAct Loop Errors

JSON parsing errors during tool selection trigger recovery prompts:

Task Cancellation

The Agent checks for cancellation at multiple points using check_if_canceled() (agent/component/base.py393-405):

Cancellation is coordinated through Redis flags (agent/canvas.py269-278):

Sources: agent/tools/base.py144-153 agent/component/agent_with_tools.py412-418 agent/component/base.py393-405 agent/canvas.py269-278

---

Component Registration

Agent components are registered through the component class discovery system. The component_class() function (agent/component/__init__.py) dynamically imports component classes:

This enables dynamic tool loading without hardcoded imports, supporting extensibility through plugins.

For details on component registration and dynamic loading, see Component Dynamic Loading.

Sources: agent/component/agent_with_tools.py120-130