Group Chat Example

GroupChat runs a turn-based, self-selecting discussion. Every agent sees the whole conversation, and each turn every agent privately bids on whether to speak. The single highest bidder above a threshold takes the floor, and only its reply is posted. There is no fixed speaking order: who speaks emerges from the bids, and a recency penalty keeps one agent from monologuing. This suits debates, brainstorming, and decision-making where you want natural dialogue rather than a rigid rotation.

The older design (a speaker_function, round-robin/random/priority speakers, @mention routing, interactive REPL sessions, and an asynchronous room where several agents could post at once) has been removed. See the GroupChat API reference for the full parameter list.

How Group Chat Works

Seed: the task is posted to the shared conversation as the first message.
Bidding: each turn, every agent is asked concurrently (through a forced respond(score, message) tool call) how much it wants to speak on a 0..1 scale, along with the reply it would give.
Recency penalty: agents that spoke within the last recency_window turns have recency_penalty subtracted from their score.
One speaker: the highest adjusted bid that carries a non-empty reply and exceeds threshold wins the turn. Only that reply is posted.
Stop condition: the chat ends at the first lull (a turn where no agent clears threshold), or once max_loops total messages have been posted.

Key Characteristics

Turn-based: exactly one agent speaks per turn; bids are collected in parallel.
Self-selecting: each agent scores how useful a reply would be right now, and low-value replies (filler agreement, repeated points) are told to score low.
Shared context: every agent sees the full transcript before bidding.
Bounded: max_loops caps total messages, and a lull ends the chat early.
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 recency-adjusted score (`0..1`) needed to take the floor. A turn where nobody clears it ends the chat. Default `0.5`.
`recency_penalty`	Subtracted from the bid of an agent that spoke recently. Default `0.3`; `0.0` disables it.
`recency_window`	How many of the most recent speakers the penalty applies to. Default `1`.
`output_type`	History format. Default `"str-all-except-first"`. Use `"list"` or `"dict"` to iterate messages.
`verbose`	Log internals and print each posted message as a panel. Default `False`.
`auto_equip`	Auto-inject the `respond` tool into agents that lack it. Default `True`.

idle_timeout is still accepted for compatibility but is unused: the chat now ends on a bidding lull, not a wall-clock timeout.

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,  # a reply must score above 0.5 to take the floor
)

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
)

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, recency_penalty, and max_loops rather than a speaker function.

A livelier room

# Lower threshold: more turns find a speaker, so the chat runs longer.
brainstorm = GroupChat(
    agents=[copywriter, art_director, strategist, creative_director],
    max_loops=20,
    threshold=0.4,
)

A more selective room

# Higher threshold: only strongly motivated replies take the floor, and the chat ends sooner.
focused = GroupChat(
    agents=[expert1, expert2, expert3],
    max_loops=10,
    threshold=0.75,
)

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 bid meaningful: agents bid high 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; a high one ends the chat at the first lull.
Many agents (4+): raise it (~0.6–0.75) so only the most relevant speaker takes each turn.

4. Tune `recency_penalty` for back-and-forth

The default 0.3 makes the last speaker less likely to win the next turn. Raise it to force more rotation, or set 0.0 to let a strongly motivated agent reply twice in a row.

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 whoever has the most to add.
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	Turn-based, 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

​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. Tune recency_penalty for back-and-forth

​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. Tune `recency_penalty` for back-and-forth

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