swarms/docs/swarms/structs/interactive_groupchat.md

InteractiveGroupChat Documentation

The InteractiveGroupChat is a sophisticated multi-agent system that enables interactive conversations between users and AI agents using @mentions. This system allows users to direct tasks to specific agents and facilitates collaborative responses when multiple agents are mentioned.

Features

• @mentions Support: Direct tasks to specific agents using @agent_name syntax
• Multi-Agent Collaboration: Multiple mentioned agents can see and respond to each other's tasks
• Callable Function Support: Supports both Agent instances and callable functions as chat participants
• Comprehensive Error Handling: Custom error classes for different scenarios
• Conversation History: Maintains a complete history of the conversation
• Flexible Output Formatting: Configurable output format for conversation history

Installation

pip install swarms

Methods Reference

Constructor (__init__)

Description:
Initializes a new InteractiveGroupChat instance with the specified configuration.

Arguments:

Parameter	Type	Description	Default
id	str	Unique identifier for the chat	auto-generated key
name	str	Name of the group chat	"InteractiveGroupChat"
description	str	Description of the chat's purpose	generic description
agents	List[Union[Agent, Callable]]	List of participating agents	empty list
max_loops	int	Maximum conversation turns	1
output_type	str	Type of output format	"string"
interactive	bool	Whether to enable interactive mode	False

Example:

from swarms import Agent, InteractiveGroupChat

# Create agents
financial_advisor = Agent(
    agent_name="FinancialAdvisor",
    system_prompt="You are a financial advisor specializing in investment strategies.",
    model_name="gpt-4"
)

tax_expert = Agent(
    agent_name="TaxExpert",
    system_prompt="You are a tax expert providing tax-related guidance.",
    model_name="gpt-4"
)

# Initialize group chat
chat = InteractiveGroupChat(
    id="finance-chat-001",
    name="Financial Advisory Team",
    description="Expert financial guidance team",
    agents=[financial_advisor, tax_expert],
    max_loops=3,
    output_type="string",
    interactive=True
)

Run Method (run)

Description:
Processes a task and gets responses from mentioned agents. This is the main method for sending tasks in non-interactive mode.

Arguments:

• task (str): The input task containing @mentions to agents

Returns:

• str: Formatted conversation history including agent responses

Example:

# Single agent interaction
response = chat.run("@FinancialAdvisor what are the best ETFs for 2024?")
print(response)

# Multiple agent collaboration
response = chat.run("@FinancialAdvisor and @TaxExpert, how can I minimize taxes on my investments?")
print(response)

Start Interactive Session (start_interactive_session)

Description:
Starts an interactive terminal session for real-time chat with agents. This creates a REPL (Read-Eval-Print Loop) interface.

Arguments: None

Example:

# Initialize chat with interactive mode
chat = InteractiveGroupChat(
    agents=[financial_advisor, tax_expert],
    interactive=True
)

# Start the interactive session
chat.start_interactive_session()

Extract Mentions (_extract_mentions)

Description:

Internal method that extracts @mentions from a task. Used by the run method to identify which agents should respond.

Arguments:

• task (str): The input task to extract mentions from

Returns:

• List[str]: List of mentioned agent names

Example:

# Internal usage example (not typically called directly)
chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert])
mentions = chat._extract_mentions("@FinancialAdvisor and @TaxExpert, please help")
print(mentions)  # ['FinancialAdvisor', 'TaxExpert']

Validate Initialization (_validate_initialization)

Description:

Internal method that validates the group chat configuration during initialization.

Arguments: None

Example:

# Internal validation happens automatically during initialization
chat = InteractiveGroupChat(
    agents=[financial_advisor],  # Valid: at least one agent
    max_loops=5  # Valid: positive number
)

Setup Conversation Context (_setup_conversation_context)

Description:

Internal method that sets up the initial conversation context with group chat information.

Arguments:

None

Example:

# Context is automatically set up during initialization
chat = InteractiveGroupChat(
    name="Investment Team",
    description="Expert investment advice",
    agents=[financial_advisor, tax_expert]
)
# The conversation context now includes chat name, description, and agent info

Update Agent Prompts (_update_agent_prompts)

Description:

Internal method that updates each agent's system prompt with information about other agents and the group chat.

Arguments:

None

Example:

# Agent prompts are automatically updated during initialization
chat = InteractiveGroupChat(agents=[financial_advisor, tax_expert])
# Each agent now knows about the other participants in the chat

Error Classes

InteractiveGroupChatError

Description:

Base exception class for InteractiveGroupChat errors.

Example:

try:
    # Some operation that might fail
    chat.run("@InvalidAgent hello")
except InteractiveGroupChatError as e:
    print(f"Chat error occurred: {e}")

AgentNotFoundError

Description:

Raised when a mentioned agent is not found in the group.

Example:

try:
    chat.run("@NonExistentAgent hello!")
except AgentNotFoundError as e:
    print(f"Agent not found: {e}")

NoMentionedAgentsError

Description:

Raised when no agents are mentioned in the task.

Example:

try:
    chat.run("Hello everyone!")  # No @mentions
except NoMentionedAgentsError as e:
    print(f"No agents mentioned: {e}")

InvalidtaskFormatError

Description:

Raised when the task format is invalid.

Example:

try:
    chat.run("@Invalid@Format")
except InvalidtaskFormatError as e:
    print(f"Invalid task format: {e}")

Best Practices

Best Practice	Description	Example
Agent Naming	Use clear, unique names for agents to avoid confusion	financial_advisor, tax_expert
task Format	Always use @mentions to direct tasks to specific agents	@financial_advisor What's your investment advice?
Error Handling	Implement proper error handling for various scenarios	try/except blocks for AgentNotFoundError
Context Management	Be aware that agents can see the full conversation history	Monitor conversation length and relevance
Resource Management	Consider the number of agents and task length to optimize performance	Limit max_loops and task size

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our GitHub repository.

License

This project is licensed under the Apache License - see the LICENSE file for details.