GroupChat

Overview

The GroupChat class enables collaborative conversations among multiple agents (or callables) with flexible speaker selection strategies, conversation history management, and interactive terminal sessions. Agents can @mention each other to request input or delegate tasks.

Class Definition

from swarms.structs.groupchat import GroupChat

Parameters

str

default:"generate_api_key(prefix='swarms-')"

Unique identifier for the group chat

str

default:"GroupChat"

Name of the group chat

str

default:"A group chat for multiple agents"

Description of the group chat’s purpose

List[Union[Agent, Callable]]

default:"[]"

List of agent objects or callables that will participate in the conversation

int

default:"1"

Maximum number of conversation loops per run

str

default:"dict"

Output format for conversation history. Options: “dict”, “str”, “list”, “json”

bool

default:"False"

If True, enables interactive terminal REPL session for human-in-the-loop conversations

Optional[Union[str, Callable]]

Speaker selection strategy. Options: “round-robin-speaker”, “random-speaker”, “priority-speaker”, “random-dynamic-speaker”, or custom callable

Optional[dict]

State/configuration for the speaker function (e.g., priorities for priority-speaker)

str

default:""

Rules for the conversation that will be added to conversation history

bool

default:"True"

Whether to enable timestamps in conversation messages

Speaker Functions

Built-in Speaker Functions

round-robin-speaker

Cycles through agents in order, ensuring each agent gets a turn sequentially.

group_chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="round-robin-speaker"
)

random-speaker

Randomly selects exactly one agent to respond to each user query.

group_chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="random-speaker"
)

priority-speaker

Selects agents based on priority weights. Requires priority configuration in speaker_state.

group_chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="priority-speaker",
    speaker_state={
        "priorities": {
            "agent1": 10,
            "agent2": 5,
            "agent3": 1
        }
    }
)

random-dynamic-speaker

Randomly selects the first agent, then follows @mentions in responses for subsequent speakers. Supports both sequential and parallel execution strategies.

group_chat = GroupChat(
    agents=[agent1, agent2, agent3],
    speaker_function="random-dynamic-speaker",
    speaker_state={"strategy": "sequential"}  # or "parallel"
)

Custom Speaker Functions

You can provide custom speaker selection logic:

def custom_speaker(agents: List[str], **kwargs) -> str:
    # Your custom logic
    return selected_agent_name

group_chat = GroupChat(
    agents=[agent1, agent2],
    speaker_function=custom_speaker
)

Direct Function Imports

The string identifiers above ("round-robin-speaker", etc.) dispatch to plain functions in swarms.structs.groupchat. You can import them directly when you want to compose them or pass them as the speaker_function= argument without the string indirection.

from swarms import (
    round_robin_speaker,
    random_speaker,
    priority_speaker,
    random_dynamic_speaker,
    expertise_based,
)

Function	Signature	Returns
`round_robin_speaker`	`(agents: List[str], current_index: int = 0)`	`str` — next agent name
`random_speaker`	`(agents: List[str], **kwargs)`	`str` — randomly chosen agent name
`priority_speaker`	`(agents: List[str], priorities: dict, **kwargs)`	`str` — weighted-random agent name
`random_dynamic_speaker`	`(agents: List[str], response: str = "", strategy: str = "parallel", **kwargs)`	`str` or `List[str]` — agents from `@mentions` in the last response
`expertise_based`	`(history: List[str], agent: Agent)`	`bool` — whether this agent should speak based on system-prompt match

expertise_based is shaped differently from the others — it’s a per-agent filter rather than a selector. Use it when you want every agent to self-decide whether to participate based on the topic of the last message.

Methods

`run()`

def run(
    self,
    task: str,
    img: Optional[str] = None,
    imgs: Optional[List[str]] = None,
) -> str

Processes a task and gets responses from agents based on speaker function. Parameters:

str

required

The user input or task to process. Can include @mentions to target specific agents

str

Optional image input for the agents

List[str]

Optional list of images for the agents

Returns:

str

The formatted conversation history (format depends on output_type)

Raises:

GroupChatError: If an unexpected error occurs
AgentNotFoundError: If a mentioned agent is not found

`start_interactive_session()`

def start_interactive_session(self) -> None

Starts an interactive terminal REPL session for chatting with agents. Features:

Chat with agents using @mentions (optional)
See available agents and descriptions
Change speaker function mid-conversation
Exit using ‘exit’ or ‘quit’
Get help using ‘help’ or ’?’

Raises:

GroupChatError: If interactive mode is not enabled

Example:

group_chat = GroupChat(
    name="AI Team",
    agents=[agent1, agent2],
    interactive=True
)

group_chat.start_interactive_session()
# Welcome to AI Team!
# You: @agent1 what do you think about this?
# agent1: [response]

