> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarms.world/llms.txt > Use this file to discover all available pages before exploring further. # GroupChat Internals: A Technical Analysis > A deep technical analysis of the turn-based, self-selecting GroupChat module — bidding mechanics, speaker selection, and termination behavior A deep dive into the architecture and formal behavior of the turn-based, self-selecting `GroupChat` module. ## Overview The `GroupChat` module (`swarms/structs/groupchat.py`) implements a *turn-based, self-selecting* group conversation among autonomous language-model agents. Unlike round-robin schemes, where an orchestrator picks who talks next from a fixed rotation, `GroupChat` has no fixed speaking order. Every turn, every agent privately rates how much it wants to reply; the single agent with the highest (recency-adjusted) desire above a threshold takes the floor, and only its message is posted. Everyone else stays silent for that turn. The class docstring states this precisely: "Each turn every agent privately bids on whether to speak; the single highest (recency-adjusted) bidder above `threshold` takes the floor and its reply is the only message posted." This document explains exactly how that bidding, selection, and termination work, grounding every claim in the function that implements it, and closes with a complete, runnable program against the real constructor. The design goal is worth stating plainly. Most multi-agent chat frameworks impose coordination from the outside: a controller computes a speaking order, or a manager agent nominates the next speaker. `GroupChat` instead asks every agent, every turn, "do you want the floor?" and lets the room self-select one speaker. It mirrors human turn-taking — everyone listens, the most motivated or relevant participant jumps in, the rest stay quiet unless they have something better to add next time. *** ## Architecture ### Execution is sequential, not an actor system `GroupChat` runs on a single event loop and has exactly one shared mutable piece of state: `self.conversation`, a plain `Conversation` object created once in `__init__`. There are no per-agent mailboxes and no background monitor task. The module's own comment on `_post` says it directly: "There are no per-agent inboxes: every agent reads the same `Conversation` when it builds its next bid, so a single append makes the message visible to everyone the following turn." The only concurrency in the whole runtime is *within* a single turn, and it exists purely to hide LLM latency, not to let agents post independently. Each turn, in `_collect_bids`, every agent's decision call is dispatched to a worker thread and awaited together: ```python theme={null} async def _collect_bids(self, sender, message): results = await asyncio.gather( *( asyncio.to_thread(self._decide_sync, agent, sender, message) for agent in self.agents ) ) return [ (agent, score, reply) for agent, (score, reply) in zip(self.agents, results) ] ``` All `N` decisions run in parallel so one slow model call doesn't stall the turn, but the function returns a plain list of `(agent, score, reply)` bids back to the single coroutine driving the loop. Exactly one of them is ever posted (see `_select_speaker` below). Because every mutation of `self.conversation` happens on that one coroutine — never inside a worker thread — there is no race to guard against and no lock anywhere in the module. ### The respond protocol The central design problem is making a *speaking decision* machine-readable. `GroupChat` forces every agent to emit a structured decision through a function-calling schema, `RESPOND_TOOL`: ```python theme={null} RESPOND_TOOL = { "type": "function", "function": { "name": "respond", "description": ( "Decide whether to reply in the groupchat. Set score 0..1 for how much " "you want to speak. If you don't want to speak, set message to empty string." ), "parameters": { "type": "object", "properties": { "score": {"type": "number", "minimum": 0, "maximum": 1}, "message": {"type": "string"}, }, "required": ["score", "message"], }, }, } ``` The agent returns a pair — a **score** in `[0, 1]` for how much it wants to speak, and the **message** it would post. Forcing a function call rather than parsing prose guarantees a typed payload, separates the *decision* (score) from the *content* (message), and gives the model a low-friction way to abstain by returning an empty string. `_ensure_respond_tool` auto-injects this schema into any agent missing it, gated by the `auto_equip` constructor flag (default `True`): ```python theme={null} def _ensure_respond_tool(self) -> None: for agent in self.agents: tools = agent.tools_list_dictionary or [] if any( tool.get("function", {}).get("name") == "respond" for tool in tools if isinstance(tool, dict) ): continue agent.tools_list_dictionary = [*tools, RESPOND_TOOL] agent.llm = agent.llm_handling() ``` The rebuild via `agent.llm_handling()` is necessary because the agent's LLM client bakes its tool list in at construction time; appending to `tools_list_dictionary` afterwards would otherwise have no effect until the client is regenerated. If `auto_equip=False` and an agent never receives `RESPOND_TOOL` some other way, its replies won't parse as a tool call and it will bid `(0.0, "")` — silent — every turn (see `_extract_args` below). The decision prompt, `GROUPCHAT_DECIDE_PROMPT`, is deliberately biased toward silence: "Silence is the default — most messages do NOT warrant a reply from you." It scores high only for direct expertise, being addressed by name, a correctable error, or a concrete next step, and scores low for off-topic remarks, redundant points, filler agreement, or speaking again right after having just spoken. ### One decision call per agent, with full typed history `_decide_sync` is what each worker thread actually runs. It formats the decide prompt with the latest posted message, then calls the agent with the *entire* shared conversation rendered as typed chat turns (the agent's own prior posts become `assistant` turns, everyone else's become `user` turns) via `messages_for`: ```python theme={null} def _decide_sync(self, agent, sender, message): prompt = GROUPCHAT_DECIDE_PROMPT.format( agent_name=agent.agent_name, other_agents=self._other_agents(agent.agent_name), sender=sender, message=message, ) try: tool_output = agent.run( task=prompt, messages=messages_for(agent.agent_name, self.conversation), ) except Exception as e: logger.warning(f"[{self.name}] {agent.agent_name} failed to bid: ...") return 0.0, "" return _extract_args(tool_output) ``` A raised exception — a bad `model_name`, a missing API key, a model without function-calling support — is caught and degraded to the silent bid `(0.0, "")` rather than crashing the turn. That makes a broken agent indistinguishable, from the outside, from an agent that simply chose not to speak — which is exactly why `_run_async` special-cases the very first turn (below) to warn loudly if *every* agent stays silent immediately. `_extract_args` is the total function that turns raw provider output into a clean `(score, message)` pair. It handles the shapes different providers return — a bare dict, a list of tool calls, a stringified repr, a pydantic object — and on any unparseable input falls back to the same silent decision `(0.0, "")`, clamping any parsed score into `[0, 1]` and stripping the message. ### `_select_speaker`: a strict, recency-adjusted argmax This is the only place that decides who speaks: ```python theme={null} def _select_speaker(self, bids, recent): best = None best_adjusted = self.threshold for agent, score, reply in bids: if not reply: continue adjusted = score if agent.agent_name in recent: adjusted -= self.recency_penalty if adjusted <= best_adjusted: continue best_adjusted = adjusted best = (agent, score, reply) return best ``` Three exact, code-level facts fall out of this: 1. **Empty replies never win**, regardless of score — `if not reply: continue` is checked before anything else. 2. **The bar is strict.** `best_adjusted` starts at `self.threshold`, and only a bid with `adjusted > best_adjusted` overwrites it. A score that exactly equals `threshold` never wins, and ties keep whichever agent was checked first — selection is a deterministic function of `self.agents` order, not random tie-breaking. 3. **The winner's *raw* score is what gets posted**, not the recency-adjusted one — the tuple stored is `(agent, score, reply)`, using the unadjusted `score`. `recency_penalty` only affects *who* wins, never the score value later attached to the posted message's metadata. `recent` is a `set` built from a `deque(maxlen=max(1, self.recency_window))` of the last speakers' names, so `recency_window <= 0` still behaves like a window of `1` — the only way to fully disable the rotation effect is `recency_penalty=0.0`. A direct consequence of the arithmetic: for an agent to win two turns in a row (with the default `recency_window=1`), its raw score on the second turn must satisfy `score > threshold + recency_penalty`, not just `score > threshold`. The penalty raises the bar specifically for whoever just spoke, which is what keeps the floor moving around the room instead of one agent monopolizing it. ### `_post`: one append, optionally chunked to a callback ```python theme={null} def _post(self, sender, content, score, streaming_callback=None): if streaming_callback is not None: self._stream_reply(sender, content, streaming_callback) metadata = {"score": score} if score is not None else None self.conversation.add(role=sender, content=content, metadata=metadata) ... ``` The seed task is posted with `score=None`; every agent turn is posted with its raw bid score. `verbose=True` also prints each posted message as a panel. Because a turn's reply is generated atomically inside the bid call — the whole message already exists before `_post` runs — `streaming_callback` can't stream real tokens. `_stream_reply` instead chunks the finished text on whitespace and replays it word-by-word, ending with an `is_final=True` sentinel, so callers get the same `(agent_name, chunk, is_final)` streaming signature used by `SequentialWorkflow` and `AgentRearrange`. *** ## The turn loop and its two termination conditions `_run_async` is the entire runtime: ```python theme={null} async def _run_async(self, task, streaming_callback=None): self._post(sender="User", content=task, score=None, streaming_callback=streaming_callback) last_sender, last_message = "User", task recent = deque(maxlen=max(1, self.recency_window)) message_count = 1 # the user task counts as the first message while message_count < self.max_loops: bids = await self._collect_bids(last_sender, last_message) selection = self._select_speaker(bids, set(recent)) if selection is None: break # lull agent, score, reply = selection self._post(sender=agent.agent_name, content=reply, score=score, streaming_callback=streaming_callback) recent.append(agent.agent_name) last_sender, last_message = agent.agent_name, reply message_count += 1 return history_output_formatter(conversation=self.conversation, type=self.output_type) ``` **Proposition (message count is bounded, deterministically).** The seed counts as message `1`. The `while` guard is `message_count < self.max_loops`, and the only way `message_count` changes is `+= 1`, exactly once, on a turn that produces a winner; every other path is `break`. So for any single call to `run()`, the number of posted messages `|H|` satisfies `1 <= |H| <= self.max_loops`, with equality on the upper bound only if every turn up to the cap produced a winner. This follows directly from the loop structure — no timing or probability argument is needed. There are exactly two ways the loop ends, and both are real, current code paths: 1. **The hard cap.** `message_count` reaches `max_loops` and the `while` condition fails. `max_loops` counts the seed, so at most `max_loops - 1` agent turns can occur. 2. **A bidding lull.** `_select_speaker` returns `None` for a turn — no agent's recency-adjusted, non-empty bid cleared `threshold`. The loop `break`s immediately, regardless of how far `message_count` is from the cap. `idle_timeout` plays no role in either path. The constructor keeps the parameter and documents it as "Deprecated/unused — the chat now ends on a bidding lull rather than a wall-clock timeout. Kept for compatibility." It is never read anywhere in `_run_async`, `_select_speaker`, or `_post`. **How `recency_penalty` can trigger termination condition 2 on its own.** Because the bar in `_select_speaker` is applied to the *adjusted* score, a turn can go from "someone wants to speak" to a lull purely because of who spoke last. If the only agent whose raw score clears `threshold` is also in `recent`, and `raw_score - recency_penalty <= threshold`, then `_select_speaker` returns `None` even though a raw bid existed above the bar. Raising `recency_penalty` therefore does two things at once: it forces rotation among speakers, and it makes lulls (termination condition 2) more likely whenever only one agent currently has something to say. **How `threshold` shapes both the speaker distribution and termination.** Raising `threshold` shrinks the set of bids that can ever win a turn, which has two effects that follow directly from the code: fewer agents qualify to speak at all (a more selective room), and a lull (condition 2) becomes more likely on any given turn, since more turns will have no bid clearing the raised bar. There is no branching or fan-out to reason about — each turn independently checks the same `adjusted > threshold` condition. ### A simplifying model for expected conversation length This is presented as an approximation for intuition, not a claim about the code's exact joint distribution — `recency_penalty` and the evolving transcript make consecutive turns dependent on each other, and the real bid distribution depends on the LLM. If we idealize each turn after the seed as an i.i.d. Bernoulli trial that "succeeds" (produces a winner) with some fixed probability `q` — the probability that at least one agent's adjusted, non-empty bid clears `threshold` — then the number of successful turns before the first lull follows a geometric distribution, truncated at `max_loops - 1` turns by the hard cap. Under that idealization, the expected number of posted messages is approximately ``` E[|H|] ≈ min(1 / (1 - q), max_loops) ``` A room tuned so `q` is small (a high `threshold`, or a decide prompt biased toward silence, which `GROUPCHAT_DECIDE_PROMPT` already is) ends quickly on its own via a lull. A room tuned so `q` is close to `1` will tend to run all the way to `max_loops`, since a lull becomes rare. This matches the two real termination conditions exactly — it's just a way to reason about which one is likely to fire first for a given configuration. *** ## Constructor reference `GroupChat.__init__` accepts exactly these parameters: | Parameter | Default | Effect | | ----------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | `name` | `"dynamic-groupchat"` | Name used in logs and serialized state. | | `description` | `"Agents take turns; one speaker per turn."` | Stored, not otherwise used by the runtime. | | `agents` | `None` | List of `Agent` instances. **Must contain at least 2** — fewer raises `ValueError`. | | `max_loops` | `20` | Hard cap on total posted messages, including the seed. | | `threshold` | `0.5` | Minimum recency-adjusted score required to take the floor. | | `recency_penalty` | `0.3` | Subtracted from the bid of an agent that spoke within the last `recency_window` turns. `0.0` disables it. | | `recency_window` | `1` | How many recent speakers are penalized. Effective minimum is `1` regardless of a lower value. | | `idle_timeout` | `8.0` | **Deprecated/unused.** Accepted for backward compatibility only; has no effect on when the chat stops. | | `output_type` | `"str-all-except-first"` | Passed through to `history_output_formatter`. | | `verbose` | `False` | Log internal messages and print each posted message as a panel. | | `auto_equip` | `True` | Auto-inject `RESPOND_TOOL` into any agent that doesn't already carry it. | `run(task, streaming_callback=None)` runs one conversation synchronously (`asyncio.run(self._run_async(...))`) and returns the transcript formatted per `output_type`. `run_batch(tasks)` calls `batched_run(self.run, tasks)`, which — with no `max_workers` passed — runs the tasks **sequentially**, one full `run()` call after another. This matters beyond throughput: `self.conversation` is created once in `__init__` and is never reset between calls to `run()`. Every task in a batch is posted into the *same* growing `Conversation` object, so agents deciding on task 2 will see the full transcript of task 1 in their history (via `messages_for`) as well. `message_count` itself is a local variable that resets to `1` on every `_run_async` call, so `max_loops` still caps each task's own turns — but the conversational context is not isolated between tasks. Construct a fresh `GroupChat` per task if isolation is required. *** ## Practical implications * **Provide at least two agents.** Fewer raises `ValueError` at construction (`GroupChat requires at least 2 agents.`). * **Let `auto_equip` do its job, or equip agents yourself.** An agent without `RESPOND_TOOL` in `tools_list_dictionary` will bid `(0.0, "")` every turn — permanently silent — because `_extract_args` can't parse a non-tool-call response into a decision. * **`idle_timeout` does nothing.** Don't tune it expecting to control when the chat stops; only `max_loops` and the bidding lull do that. * **`max_loops` counts the seed.** A chat configured with `max_loops=10` gets at most 9 agent turns. * **Raise `threshold` for a more selective, shorter-running room; raise `recency_penalty` to force rotation** — but know that a high `recency_penalty` can itself end the chat early by turning a would-be winner into a lull. * **`run_batch` shares one conversation across tasks.** Build a new `GroupChat` per independent task unless carrying context between tasks is intended. * **A silent room on the very first turn usually means misconfiguration, not a design choice.** `_run_async` specifically logs a loud warning if no agent produces any reply on turn one, calling out a bad `model_name`, a missing API key, or a model without function-calling support as likely causes. Run with `verbose=True` to see each bid. * **The metadata score on a posted message is the raw bid**, not the recency-adjusted score that actually won the turn — inspect `chat.conversation.conversation_history` if you need the exact value that determined selection versus the value stored for display. *** ## Complete worked example The following program builds a four-agent room, runs a discussion, and inspects the result. It is fully runnable once an LLM API key is set in the environment. ```python theme={null} """ GroupChat end-to-end example. Prereqs: pip install swarms export OPENAI_API_KEY="sk-..." # or any LiteLLM-supported provider """ from swarms import Agent from swarms.structs.groupchat import GroupChat, RESPOND_TOOL def build_panel(): """Construct four specialists for a turn-based discussion. Each agent carries RESPOND_TOOL explicitly so it can emit the structured (score, message) bid the chat uses to select a speaker each turn. We also set max_loops=1 and persistent_memory=False so every decision call is cheap and stateless; the GroupChat transcript is the only shared context (auto_equip=True on the GroupChat itself is a safety net in case any agent were missing the tool). """ common = dict( model_name="gpt-5.4", max_loops=1, persistent_memory=False, tools_list_dictionary=[RESPOND_TOOL], ) optimist = Agent( agent_name="Optimist", system_prompt=( "You are a technology optimist. You argue for the upside and the " "opportunities. Speak only when you can add a concrete benefit that " "has not already been raised." ), **common, ) skeptic = Agent( agent_name="Skeptic", system_prompt=( "You are a risk-focused skeptic. You surface failure modes, hidden " "costs, and weak assumptions. Speak only to sharpen or correct a " "claim, not merely to disagree." ), **common, ) economist = Agent( agent_name="Economist", system_prompt=( "You are an economist. You analyze incentives, markets, and labor " "effects. Speak only when an economic angle is missing from the " "discussion." ), **common, ) ethicist = Agent( agent_name="Ethicist", system_prompt=( "You are an ethicist. You raise fairness, consent, and accountability " "concerns. Speak only when a concrete ethical issue is at stake." ), **common, ) return [optimist, skeptic, economist, ethicist] def main(): agents = build_panel() chat = GroupChat( name="ai-impact-room", description="Turn-based discussion on the societal impact of advanced AI.", agents=agents, max_loops=12, # hard cap on total posted messages, seed included threshold=0.6, # min (recency-adjusted) score to take the floor recency_penalty=0.3, # subtracted from a recent speaker's next bid recency_window=1, # only the immediately preceding speaker is penalized output_type="str-all-except-first", verbose=True, # emit internal log lines and print each turn auto_equip=True, # inject RESPOND_TOOL into any agent missing it ) task = ( "Should advanced AI systems be allowed to make autonomous decisions in " "high-stakes domains such as healthcare and criminal justice? Discuss the " "tradeoffs." ) transcript = chat.run(task) print("\n" + "=" * 70) print("FINAL TRANSCRIPT") print("=" * 70) print(transcript) # Inspect structured history directly off the conversation object. Each # posted turn stores the winning agent's raw bid score in its metadata. print("\n" + "=" * 70) print("PER-MESSAGE SCORES") print("=" * 70) for msg in chat.conversation.conversation_history: role = msg.get("role") meta = msg.get("metadata") or {} score = meta.get("score") tag = "seed" if score is None else f"score={score:.2f}" content = str(msg.get("content", "")) preview = content[:80].replace("\n", " ") print(f"[{role:<10}] ({tag}) {preview}") def batch_example(): """Run several discussions via run_batch. run_batch calls batched_run(self.run, tasks) with no max_workers, so tasks run sequentially. GroupChat never resets self.conversation between calls to run(), so both tasks below are appended to the SAME transcript — agents answering the second task will see the first task's discussion too. Build a new GroupChat per task if that isolation matters to you. """ agents = build_panel() chat = GroupChat(agents=agents, max_loops=10, threshold=0.6) tasks = [ "Will open-source models overtake closed models by 2030?", "Is universal basic income a sound response to AI-driven automation?", ] results = chat.run_batch(tasks) for i, result in enumerate(results, start=1): print(f"\n--- Discussion {i} ---\n{result}") if __name__ == "__main__": main() # batch_example() # uncomment to run the batch variant ``` ### What to expect when you run it The seed task is posted as `User`. Every turn, all four agents privately bid through the forced `respond` call; `_select_speaker` picks the single highest recency-adjusted bidder above `0.6` and posts only that reply, which then becomes the "latest message" the next turn's bids are formed around. Because the decide prompt defaults to silence and `recency_penalty=0.3` discourages back-to-back turns from the same agent, expect the floor to move between two or three of the four agents over a handful of turns before the room hits a lull — no bid clears `0.6` — and `run()` returns. If the panel stays contentious enough that some agent keeps clearing the threshold, the chat instead runs until `max_loops=12` is reached, the hard cap. *** ## Summary `GroupChat` runs a single-event-loop, turn-based loop with no per-agent mailboxes, no monitor task, and no lock — the only concurrency is gathering one turn's bids in parallel via `asyncio.to_thread` before the single coroutine driving `_run_async` posts at most one winner (`_select_speaker`, a strict recency-adjusted argmax over non-empty bids). The loop is bounded deterministically by `max_loops` and can end earlier at any bidding lull where no adjusted score clears `threshold`; `idle_timeout` is accepted for compatibility but does nothing. `threshold` and `recency_penalty` jointly shape both who gets to speak and how likely a lull is on any given turn, including the case where the penalty alone turns a would-be winner into a lull. `run_batch` runs tasks sequentially against the same unreset `self.conversation`, so batched tasks share transcript context unless a new `GroupChat` is constructed per task.