You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
255 lines
7.7 KiB
255 lines
7.7 KiB
# GroupChat Swarm Documentation
|
|
|
|
A production-grade multi-agent system enabling sophisticated group conversations between AI agents with customizable speaking patterns, parallel processing capabilities, and comprehensive conversation tracking.
|
|
|
|
## Advanced Configuration
|
|
|
|
### Agent Parameters
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-----------|------|---------|-------------|
|
|
| agent_name | str | Required | Unique identifier for the agent |
|
|
| system_prompt | str | Required | Role and behavior instructions |
|
|
| llm | Any | Required | Language model instance |
|
|
| max_loops | int | 1 | Maximum conversation turns |
|
|
| autosave | bool | False | Enable conversation saving |
|
|
| dashboard | bool | False | Enable monitoring dashboard |
|
|
| verbose | bool | True | Enable detailed logging |
|
|
| dynamic_temperature | bool | True | Enable dynamic temperature |
|
|
| retry_attempts | int | 1 | Failed request retry count |
|
|
| context_length | int | 200000 | Maximum context window |
|
|
| output_type | str | "string" | Response format type |
|
|
| streaming_on | bool | False | Enable streaming responses |
|
|
|
|
### GroupChat Parameters
|
|
|
|
| Parameter | Type | Default | Description |
|
|
|-----------|------|---------|-------------|
|
|
| name | str | "GroupChat" | Chat group identifier |
|
|
| description | str | "" | Purpose description |
|
|
| agents | List[Agent] | [] | Participating agents |
|
|
| speaker_fn | Callable | round_robin | Speaker selection function |
|
|
| max_loops | int | 10 | Maximum conversation turns |
|
|
|
|
|
|
## Core Concepts
|
|
|
|
The GroupChat system consists of several key components:
|
|
|
|
1. **Agents**: Individual AI agents with specialized knowledge and roles
|
|
2. **Speaker Functions**: Control mechanisms for conversation flow
|
|
3. **Chat History**: Structured conversation tracking
|
|
4. **Response Models**: Pydantic models for data validation
|
|
|
|
## Basic Usage
|
|
|
|
```python
|
|
|
|
import os
|
|
from dotenv import load_dotenv
|
|
from swarms import Agent, GroupChat, expertise_based
|
|
|
|
if __name__ == "__main__":
|
|
|
|
# Example agents
|
|
agent1 = Agent(
|
|
agent_name="Financial-Analysis-Agent",
|
|
system_prompt="You are a financial analyst specializing in investment strategies.",
|
|
model_name="gpt-4.1",
|
|
max_loops=1,
|
|
)
|
|
|
|
agent2 = Agent(
|
|
agent_name="Tax-Adviser-Agent",
|
|
system_prompt="You are a tax adviser who provides clear and concise guidance on tax-related queries.",
|
|
model_name="gpt-4.1",
|
|
max_loops=1,
|
|
)
|
|
|
|
agents = [agent1, agent2]
|
|
|
|
chat = GroupChat(
|
|
name="Investment Advisory",
|
|
description="Financial and tax analysis group",
|
|
agents=agents,
|
|
speaker_fn=expertise_based,
|
|
)
|
|
|
|
history = chat.run(
|
|
"How to optimize tax strategy for investments?"
|
|
)
|
|
print(history.model_dump_json(indent=2))
|
|
|
|
```
|
|
|
|
## Speaker Functions
|
|
|
|
|
|
### Built-in Functions
|
|
|
|
```python
|
|
def round_robin(history: List[str], agent: Agent) -> bool:
|
|
"""
|
|
Enables agents to speak in turns.
|
|
Returns True for each agent in sequence.
|
|
"""
|
|
return True
|
|
|
|
def expertise_based(history: List[str], agent: Agent) -> bool:
|
|
"""
|
|
Enables agents to speak based on their expertise.
|
|
Returns True if agent's role matches conversation context.
|
|
"""
|
|
return agent.system_prompt.lower() in history[-1].lower() if history else True
|
|
|
|
def random_selection(history: List[str], agent: Agent) -> bool:
|
|
"""
|
|
Randomly selects speaking agents.
|
|
Returns True/False with 50% probability.
|
|
"""
|
|
import random
|
|
return random.choice([True, False])
|
|
|
|
def most_recent(history: List[str], agent: Agent) -> bool:
|
|
"""
|
|
Enables agents to respond to their mentions.
|
|
Returns True if agent was last speaker.
|
|
"""
|
|
return agent.agent_name == history[-1].split(":")[0].strip() if history else True
|
|
```
|
|
|
|
### Custom Speaker Function Example
|
|
|
|
```python
|
|
def custom_speaker(history: List[str], agent: Agent) -> bool:
|
|
"""
|
|
Custom speaker function with complex logic.
|
|
|
|
Args:
|
|
history: Previous conversation messages
|
|
agent: Current agent being evaluated
|
|
|
|
Returns:
|
|
bool: Whether agent should speak
|
|
"""
|
|
# No history - let everyone speak
|
|
if not history:
|
|
return True
|
|
|
|
last_message = history[-1].lower()
|
|
|
|
# Check for agent expertise keywords
|
|
expertise_relevant = any(
|
|
keyword in last_message
|
|
for keyword in agent.expertise_keywords
|
|
)
|
|
|
|
# Check for direct mentions
|
|
mentioned = agent.agent_name.lower() in last_message
|
|
|
|
# Check if agent hasn't spoken recently
|
|
not_recent_speaker = not any(
|
|
agent.agent_name in msg
|
|
for msg in history[-3:]
|
|
)
|
|
|
|
return expertise_relevant or mentioned or not_recent_speaker
|
|
|
|
# Usage
|
|
chat = GroupChat(
|
|
agents=[agent1, agent2],
|
|
speaker_fn=custom_speaker
|
|
)
|
|
```
|
|
|
|
## Advanced Examples
|
|
|
|
### Multi-Agent Analysis Team
|
|
|
|
```python
|
|
# Create specialized agents
|
|
data_analyst = Agent(
|
|
agent_name="Data-Analyst",
|
|
system_prompt="You analyze numerical data and patterns",
|
|
model_name="gpt-4.1",
|
|
)
|
|
|
|
market_expert = Agent(
|
|
agent_name="Market-Expert",
|
|
system_prompt="You provide market insights and trends",
|
|
model_name="gpt-4.1",
|
|
)
|
|
|
|
strategy_advisor = Agent(
|
|
agent_name="Strategy-Advisor",
|
|
system_prompt="You formulate strategic recommendations",
|
|
model_name="gpt-4.1",
|
|
)
|
|
|
|
# Create analysis team
|
|
analysis_team = GroupChat(
|
|
name="Market Analysis Team",
|
|
description="Comprehensive market analysis group",
|
|
agents=[data_analyst, market_expert, strategy_advisor],
|
|
speaker_fn=expertise_based,
|
|
max_loops=15
|
|
)
|
|
|
|
# Run complex analysis
|
|
history = analysis_team.run("""
|
|
Analyze the current market conditions:
|
|
1. Identify key trends
|
|
2. Evaluate risks
|
|
3. Recommend investment strategy
|
|
""")
|
|
```
|
|
|
|
### Parallel Processing
|
|
|
|
```python
|
|
# Define multiple analysis tasks
|
|
tasks = [
|
|
"Analyze tech sector trends",
|
|
"Evaluate real estate market",
|
|
"Review commodity prices",
|
|
"Assess global economic indicators"
|
|
]
|
|
|
|
# Run tasks concurrently
|
|
histories = chat.concurrent_run(tasks)
|
|
|
|
# Process results
|
|
for task, history in zip(tasks, histories):
|
|
print(f"\nAnalysis for: {task}")
|
|
for turn in history.turns:
|
|
for response in turn.responses:
|
|
print(f"{response.agent_name}: {response.message}")
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
| Category | Recommendations |
|
|
|---------------------|--------------------------------------------------------------------------------------------------|
|
|
| **Agent Design** | - Give agents clear, specific roles<br>- Use detailed system prompts<br>- Set appropriate context lengths<br>- Enable retries for reliability |
|
|
| **Speaker Functions** | - Match function to use case<br>- Consider conversation flow<br>- Handle edge cases<br>- Add appropriate logging |
|
|
| **Error Handling** | - Use try-except blocks<br>- Log errors appropriately<br>- Implement retry logic<br>- Provide fallback responses |
|
|
| **Performance** | - Use concurrent processing for multiple tasks<br>- Monitor context lengths<br>- Implement proper cleanup<br>- Cache responses when appropriate |
|
|
|
|
## API Reference
|
|
|
|
### GroupChat Methods
|
|
|
|
| Method | Description | Arguments | Returns |
|
|
|--------|-------------|-----------|---------|
|
|
| run | Run single conversation | task: str | ChatHistory |
|
|
| batched_run | Run multiple sequential tasks | tasks: List[str] | List[ChatHistory] |
|
|
| concurrent_run | Run multiple parallel tasks | tasks: List[str] | List[ChatHistory] |
|
|
| get_recent_messages | Get recent messages | n: int = 3 | List[str] |
|
|
|
|
### Agent Methods
|
|
|
|
| Method | Description | Returns |
|
|
|--------|-------------|---------|
|
|
| run | Process single task | str |
|
|
| generate_response | Generate LLM response | str |
|
|
| save_context | Save conversation context | None | |