Skip to main content

​
Overview

GroupChat is a powerful multi-agent management system that coordinates multiple agents in collaborative conversations. It manages speaking order, routes messages between agents, and supports both AI agents and human participants.
GroupChat is ideal for complex workflows that benefit from specialized agents working together, such as code review teams, research discussions, or customer support scenarios.

​
Key Features

Multi-Agent Coordination

Manage multiple specialized agents in one conversation

Flexible Selection

Auto, round-robin, random, or manual speaker selection

Human-in-the-Loop

Include real human participants in the conversation

Context Sharing

All agents see the full conversation history

​
Constructor

from qwen_agent.agents import GroupChat, Assistant, ReActChat

# Create agents
agent1 = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Researcher',
    description='An expert at researching and finding information'
)

agent2 = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Writer',
    description='An expert at writing clear, engaging content'
)

# Create group chat
group = GroupChat(
    agents=[agent1, agent2],
    agent_selection_method='auto',
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'}
)

​
Parameters

​
agents
list | dict
List of Agent objects or configuration dict:
{
  'background': 'Description of the group',
  'agents': [
    {'name': 'Agent1', 'description': '...', 'instructions': '...'},
    {'name': 'Agent2', 'description': '...', 'is_human': True}
  ]
}
​
agent_selection_method
str
default:"auto"
Speaker selection method:
  • auto: Host agent chooses based on context (requires LLM)
  • round_robin: Agents speak in order
  • random: Random speaker selection
  • manual: Manual speaker specification
​
function_list
list
Tools available to the host agent (for auto mode).
​
llm
dict | BaseChatModel
LLM for the host agent (required for auto mode).

​
Agent Selection Methods

The host agent intelligently chooses who should speak next: 
from qwen_agent.agents import GroupChat, Assistant

researcher = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Researcher',
    description='Expert at finding and analyzing information',
    function_list=['web_search']
)

writer = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Writer',
    description='Expert at creating clear, engaging content'
)

reviewer = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Reviewer',
    description='Expert at reviewing and providing feedback'
)

group = GroupChat(
    agents=[researcher, writer, reviewer],
    agent_selection_method='auto',
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'}
)

messages = [{
    'role': 'user',
    'content': 'Write a blog post about quantum computing'
}]

for response in group.run(messages=messages):
    print(f"{response[-1]['name']}: {response[-1]['content']}")

​
Round Robin

Agents speak in order: 
group = GroupChat(
    agents=[agent1, agent2, agent3],
    agent_selection_method='round_robin'
)

# Agents will speak: agent1 → agent2 → agent3 → agent1 → ...

​
Random Selection

Random speaker each turn: 
group = GroupChat(
    agents=[agent1, agent2, agent3],
    agent_selection_method='random'
)

​
Manual Selection

Explicitly specify who should speak: 
group = GroupChat(
    agents=[agent1, agent2],
    agent_selection_method='manual'
)

messages = [{'role': 'user', 'content': 'Hello'}]

# Specify next speaker
for response in group.run(messages=messages, next_agent='agent1'):
    print(response)

​
Configuration-based Setup

from qwen_agent.agents import GroupChat

config = {
    'background': 'A software development team',
    'agents': [
        {
            'name': 'Developer',
            'description': 'Writes code',
            'instructions': 'You are an experienced Python developer',
            'selected_tools': ['code_interpreter']
        },
        {
            'name': 'Tester',
            'description': 'Tests code',
            'instructions': 'You are a QA engineer who writes tests',
            'selected_tools': ['code_interpreter']
        },
        {
            'name': 'ProductManager',
            'description': 'Defines requirements',
            'instructions': 'You are a product manager',
            'is_human': True  # Human participant
        }
    ]
}

group = GroupChat(
    agents=config,
    agent_selection_method='auto',
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'}
)

​
Human-in-the-Loop

Include human participants: 
from qwen_agent.agents import GroupChat

config = {
    'background': 'Customer support team',
    'agents': [
        {
            'name': 'SupportBot',
            'description': 'AI assistant for common questions',
            'instructions': 'Help customers with common questions'
        },
        {
            'name': 'HumanAgent',
            'description': 'Human support specialist',
            'is_human': True
        }
    ]
}

group = GroupChat(
    agents=config,
    agent_selection_method='auto',
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'}
)

# When HumanAgent is selected, the system will wait for input
messages = [{'role': 'user', 'content': 'I need help with my order'}]

for response in group.run(messages=messages):
    if 'PENDING_USER_INPUT' in str(response):
        # Prompt human for input
        human_input = input('Human Agent: ')
        messages.append({'role': 'user', 'content': human_input, 'name': 'HumanAgent'})
    else:
        print(response)

​
Complete Example: Research Team

from qwen_agent.agents import GroupChat, Assistant

# Create specialized agents
researcher = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Researcher',
    description='Finds and analyzes information using web search',
    function_list=['web_search'],
    system_message='You are a research specialist. Find relevant information and cite sources.'
)

analyst = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Analyst',
    description='Analyzes data and creates visualizations',
    function_list=['code_interpreter'],
    system_message='You are a data analyst. Analyze data and create clear visualizations.'
)

writer = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Writer',
    description='Writes clear, engaging content',
    system_message='You are a technical writer. Create clear, well-structured content.'
)

reviewer = Assistant(
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'},
    name='Reviewer',
    description='Reviews work and provides feedback',
    system_message='You are an editor. Review content for accuracy and clarity.'
)

# Create group
team = GroupChat(
    agents=[researcher, analyst, writer, reviewer],
    agent_selection_method='auto',
    llm={'model': 'qwen-max', 'model_type': 'qwen_dashscope'}
)

# Run collaborative task
messages = [{
    'role': 'user',
    'content': 'Research the growth of renewable energy, analyze trends, and write a report'
}]

for response in team.run(messages=messages):
    agent_name = response[-1].get('name', 'Unknown')
    content = response[-1]['content']
    print(f"\n{agent_name}:\n{content}\n{'-'*50}")

​
Best Practices

  • Give each agent a clear, specific role
  • Use descriptive names and descriptions
  • Provide focused instructions for each agent
  • Limit the number of agents (3-5 recommended)
  • Use auto for complex, dynamic conversations
  • Use round_robin for structured workflows
  • Use random for brainstorming or exploration
  • Use manual for full control
  • More agents = more LLM calls = higher latency
  • Set clear termination conditions
  • Monitor conversation length
  • Use tools strategically across agents

Multi-Agent Guide

Comprehensive multi-agent patterns

Multi-Agent Examples

Complete working examples

Router Agent

Simple agent routing

API Reference

Complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us