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.
256 lines
14 KiB
256 lines
14 KiB
# 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 | Example Configuration |
|
|
|------------|----------|------------|---------------------|
|
|
| `AgentRearrange` | Dynamic workflows | - Complex task decomposition<br>- Adaptive processing<br>- Multi-stage analysis<br>- Dynamic resource allocation | ```python<br>{"swarm_type": "AgentRearrange",<br> "rearrange_flow": "optimize for efficiency",<br> "max_loops": 3}``` |
|
|
| `MixtureOfAgents` | Diverse expertise | - Cross-domain problems<br>- Comprehensive analysis<br>- Multi-perspective tasks<br>- Research synthesis | ```python<br>{"swarm_type": "MixtureOfAgents",<br> "agents": [{"role": "researcher"},<br> {"role": "analyst"},<br> {"role": "writer"}]}``` |
|
|
| `SpreadSheetSwarm` | Data processing | - Financial analysis<br>- Data transformation<br>- Batch calculations<br>- Report generation | ```python<br>{"swarm_type": "SpreadSheetSwarm",<br> "data_format": "csv",<br> "analysis_type": "financial"}``` |
|
|
| `SequentialWorkflow` | Linear processes | - Document processing<br>- Step-by-step analysis<br>- Quality control<br>- Content pipeline | ```python<br>{"swarm_type": "SequentialWorkflow",<br> "steps": ["research", "draft",<br> "review", "finalize"]}``` |
|
|
| `ConcurrentWorkflow` | Parallel tasks | - Batch processing<br>- Independent analyses<br>- High-throughput needs<br>- Multi-market analysis | ```python<br>{"swarm_type": "ConcurrentWorkflow",<br> "max_parallel": 5,<br> "batch_size": 10}``` |
|
|
| `GroupChat` | Collaborative solving | - Brainstorming<br>- Decision making<br>- Problem solving<br>- Strategy development | ```python<br>{"swarm_type": "GroupChat",<br> "participants": ["expert1", "expert2"],<br> "discussion_rounds": 3}``` |
|
|
| `MultiAgentRouter` | Task distribution | - Load balancing<br>- Specialized processing<br>- Resource optimization<br>- Service routing | ```python<br>{"swarm_type": "MultiAgentRouter",<br> "routing_strategy": "skill_based",<br> "fallback_agent": "general"}``` |
|
|
| `AutoSwarmBuilder` | Automated setup | - Quick prototyping<br>- Simple tasks<br>- Testing<br>- MVP development | ```python<br>{"swarm_type": "AutoSwarmBuilder",<br> "complexity": "medium",<br> "optimize_for": "speed"}``` |
|
|
| `HiearchicalSwarm` | Complex organization | - Project management<br>- Research analysis<br>- Enterprise workflows<br>- Team automation | ```python<br>{"swarm_type": "HiearchicalSwarm",<br> "levels": ["manager", "specialist",<br> "worker"]}``` |
|
|
| `MajorityVoting` | Consensus needs | - Quality assurance<br>- Decision validation<br>- Risk assessment<br>- Content moderation | ```python<br>{"swarm_type": "MajorityVoting",<br> "min_votes": 3,<br> "threshold": 0.7}``` |
|
|
|
|
=== "Application Patterns"
|
|
|
|
!!! tip "Specialized Application Configurations"
|
|
|
|
| Application | Recommended Swarm | Configuration Example | Benefits |
|
|
|------------|-------------------|----------------------|-----------|
|
|
| **Team Automation** | `HiearchicalSwarm` | ```python<br>{<br> "swarm_type": "HiearchicalSwarm",<br> "agents": [<br> {"role": "ProjectManager",<br> "responsibilities": ["planning", "coordination"]},<br> {"role": "TechLead",<br> "responsibilities": ["architecture", "review"]},<br> {"role": "Developers",<br> "count": 3,<br> "specializations": ["frontend", "backend", "testing"]}<br> ]<br>}``` | - Automated team coordination<br>- Clear responsibility chain<br>- Scalable team structure |
|
|
| **Research Pipeline** | `SequentialWorkflow` | ```python<br>{<br> "swarm_type": "SequentialWorkflow",<br> "pipeline": [<br> {"stage": "Literature Review",<br> "agent_type": "Researcher"},<br> {"stage": "Data Analysis",<br> "agent_type": "Analyst"},<br> {"stage": "Report Generation",<br> "agent_type": "Writer"}<br> ]<br>}``` | - Structured research process<br>- Quality control at each stage<br>- Comprehensive output |
|
|
| **Trading System** | `ConcurrentWorkflow` | ```python<br>{<br> "swarm_type": "ConcurrentWorkflow",<br> "agents": [<br> {"market": "crypto",<br> "strategy": "momentum"},<br> {"market": "forex",<br> "strategy": "mean_reversion"},<br> {"market": "stocks",<br> "strategy": "value"}<br> ]<br>}``` | - Multi-market coverage<br>- Real-time analysis<br>- Risk distribution |
|
|
| **Content Factory** | `MixtureOfAgents` | ```python<br>{<br> "swarm_type": "MixtureOfAgents",<br> "workflow": [<br> {"role": "Researcher",<br> "focus": "topic_research"},<br> {"role": "Writer",<br> "style": "engaging"},<br> {"role": "Editor",<br> "quality_standards": "high"}<br> ]<br>}``` | - Automated content creation<br>- Consistent quality<br>- High throughput |
|
|
|
|
=== "Cost Optimization"
|
|
|
|
!!! tip "Advanced Cost Management Strategies"
|
|
|
|
| Strategy | Implementation | Impact | Configuration Example |
|
|
|----------|----------------|---------|---------------------|
|
|
| Batch Processing | Group related tasks | 20-30% cost reduction | ```python<br>{"batch_size": 10,<br> "parallel_execution": true,<br> "deduplication": true}``` |
|
|
| Off-peak Usage | Schedule for 8 PM - 6 AM PT | 15-25% cost reduction | ```python<br>{"schedule": "0 20 * * *",<br> "timezone": "America/Los_Angeles"}``` |
|
|
| Token Optimization | Precise prompts, focused tasks | 10-20% cost reduction | ```python<br>{"max_tokens": 2000,<br> "compression": true,<br> "cache_similar": true}``` |
|
|
| Caching | Store reusable results | 30-40% cost reduction | ```python<br>{"cache_ttl": 3600,<br> "similarity_threshold": 0.95}``` |
|
|
| Agent Optimization | Use minimum required agents | 15-25% cost reduction | ```python<br>{"auto_scale": true,<br> "min_agents": 2,<br> "max_agents": 5}``` |
|
|
| Smart Routing | Route to specialized agents | 10-15% cost reduction | ```python<br>{"routing_strategy": "cost_effective",<br> "fallback": "general"}``` |
|
|
| Prompt Engineering | Optimize input tokens | 15-20% cost reduction | ```python<br>{"prompt_template": "focused",<br> "remove_redundancy": true}``` |
|
|
|
|
=== "Industry Solutions"
|
|
|
|
!!! example "Industry-Specific Swarm Patterns"
|
|
|
|
| Industry | Swarm Pattern | Configuration | Use Case |
|
|
|----------|---------------|---------------|-----------|
|
|
| **Finance** | ```python<br>{<br> "swarm_type": "HiearchicalSwarm",<br> "agents": [<br> {"role": "RiskManager",<br> "models": ["risk_assessment"]},<br> {"role": "MarketAnalyst",<br> "markets": ["stocks", "crypto"]},<br> {"role": "Trader",<br> "strategies": ["momentum", "value"]}<br> ]<br>}``` | - Portfolio management<br>- Risk assessment<br>- Market analysis<br>- Trading execution | Automated trading desk |
|
|
| **Healthcare** | ```python<br>{<br> "swarm_type": "SequentialWorkflow",<br> "workflow": [<br> {"stage": "PatientIntake",<br> "agent": "DataCollector"},<br> {"stage": "Diagnosis",<br> "agent": "DiagnosticsSpecialist"},<br> {"stage": "Treatment",<br> "agent": "TreatmentPlanner"}<br> ]<br>}``` | - Patient analysis<br>- Diagnostic support<br>- Treatment planning<br>- Follow-up care | Clinical workflow automation |
|
|
| **Legal** | ```python<br>{<br> "swarm_type": "MixtureOfAgents",<br> "team": [<br> {"role": "Researcher",<br> "expertise": "case_law"},<br> {"role": "Analyst",<br> "expertise": "contracts"},<br> {"role": "Reviewer",<br> "expertise": "compliance"}<br> ]<br>}``` | - Document review<br>- Case analysis<br>- Contract review<br>- Compliance checks | Legal document processing |
|
|
| **E-commerce** | ```python<br>{<br> "swarm_type": "ConcurrentWorkflow",<br> "processes": [<br> {"task": "ProductCatalog",<br> "agent": "ContentManager"},<br> {"task": "PricingOptimization",<br> "agent": "PricingAnalyst"},<br> {"task": "CustomerService",<br> "agent": "SupportAgent"}<br> ]<br>}``` | - Product management<br>- Pricing optimization<br>- Customer support<br>- Inventory management | E-commerce operations |
|
|
|
|
=== "Error Handling"
|
|
|
|
!!! warning "Advanced Error Management Strategies"
|
|
|
|
| Error Code | Strategy | Implementation | Recovery Pattern |
|
|
|------------|----------|----------------|------------------|
|
|
| 400 | Input Validation | Pre-request parameter checks | ```python<br>{"validation": "strict",<br> "retry_on_fix": true}``` |
|
|
| 401 | Auth Management | Regular key rotation, secure storage | ```python<br>{"key_rotation": "7d",<br> "backup_keys": true}``` |
|
|
| 429 | Rate Limiting | Exponential backoff, request queuing | ```python<br>{"backoff_factor": 2,<br> "max_retries": 5}``` |
|
|
| 500 | Resilience | Retry with backoff, fallback logic | ```python<br>{"circuit_breaker": true,<br> "fallback_mode": "degraded"}``` |
|
|
| 503 | High Availability | Multi-region setup, redundancy | ```python<br>{"regions": ["us", "eu"],<br> "failover": true}``` |
|
|
| 504 | Timeout Handling | Adaptive timeouts, partial results | ```python<br>{"timeout_strategy": "adaptive",<br> "partial_results": true}``` |
|
|
|
|
## 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) |