Agent Canvas/Tools & Integration/ — Tools & Integration

Contents

Architecture

graph TB
    BASE["ToolBase
Abstract Base"]
    REGISTRY["Tool
Registry"]
    BASE --> REGISTRY
    
    CODE["code_exec
Sandbox
RestrictedPython"] --> REGISTRY
    TAVILY["tavily
Web Search
Tavily API"] --> REGISTRY
    RETRIEVAL["retrieval
RAG Query
Vector DB"] --> REGISTRY
    SQL["sql_executor
SQL Query
Database"] --> REGISTRY
    CRAWLER["web_crawler
HTML Parse
BeautifulSoup"] --> REGISTRY
    EMAIL["email
SMTP
Send Mail"] --> REGISTRY
    API["api_request
HTTP
GET/POST"] --> REGISTRY
    INVOKE["tool_invoke
Recursive
Call Tool"] --> REGISTRY

flowchart TD
    Lookup["Tool Lookup
By Name"]
    Init["__init__
Configure"]
    Validate["Validate
Params"]
    Execute["_execute()
Run Tool"]
    Retry{"Transient
Error?"}
    Success["Success
Return Result"]
    Fallback["Fallback
exception_default_value"]
    
    Lookup --> Init
    Init --> Validate
    Validate --> Execute
    Execute --> Retry
    Retry -->|Yes| Execute
    Retry -->|No| Success
    Retry -->|Exhausted| Fallback
    style Success fill:#c8e6c9
    style Fallback fill:#ffccbc

Key Classes

Data Structures

Interactions

Configuration

Directory Map

submod_name/
├── file_a.ext                 ← Role: brief annotation
├── file_b.ext                 ← Role: brief annotation
├── file_c.ext                 ← Role: brief annotation
└── index.ext                  ← Role: entry point

📑 Annotated Code Walkthrough

The most important code in this sub-module, annotated with WHY each piece exists:

// Replace with actual code from the source
void key_function() {
    // ← WHY: Explain the purpose of this line
    // ← WHY: What constraint or requirement drives this?
}

⚠️ Edge Cases & Boundaries

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Typical Usage

// Replace with actual code example
void example() {
    // ...
}

Tool Failure Modes & Recovery Strategies

Tools fail in predictable ways. RAGFlow implements tiered recovery strategies for each failure mode.

Failure Mode Classification

Retry Configuration Example

{
  "nodes": [
    {
      "id": "web_search_1",
      "type": "tavily",
      "config": {
        "query": "{{llm_1@output.search_query}}",
        "max_results": 10,
        "timeout": 30,
        "retry_max": 3,
        "retry_backoff_ms": 100,
        "exception_default_value": {
          "results": [],
          "error": "Search service unavailable; using empty results"
        }
      }
    }
  ]
}

Tool Monitoring & Observability

• Execution time: Each tool execution step in history includes duration_ms. Use to identify bottlenecks (e.g., if tavily searches are taking >5s, investigate network or service latency).
• Retry counts: If a tool is retrying frequently, log and alert. Could indicate flaky service or misconfigured timeout.
• Exception patterns: If same tool always fails with same error (e.g., "API key invalid"), fix configuration before next run.
• Fallback activation: If exception_default_value is used, workflow continues but with degraded data. Monitor for this and adjust strategy if too frequent.

Advanced Tool Patterns & Integration

Beyond basic tool invocation, RAGFlow supports sophisticated patterns for composition, fallbacks, and context passing.

Tool Composition Patterns

• Sequential Chaining: Output of one tool flows as input to next. Example: retrieval → llm_answer (context-aware). Via variable references (tool_a@result → tool_b@context).
• Conditional Execution: Tools run only if preconditions met (Switch nodes). Example: run code_exec if code snippet detected, else skip.
• Fallback Chains: Multiple tools with fallback semantics. web_crawler fails → try api_request; both fail → return error message. Via exception_default_value or exception_goto.
• Iteration Parallelism: No built-in multi-threading, but Iteration node runs tool N times across list. Each iteration gets isolated sub-DAG; results aggregated.
• Dynamic Tool Selection: Tool name determined at runtime. Agent component inspects LLM output to pick next tool (ReAct pattern, tool_choice semantics).

Error Handling & Resilience Tiers

Tool Context & State Management

• Tool Isolation: Each tool invocation is isolated; no persistent state between calls (unless explicitly managed). Useful for determinism and testability.
• Context Injection: Tools can receive workflow context via params. Example: retrieval tool gets search_keywords param from LLM reasoning step.
• Output Caching: Component outputs cached in _outputs[component_id]. Tools that are deterministic (same input → same output) can skip re-execution if node already run.
• User Context: Some tools (email, api_request) may need user credentials or request ID. Passed via workflow params or global variables (user_id, auth_token, etc.).