Group Chat - swarms

GroupChat creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve problems. Support for various speaker selection strategies and interactive terminal sessions makes it ideal for debate, brainstorming, and complex decision-making.

When to Use

Debate and discussion: Multiple perspectives on complex topics
Collaborative problem-solving: Agents work together through conversation
Brainstorming: Generate ideas through multi-agent interaction
Contract negotiation: Back-and-forth discussion with stakeholders
Interactive sessions: Human-in-the-loop group conversations

Key Features

Multiple speaker selection strategies
@mention support for agent targeting
Interactive REPL terminal sessions
Conversation history tracking
Collaborative response protocols
Dynamic speaker function switching
Time-stamped messages

Basic Example

from swarms import Agent, GroupChat

# Create agents with different perspectives
tech_optimist = Agent(
    agent_name="TechOptimist",
    system_prompt="Argue for the benefits of AI in society.",
    model_name="gpt-5.4",
)

tech_critic = Agent(
    agent_name="TechCritic",
    system_prompt="Argue against unchecked AI advancement.",
    model_name="gpt-5.4",
)

moderator = Agent(
    agent_name="Moderator",
    system_prompt="Moderate the discussion and synthesize viewpoints.",
    model_name="gpt-5.4",
)

# Create group chat
chat = GroupChat(
    name="AI-Ethics-Debate",
    description="Discussion on AI's societal impact",
    agents=[tech_optimist, tech_critic, moderator],
    max_loops=6,  # Number of conversation turns
)

# Run the discussion
result = chat.run(
    "Should we prioritize AI development or AI regulation?"
)
print(result)

Speaker Selection Strategies

Round Robin

Agents speak in order, cycling through the list:

chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="round-robin-speaker",
)

# Execution: agent1 -> agent2 -> agent3 -> agent1 -> ...

Random Speaker

Randomly select one agent per turn:

chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="random-speaker",
)

# Each turn: randomly pick one agent

Priority-Based

Select agents based on priority weights:

chat = GroupChat(
    agents=[expert, analyst, assistant],
    speaker_function="priority-speaker",
    speaker_state={
        "priorities": {
            "expert": 5,
            "analyst": 3,
            "assistant": 1,
        }
    },
)

# Higher priority = more likely to speak

Random Dynamic

First speaker random, then follows @mentions:

chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="random-dynamic-speaker",
    speaker_state={"strategy": "sequential"},  # or "parallel"
)

# Agent can mention others: "I think @agent2 should review this"

@Mention Support

Agents can reference each other using @mentions:

# Agents automatically learn about @mentions
chat = GroupChat(
    agents=[researcher, analyst, writer],
)

# In responses, agents can use:
# "Let me ask @researcher to investigate this further"
# "I agree with @analyst's assessment"
# "@writer can you summarize our findings?"

When using @mentions:

Agents receive collaboration guidelines
Mention instructions added to system prompts
Context about available agents provided

Interactive Terminal Sessions

# Enable interactive mode
chat = GroupChat(
    name="Research-Team",
    agents=[researcher, analyst, writer],
    interactive=True,
)

# Start REPL session
chat.start_interactive_session()

# User can:
# - Type questions and tasks
# - Use @mentions to target specific agents
# - Type 'help' for commands
# - Type 'speaker' to change speaker function
# - Type 'exit' to end session

Interactive commands:

help or ? - Show help menu
exit or quit - End session
speaker - Change speaker selection strategy
@agent_name - Mention specific agents (optional)

Key Parameters

str

default:"GroupChat"

Name for the group chat

str

Description of the group chat’s purpose

List[Agent]

required

List of agents participating in the chat

int

default:"1"

Maximum number of conversation turns

Union[str, Callable]

Speaker selection strategy (“round-robin-speaker”, “random-speaker”, etc.)

dict

Configuration for speaker function (e.g., priorities, strategy)

str

default:"dict"

Output format for conversation history

bool

default:"False"

Enable interactive terminal session

str

Rules to add to conversation context

bool

default:"True"

Include timestamps in messages

Methods

run()

Execute the group chat with a task.

