Multi-Agent Chat - Qwen-Agent

Qwen-Agent supports sophisticated multi-agent systems where multiple AI agents collaborate, delegate tasks, and interact with human users. This guide covers group chat systems and agent routing patterns.

Group Chat System

Create conversations with multiple AI agents and human participants.

Basic Group Chat

group_chat_demo.py

import json5
from qwen_agent.agents import GroupChat, GroupChatCreator
from qwen_agent.gui import WebUI

# Define group chat configuration
CFGS = {
    'background': '一个陌生人互帮互助群聊',
    'agents': [
        {
            'name': '小塘',
            'description': '一个勤劳的打工人，每天沉迷工作，日渐消瘦。（这是一个真实用户）',
            'is_human': True  # Mark as real person
        },
        {
            'name': '甄嬛',
            'description': '一位后宫妃嫔',
            'instructions': '你是甄嬛，你正在想办法除掉皇后，你说话风格为文言文，每次说完话会调image_gen工具画一幅图，展示心情。',
            'knowledge_files': [],
            'selected_tools': ['image_gen']
        },
        {
            'name': 'ikun',
            'description': '熟悉蔡徐坤的动态',
            'instructions': '你是蔡徐坤的粉丝，说话很简短，喜欢用颜文字表达心情，你最近迷恋看《甄嬛传》',
            'knowledge_files': [],
            'selected_tools': []
        },
        {
            'name': '大头',
            'description': '是一个体育生，不喜欢追星',
            'instructions': '你是一个体育生，热爱运动，你不喜欢追星，你喜欢安利别人健身',
            'knowledge_files': [],
            'selected_tools': []
        }
    ]
}

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

def app():
    bot = init_agent_service(cfgs=CFGS)
    
    # Run group chat
    messages = []
    for response in bot.run(messages, need_batch_response=False):
        for msg in response:
            print(f"{msg.name}: {msg.content}")

if __name__ == '__main__':
    app()

How It Works

Define Agents

Configure each agent with name, description, instructions, and tools

Initialize GroupChat

Create a GroupChat instance that manages all agents

Run Conversation

The system automatically selects which agent speaks next based on context

Handle Responses

Process responses from agents and humans

Agent Configuration

Agent Schema

Each agent is defined with these properties:

agent_config = {
    'name': 'Agent Name',
    'description': 'Brief description of the agent\'s role',
    'instructions': 'Detailed system instructions for behavior',
    'knowledge_files': ['doc1.pdf', 'doc2.txt'],  # Optional
    'selected_tools': ['tool1', 'tool2'],  # Optional
    'is_human': False  # True for human participants
}

Human Participants

Include humans in the conversation:

{
    'name': 'John',
    'description': 'Software engineer with expertise in Python',
    'is_human': True  # This marks the agent as a real person
}

When an agent is marked as human, the system will wait for user input instead of generating a response.

Agent Mention System

Direct messages to specific agents using @mentions:

messages = [
    {
        'role': 'user',
        'content': '@甄嬛 今天天气如何？',
        'name': 'user'
    }
]

# The system will prioritize 甄嬛 to respond
for response in bot.run(messages, mentioned_agents_name=['甄嬛']):
    print(response)

Mention Priority

When multiple agents are mentioned:

# Agents will respond in order of mention
messages = [{
    'role': 'user',
    'content': '@甄嬛 @ikun 你们怎么看？'
}]

# 甄嬛 responds first, then ikun
for response in bot.run(
    messages,
    mentioned_agents_name=['甄嬛', 'ikun']
):
    print(response)

Multi-Agent Router

Use a router to delegate tasks to specialized agents.

Router Pattern

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']

    # Define a vision agent
    bot_vl = Assistant(
        llm=llm_cfg_vl,
        name='多模态助手',
        description='可以理解图像内容。'
    )

    # Define a tool agent
    bot_tool = ReActChat(
        llm=llm_cfg,
        name='工具助手',
        description='可以使用画图工具和运行代码来解决问题',
        function_list=tools,
    )

    # Define a router (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()

How Router Works

Receive Request

Router receives user query with text, images, or files

Analyze Requirements

Router analyzes what capabilities are needed

Select Agent

Router delegates to the most appropriate agent:

