Multi-Agent Systems

Overview

Qwen-Agent provides powerful multi-agent orchestration capabilities, allowing you to build systems where multiple specialized agents work together to solve complex tasks. The framework supports various coordination patterns including routing, group chat, and custom orchestration.

Multi-Agent Patterns

Qwen-Agent supports three main multi-agent patterns:

Router: Intelligent routing to specialized agents
GroupChat: Collaborative conversation between agents
MultiAgentHub: Custom multi-agent orchestration

Router Pattern

The Router pattern (qwen_agent/agents/router.py:36) automatically selects the best agent for each task.

Quick Start

from qwen_agent.agents import Assistant, ReActChat, Router

# Define specialized agents
vl_agent = Assistant(
    llm={'model': 'qwen-vl-max'},
    name='Vision Assistant',
    description='Can understand image content'
)

tool_agent = ReActChat(
    llm={'model': 'qwen-max'},
    name='Tool Assistant',
    description='Can use drawing tools and run code',
    function_list=['image_gen', 'code_interpreter']
)

# Create router
bot = Router(
    llm={'model': 'qwen-max'},
    agents=[vl_agent, tool_agent]
)

messages = [{'role': 'user', 'content': 'Draw a chart showing sales data'}]
for response in bot.run(messages):
    print(response)

How Router Works

The Router acts as a coordinator (examples/multi_agent_router.py:44):

1. User Query
      ↓
2. Router analyzes query
      ↓
3. Selects appropriate agent
   OR handles directly
      ↓
4. Selected agent processes
      ↓
5. Response to user

Router Configuration

from qwen_agent.agents import Router

router = Router(
    llm={'model': 'qwen-max'},
    agents=[agent1, agent2, agent3],
    name='MainRouter',
    description='Routes tasks to specialized agents',
    files=['knowledge.pdf'],  # Optional RAG
    function_list=['search']  # Optional tools for router itself
)

Complete Router Example

From the codebase (examples/multi_agent_router.py):

from qwen_agent.agents import Assistant, ReActChat, Router
from qwen_agent.gui import WebUI

def init_agent_service():
    llm_cfg = {'model': 'qwen-max'}
    llm_cfg_vl = {'model': 'qwen-vl-max'}
    tools = ['image_gen', 'code_interpreter']

    # Vision agent
    bot_vl = Assistant(
        llm=llm_cfg_vl,
        name='Multimodal Assistant',
        description='Can understand image content'
    )

    # Tool agent
    bot_tool = ReActChat(
        llm=llm_cfg,
        name='Tool Assistant',
        description='Can use drawing tools and run code to solve problems',
        function_list=tools
    )

    # Router agent (also serves as text agent)
    bot = Router(
        llm=llm_cfg,
        agents=[bot_vl, bot_tool]
    )
    return bot

def app_gui():
    bot = init_agent_service()
    chatbot_config = {'verbose': True}
    WebUI(bot, chatbot_config=chatbot_config).run()

if __name__ == '__main__':
    app_gui()

GroupChat Pattern

GroupChat (qwen_agent/agents/group_chat.py:29) enables multiple agents to have conversations.

Quick Start

from qwen_agent.agents import GroupChat

cfgs = {
    'background': 'A collaborative problem-solving team',
    'agents': [
        {
            'name': 'Researcher',
            'description': 'Expert in research and analysis',
            'instructions': 'You are a thorough researcher who provides detailed analysis.',
            'selected_tools': []
        },
        {
            'name': 'Coder',
            'description': 'Expert programmer',
            'instructions': 'You write clean, efficient code to solve problems.',
            'selected_tools': ['code_interpreter']
        },
        {
            'name': 'Writer',
            'description': 'Expert technical writer',
            'instructions': 'You document solutions clearly and concisely.',
            'selected_tools': []
        }
    ]
}

bot = GroupChat(
    agents=cfgs,
    llm={'model': 'qwen-max'},
    agent_selection_method='auto'
)

messages = [{'role': 'user', 'content': 'Build a data analysis solution'}]
for response in bot.run(messages, max_round=5):
    print(response)

Agent Selection Methods

GroupChat supports multiple selection strategies (qwen_agent/agents/group_chat.py:36):

# LLM selects the next speaker
bot = GroupChat(
    agents=cfgs,
    llm={'model': 'qwen-max'},
    agent_selection_method='auto'  # Smart selection
)

Mentioning Agents

Agents can explicitly mention others using @ syntax:

messages = [
    {'role': 'user', 'content': '@Researcher please analyze this problem first'}
]

for response in bot.run(messages):
    print(response)

Human-in-the-Loop

Include human participants in group chats:

cfgs = {
    'background': 'A team working on a project',
    'agents': [
        {
            'name': 'Alice',
            'description': 'Project manager and stakeholder',
            'is_human': True  # Mark as human
        },
        {
            'name': 'AI Assistant',
            'description': 'Helpful AI assistant',
            'instructions': 'You help Alice with various tasks.',
            'selected_tools': ['code_interpreter']
        }
    ]
}