result = chat.run(
    task="Discuss the future of quantum computing",
    img=None,  # Optional image
)

start_interactive_session()

Start an interactive REPL session.

chat = GroupChat(
    agents=agents,
    interactive=True,
)

chat.start_interactive_session()

set_speaker_function()

Dynamically change speaker selection:

chat.set_speaker_function(
    speaker_function="priority-speaker",
    speaker_state={"priorities": {"expert": 5, "novice": 1}},
)

get_available_speaker_functions()

List all available speaker strategies:

functions = chat.get_available_speaker_functions()
print(functions)
# ['round-robin-speaker', 'random-speaker', 'priority-speaker', 'random-dynamic-speaker']

Collaborative Response Protocol

Agents automatically receive collaboration guidelines: Response Structure:

ACKNOWLEDGE: Reference other agents’ contributions
BUILD: Add perspective while building on insights
CONTRIBUTE: Provide unique expertise
COLLABORATE: Use @mentions when needed
COMPLETE: Indicate task status
SYNTHESIZE: Combine insights

Example Good Collaboration:

"I've reviewed @analyst's data analysis and @researcher's market insights. 
The data shows strong growth potential, and I agree with @researcher that we 
should focus on emerging markets. Let me add that from a content perspective, 
we should ask @writer to create targeted messaging. I have completed my market 
analysis. The task now requires @writer to develop content."

Use Cases

Debate System

pro_agent = Agent(agent_name="ProAI", system_prompt="Argue for AI benefits", ...)
con_agent = Agent(agent_name="ConAI", system_prompt="Argue AI risks", ...)
judge = Agent(agent_name="Judge", system_prompt="Evaluate arguments", ...)

debate = GroupChat(
    name="AI-Debate",
    agents=[pro_agent, con_agent, judge],
    max_loops=9,  # 3 rounds each
    speaker_function="round-robin-speaker",
)

verdict = debate.run("Should AI development be regulated?")

Research Collaboration

literature_expert = Agent(agent_name="LitExpert", ...)
data_scientist = Agent(agent_name="DataSci", ...)
statistician = Agent(agent_name="Stats", ...)
writer = Agent(agent_name="Writer", ...)

research_chat = GroupChat(
    name="Research-Collaboration",
    agents=[literature_expert, data_scientist, statistician, writer],
    speaker_function="random-dynamic-speaker",
    speaker_state={"strategy": "sequential"},
)

paper = research_chat.run("Collaborate on research paper about machine learning")

Customer Service Team

technical_support = Agent(agent_name="TechSupport", ...)
billing_specialist = Agent(agent_name="Billing", ...)
product_expert = Agent(agent_name="ProductExpert", ...)
escalation_manager = Agent(agent_name="Manager", ...)

support_team = GroupChat(
    name="Support-Team",
    agents=[technical_support, billing_specialist, product_expert, escalation_manager],
    speaker_function="priority-speaker",
    speaker_state={
        "priorities": {
            "Manager": 5,
            "ProductExpert": 3,
            "TechSupport": 2,
            "Billing": 2,
        }
    },
    interactive=True,
)

support_team.start_interactive_session()

Custom Speaker Functions

def expertise_based_speaker(agents: List[str], last_response: str = "", **kwargs) -> str:
    """Select agent based on expertise keywords in last response"""
    if not last_response:
        return random.choice(agents)
    
    # Check for expertise keywords
    if "technical" in last_response.lower():
        return "TechExpert"
    elif "legal" in last_response.lower():
        return "Lawyer"
    else:
        return random.choice(agents)

chat = GroupChat(
    agents=agents,
    speaker_function=expertise_based_speaker,
)

Conversation Context

Agents receive complete context:

# Each agent sees:
# 1. Group chat name and description
# 2. List of all participants
# 3. @mention instructions
# 4. Collaboration guidelines
# 5. Complete conversation history
# 6. Task completion guidelines

Agent Context Prompt

Automatic prompt augmentation:

# Added to each agent's system prompt:
"""
You are part of a group chat named '{name}' with description: {description}

Other participants:
- @agent1: {description}
- @agent2: {description}

You can mention other agents using @agent_name to request input.

COLLABORATIVE RESPONSE PROTOCOL:
1. FIRST: Read all previous responses
2. ACKNOWLEDGE: Reference other agents' contributions
3. BUILD UPON: Add your perspective
4. MENTION: Use @agent_name when needed
5. COMPLETE: Indicate when done
"""

Sequential vs Parallel Strategies

Sequential Strategy

One mentioned agent responds at a time:

chat = GroupChat(
    agents=agents,
    speaker_function="random-dynamic-speaker",
    speaker_state={"strategy": "sequential"},
)

# If agent says "@agent2 @agent3 please review"
# Executes: agent2 -> agent3

Parallel Strategy

All mentioned agents respond simultaneously:

chat = GroupChat(
    agents=agents,
    speaker_function="random-dynamic-speaker",
    speaker_state={"strategy": "parallel"},
)

# If agent says "@agent2 @agent3 please review"
# Executes: agent2 and agent3 in parallel

Output Formats

# Dictionary format
chat_dict = GroupChat(agents=agents, output_type="dict")

# String format
chat_str = GroupChat(agents=agents, output_type="str")

# List format
chat_list = GroupChat(agents=agents, output_type="list")

Best Practices

Speaker Selection: Match strategy to task - round robin for equal participation, priority for expert weighting

Clear Roles: Give agents distinct perspectives/expertise
Appropriate Length: 4-12 turns typically optimal
Speaker Strategy: Choose based on desired interaction pattern
@Mentions: Enable for targeted collaboration
Max Loops: Balance thoroughness with efficiency

Conversation length grows linearly with agents and turns - monitor context window limits

Interactive Session Example

Welcome to Research-Team!
Description: Collaborative research group

Available agents:
- @Researcher: Expert in research
- @Analyst: Data analysis specialist
- @Writer: Technical writer

Commands:
- Type 'help' or '?' for help
- Type 'exit' or 'quit' to end
- Use @agent_name to mention agents

You: I need help analyzing market data

[Analyst]: I can help with that. Let me analyze the key metrics...
[Researcher]: I'll gather supporting research...
[Writer]: I'll document our findings...

You: @Analyst can you focus on growth trends?

[Analyst]: Focusing on growth trends, I see...

Error Handling

try:
    result = chat.run("Task")
except GroupChatError as e:
    print(f"Chat error: {e}")
except AgentNotFoundError as e:
    print(f"Agent not found: {e}")
    # Mentioned agent doesn't exist
except InvalidSpeakerFunctionError as e:
    print(f"Invalid speaker function: {e}")

Hierarchical Swarm - Structured coordination
Mixture of Agents - Parallel with synthesis
Social Algorithms - Custom communication patterns
Agent Rearrange - Custom flows

​When to Use

​Key Features

​Basic Example

​Speaker Selection Strategies

​Round Robin

​Random Speaker

​Priority-Based

​Random Dynamic

​@Mention Support

​Interactive Terminal Sessions

​Key Parameters

​Methods

​run()

​start_interactive_session()

​set_speaker_function()

​get_available_speaker_functions()

​Collaborative Response Protocol

​Use Cases

​Debate System

​Research Collaboration

​Customer Service Team

​Custom Speaker Functions

​Conversation Context

​Agent Context Prompt

​Sequential vs Parallel Strategies

​Sequential Strategy

​Parallel Strategy

​Output Formats

​Best Practices

​Interactive Session Example

​Error Handling

​Related Architectures

When to Use

Key Features

Basic Example

Speaker Selection Strategies

Round Robin

Random Speaker

Priority-Based

Random Dynamic

@Mention Support

Interactive Terminal Sessions

Key Parameters

Methods

run()

start_interactive_session()

set_speaker_function()

get_available_speaker_functions()

Collaborative Response Protocol

Use Cases

Debate System

Research Collaboration

Customer Service Team

Custom Speaker Functions

Conversation Context

Agent Context Prompt

Sequential vs Parallel Strategies

Sequential Strategy

Parallel Strategy

Output Formats

Best Practices

Interactive Session Example

Error Handling

Related Architectures