Vision agent for image understanding
Tool agent for code/image generation
Itself for general text queries

Return Response

Selected agent processes request and returns result

Specialized Agent Types

ReActChat Agent

Reasoning and acting agent for tool use:

from qwen_agent.agents import ReActChat

bot = ReActChat(
    llm={'model': 'qwen-max'},
    name='Tool Expert',
    description='Uses tools to solve problems',
    function_list=['code_interpreter', 'web_search', 'calculator'],
)

Best for:

Multi-step problem solving
Tool-heavy workflows
Data analysis tasks

Assistant Agent

General-purpose conversational agent:

from qwen_agent.agents import Assistant

bot = Assistant(
    llm={'model': 'qwen-max'},
    name='General Assistant',
    description='Helps with various tasks',
    system_message='You are a helpful assistant.',
)

Best for:

Conversations
Document QA
General queries

Router Agent

Delegates to other agents:

from qwen_agent.agents import Router

bot = Router(
    llm={'model': 'qwen-max'},
    agents=[agent1, agent2, agent3],
    name='Router',
    description='Routes requests to specialized agents',
)

Best for:

Complex multi-capability systems
Task delegation
Hierarchical agent structures

Group Chat with Web UI

Create an interactive web interface for group chat:

import gradio as gr
from qwen_agent.gui.gradio_dep import mgr, ms

def create_group_chat_ui():
    bot = init_agent_service(cfgs=CFGS)
    
    with gr.Blocks(theme='soft') as demo:
        with ms.Application():
            chatbot = mgr.Chatbot(
                elem_id='chatbot',
                height=750,
                show_copy_button=True,
                flushing=False
            )
            
            with gr.Row():
                chat_txt = gr.Textbox(
                    show_label=False,
                    placeholder='Chat with agents...',
                    container=False,
                )
                chat_btn = gr.Button('Send')
            
            # Connect components
            chat_txt.submit(add_text, [chat_txt], [chatbot, chat_txt])
            chat_btn.click(add_text, [chat_txt], [chatbot, chat_txt])
    
    return demo

if __name__ == '__main__':
    demo = create_group_chat_ui()
    demo.queue().launch()

Group Chat Creator

Dynamically create and configure group chats:

from qwen_agent.agents import GroupChatCreator

def create_dynamic_group():
    llm_cfg = {'model': 'qwen-max'}
    creator = GroupChatCreator(llm=llm_cfg)
    
    # Let AI create agent configuration
    messages = [{
        'role': 'user',
        'content': '创建一个关于旅游规划的群聊，包含导游、摄影师和美食家三个角色'
    }]
    
    for response in creator.run(messages):
        print(response)
        # Response contains generated agent configurations

if __name__ == '__main__':
    create_dynamic_group()

Advanced Patterns

Conversation Flow Control

Control the number of turns:

MAX_ROUND = 5

for i in range(MAX_ROUND):
    for response in bot.run(messages, need_batch_response=False):
        if not response:
            print('Conversation ended')
            break
        
        messages.extend(response)
        
        # Check for user input needed
        if response[-1].content == PENDING_USER_INPUT:
            break

Batch Responses

Get all agent responses at once:

# Get all responses before proceeding
for response in bot.run(messages, need_batch_response=True):
    # response contains messages from all agents who want to speak
    for msg in response:
        print(f"{msg.name}: {msg.content}")

Custom Agent Selection

Implement custom logic for agent selection:

class CustomGroupChat(GroupChat):
    def select_next_agent(self, messages, agents):
        # Your custom logic
        # Return the next agent to speak
        return selected_agent

Use Cases

Brainstorming Session

cfgs = {
    'background': 'Product brainstorming meeting',
    'agents': [
        {
            'name': 'Product Manager',
            'instructions': 'Focus on user needs and business value',
        },
        {
            'name': 'Designer',
            'instructions': 'Consider user experience and aesthetics',
            'selected_tools': ['image_gen']
        },
        {
            'name': 'Engineer',
            'instructions': 'Evaluate technical feasibility',
            'selected_tools': ['code_interpreter']
        },
    ]
}

Educational Debate

