====== XAgent: Autonomous LLM Agent for Complex Tasks ======

XAgent is an open-source autonomous agent developed by OpenBMB at Tsinghua University, with over 8,500 GitHub stars. Designed to solve complex, multi-step tasks without human intervention, XAgent uses a hierarchical planning architecture with three core components -- Dispatcher, Planner, and Actor -- that decompose high-level goals into executable subtasks. All tool execution runs safely inside Docker containers via the ToolServer system.

XAgent represents a research-driven approach to autonomous agents, emphasizing safety through sandboxed execution, extensibility through modular tool integration, and human-agent collaboration when needed. It supports a wide range of built-in tools including file editing, Python notebooks, web browsing, and shell access.

===== Architecture =====

XAgent's core architecture consists of three interconnected components that work together in a hierarchical planning loop:

  * **Dispatcher** -- Dynamically instantiates and manages agents, routing tasks to the appropriate Planner or Actor based on task type and complexity. Enables extensibility by supporting new agent types.
  * **Planner** -- Generates and refines execution plans by decomposing high-level tasks into subtasks and milestones. Uses a tree-based search strategy to explore different plan paths and select optimal approaches.
  * **Actor** -- Executes concrete actions to achieve subtask goals by leveraging tools from the ToolServer. Reports results back to the Planner for plan refinement.

The system operates through a **dual-loop mechanism**:
  * **Outer Loop** -- The Planner iteratively decomposes tasks, evaluates progress, and adjusts the plan based on Actor feedback
  * **Inner Loop** -- The Actor executes individual subtask steps, calling tools and processing results until the subtask is complete or requires replanning

===== ToolServer =====

ToolServer is a Docker-based infrastructure providing safe, sandboxed tool execution:

  * **ToolServerManager** -- Creates and manages ToolServerNode instances
  * **ToolServerMonitor** -- Monitors health and automatically removes failing instances
  * **ToolServerNode** -- Individual containers providing tools to agents

Built-in tools include:
  * **File Editor** -- Read, write, and modify files
  * **Python Notebook** -- Interactive Python execution for data analysis and visualization
  * **Web Browser** -- Search and navigate web pages
  * **Shell** -- Execute bash commands, install packages, host services
  * **Rapid API** -- Access thousands of third-party APIs

===== Code Example =====

<code python>
# XAgent configuration and task execution
# 1. Clone and set up the environment
# git clone https://github.com/OpenBMB/XAgent.git
# cd XAgent && pip install -r requirements.txt

# 2. Start ToolServer (Docker required)
# docker compose up -d toolserver

# 3. Configure and run XAgent
from XAgent.core import XAgentCore
from XAgent.config import XAgentConfig

config = XAgentConfig(
    model="gpt-4",
    api_key="your-openai-key",
    toolserver_url="http://localhost:8080",
    max_chain_length=10,
    enable_human_feedback=False,
)

# Initialize XAgent with the Dispatcher-Planner-Actor architecture
agent = XAgentCore(config=config)

# Submit a complex task -- XAgent decomposes it automatically
task = "Analyze the CSV file sales_data.csv, generate summary statistics, "  \
       "create visualizations for trends, and write a report in markdown."

# The Dispatcher routes to Planner, which creates subtasks:
#   1. Read and parse the CSV file (Actor + File Editor)
#   2. Compute statistics (Actor + Python Notebook)
#   3. Generate charts (Actor + Python Notebook)
#   4. Write markdown report (Actor + File Editor)
result = agent.run(task)

# Access results and execution trace
print(result.summary)
print(result.artifacts)  # Generated files: charts, report, etc.
</code>

===== System Flow =====

<code>
%%{init: {"theme": "base", "themeVariables": {"primaryColor": "#8E44AD"}}}%%
graph TD
    A[User Task] --> B[Dispatcher]
    B --> C[Planner]
    C --> D[Task Decomposition]
    D --> E[Subtask 1]
    D --> F[Subtask 2]
    D --> G[Subtask N]
    E --> H[Actor]
    F --> H
    G --> H
    H --> I{Tool Needed?}
    I -->|Yes| J[ToolServer]
    J --> K[File Editor]
    J --> L[Python Notebook]
    J --> M[Web Browser]
    J --> N[Shell]
    I -->|No| O[LLM Reasoning]
    K --> P[Result]
    L --> P
    M --> P
    N --> P
    O --> P
    P --> Q{Subtask Complete?}
    Q -->|No| H
    Q -->|Yes| R{All Subtasks Done?}
    R -->|No| C
    R -->|Yes| S[Final Result]
</code>

===== Key Features =====

  * **Autonomous Execution** -- Solves complex multi-step tasks without human intervention
  * **Hierarchical Planning** -- Tree-based task decomposition with milestone tracking
  * **Safe Execution** -- All tools run in isolated Docker containers via ToolServer
  * **Dual-Loop Design** -- Outer planning loop with inner execution loop for adaptive behavior
  * **Human Collaboration** -- Optional human-in-the-loop for guidance on challenging subtasks
  * **Extensible Tools** -- Modular architecture for adding custom tools and agents
  * **GUI Interface** -- Web-based interface for task submission and progress monitoring

===== References =====

  * [[https://github.com/OpenBMB/XAgent|XAgent GitHub Repository]]
  * [[https://blog.x-agent.net/blog/xagent/|Official Blog Post]]
  * [[https://xagent-doc.readthedocs.io|XAgent Documentation]]
  * [[https://www.openbmb.cn/|OpenBMB (Tsinghua University)]]

===== See Also =====

  * [[mastra|Mastra]] -- TypeScript agent framework with workflow orchestration
  * [[r2r|R2R]] -- Agentic RAG system with multi-step reasoning
  * [[vanna|Vanna]] -- Autonomous SQL generation agent