swarms/docs/swarms_cloud/best_practices.md

# Swarms API Best Practices Guide

This comprehensive guide outlines production-grade best practices for using the Swarms API effectively. Learn how to choose the right swarm architecture, optimize costs, and implement robust error handling.

## Quick Reference Cards

=== "Swarm Types"
    
    !!! info "Available Swarm Architectures"
        
        | Swarm Type | Best For | Use Cases |
        |------------|----------|------------|
        | `AgentRearrange` | Dynamic workflows | - Complex task decomposition<br>- Adaptive processing<br>- Multi-stage analysis |
        | `MixtureOfAgents` | Diverse expertise | - Cross-domain problems<br>- Comprehensive analysis<br>- Multi-perspective tasks |
        | `SpreadSheetSwarm` | Data processing | - Financial analysis<br>- Data transformation<br>- Batch calculations |
        | `SequentialWorkflow` | Linear processes | - Document processing<br>- Step-by-step analysis<br>- Quality control |
        | `ConcurrentWorkflow` | Parallel tasks | - Batch processing<br>- Independent analyses<br>- High-throughput needs |
        | `GroupChat` | Collaborative solving | - Brainstorming<br>- Decision making<br>- Problem solving |
        | `MultiAgentRouter` | Task distribution | - Load balancing<br>- Specialized processing<br>- Resource optimization |
        | `AutoSwarmBuilder` | Automated setup | - Quick prototyping<br>- Simple tasks<br>- Testing |
        | `HiearchicalSwarm` | Complex organization | - Project management<br>- Research analysis<br>- Enterprise workflows |
        | `MajorityVoting` | Consensus needs | - Quality assurance<br>- Decision validation<br>- Risk assessment |

=== "Cost Optimization"

    !!! tip "Cost Management Strategies"
        
        | Strategy | Implementation | Impact |
        |----------|----------------|---------|
        | Batch Processing | Group related tasks | 20-30% cost reduction |
        | Off-peak Usage | Schedule for 8 PM - 6 AM PT | 15-25% cost reduction |
        | Token Optimization | Precise prompts, focused tasks | 10-20% cost reduction |
        | Caching | Store reusable results | 30-40% cost reduction |
        | Agent Optimization | Use minimum required agents | 15-25% cost reduction |

=== "Error Handling"

    !!! warning "Error Management Best Practices"
        
        | Error Code | Strategy | Implementation |
        |------------|----------|----------------|
        | 400 | Input Validation | Pre-request parameter checks |
        | 401 | Auth Management | Regular key rotation, secure storage |
        | 429 | Rate Limiting | Exponential backoff, request queuing |
        | 500 | Resilience | Retry with backoff, fallback logic |
        | 503 | High Availability | Multi-region setup, redundancy |

## Choosing the Right Swarm Architecture

### Decision Framework

Use this framework to select the optimal swarm architecture for your use case:

1. **Task Complexity Analysis**
    - Simple tasks → `AutoSwarmBuilder`
    
    - Complex tasks → `HiearchicalSwarm` or `MultiAgentRouter`
    
    - Dynamic tasks → `AgentRearrange`

2. **Workflow Pattern**
    
    - Linear processes → `SequentialWorkflow`
    
    - Parallel operations → `ConcurrentWorkflow`
    
    - Collaborative tasks → `GroupChat`

3. **Domain Requirements**
    
    - Multi-domain expertise → `MixtureOfAgents`
    
    - Data processing → `SpreadSheetSwarm`
    
    - Quality assurance → `MajorityVoting`

### Industry-Specific Recommendations

=== "Finance"
    
    !!! example "Financial Applications"
        
        
        - Risk Analysis: `HiearchicalSwarm`
        
        - Market Research: `MixtureOfAgents`
        
        - Trading Strategies: `ConcurrentWorkflow`
        
        - Portfolio Management: `SpreadSheetSwarm`

=== "Healthcare"
    
    !!! example "Healthcare Applications"
        
        
        - Patient Analysis: `SequentialWorkflow`
        
        - Research Review: `MajorityVoting`
        
        - Treatment Planning: `GroupChat`
        
        - Medical Records: `MultiAgentRouter`

=== "Legal"
    
    !!! example "Legal Applications"
        
        
        - Document Review: `SequentialWorkflow`
        
        - Case Analysis: `MixtureOfAgents`
        
        - Compliance Check: `HiearchicalSwarm`
        
        - Contract Analysis: `ConcurrentWorkflow`

## Production Implementation Guide

### Authentication Best Practices

```python
import os
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Secure API key management
API_KEY = os.getenv("SWARMS_API_KEY")
if not API_KEY:
    raise EnvironmentError("API key not found")

# Headers with retry capability
headers = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}
```

### Robust Error Handling

```python
import backoff
import requests
from typing import Dict, Any

class SwarmsAPIError(Exception):
    """Custom exception for Swarms API errors"""
    pass

@backoff.on_exception(
    backoff.expo,
    (requests.exceptions.RequestException, SwarmsAPIError),
    max_tries=5
)
def execute_swarm(payload: Dict[str, Any]) -> Dict[str, Any]:
    """
    Execute swarm with robust error handling and retries
    """
    try:
        response = requests.post(
            f"{BASE_URL}/v1/swarm/completions",
            headers=headers,
            json=payload,
            timeout=30
        )
        
        response.raise_for_status()
        return response.json()
        
    except requests.exceptions.RequestException as e:
        if e.response is not None:
            if e.response.status_code == 429:
                # Rate limit exceeded
                raise SwarmsAPIError("Rate limit exceeded")
            elif e.response.status_code == 401:
                # Authentication error
                raise SwarmsAPIError("Invalid API key")
        raise SwarmsAPIError(f"API request failed: {str(e)}")
```


## Appendix

### Common Patterns and Anti-patterns

!!! success "Recommended Patterns"
    
    - Use appropriate swarm types for tasks
    
    - Implement robust error handling
    
    - Monitor and log executions
    
    - Cache repeated results
    
    - Rotate API keys regularly

!!! danger "Anti-patterns to Avoid"
    
    
    - Hardcoding API keys
    
    - Ignoring rate limits
    
    - Missing error handling
    
    
    - Excessive agent count
    
    - Inadequate monitoring

### Performance Benchmarks

!!! note "Typical Performance Metrics"
    
    | Metric | Target Range | Warning Threshold |
    |--------|--------------|-------------------|
    | Response Time | < 2s | > 5s |
    | Success Rate | > 99% | < 95% |
    | Cost per Task | < $0.05 | > $0.10 |
    | Cache Hit Rate | > 80% | < 60% |
    | Error Rate | < 1% | > 5% |

### Additional Resources

!!! info "Useful Links"
    
    - [Swarms API Documentation](https://docs.swarms.world)
    - [API Dashboard](https://swarms.world/platform/api-keys)