`set_speaker_function()`

def set_speaker_function(
    self,
    speaker_function: Union[str, Callable],
    speaker_state: Optional[dict] = None,
) -> None

Sets or changes the speaker function. Parameters:

Union[str, Callable]

required

Either a string name of predefined function or custom callable

dict

Optional state for the speaker function

Raises:

InvalidSpeakerFunctionError: If the speaker function is invalid

`get_available_speaker_functions()`

def get_available_speaker_functions(self) -> List[str]

Returns a list of all available built-in speaker function names. Returns:

List[str]

List of available speaker function names

`get_current_speaker_function()`

def get_current_speaker_function(self) -> str

Returns the name of the current speaker function. Returns:

str

Name of current speaker function, or “custom” if it’s a custom function

Collaboration Features

@Mentions

Agents can mention other agents using @agent_name syntax:

# Agent response example:
"I think @analyst should review this data, and @writer can help document it"

Automatic Prompt Augmentation

GroupChat automatically adds collaboration instructions to each agent’s system prompt:

How to use @mentions
Collaboration guidelines
Task completion protocols
Response structure recommendations

Conversation Context

Each agent receives the complete conversation history, enabling:

Context-aware responses
Building upon others’ contributions
Acknowledging previous agents’ work

Usage Examples

Basic GroupChat

from swarms.structs.agent import Agent
from swarms.structs.groupchat import GroupChat

# Create agents
researcher = Agent(
    agent_name="researcher",
    system_prompt="You are a research specialist",
    model_name="claude-sonnet-4-6"
)

analyst = Agent(
    agent_name="analyst",
    system_prompt="You are a data analyst",
    model_name="claude-sonnet-4-6"
)

# Create group chat
group_chat = GroupChat(
    name="Research Team",
    description="A collaborative research team",
    agents=[researcher, analyst],
    speaker_function="round-robin-speaker",
    output_type="dict"
)

# Run a task
result = group_chat.run(
    task="Analyze the latest trends in renewable energy"
)

Interactive Session

group_chat = GroupChat(
    name="AI Advisors",
    agents=[advisor1, advisor2, advisor3],
    interactive=True,
    speaker_function="random-dynamic-speaker"
)

# Start interactive REPL
group_chat.start_interactive_session()

Priority-Based Selection

group_chat = GroupChat(
    name="Expert Panel",
    agents=[senior_expert, mid_expert, junior_expert],
    speaker_function="priority-speaker",
    speaker_state={
        "priorities": {
            "senior_expert": 10,
            "mid_expert": 5,
            "junior_expert": 1
        }
    }
)

result = group_chat.run("What's the best approach to this problem?")

Exception Classes

GroupChatError: Base exception for GroupChat errors
AgentNotFoundError: Raised when a mentioned agent is not found
InvalidTaskFormatError: Raised when task format is invalid
InvalidSpeakerFunctionError: Raised when invalid speaker function is provided

Source Code

View the source code on GitHub

Core Classes

Multi-Agent Harnesses

Tools & Utilities

Deployment

Overview

Class Definition

Parameters

Speaker Functions

Built-in Speaker Functions

round-robin-speaker

random-speaker

priority-speaker

random-dynamic-speaker

Custom Speaker Functions

Direct Function Imports

Methods

`run()`

`start_interactive_session()`

`set_speaker_function()`

`get_available_speaker_functions()`

`get_current_speaker_function()`

Collaboration Features

@Mentions

Automatic Prompt Augmentation

Conversation Context

Usage Examples

Basic GroupChat

Interactive Session

Priority-Based Selection

Exception Classes

Source Code

​Overview

​Class Definition

​Parameters

​Speaker Functions

​Built-in Speaker Functions

​round-robin-speaker

​random-speaker

​priority-speaker

​random-dynamic-speaker

​Custom Speaker Functions

​Direct Function Imports

​Methods

​run()

​start_interactive_session()

​set_speaker_function()

​get_available_speaker_functions()

​get_current_speaker_function()

​Collaboration Features

​@Mentions

​Automatic Prompt Augmentation

​Conversation Context

​Usage Examples

​Basic GroupChat

​Interactive Session

​Priority-Based Selection

​Exception Classes

​Source Code

Overview

Class Definition

Parameters

Speaker Functions

Built-in Speaker Functions

round-robin-speaker

random-speaker

priority-speaker

random-dynamic-speaker

Custom Speaker Functions

Direct Function Imports

Methods

`run()`

`start_interactive_session()`

`set_speaker_function()`

`get_available_speaker_functions()`

`get_current_speaker_function()`

Collaboration Features

@Mentions

Automatic Prompt Augmentation

Conversation Context

Usage Examples

Basic GroupChat

Interactive Session

Priority-Based Selection

Exception Classes

Source Code