[feat][async-groupchat][rewrite groupchat as self-selecting async

  chat][feat][respond-tool][export respond tool for groupchat
  agents][improvement][drop-speaker-functions][remove speaker function
  api from router and
  exports][improvement][agent-tools-default][default
  tools_list_dictionary to empty
  list][improvement][groupchat-examples-refresh][update groupchat
  examples to new api][feat][new-groupchat-examples][add dynamic and
  router groupchat examples][feat][fable-agent-example][add fable
  single agent example][docs][groupchat-docs][rewrite groupchat docs
  and guides][improvement][groupchat-tests][rewrite groupchat tests for
  new api]

Author: kyegomez

CLAUDE.md

@@ -575,25 +575,49 @@ result = swarm.run("Produce a comprehensive competitive analysis of the AI chip
 
 ### GroupChat
 
-Agents engage in a round-table discussion. A speaker selection function decides who speaks next. Use for brainstorming, debate, or collaborative problem-solving.
+An asynchronous, self-selecting groupchat. There are no rounds or speaker-selection functions — every agent listens in parallel and decides on its own whether to chime in. A forced `respond(score, message)` function call asks each agent how much it wants to speak (0..1); replies above `threshold` are broadcast. The chat ends when `max_loops` messages have been posted or no message arrives for `idle_timeout` seconds.
 
 ```python
-from swarms import Agent, GroupChat
-from swarms.structs.groupchat import expertise_based, round_robin_speaker
+from swarms import Agent
+from swarms.structs.groupchat import GroupChat, RESPOND_TOOL
 
-optimist  = Agent(agent_name="Optimist",  system_prompt="You argue for the benefits.", model_name="gpt-4.1", max_loops=1)
-pessimist = Agent(agent_name="Pessimist", system_prompt="You argue for the risks.",    model_name="gpt-4.1", max_loops=1)
-realist   = Agent(agent_name="Realist",   system_prompt="You seek balanced analysis.", model_name="gpt-4.1", max_loops=1)
+# Every agent MUST carry RESPOND_TOOL so the chat can ask it whether to speak.
+# Recommended per-agent: max_loops=1, persistent_memory=False.
+optimist = Agent(
+    agent_name="Optimist",
+    system_prompt="You argue for the benefits.",
+    model_name="gpt-4.1",
+    max_loops=1,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
+)
+pessimist = Agent(
+    agent_name="Pessimist",
+    system_prompt="You argue for the risks.",
+    model_name="gpt-4.1",
+    max_loops=1,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
+)
+realist = Agent(
+    agent_name="Realist",
+    system_prompt="You seek balanced analysis.",
+    model_name="gpt-4.1",
+    max_loops=1,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
+)
 
 chat = GroupChat(
     agents=[optimist, pessimist, realist],
-    speaker_fn=round_robin_speaker,   # or expertise_based, random_speaker, priority_speaker
-    max_loops=3,                      # 3 rounds of discussion
+    max_loops=10,        # hard cap on total messages posted
+    threshold=0.5,       # min decision score (0..1) to publish a reply
+    idle_timeout=8.0,    # seconds of silence before stopping
 )
 result = chat.run("Should we adopt AI for medical diagnosis?")
 ```
 
-**Speaker functions:** `round_robin_speaker`, `expertise_based`, `random_speaker`, `priority_speaker`, `random_dynamic_speaker`
+**Tuning:** raise `threshold` for a more selective room; lower it for livelier chats. Raise `idle_timeout` if agents need time to think before replying.
 
 ---
 

README.md

@@ -500,29 +500,38 @@ print(recommendation)
 
 ### GroupChat
 
-`GroupChat` creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve a problem. You can define the speaking order or let it be determined dynamically. This architecture is ideal for tasks that benefit from debate and multi-perspective reasoning, such as contract negotiation, brainstorming, or complex decision-making.
+`GroupChat` is an asynchronous, self-selecting groupchat. All agents listen in parallel; for each broadcast message, every other agent runs a forced `respond(score, message)` function call to decide whether to chime in, and replies above `threshold` are broadcast. The chat ends when `max_loops` messages have been posted or no message arrives for `idle_timeout` seconds. There is no turn order — multiple agents can react to the same message at the same time, and silent agents stay silent.
 
 ```python
-from swarms import Agent, GroupChat
+from swarms import Agent, GroupChat, RESPOND_TOOL
 
-# Define agents for a debate
-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 the unchecked advancement of AI.", model_name="gpt-5.4")
+# Every agent MUST carry RESPOND_TOOL so the chat can ask it whether to speak.
+tech_optimist = Agent(
+    agent_name="TechOptimist",
+    system_prompt="Argue for the benefits of AI in society.",
+    model_name="gpt-4.1",
+    max_loops=1,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
+)
+tech_critic = Agent(
+    agent_name="TechCritic",
+    system_prompt="Argue against the unchecked advancement of AI.",
+    model_name="gpt-4.1",
+    max_loops=1,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
+)
 
-# Create the group chat
 chat = GroupChat(
     agents=[tech_optimist, tech_critic],
-    max_loops=4, # Limit the number of turns in the conversation
+    max_loops=10,       # hard cap on total messages posted
+    threshold=0.5,      # min decision score (0..1) to publish a reply
+    idle_timeout=8.0,   # seconds of silence before stopping
 )
 
-# Run the chat with an initial topic
-conversation_history = chat.run(
-    "Let's discuss the societal impact of artificial intelligence."
-)
-
-# Print the full conversation
-for message in conversation_history:
-    print(f"[{message['agent_name']}]: {message['content']}")
+result = chat.run("Let's discuss the societal impact of artificial intelligence.")
+print(result)
 ```
 
 ----

docs/MULTI_AGENT_STRUCTURES.md

@@ -47,7 +47,7 @@ The table below lists every multi-agent structure currently shipped, with a one-
 | `CouncilAsAJudge` | Council evaluates a response across multiple dimensions; ranks/scores outputs. | [link](swarms/structs/council_as_judge.py) |
 | `LLMCouncil` | Independent expert agents respond, peer-review each other, then synthesize. | [link](swarms/structs/llm_council.py) |
 | `DebateWithJudge` | Adversarial debate rounds followed by a judge ruling; supports self-refinement. | [link](swarms/structs/debate_with_judge.py) |
-| `GroupChat` | Round-table chat with pluggable speaker-selection (round-robin, expertise, random, priority, dynamic). | [link](swarms/structs/groupchat.py) |
+| `GroupChat` | Asynchronous self-selecting groupchat — every agent independently scores each message via a forced `respond(score, message)` tool call and broadcasts when the score clears `threshold`. | [link](swarms/structs/groupchat.py) |
 | `ForestSwarm` | A forest of `Tree`s of `TreeAgent`s; routes tasks to the best matching tree leaf. | [link](swarms/structs/tree_swarm.py) |
 | `AdvisorSwarm` | Cheap executor + powerful advisor consulted on-demand between turns. | [link](swarms/structs/advisor_swarm.py) |
 | `PlannerGeneratorEvaluator` | Three-agent harness: Planner emits step contracts, Generator produces, Evaluator scores. | [link](swarms/structs/planner_generator_evaluator.py) |

docs/PERFORMANCE_AUDIT.md

@@ -177,7 +177,7 @@ def __getattr__(name):
 ```
 
 ### 4.2 Repeated regex compilation
-`groupchat.py:952, 311`, `cron_job.py:121`, agent-name sanitisation. Hoist to module-level `_COMPILED = re.compile(...)`.
+`cron_job.py:121`, agent-name sanitisation. Hoist to module-level `_COMPILED = re.compile(...)`.
 
 ### 4.3 Serialisation round-trips
 - `base_structure.py:333-356` does `json.dumps(json.dumps(data))` before gzip — double encoding, ~2× the bytes.

docs/swarms/concept/how_to_choose_swarms.md

@@ -468,13 +468,13 @@ print(recommendation)
 
 [📖 Documentation](https://docs.swarms.world/swarms/structs/group_chat/)
 
-GroupChat creates a conversational environment where multiple agents can interact, discuss, and collaboratively solve problems. Agents take turns in conversation, building on each other's ideas and reaching consensus through dialogue. This architecture is ideal for brainstorming, negotiation, and complex decision-making requiring iterative discussion.
+GroupChat is an asynchronous, self-selecting room. Every agent listens to every broadcast message in parallel and independently scores how much it wants to reply via a forced `respond(score, message)` tool call. Replies whose score exceeds the configured `threshold` are broadcast back into the room. There are no rounds, no turn order, and no central speaker selector — agents decide for themselves whether each message is worth a response. The chat ends when either `max_loops` total messages have been posted or no new message arrives for `idle_timeout` seconds.
 
 Best For: GroupChat is ideal for brainstorming sessions, negotiation and debate, collaborative problem-solving, real-time decision-making, creative ideation, and contract or agreement drafting.
 
-Advantages: This architecture enables natural conversational interaction, builds on collective intelligence, allows for clarification and follow-up, and mimics human collaborative processes.
+Advantages: This architecture lets specialised agents stay silent on messages outside their expertise, mixes model providers transparently, and scales to many participants without a coordinator bottleneck.
 
-Trade-offs: GroupChat can be unpredictable in direction, may require careful moderation, has conversation length that can be variable, and is not suitable for time-critical tasks.
+Trade-offs: GroupChat can be unpredictable in direction, requires `threshold` tuning to avoid either silent rooms or runaway chatter, has variable conversation length, and is not suitable for time-critical tasks.
 
 ### Architecture Diagram
 
@@ -499,50 +499,54 @@ graph TD
 ### Code Example
 
 ```python
-from swarms import Agent, GroupChat
+from swarms import Agent, GroupChat, RESPOND_TOOL
+
+# Define agents with different perspectives for an asynchronous discussion.
+# Every participant must include tools_list_dictionary=[RESPOND_TOOL] so the
+# chat can read each agent's structured (score, message) decision.
 
-# Define agents with different perspectives for a debate
 optimist = Agent(
     agent_name="TechnologyOptimist",
     system_prompt="Argue for the benefits and opportunities of AI advancement. Focus on positive impacts.",
     model_name="anthropic/claude-sonnet-4-5",
-    top_p=None,
     max_loops=1,
-    dynamic_temperature_enabled=True,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
 )
 
 critic = Agent(
     agent_name="TechnologyCritic",
     system_prompt="Critically examine AI development challenges, risks, and potential negative consequences.",
     model_name="anthropic/claude-sonnet-4-5",
-    top_p=None,
     max_loops=1,
-    dynamic_temperature_enabled=True,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
 )
 
 ethicist = Agent(
     agent_name="EthicsSpecialist",
     system_prompt="Focus on ethical implications, responsible AI development, and societal considerations.",
     model_name="anthropic/claude-sonnet-4-5",
-    top_p=None,
     max_loops=1,
-    dynamic_temperature_enabled=True,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
 )
 
 moderator = Agent(
     agent_name="Moderator",
     system_prompt="Facilitate constructive dialogue, ensure all voices are heard, and help reach balanced conclusions.",
     model_name="anthropic/claude-sonnet-4-5",
-    top_p=None,
     max_loops=1,
-    dynamic_temperature_enabled=True,
+    persistent_memory=False,
+    tools_list_dictionary=[RESPOND_TOOL],
 )
 
-# Create the group chat with controlled conversation length
+# Create the group chat. Replies are broadcast only when score > threshold.
 chat = GroupChat(
     agents=[optimist, critic, ethicist, moderator],
-    max_loops=6,  # Limit conversation turns for focused discussion
-    speaker_selection_method="round_robin"  # Alternating turns
+    max_loops=10,        # hard cap on total messages
+    threshold=0.55,      # raise to silence weak replies, lower for liveliness
+    idle_timeout=8.0,    # stop after 8 seconds with no new message
 )
 
 # Run the collaborative discussion
@@ -553,10 +557,7 @@ conversation_history = chat.run(
 
 # Display the full conversation
 print("=== Group Chat Discussion ===\n")
-for i, message in enumerate(conversation_history, 1):
-    print(f"Turn {i}: [{message['agent_name']}]")
-    print(f"{message['content']}\n")
-    print("-" * 50)
+print(conversation_history)
 ```
 
 ---

docs/swarms/concept/swarm_architectures.md

@@ -26,7 +26,7 @@ Multi-agent architectures leverage these communication patterns to ensure that a
 | Sequential Coordination           | Agents perform tasks in a specific sequence, where the completion of one task triggers the start of the next.                                                           | [Learn More](https://docs.swarms.world/swarms/structs/sequential_workflow/)               | Step-by-step assembly lines, sequential sales processes, stepwise patient treatment workflows     |
 | Mixture of Agents                 | A heterogeneous architecture where agents with different capabilities are combined to solve complex problems.                                                           | [Learn More](https://docs.swarms.world/swarms/structs/moa/)                               | Financial forecasting, complex problem-solving requiring diverse skills                           |
 | Graph Workflow                    | Agents collaborate in a directed acyclic graph (DAG) format to manage dependencies and parallel tasks.                                                                  | [Learn More](https://docs.swarms.world/swarms/structs/graph_workflow/)                    | AI-driven software development pipelines, complex project management                              |
-| Group Chat                        | Agents engage in a chat-like interaction to reach decisions collaboratively.                                                                                           | [Learn More](https://docs.swarms.world/swarms/structs/group_chat/)                        | Real-time collaborative decision-making, contract negotiations                                    |
+| Group Chat                        | Asynchronous self-selecting chat — each agent independently scores whether each message warrants a reply.                                                              | [Learn More](https://docs.swarms.world/swarms/structs/group_chat/)                        | Real-time collaborative decision-making, contract negotiations                                    |
 | Interactive Group Chat           | Enhanced group chat with dynamic speaker selection and interaction patterns.                                                                                           | [Learn More](https://docs.swarms.world/swarms/structs/interactive_groupchat/)             | Advanced collaborative decision-making, dynamic team coordination                                 |
 | SpreadSheet                       | Manages tasks at scale, tracking agent outputs in a structured format like CSV files.                                                                                   | [Learn More](https://docs.swarms.world/swarms/structs/spreadsheet_swarm/)                 | Large-scale marketing analytics, financial audits                                                 |
 | Router                            | Routes and chooses the architecture based on the task requirements and available agents.                                                                               | [Learn More](https://docs.swarms.world/swarms/structs/swarm_router/)                       | Dynamic task routing, adaptive architecture selection, optimized agent allocation                 |
@@ -347,7 +347,7 @@ graph TD
 ### Group Chat
 
 **Overview:**
-Enables agents to engage in chat-like interactions to reach decisions collaboratively through discussion and consensus building.
+An asynchronous, self-selecting room where every agent listens to every broadcast message in parallel and independently scores whether to reply via a forced `respond(score, message)` tool call. Replies above the configured `threshold` are broadcast back into the room; the chat ends when `max_loops` messages have been posted or no new message arrives for `idle_timeout` seconds.
 
 **Use Cases:**