agent.mdx

Overview

The Agent component is a core part of the Ragflow framework designed to empower Large Language Models (LLMs) with autonomous reasoning, tool usage, and multi-agent collaboration capabilities. Since version 0.20.5, the Agent can operate independently or as a planner orchestrating tools and subagents, enabling sophisticated workflows involving reflection, adjustment, and task delegation.

The Agent component is primarily responsible for fine-tuning the LLM prompt and managing its interaction with tools and other agents, facilitating complex tasks such as summarization, translation, or multi-step control processes.

Detailed Explanation

Purpose and Functionality

• Autonomous Reasoning: Agents can reflect on their outputs and adjust based on environmental feedback.

• Tool and Subagent Utilization: Agents can invoke external tools or delegate tasks to subagents.

• Multi-agent Collaboration: Supports orchestrating multiple agents and tools in a hierarchical or parallel manner.

• Flexible Prompting: Supports detailed configuration of system and user prompts, including framework-level prompt blocks for advanced customization.

Components of the Agent

This documentation focuses on the Agent component as a configuration and runtime entity within Ragflow. It is not a traditional code file but a component specification guiding the behavior of LLM-driven agents.

Configuration Parameters

Advanced Prompt Blocks (v0.20.5+)

The Agent supports advanced, framework-level prompt blocks to modularize and customize its reasoning workflow. These blocks can be selected or overridden in the System prompt configuration:

Usage Examples

Standalone Agent Configuration

• Select a chat model.

• Optionally customize system prompt.

• Customize user prompt, referencing variables like sys.query and formalized_content.

• Skip adding tools or subagents.

• Connect to next workflow component if needed.

Agent as a Planner with MCP Server

• Configure the MCP server with name, URL, API key, and server type.

• Add the MCP server as a tool under the Agent.

• Set system prompt to specify when tools should be invoked.

• Use advanced prompt blocks to enable task analysis, planning, and reflection.

• View and select tools exposed by the MCP server on the canvas.

Important Implementation Details

• Keys (Variables): Agents consume input keys that may come from non-immediate upstream components; arrows in workflows reflect processing order, not necessarily data flow.

• Multi-turn Dialogue: Message window size controls how many previous dialogue rounds are sent to the LLM, increasing context at the cost of token usage.

• Retries and Delay: Built-in retry mechanism with configurable max attempts and delay helps robustness.

• Reflection: Agents can iteratively reflect on tool calls and task progress to improve outputs.

• Prompt Engineering: System and user prompts are essential to guide the Agent’s behavior; the component supports complex prompt block structures for modularity.

• Model Freedom Presets: Abstracts complex LLM parameters into presets (Improvise, Precise, Balance) for ease of use.

Interaction with Other System Components

• Models: The Agent depends on chat models configured in the Model providers page.

• Tools: Can invoke external tools (e.g., Retrieval components, MCP servers) to extend capabilities.

• Subagents: Can delegate subtasks to subordinate Agents, enabling multi-agent workflows.

• Knowledge Bases: When used with retrieval, Agents incorporate dataset content via variables such as formalized_content.

• MCP Servers: Agents connect to MCP servers (e.g., Tavily) to access external tools and services.

• Workflow: The Agent is a node in a Ragflow workflow graph; outputs can be consumed by downstream components.

Frequently Asked Questions

Why does the Agent take a long time to respond?

• Response time depends on the complexity of the prompt and the LLM capabilities.

• Using simpler prompts and smaller models reduces latency.

• Complex multi-step reasoning and reflection increase processing time.

• Balancing task complexity and model selection is critical for performance.

Best Practices

• Use simpler prompts and smaller models for straightforward tasks.

• Employ full planning and reflection capabilities for complex workflows.

• Delegate simple subtasks to subagents with smaller models.

• Minimize output length to reduce token consumption and latency.

• Adjust reflection rounds judiciously to balance quality and speed.

Visual Diagram: Structure of the Agent Component

classDiagram
    class Agent {
        +model: ChatModel
        +freedom: enum {Improvise, Precise, Balance}
        +temperature: float
        +top_p: float
        +presence_penalty: float
        +frequency_penalty: float
        +max_tokens: int
        +system_prompt: string
        +user_prompt: string
        +tools: List~Tool~
        +sub_agents: List~Agent~
        +message_window_size: int
        +max_retries: int
        +delay_after_error: int
        +max_reflection_rounds: int
        +output_variable: string
        +run()
        +reflect()
        +plan()
        +call_tools()
    }

    class Tool {
        +name: string
        +invoke()
    }

    Agent "1" *-- "*" Tool : uses
    Agent "1" *-- "*" Agent : sub_agents

Summary

The Agent component in Ragflow is a highly configurable LLM orchestrator that supports autonomous reasoning, tool invocation, and multi-agent collaboration. It balances flexibility with usability via intuitive configuration options and advanced prompt engineering features. Its integration with chat models, external tools, and subagents enables powerful workflows for complex AI-driven tasks.

This documentation provides the conceptual and practical details needed to effectively configure and use the Agent component within Ragflow workflows.