Group Chat Example

GroupChat creates an asynchronous, self-selecting room where every agent sees every message and independently decides whether to speak. There is no fixed speaking order — agents chime in only when their self-rated desire to respond clears a threshold. This is ideal for debates, brainstorming, and complex decision-making where you want natural, emergent dialogue rather than a rigid turn order.

This page reflects the current asynchronous GroupChat. The older turn-based design — speaker_function, round-robin/random/priority speakers, @mention routing, and interactive REPL sessions — has been removed. See the GroupChat API reference for the full parameter list.

How Group Chat Works

Seed — the task is broadcast to every agent’s inbox as the first message.
Self-selection — for each message, every agent is asked (via a forced respond(score, message) tool call) how much it wants to speak, on a 0..1 scale.
Threshold — a reply is published only when its score exceeds threshold and the message is non-empty.
Concurrent broadcast — published replies wake every other agent’s inbox at once; multiple agents can react to the same message in parallel.
Stop condition — the chat ends when max_loops total messages have been posted, or no new message arrives for idle_timeout seconds.

Key Characteristics

Asynchronous: agents listen in parallel; there is no global turn order.
Self-selecting: silence is the default — agents only speak when they add value.
Shared context: every agent sees the full transcript before deciding.
Bounded: max_loops caps total messages; idle_timeout ends quiet chats.
Auto-equipped: with auto_equip=True (default), the respond tool is injected into each agent for you.

Key Parameters

Parameter	Purpose
`agents`	Participating agents (at least 2 required).
`max_loops`	Hard cap on total messages posted (the user task counts as the first). Default `20`.
`threshold`	Minimum decision score (`0..1`) to publish a reply. Default `0.5`. Raise for a more selective room.
`idle_timeout`	Seconds of silence before the chat stops. Default `8.0`.
`output_type`	History format. Default `"str-all-except-first"`. Use `"list"` or `"dict"` to iterate messages.
`print_on`	Print each broadcast as a styled panel. Default `True`.
`auto_equip`	Auto-inject the `respond` tool into agents that lack it. Default `True`.

Basic Example: Tech Debate

A two-sided debate about AI’s societal impact. Each agent uses max_loops=1 and persistent_memory=False so every speaking decision is a clean single-shot call.

from swarms import Agent, GroupChat

