Group Chat

GroupChat runs a turn-based, self-selecting conversation: there is no fixed speaking order and no speaker-selection function, but exactly one agent speaks per turn. Each turn, every agent privately “bids” — via a forced respond(score, message) tool call — on how much it wants the floor; the single highest (recency-adjusted) bidder above threshold speaks, and only that reply is posted. A recency_penalty discourages the same agent from speaking twice in a row, so the floor moves around the room even though there’s no explicit rotation.

When to Use

Debate and discussion: multiple perspectives on a complex topic
Collaborative problem-solving: agents build on each other through conversation
Brainstorming: emergent ideas from parallel contributions
Negotiation: back-and-forth between stakeholders
Peer review: evaluating work from several angles at once

This is a rewrite of the older speaker-function design. speaker_function, speaker_state, set_speaker_function, start_interactive_session, @mention routing, and the round-robin-speaker / random-speaker / priority-speaker selectors no longer exist. Use threshold / recency_penalty / max_loops to shape the conversation instead. See the GroupChat API reference.

How It Works

Seed — the task is posted to the shared conversation as the first message; every agent sees it.
Bid (in parallel) — each turn, every agent is asked concurrently (via 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.
Select one speaker — the single highest recency-adjusted bidder that clears threshold and has a non-empty reply takes the floor. Only that one reply is posted to the conversation for this turn.
Recency penalty — an agent that spoke within the last recency_window turns has recency_penalty subtracted from its bid, so the floor tends to move around the room instead of one agent monologuing.
Stop — the chat ends when max_loops total messages have been posted, or a turn arrives where no agent’s adjusted bid clears threshold (a conversational lull).

idle_timeout is accepted for backward compatibility but is currently unused — the chat stops on a bidding lull (step 5 above), not a wall-clock timeout.

Key Features

Turn-based self-selection: bids are collected in parallel, but exactly one agent speaks per turn (no fixed speaking order)
Self-selection: silence is the default; agents speak only when they add value
Forced respond(score, message) decision via RESPOND_TOOL
Threshold-based speaker selection with a recency penalty to rotate the floor
Auto-equips the respond tool into agents (auto_equip=True)
Conversation history tracking and flexible output formats

Basic Example

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 unchecked AI advancement.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

realist = Agent(
    agent_name="Realist",
    system_prompt="You weigh both sides and seek a balanced view.",
    model_name="gpt-5.4",
    max_loops=1,
    persistent_memory=False,
)

chat = GroupChat(
    name="AI-Ethics-Debate",
    description="Discussion on AI's societal impact",
    agents=[tech_optimist, tech_critic, realist],
    max_loops=8,          # hard cap on total messages
    threshold=0.5,        # only the top bidder above 0.5 takes the floor each turn
    recency_penalty=0.3,  # discourage the same agent speaking twice in a row
)

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

auto_equip=True (the default) injects the respond tool into each agent, so you do not need to add tools_list_dictionary=[RESPOND_TOOL] yourself.

Shaping the Conversation

There is no speaker function — you steer the room with three parameters.

Threshold

# Livelier: more agents chime in on each message.
lively = GroupChat(agents=agents, max_loops=20, threshold=0.4)

# More selective: only strongly-motivated, high-value replies are published.
focused = GroupChat(agents=agents, max_loops=12, threshold=0.75)

Recency penalty

# Rotate the floor more aggressively so no agent can speak twice in a row.
rotating = GroupChat(agents=agents, max_loops=16, recency_penalty=0.5, recency_window=1)

# Allow an agent to keep the floor across consecutive turns if it keeps winning bids.
persistent = GroupChat(agents=agents, max_loops=16, recency_penalty=0.0)

Max loops (total messages)

max_loops caps the total number of messages posted (the seed task counts as the first), not turns per agent — it’s the primary cost control.

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

Key Parameters

str

default:"dynamic-groupchat"

Name for the group chat.

str

default:"Agents take turns; one speaker per turn."

Description of the group chat’s purpose.

List[Agent]

required

Participating agents. At least two are required — each message is broadcast to the other agents.

int

default:"20"

Hard cap on total messages posted, including the initial user task.

float

default:"0.5"

Minimum recency-adjusted decision score (0..1) required for an agent to take the floor for a turn.

float

default:"0.3"

Amount subtracted from an agent’s bid if it spoke within the last recency_window turns. Discourages one agent from monologuing; set to 0.0 to disable.

int

default:"1"

How many of the most recent speakers are subject to recency_penalty.

float

default:"8.0"

Accepted for backward compatibility but currently unused — the chat now stops on a bidding lull (no agent clears threshold) rather than a wall-clock timeout.

str

default:"str-all-except-first"

History format. Use "list" or "dict" to iterate individual messages.

bool

default:"True"

Auto-inject the respond tool into agents that lack it.

bool

default:"False"

Emit internal log messages (decision scores, broadcasts, stop events) and print each posted message as a styled panel.

Methods

run()

Run the group chat until no agent’s bid clears threshold (a lull) or max_loops is hit.

result = chat.run("Discuss the future of quantum computing")

By default the result is a formatted string. For per-message iteration, set output_type="list" and read role / content:

chat = GroupChat(agents=agents, max_loops=8, output_type="list")
for message in chat.run("Discuss the tradeoffs of multi-agent systems."):
    print(f"[{message['role']}]: {message['content']}")

run_batch()

Run several independent group chats sequentially, one per task.

results = chat.run_batch([
    "Topic A to discuss",
    "Topic B to discuss",
])

The `respond` Tool

Every agent must carry RESPOND_TOOL so the chat can force a structured speaking decision. With auto_equip=True this is automatic; otherwise add it yourself:

from swarms import Agent
from swarms.structs.groupchat import GroupChat, RESPOND_TOOL

agents = [
    Agent(
        agent_name=name,
        system_prompt=prompt,
        model_name="gpt-5.4",
        max_loops=1,
        persistent_memory=False,
        tools_list_dictionary=[RESPOND_TOOL],
    )
    for name, prompt in [
        ("Researcher", "You contribute research and evidence."),
        ("Critic", "You stress-test claims and find weaknesses."),
    ]
]

chat = GroupChat(agents=agents, auto_equip=False, max_loops=8)
result = chat.run("Debate the tradeoffs of autonomous agents.")

The tool forces a call to respond(score, message): score (0..1) is how much the agent wants to speak, and message is the reply (empty string to stay silent). Each turn, only the single agent with the highest recency-adjusted score above threshold gets its message published.

Use Cases

Debate

pro = Agent(agent_name="Pro", system_prompt="Argue for the motion.",
            model_name="gpt-5.4", max_loops=1, persistent_memory=False)
con = Agent(agent_name="Con", system_prompt="Argue against the motion.",
            model_name="gpt-5.4", max_loops=1, persistent_memory=False)
moderator = Agent(agent_name="Moderator", system_prompt="Summarize and find common ground.",
                  model_name="gpt-5.4", max_loops=1, persistent_memory=False)

debate = GroupChat(
    name="AI-Debate",
    agents=[pro, con, moderator],
    max_loops=10,
    threshold=0.5,
)
verdict = debate.run("Should AI development be regulated?")

Expert Panel

research_chat = GroupChat(
    name="Research-Collaboration",
    agents=[literature_expert, data_scientist, statistician, writer],
    max_loops=14,
    threshold=0.6,  # specialists stay quiet outside their domain
)
paper = research_chat.run("Collaborate on a paper about machine learning.")

Best Practices

Tuning over speaker functions: shape participation with threshold (selectivity), recency_penalty (how aggressively the floor rotates), and max_loops (total length) — there is no speaker-selection function.

Distinct roles: give each agent a specific perspective so its respond decision is meaningful.
max_loops=1 + persistent_memory=False per agent: keep each speaking decision a clean single-shot call.
Tune threshold to room size: lower (~0.4–0.5) for 2–3 agents, higher (~0.6–0.75) for 4+.
Pick the right output_type: a transcript string by default, or "list"/"dict" to iterate messages.

Conversation length grows with agents and turns — use max_loops to bound total messages and watch context limits.

When NOT to Use

Simple tasks — 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.
Director-led delegation — use HierarchicalSwarm.

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

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

When to Use

How It Works

Key Features

Basic Example

Shaping the Conversation

Threshold

Recency penalty

Max loops (total messages)

Key Parameters

Methods

run()

run_batch()

The `respond` Tool

Use Cases

Debate

Expert Panel

Best Practices

When NOT to Use

​When to Use

​How It Works

​Key Features

​Basic Example

​Shaping the Conversation

​Threshold

​Recency penalty

​Max loops (total messages)

​Key Parameters

​Methods

​run()

​run_batch()

​The respond Tool

​Use Cases

​Debate

​Expert Panel

​Best Practices

​When NOT to Use

​Related Architectures

When to Use

How It Works

Key Features

Basic Example

Shaping the Conversation

Threshold

Recency penalty

Max loops (total messages)

Key Parameters

Methods

run()

run_batch()

The `respond` Tool

Use Cases

Debate

Expert Panel

Best Practices

When NOT to Use

Related Architectures