bot = GroupChat(agents=cfgs, llm={'model': 'qwen-max'})

Complete GroupChat Example

From the codebase (examples/group_chat_demo.py:51):

from qwen_agent.agents import GroupChat
from qwen_agent.gui import gradio

CFGS = {
    'background': 'A mutual aid group',
    'agents': [
        {
            'name': 'Tang',
            'description': 'A hardworking person (real user)',
            'is_human': True
        },
        {
            'name': 'Zhen Huan',
            'description': 'A palace concubine',
            'instructions': 'You are Zhen Huan. You speak in classical Chinese. After each message, call image_gen to show your mood.',
            'knowledge_files': [],
            'selected_tools': ['image_gen']
        },
        {
            'name': 'ikun',
            'description': 'Familiar with celebrity Cai Xukun',
            'instructions': 'You are a fan of Cai Xukun. You speak briefly and like using emoticons. You recently love watching "Legend of Zhen Huan".',
            'knowledge_files': [],
            'selected_tools': []
        },
        {
            'name': 'Datou',
            'description': 'An athlete who dislikes celebrity culture',
            'instructions': 'You are an athlete. You love sports. You dislike celebrity worship. You like recommending fitness to others.',
            'knowledge_files': [],
            'selected_tools': []
        }
    ]
}

bot = GroupChat(
    agents=CFGS,
    llm={'model': 'qwen-max'},
    agent_selection_method='auto'
)

MultiAgentHub

MultiAgentHub (qwen_agent/multi_agent_hub.py:22) is the base class for custom multi-agent orchestration.

Creating Custom Multi-Agent Systems

from qwen_agent import Agent, MultiAgentHub
from qwen_agent.llm.schema import Message
from typing import List, Iterator

class CustomOrchestrator(Agent, MultiAgentHub):
    """Custom multi-agent orchestration."""
    
    def __init__(self, agents, llm, **kwargs):
        super().__init__(llm=llm, **kwargs)
        self._agents = agents
    
    def _run(self, messages: List[Message], **kwargs) -> Iterator[List[Message]]:
        # Custom orchestration logic
        
        # Example: Sequential processing
        current_messages = messages
        for agent in self.agents:
            print(f"Running {agent.name}...")
            response = agent.run_nonstream(current_messages)
            current_messages.extend(response)
        
        yield current_messages

# Usage
agents = [
    Assistant(llm={'model': 'qwen-max'}, name='Agent1'),
    Assistant(llm={'model': 'qwen-max'}, name='Agent2')
]

orchestrator = CustomOrchestrator(
    agents=agents,
    llm={'model': 'qwen-max'}
)

MultiAgentHub Properties

The MultiAgentHub provides useful properties:

# Get all agents
agents = orchestrator.agents  # List[Agent]

# Get agent names
names = orchestrator.agent_names  # List[str]

# Get non-user agents
ai_agents = orchestrator.nonuser_agents  # List[Agent]

Advanced Patterns

Hierarchical Multi-Agent Systems

from qwen_agent.agents import Assistant, Router, GroupChat

# Bottom layer: Specialized workers
research_team = GroupChat(
    agents=[
        {'name': 'Researcher1', 'description': '...', 'instructions': '...'},
        {'name': 'Researcher2', 'description': '...', 'instructions': '...'},
    ],
    llm={'model': 'qwen-max'}
)

dev_team = GroupChat(
    agents=[
        {'name': 'Developer1', 'description': '...', 'instructions': '...'},
        {'name': 'Developer2', 'description': '...', 'instructions': '...'},
    ],
    llm={'model': 'qwen-max'}
)

# Top layer: Router coordinates teams
project_manager = Router(
    llm={'model': 'qwen-max'},
    agents=[research_team, dev_team],
    name='ProjectManager'
)

messages = [{'role': 'user', 'content': 'Build a new feature'}]
for response in project_manager.run(messages):
    print(response)

Parallel Processing

import asyncio
from qwen_agent.agents import Assistant

async def parallel_agents(messages):
    agents = [
        Assistant(llm={'model': 'qwen-max'}, name=f'Agent{i}')
        for i in range(3)
    ]
    
    # Run agents in parallel
    tasks = [
        asyncio.create_task(run_agent(agent, messages))
        for agent in agents
    ]
    
    results = await asyncio.gather(*tasks)
    return results

async def run_agent(agent, messages):
    response = agent.run_nonstream(messages)
    return response

# Usage
messages = [{'role': 'user', 'content': 'Analyze from different perspectives'}]
results = asyncio.run(parallel_agents(messages))

Specialized Agent Pipeline

from qwen_agent.agents import Assistant