tech_optimist = Agent(
    agent_name="TechOptimist",
    system_prompt="You argue for the benefits of AI in society.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

tech_critic = Agent(
    agent_name="TechCritic",
    system_prompt="You argue against the unchecked advancement of AI.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

chat = GroupChat(
    agents=[tech_optimist, tech_critic],
    max_loops=8,       # stop after 8 total messages
    threshold=0.5,     # publish replies scoring above 0.5
    idle_timeout=8.0,  # stop after 8s of silence
)

result = chat.run(
    "Let's discuss the societal impact of artificial intelligence."
)
print(result)

By default result is a formatted string (output_type="str-all-except-first"). To iterate over individual messages, set output_type="list":

chat = GroupChat(
    agents=[tech_optimist, tech_critic],
    max_loops=8,
    output_type="list",
)

messages = chat.run("Discuss the societal impact of artificial intelligence.")

for message in messages:
    print(f"[{message['role']}]: {message['content']}")

Each message dict carries role (the agent name, or "User" for the seed task) and content.

Real-World Examples

Business Strategy Discussion

Executives with distinct mandates weigh in only where they have something to add.

from swarms import Agent, GroupChat

ceo = Agent(
    agent_name="CEO",
    system_prompt="Focus on long-term vision, mission, and stakeholder value.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
cfo = Agent(
    agent_name="CFO",
    system_prompt="Focus on financial viability, costs, revenue, and ROI.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
cto = Agent(
    agent_name="CTO",
    system_prompt="Focus on technical feasibility, architecture, and scalability.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
cmo = Agent(
    agent_name="CMO",
    system_prompt="Focus on market positioning, customer needs, and brand impact.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

exec_team = GroupChat(
    agents=[ceo, cfo, cto, cmo],
    max_loops=12,      # room for several rounds of contribution
    threshold=0.6,     # only fairly motivated replies get published
    idle_timeout=12.0,
)

discussion = exec_team.run(
    "Should we pivot from B2C to B2B and rebuild our product for enterprise "
    "customers? This would require 18 months and $5M investment."
)
print(discussion)

Legal Contract Negotiation

from swarms import Agent, GroupChat

buyer_attorney = Agent(
    agent_name="Buyer-Attorney",
    system_prompt="Represent the buyer. Negotiate favorable terms and minimize liability.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
seller_attorney = Agent(
    agent_name="Seller-Attorney",
    system_prompt="Represent the seller. Ensure fair payment and protect IP.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
mediator = Agent(
    agent_name="Mediator",
    system_prompt="Facilitate fair negotiation. Find common ground and propose compromises.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

negotiation = GroupChat(
    agents=[buyer_attorney, seller_attorney, mediator],
    max_loops=14,
    threshold=0.5,
)

contract_discussion = negotiation.run(
    "Negotiate a software licensing agreement. Key issues: payment terms "
    "(buyer wants net-60, seller wants net-30), liability cap (buyer wants $1M, "
    "seller wants $100K), and IP ownership of customizations."
)
print(contract_discussion)

Medical Case Conference

from swarms import Agent, GroupChat

attending = Agent(
    agent_name="Attending-Physician",
    system_prompt="Present the case and synthesize recommendations.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
cardiologist = Agent(
    agent_name="Cardiologist",
    system_prompt="Evaluate from a cardiovascular perspective.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
neurologist = Agent(
    agent_name="Neurologist",
    system_prompt="Evaluate from a neurological perspective.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)
pharmacologist = Agent(
    agent_name="Pharmacologist",
    system_prompt="Evaluate drug interactions and medication recommendations.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

case_conference = GroupChat(
    agents=[attending, cardiologist, neurologist, pharmacologist],
    max_loops=12,
    threshold=0.6,  # specialists stay quiet outside their domain
)

case_discussion = case_conference.run(
    "Patient: 68-year-old male with hypertension and diabetes. Symptoms: severe "
    "headaches, dizziness, BP 180/110, slight confusion. Medications: metformin, "
    "lisinopril, aspirin. Discuss diagnosis and treatment plan."
)
print(case_discussion)

Tuning the Conversation

Because there is no fixed turn order, you shape the conversation with threshold, max_loops, and idle_timeout rather than a speaker function.

A livelier room

# Lower threshold → more agents chime in on each message.
brainstorm = GroupChat(
    agents=[copywriter, art_director, strategist, creative_director],
    max_loops=20,
    threshold=0.4,
    idle_timeout=10.0,
)

A more selective room

# Higher threshold → only strongly-motivated, high-value replies are published.
focused = GroupChat(
    agents=[expert1, expert2, expert3],
    max_loops=10,
    threshold=0.75,
    idle_timeout=15.0,  # give agents time to deliberate
)

Bounding total length

max_loops is the primary cost control — it caps the total number of messages posted (the seed task included), not the turns per agent.

# At most 6 messages total, then the chat stops.
quick = GroupChat(agents=[proponent, opponent], max_loops=6)

Best Practices

1. Give each agent a distinct, specific role

# Good: a specific perspective the agent can defend.
agent = Agent(
    agent_name="Privacy-Advocate",
    system_prompt="You are a privacy advocate. Always weigh data protection, "
                  "consent, and privacy implications.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

Distinct roles make the respond decision meaningful — agents speak inside their lane and stay quiet outside it.

2. Use `max_loops=1` and `persistent_memory=False` per agent

Each participating agent should make a clean, single-shot decision per message. Stateful memory across decisions can distort the speaking score.

3. Tune `threshold` to the room size

Few agents (2–3): a lower threshold (~0.4–0.5) keeps the dialogue flowing.
Many agents (4+): raise it (~0.6–0.75) so the room doesn’t pile on every message.

4. Set `idle_timeout` to match thinking time

Raise it when models need longer to reason; lower it to end quiet chats faster.

5. Choose the right `output_type`

"str-all-except-first" (default) — a single readable transcript string.
"list" / "dict" — structured messages you can iterate (role, content).

When to Use Group Chat

Ideal for:

Debates and discussions — exploring opposing viewpoints.
Collaborative decision-making — stakeholders converging on consensus.
Brainstorming — emergent ideas from parallel contributions.
Negotiation — parties working toward agreement.
Peer review — evaluating work from multiple angles.

When NOT to Use Group Chat

Simple tasks — the coordination overhead isn’t justified (use a single Agent).
Independent analysis — when agents shouldn’t influence each other (use ConcurrentWorkflow).
Strict ordering — when a fixed sequence is required (use SequentialWorkflow).
Hierarchical coordination — when a director must delegate (use HierarchicalSwarm).

Comparison with Other Patterns

Pattern	Interaction Style	Best For
GroupChat	Asynchronous, self-selecting dialogue	Debates, brainstorms, negotiations
MixtureOfAgents	Parallel → synthesis	Combining expert analyses
HierarchicalSwarm	Director → workers	Project coordination
SequentialWorkflow	Linear pipeline	Step-by-step processes
ConcurrentWorkflow	Independent parallel	Multi-perspective analysis

MixtureOfAgents: parallel experts with synthesis
HierarchicalSwarm: director-worker coordination
ConcurrentWorkflow: independent parallel execution

Index

Basic Examples

Model Providers

Single Agent

Multi-Agent Examples

Auto Agent Builder

Scheduled Agents

Applications

Research

Technical Analysis

Use Cases

Finance

Voice Agents

Integrations

MCP Tool Integrations

Deployment

CLI

Group Chat Example

How Group Chat Works

Key Characteristics

Key Parameters

Basic Example: Tech Debate

Real-World Examples

Business Strategy Discussion

Legal Contract Negotiation

Medical Case Conference

Tuning the Conversation

A livelier room

A more selective room

Bounding total length

Best Practices

1. Give each agent a distinct, specific role

2. Use `max_loops=1` and `persistent_memory=False` per agent

3. Tune `threshold` to the room size

4. Set `idle_timeout` to match thinking time

5. Choose the right `output_type`

When to Use Group Chat

When NOT to Use Group Chat

Comparison with Other Patterns

Learn More

​How Group Chat Works

​Key Characteristics

​Key Parameters

​Basic Example: Tech Debate

​Real-World Examples

​Business Strategy Discussion

​Legal Contract Negotiation

​Medical Case Conference

​Tuning the Conversation

​A livelier room

​A more selective room

​Bounding total length

​Best Practices

​1. Give each agent a distinct, specific role

​2. Use max_loops=1 and persistent_memory=False per agent

​3. Tune threshold to the room size

​4. Set idle_timeout to match thinking time

​5. Choose the right output_type

​When to Use Group Chat

​When NOT to Use Group Chat

​Comparison with Other Patterns

​Related Architectures

​Learn More

How Group Chat Works

Key Characteristics

Key Parameters

Basic Example: Tech Debate

Real-World Examples

Business Strategy Discussion

Legal Contract Negotiation

Medical Case Conference

Tuning the Conversation

A livelier room

A more selective room

Bounding total length

Best Practices

1. Give each agent a distinct, specific role

2. Use `max_loops=1` and `persistent_memory=False` per agent

3. Tune `threshold` to the room size

4. Set `idle_timeout` to match thinking time

5. Choose the right `output_type`

When to Use Group Chat

When NOT to Use Group Chat

Comparison with Other Patterns

Related Architectures

Learn More