# Quick Start Guide

This guide will help you create your first Multi-Swarm agency with multiple collaborative agents.

## Basic Example

Here's a simple example to get you started:

```python
from multi_swarm import Agency, Agent

# Create specialized agents
researcher = Agent(
    name="Researcher",
    description="Research and knowledge gathering specialist"
    # Framework will automatically use claude-3-5-opus-latest for research
)

developer = Agent(
    name="Developer",
    description="Technical implementation specialist"
    # Framework will automatically use claude-3-5-sonnet-latest for code
)

operator = Agent(
    name="Operator",
    description="System operations and monitoring specialist"
    # Framework will automatically use gemini-2.0-flash-exp for operations
)

# Create agency with communication flows
agency = Agency(
    name="ResearchAgency",
    description="Research and development agency",
    agents=[researcher, developer, operator],
    flows=[
        [researcher, developer],  # Researcher can communicate with Developer
        [developer, operator],    # Developer can communicate with Operator
        [operator, researcher]    # Operator can communicate with Researcher
    ],
    use_rag=True,  # Enable RAG capabilities
    use_file_storage=True  # Enable file storage
)

# Run the agency
agency.run()
```

## Key Components

### 1. Agents

Each agent has specific roles and capabilities. The framework automatically selects the most appropriate model based on the agent's description:

```python
agent = Agent(
    name="MyAgent",
    description="Agent description"  # Used to determine the best model
)

# Or explicitly specify provider while letting framework choose model
agent = Agent(
    name="MyAgent",
    description="Agent description",
    llm_provider="claude"  # Will use appropriate Claude model
)

# Or fully customize the configuration
agent = Agent(
    name="MyAgent",
    description="Agent description",
    llm_provider="claude",
    provider_config={
        "model": "model_name",
        "api_version": "api_version",
        "max_tokens": 4096
    }
)
```

### 2. Configuration Management

As of version 1.0.5, you can manage model configurations centrally:

```python
from multi_swarm.utils.config_manager import ConfigManager

# Initialize configuration manager
config_manager = ConfigManager()

# Update model configuration
config_manager.update_model(
    provider="claude",
    model_name="custom-model",
    model_config={
        "name": "custom-model",
        "provider": "claude",
        "api_version": "2024-03",
        "max_tokens": 4096
    }
)

# Set task preferences
config_manager.update_task_preference(
    provider="claude",
    task="custom_task",
    model_name="custom-model"
)
```

### 3. Communication Flows

Define how agents interact:

```python
flows = [
    [agent1, agent2],  # agent1 can communicate with agent2
    [agent2, agent3],  # agent2 can communicate with agent3
    # ... more flows
]
```

### 4. Knowledge Management

Enable RAG (Retrieval-Augmented Generation):

```python
# Add knowledge
agency.add_to_shared_knowledge(
    content="Important information",
    metadata={"source": "document", "date": "2024-03-01"}
)

# Search knowledge
results = agency.search_knowledge_with_coordination(
    query="search query",
    coordinating_agents=["Agent1", "Agent2"]
)
```

### 5. File Management

Handle files within the agency:

```python
# Upload file
with open("document.pdf", "rb") as f:
    agency.upload_file(
        file=f,
        filename="document.pdf",
        purpose="research",
        metadata={"type": "pdf", "author": "John Doe"}
    )
```

## Advanced Features

### 1. Task-Specific Model Selection

The framework automatically selects the best model based on the agent's role:

```python
# For code generation tasks
code_agent = Agent(
    name="CodeGenerator",
    description="Generates and reviews code",
    llm_provider="claude",  # Will use claude-3-5-sonnet-latest
)

# For research tasks
research_agent = Agent(
    name="Researcher",
    description="Conducts research and analysis",
    llm_provider="claude",  # Will use claude-3-5-opus-latest
)

# For real-time operations
ops_agent = Agent(
    name="Operator",
    description="Handles system operations",
    llm_provider="gemini",  # Will use gemini-2.0-flash-exp
)
```

### 2. Knowledge Coordination

Enable sophisticated knowledge sharing:

```python
# Add knowledge with distribution
agency.add_to_shared_knowledge(
    content="Technical documentation",
    metadata={
        "type": "documentation",
        "created_at": datetime.now(UTC),
        "confidence": "high"
    },
    target_agents=["Developer", "Researcher"]
)

# Search with coordination
results = agency.search_knowledge_with_coordination(
    query="system architecture",
    k=5,
    coordinating_agents=["Researcher", "Developer"]
)

# Access synthesis
synthesis = results["synthesis"]
print("Confidence Score:", synthesis["confidence_score"])
print("Knowledge Gaps:", synthesis["knowledge_gaps"])
print("Recommendations:", synthesis["recommendations"])
```

### 3. State Management

Save and load agency state:

```python
# Save state
agency.save_state("agency_state.json")

# Load state
agency.load_state("agency_state.json")
```

### 4. Message Broadcasting

Send messages to multiple agents:

```python
# Broadcast from researcher to all connected agents
agency.broadcast_message(
    source="Researcher",
    content="Important update: New research findings",
    metadata={"priority": "high"}
)
```

## Best Practices

1. **Agent Design**
   - Give agents focused responsibilities
   - Use descriptive names and roles
   - Configure appropriate models for tasks

2. **Communication Flows**
   - Design clear communication paths
   - Avoid circular dependencies
   - Use broadcasting judiciously

3. **Knowledge Management**
   - Add metadata to knowledge
   - Use coordinated search for complex queries
   - Monitor knowledge gaps

4. **Error Handling**
   ```python
   try:
       results = agency.search_knowledge_with_coordination(query="search")
   except Exception as e:
       if "RAG not enabled" in str(e):
           # Enable RAG and retry
           agency.config.use_rag = True
           results = agency.search_knowledge_with_coordination(query="search")
   ```

## Next Steps

- Learn about [Core Concepts](concepts.md)
- Explore [Advanced Features](../api/core.md)
- Check out [Real-world Examples](../examples/advanced.md) 