class Pipeline:
    def __init__(self):
        self.agents = [
            Assistant(
                llm={'model': 'qwen-max'},
                name='Analyzer',
                system_message='Analyze the input and extract key points'
            ),
            Assistant(
                llm={'model': 'qwen-max'},
                name='Enhancer',
                system_message='Enhance the analysis with additional context'
            ),
            Assistant(
                llm={'model': 'qwen-max'},
                name='Formatter',
                system_message='Format the final output professionally'
            )
        ]
    
    def run(self, messages):
        current = messages
        for agent in self.agents:
            print(f"Running {agent.name}...")
            response = agent.run_nonstream(current)
            current.extend(response)
        return current

pipeline = Pipeline()
result = pipeline.run([{'role': 'user', 'content': 'Analyze this data...'}])

Best Practices

Multi-Agent Design Tips

Give each agent a clear, specific role and description
Use descriptive agent names (helps LLM routing)
Start with 2-3 agents, add more as needed
Set max_round limits to prevent infinite loops
Use Router for task-based delegation
Use GroupChat for collaborative problem-solving
Monitor conversation flow during development

Common Pitfalls

Too many agents can lead to confusion
Vague agent descriptions reduce routing accuracy
Not setting max_round can cause long conversations
Overlapping agent capabilities create redundancy
Missing agent names breaks multi-agent communication

Debugging Multi-Agent Systems

Verbose Mode

bot = GroupChat(
    agents=cfgs,
    llm={'model': 'qwen-max'}
)

chatbot_config = {
    'verbose': True  # Show detailed agent selection and responses
}

WebUI(bot, chatbot_config=chatbot_config).run()

Logging

from qwen_agent.log import logger
import logging

logger.setLevel(logging.DEBUG)

# Shows agent selection and communication
for response in bot.run(messages):
    logger.info(f"Response from {response[-1].name}")
    print(response)

Performance Considerations

Token Usage

# Multi-agent systems use more tokens
# Each agent sees conversation history
# Optimize by:

# 1. Limit conversation rounds
for response in bot.run(messages, max_round=3):
    pass

# 2. Use concise agent instructions
agent = Assistant(
    llm={'model': 'qwen-max'},
    system_message='Brief, focused instructions'  # Not lengthy prompts
)

# 3. Selectively pass context
# Only include relevant history for each agent

Latency

# Sequential agents increase latency
# Optimize by:

# 1. Use parallel processing where possible
# 2. Cache agent responses
# 3. Use faster models for routing
router = Router(
    llm={'model': 'qwen-turbo'},  # Faster model for routing
    agents=[agent1, agent2]
)

Next Steps

Learn about Building Agents to create specialized agents
Explore Custom Tools to extend agent capabilities
See GUI Deployment to build multi-agent interfaces

Get Started

Core Concepts

Guides

Built-in Agents

Built-in Tools

Overview

Multi-Agent Patterns

Router Pattern

Quick Start

How Router Works

Router Configuration

Complete Router Example

GroupChat Pattern

Quick Start

Agent Selection Methods

Mentioning Agents

Human-in-the-Loop

Complete GroupChat Example

MultiAgentHub

Creating Custom Multi-Agent Systems

MultiAgentHub Properties

Advanced Patterns

Hierarchical Multi-Agent Systems

Parallel Processing

Specialized Agent Pipeline

Best Practices

Debugging Multi-Agent Systems

Verbose Mode

Logging

Performance Considerations

Token Usage

Latency

Next Steps

Get Started

Core Concepts

Guides

Built-in Agents

Built-in Tools

Documentation Index

​Overview

​Multi-Agent Patterns

​Router Pattern

​Quick Start

​How Router Works

​Router Configuration

​Complete Router Example

​GroupChat Pattern

​Quick Start

​Agent Selection Methods

​Mentioning Agents

​Human-in-the-Loop

​Complete GroupChat Example

​MultiAgentHub

​Creating Custom Multi-Agent Systems

​MultiAgentHub Properties

​Advanced Patterns

​Hierarchical Multi-Agent Systems

​Parallel Processing

​Specialized Agent Pipeline

​Best Practices

​Debugging Multi-Agent Systems

​Verbose Mode

​Logging

​Performance Considerations

​Token Usage

​Latency

​Next Steps

Overview

Multi-Agent Patterns

Router Pattern

Quick Start

How Router Works

Router Configuration

Complete Router Example

GroupChat Pattern

Quick Start

Agent Selection Methods

Mentioning Agents

Human-in-the-Loop

Complete GroupChat Example

MultiAgentHub

Creating Custom Multi-Agent Systems

MultiAgentHub Properties

Advanced Patterns

Hierarchical Multi-Agent Systems

Parallel Processing

Specialized Agent Pipeline

Best Practices

Debugging Multi-Agent Systems

Verbose Mode

Logging

Performance Considerations

Token Usage

Latency

Next Steps