cfgs = {
    'background': 'Debate on AI ethics',
    'agents': [
        {
            'name': 'Proponent',
            'instructions': 'Argue in favor of AI development',
        },
        {
            'name': 'Skeptic',
            'instructions': 'Raise concerns about AI risks',
        },
        {
            'name': 'Moderator',
            'instructions': 'Keep discussion balanced and on-topic',
            'is_human': True
        },
    ]
}

Customer Support Team

cfgs = {
    'background': 'Customer support team',
    'agents': [
        {
            'name': 'First Line Support',
            'instructions': 'Handle common questions',
            'knowledge_files': ['faq.pdf']
        },
        {
            'name': 'Technical Expert',
            'instructions': 'Solve complex technical issues',
            'selected_tools': ['code_interpreter']
        },
        {
            'name': 'Customer',
            'is_human': True
        },
    ]
}

Best Practices

Clear Roles

Give each agent a distinct, well-defined role and personality

Appropriate Tools

Assign tools that match each agent’s expertise

Context Management

Monitor conversation length and summarize when needed

Flow Control

Use mentions and max rounds to control conversation flow

Configuration Tips

Agent Instructions

Write effective agent instructions:

# Good: Specific and actionable
instructions = '''
You are a Python expert. When asked coding questions:
1. First explain the concept
2. Then provide working code
3. Add comments explaining key parts
4. Suggest best practices
Always use code_interpreter to test code before sharing.
'''

# Bad: Too vague
instructions = 'You are helpful with coding.'

Tool Selection

# Match tools to agent role
agents = [
    {
        'name': 'Data Scientist',
        'selected_tools': ['code_interpreter'],  # For analysis
    },
    {
        'name': 'Artist',
        'selected_tools': ['image_gen'],  # For creation
    },
    {
        'name': 'Researcher',
        'selected_tools': ['web_search'],  # For information
    },
]

Troubleshooting

Agent not responding

Check agent description matches query context
Verify agent has required tools
Try using @mention to directly address agent
Check max_rounds hasn’t been reached

Wrong agent selected

Improve agent descriptions to be more distinct
Use mentions for explicit routing
Check router logic and agent priorities

Conversation loops

Set MAX_ROUND limit
Implement termination conditions
Add a moderator agent to control flow

Human input not working

Verify is_human=True is set
Check for PENDING_USER_INPUT in responses
Ensure UI is properly handling user input

Performance Considerations

API Calls: Each agent response requires LLM API call
Latency: Multi-turn conversations can take time
Cost: More agents = more API usage
Context: Long conversations may hit token limits

Optimization strategies:

# Use faster model for simple agents
simple_agent_llm = {'model': 'qwen-turbo'}
complex_agent_llm = {'model': 'qwen-max'}

# Limit conversation rounds
MAX_ROUND = 3

# Summarize long conversations
if len(messages) > 20:
    summary = summarize_conversation(messages)
    messages = [summary] + messages[-5:]

Browser Extension

Examples

​Group Chat System

​Basic Group Chat

​How It Works

​Agent Configuration

​Agent Schema

​Human Participants

​Agent Mention System

​Mention Priority

​Multi-Agent Router

​Router Pattern

​How Router Works

​Specialized Agent Types

​ReActChat Agent

​Assistant Agent

​Router Agent

​Group Chat with Web UI

​Group Chat Creator

​Advanced Patterns

​Conversation Flow Control

​Batch Responses

​Custom Agent Selection

​Use Cases

​Brainstorming Session

​Educational Debate

​Customer Support Team

​Best Practices

Clear Roles

Appropriate Tools

Context Management

Flow Control

​Configuration Tips

​Agent Instructions

​Tool Selection

​Troubleshooting

​Performance Considerations

​Next Steps

Assistant Demos

Function Calling

Build docs developers (and LLMs) love

Group Chat System

Basic Group Chat

How It Works

Agent Configuration

Agent Schema

Human Participants

Agent Mention System

Mention Priority

Multi-Agent Router

Router Pattern

How Router Works

Specialized Agent Types

ReActChat Agent

Assistant Agent

Router Agent

Group Chat with Web UI

Group Chat Creator

Advanced Patterns

Conversation Flow Control

Batch Responses

Custom Agent Selection

Use Cases

Brainstorming Session

Educational Debate

Customer Support Team

Best Practices

Configuration Tips

Agent Instructions

Tool Selection

Troubleshooting

Performance Considerations

Next Steps