ai-mirow-projects
/
swarms
mirror of https://github.com/kyegomez/swarms
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

[DOCS][Cleanup Swarms API Un-used docs which are all on docs.swarms.ai]

Browse Source
pull/1078/head
Kye Gomez 1 month ago
parent fc72304491
commit 9068b7f061
32 changed files with 0 additions and 10054 deletions
Show Stats Download Patch File Download Diff File

36
docs/mkdocs.yml
Unescape View File

@ -336,12 +336,6 @@ nav:
- Social Media:
- Twitter: "swarms_tools/twitter.md"
# - Memory:
# - Overview: "swarms_memory/index.md"
# - Memory Systems:
# - ChromaDB: "swarms_memory/chromadb.md"
# - Pinecone: "swarms_memory/pinecone.md"
# - Faiss: "swarms_memory/faiss.md"
- Deployment Solutions:
- Overview: "deployment_solutions/overview.md"
@ -399,15 +393,6 @@ nav:
# - Swarms Tools:
# - Agent with Yahoo Finance: "swarms/examples/yahoo_finance.md"
# - Twitter Agents: "swarms_tools/twitter.md"
# - Blockchain Agents:
# - Agent with HTX + CoinGecko: "swarms/examples/swarms_tools_htx.md"
# - Agent with HTX + CoinGecko Function Calling: "swarms/examples/swarms_tools_htx_gecko.md"
# - Lumo: "swarms/examples/lumo.md"
# - Quant Crypto Agent: "swarms/examples/quant_crypto_agent.md"
- Advanced Examples:
- Multi-Agent Architectures:
- HierarchicalSwarm Examples: "swarms/examples/hierarchical_swarm_example.md"
@ -450,27 +435,6 @@ nav:
- Overview: "swarms_cloud/migration.md"
# - Capabilities:
# - Agents:
# - Individual Agent Completions: "swarms_cloud/agent_api.md"
# - Tools: "swarms_cloud/swarms_api_tools.md"
# - Multi-Agent:
# - Multi Agent Architectures Available: "swarms_cloud/swarm_types.md"
# - Swarm Types:
# - AgentRearrange: "swarms_cloud/agent_rearrange.md"
# - MixtureOfAgents: "swarms_cloud/mixture_of_agents.md"
# - SequentialWorkflow: "swarms_cloud/sequential_workflow.md"
# - ConcurrentWorkflow: "swarms_cloud/concurrent_workflow.md"
# - GroupChat: "swarms_cloud/group_chat.md"
# - MultiAgentRouter: "swarms_cloud/multi_agent_router.md"
# - HierarchicalSwarm: "swarms_cloud/hierarchical_swarm.md"
# - MajorityVoting: "swarms_cloud/majority_voting.md"
# # - AutoSwarmBuilder: "swarms_cloud/auto_swarm_builder.md"
# # - Auto: "swarms_cloud/auto.md"
# - Examples:
# - Medical Swarm: "swarms/examples/swarms_api_medical.md"
# - Finance Swarm: "swarms/examples/swarms_api_finance.md"
- Swarms Marketplace:
- Overview: "swarms_platform/index.md"
- Marketplace:

127
docs/swarms/examples/swarms_api_finance.md
Unescape View File

@ -1,127 +0,0 @@
# Finance Swarm Example
1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys)
2. Create a `.env` file in the root directory and add your API key:
```bash
SWARMS_API_KEY=<your-api-key>
```
3. Create a Python script to create and trigger the financial swarm:
```python
import os
import requests
from dotenv import load_dotenv
import json
load_dotenv()
# Retrieve API key securely from .env
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
# Headers for secure API communication
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
def create_financial_swarm(equity_data: str):
"""
Constructs and triggers a full-stack financial swarm consisting of three agents:
Equity Analyst, Risk Assessor, and Market Advisor.
Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability.
"""
payload = {
"swarm_name": "Enhanced Financial Analysis Swarm",
"description": "A swarm of agents specialized in performing comprehensive financial analysis, risk assessment, and market recommendations.",
"agents": [
{
"agent_name": "Equity Analyst",
"description": "Agent specialized in analyzing equities data to provide insights on stock performance and valuation.",
"system_prompt": (
"You are an experienced equity analyst with expertise in financial markets and stock valuation. "
"Your role is to analyze the provided equities data, including historical performance, financial statements, and market trends. "
"Provide a detailed analysis of the stock's potential, including valuation metrics and growth prospects. "
"Consider macroeconomic factors, industry trends, and company-specific news. Your analysis should be clear, actionable, and well-supported by data."
),
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 4000,
"temperature": 0.3,
"auto_generate_prompt": False
},
{
"agent_name": "Risk Assessor",
"description": "Agent responsible for evaluating the risks associated with equity investments.",
"system_prompt": (
"You are a certified risk management professional with expertise in financial risk assessment. "
"Your task is to evaluate the risks associated with the provided equities data, including market risk, credit risk, and operational risk. "
"Provide a comprehensive risk analysis, including potential scenarios and their impact on investment performance. "
"Your output should be detailed, reliable, and compliant with current risk management standards."
),
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 3000,
"temperature": 0.2,
"auto_generate_prompt": False
},
{
"agent_name": "Market Advisor",
"description": "Agent dedicated to suggesting investment strategies based on market conditions and equity analysis.",
"system_prompt": (
"You are a knowledgeable market advisor with expertise in investment strategies and portfolio management. "
"Based on the analysis provided by the Equity Analyst and the risk assessment, your task is to recommend a comprehensive investment strategy. "
"Your suggestions should include asset allocation, diversification strategies, and considerations for market conditions. "
"Explain the rationale behind each recommendation and reference relevant market data where applicable. "
"Your recommendations should be reliable, detailed, and clearly prioritized based on risk and return."
),
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 5000,
"temperature": 0.3,
"auto_generate_prompt": False
}
],
"max_loops": 1,
"swarm_type": "SequentialWorkflow",
"task": equity_data,
}
# Payload includes the equity data as the task to be processed by the swarm
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload,
)
if response.status_code == 200:
print("Swarm successfully executed!")
return json.dumps(response.json(), indent=4)
else:
print(f"Error {response.status_code}: {response.text}")
return None
# Example Equity Data for the Swarm to analyze
if __name__ == "__main__":
equity_data = (
"Analyze the equity data for Company XYZ, which has shown a 15% increase in revenue over the last quarter, "
"with a P/E ratio of 20 and a market cap of $1 billion. Consider the current market conditions and potential risks."
)
financial_output = create_financial_swarm(equity_data)
print(financial_output)
```
4. Run the script:
```bash
python financial_swarm.py
```

128
docs/swarms/examples/swarms_api_medical.md
Unescape View File

@ -1,128 +0,0 @@
# Medical Swarm Example
1. Get your API key from the Swarms API dashboard [HERE](https://swarms.world/platform/api-keys)
2. Create a `.env` file in the root directory and add your API key:
```bash
SWARMS_API_KEY=<your-api-key>
```
3. Create a Python script to create and trigger the medical swarm:
```python
import os
import requests
from dotenv import load_dotenv
import json
load_dotenv()
# Retrieve API key securely from .env
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
# Headers for secure API communication
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
def create_medical_swarm(patient_case: str):
"""
Constructs and triggers a full-stack medical swarm consisting of three agents:
Diagnostic Specialist, Medical Coder, and Treatment Advisor.
Each agent is provided with a comprehensive, detailed system prompt to ensure high reliability.
"""
payload = {
"swarm_name": "Enhanced Medical Diagnostic Swarm",
"description": "A swarm of agents specialized in performing comprehensive medical diagnostics, analysis, and coding.",
"agents": [
{
"agent_name": "Diagnostic Specialist",
"description": "Agent specialized in analyzing patient history, symptoms, lab results, and imaging data to produce accurate diagnoses.",
"system_prompt": (
"You are an experienced, board-certified medical diagnostician with over 20 years of clinical practice. "
"Your role is to analyze all available patient information—including history, symptoms, lab tests, and imaging results—"
"with extreme attention to detail and clinical nuance. Provide a comprehensive differential diagnosis considering "
"common, uncommon, and rare conditions. Always cross-reference clinical guidelines and evidence-based medicine. "
"Explain your reasoning step by step and provide a final prioritized list of potential diagnoses along with their likelihood. "
"Consider patient demographics, comorbidities, and risk factors. Your diagnosis should be reliable, clear, and actionable."
),
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 4000,
"temperature": 0.3,
"auto_generate_prompt": False
},
{
"agent_name": "Medical Coder",
"description": "Agent responsible for translating medical diagnoses and procedures into accurate standardized medical codes (ICD-10, CPT, etc.).",
"system_prompt": (
"You are a certified and experienced medical coder, well-versed in ICD-10, CPT, and other coding systems. "
"Your task is to convert detailed medical diagnoses and treatment procedures into precise, standardized codes. "
"Consider all aspects of the clinical documentation including severity, complications, and comorbidities. "
"Provide clear explanations for the codes chosen, referencing the latest coding guidelines and payer policies where relevant. "
"Your output should be comprehensive, reliable, and fully compliant with current medical coding standards."
),
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 3000,
"temperature": 0.2,
"auto_generate_prompt": False
},
{
"agent_name": "Treatment Advisor",
"description": "Agent dedicated to suggesting evidence-based treatment options, including pharmaceutical and non-pharmaceutical interventions.",
"system_prompt": (
"You are a highly knowledgeable medical treatment specialist with expertise in the latest clinical guidelines and research. "
"Based on the diagnostic conclusions provided, your task is to recommend a comprehensive treatment plan. "
"Your suggestions should include first-line therapies, potential alternative treatments, and considerations for patient-specific factors "
"such as allergies, contraindications, and comorbidities. Explain the rationale behind each treatment option and reference clinical guidelines where applicable. "
"Your recommendations should be reliable, detailed, and clearly prioritized based on efficacy and safety."
),
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 5000,
"temperature": 0.3,
"auto_generate_prompt": False
}
],
"max_loops": 1,
"swarm_type": "SequentialWorkflow",
"task": patient_case,
}
# Payload includes the patient case as the task to be processed by the swar
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload,
)
if response.status_code == 200:
print("Swarm successfully executed!")
return json.dumps(response.json(), indent=4)
else:
print(f"Error {response.status_code}: {response.text}")
return None
# Example Patient Task for the Swarm to diagnose and analyze
if __name__ == "__main__":
patient_case = (
"Patient is a 55-year-old male presenting with severe chest pain, shortness of breath, elevated blood pressure, "
"nausea, and a family history of cardiovascular disease. Blood tests show elevated troponin levels, and EKG indicates ST-segment elevations. "
"The patient is currently unstable. Provide a detailed diagnosis, coding, and treatment plan."
)
diagnostic_output = create_medical_swarm(patient_case)
print(diagnostic_output)
```
4. Run the script:
```bash
python medical_swarm.py
```

56
docs/swarms_cloud/add_agent.md
Unescape View File

@ -1,56 +0,0 @@
# Publishing an Agent to Agent Marketplace
## Requirements
- `swarms-cloud` package with `pip3 install -U swarms-cloud`
- Onboarding Process with `swarms-cloud onboarding`
- A Dockerfile `Dockerfile` containing the API of your agent code with FastAPI
- A YAML file for configuration `agent.yaml`
## Deployment YAML
```yaml
# Agent metadata and description
agent_name: "example-agent" # The name of the agent
description: "This agent performs financial data analysis." # A brief description of the agent's purpose
version: "v1.0" # The version number of the agent
author: "Agent Creator Name" # The name of the person or entity that created the agent
contact_email: "creator@example.com" # The email address for contacting the agent's creator
tags:
- "financial" # Tag indicating the agent is related to finance
- "data-analysis" # Tag indicating the agent performs data analysis
- "agent" # Tag indicating this is an agent
# Deployment configuration
deployment_config:
# Dockerfile configuration
dockerfile_path: "./Dockerfile" # The path to the Dockerfile for building the agent's image
dockerfile_port: 8080 # The port number the agent will listen on
# Resource allocation for the agent
resources:
cpu: 2 # Number of CPUs allocated to the agent
memory: "2Gi" # Memory allocation for the agent in gigabytes
max_instances: 5 # Maximum number of instances to scale up to
min_instances: 1 # Minimum number of instances to keep running
timeout: 300s # Request timeout setting in seconds
# Autoscaling configuration
autoscaling:
max_concurrency: 80 # Maximum number of requests the agent can handle concurrently
target_utilization: 0.6 # CPU utilization target for auto-scaling
# Environment variables for the agent
environment_variables:
DATABASE_URL: "postgres://user:password@db-url" # URL for the database connection
API_KEY: "your-secret-api-key" # API key for authentication
LOG_LEVEL: "info" # Log level for the agent
# Secrets configuration
secrets:
SECRET_NAME_1: "projects/my-project/secrets/my-secret/versions/latest" # Path to a secret
```

608
docs/swarms_cloud/agent_api.md
Unescape View File

@ -1,608 +0,0 @@
# Agent API
The Swarms.ai Agent API provides powerful endpoints for running individual AI agents and batch agent operations. This documentation explains how to use these endpoints for effective agent-based task execution.
## Getting Started
To use the Agent API, you'll need a Swarms.ai API key:
1. Go to [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)
2. Generate a new API key
3. Store your API key securely - it won't be shown again
```python
import os
import requests
from dotenv import load_dotenv
# Load API key from environment
load_dotenv()
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
# Configure headers with your API key
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
```
## Individual Agent API
The Individual Agent API allows you to run a single agent with a specific configuration and task.
### Agent Configuration (`AgentSpec`)
The `AgentSpec` class defines the configuration for an individual agent.
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `agent_name` | string | Required | Unique name identifying the agent and its functionality |
| `description` | string | None | Detailed explanation of the agent's purpose and capabilities |
| `system_prompt` | string | None | Initial instructions guiding the agent's behavior and responses |
| `model_name` | string | "gpt-4o-mini" | The AI model used by the agent (e.g., gpt-4o, gpt-4o-mini, openai/o3-mini) |
| `auto_generate_prompt` | boolean | false | Whether the agent should automatically create prompts based on task requirements |
| `max_tokens` | integer | 8192 | Maximum number of tokens the agent can generate in its responses |
| `temperature` | float | 0.5 | Controls output randomness (lower values = more deterministic responses) |
| `role` | string | "worker" | The agent's role within a swarm, influencing its behavior and interactions |
| `max_loops` | integer | 1 | Maximum number of times the agent can repeat its task for iterative processing |
| `tools_dictionary` | array | None | Dictionary of tools the agent can use to complete its task |
| `mcp_url` | string | None | URL for the MCP server that the agent can connect to |
### Agent Completion
The `AgentCompletion` class combines an agent configuration with a specific task.
| Parameter | Type | Description |
|-----------|------|-------------|
| `agent_config` | AgentSpec | Configuration of the agent to be completed |
| `task` | string | The task to be completed by the agent |
| `history` | Optional[Union[Dict[Any, Any], List[Dict[str, str]]]] | The history of the agent's previous tasks and responses. Can be either a dictionary or a list of message objects. |
### Single Agent Endpoint
**Endpoint:** `POST /v1/agent/completions`
Run a single agent with a specific configuration and task.
#### Request
```python
def run_single_agent(agent_config, task):
"""
Run a single agent with the AgentCompletion format.
Args:
agent_config: Dictionary containing agent configuration
task: String describing the task for the agent
Returns:
Dictionary containing the agent's response
"""
payload = {
"agent_config": agent_config,
"task": task
}
try:
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error making request: {e}")
return None
```
#### Example Usage
```python
agent_config = {
"agent_name": "Research Analyst",
"description": "An expert in analyzing and synthesizing research data",
"system_prompt": (
"You are a Research Analyst with expertise in data analysis and synthesis. "
"Your role is to analyze provided information, identify key insights, "
"and present findings in a clear, structured format. "
"Focus on accuracy, clarity, and actionable recommendations."
),
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 2,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False,
}
task = "Analyze the impact of artificial intelligence on healthcare delivery and provide a comprehensive report with key findings and recommendations."
result = run_single_agent(agent_config, task)
print(result)
```
#### Response Structure
```json
{
"id": "agent-6a8b9c0d1e2f3g4h5i6j7k8l9m0n",
"success": true,
"name": "Research Analyst",
"description": "An expert in analyzing and synthesizing research data",
"temperature": 0.5,
"outputs": {
"content": "# Impact of Artificial Intelligence on Healthcare Delivery\n\n## Executive Summary\n...",
"role": "assistant"
},
"usage": {
"input_tokens": 1250,
"output_tokens": 3822,
"total_tokens": 5072
},
"timestamp": "2025-05-10T18:35:29.421Z"
}
```
## Batch Agent API
The Batch Agent API allows you to run multiple agents in parallel, each with different configurations and tasks.
### Batch Agent Endpoint
**Endpoint:** `POST /v1/agent/batch/completions`
Run multiple agents with different configurations and tasks in a single API call.
#### Request
```python
def run_batch_agents(agent_completions):
"""
Run multiple agents in batch.
Args:
agent_completions: List of dictionaries, each containing agent_config and task
Returns:
List of agent responses
"""
try:
response = requests.post(
f"{BASE_URL}/v1/agent/batch/completions",
headers=headers,
json=agent_completions
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error making batch request: {e}")
return None
```
#### Example Usage
```python
batch_completions = [
{
"agent_config": {
"agent_name": "Research Analyst",
"description": "An expert in analyzing research data",
"system_prompt": "You are a Research Analyst...",
"model_name": "gpt-4o",
"max_loops": 2
},
"task": "Analyze the impact of AI on healthcare delivery."
},
{
"agent_config": {
"agent_name": "Market Analyst",
"description": "An expert in market analysis",
"system_prompt": "You are a Market Analyst...",
"model_name": "gpt-4o",
"max_loops": 1
},
"task": "Analyze the AI startup landscape in 2025."
}
]
batch_results = run_batch_agents(batch_completions)
print(batch_results)
```
#### Response Structure
```json
[
{
"id": "agent-1a2b3c4d5e6f7g8h9i0j",
"success": true,
"name": "Research Analyst",
"description": "An expert in analyzing research data",
"temperature": 0.5,
"outputs": {
"content": "# Impact of AI on Healthcare Delivery\n...",
"role": "assistant"
},
"usage": {
"input_tokens": 1250,
"output_tokens": 3822,
"total_tokens": 5072
},
"timestamp": "2025-05-10T18:35:29.421Z"
},
{
"id": "agent-9i8h7g6f5e4d3c2b1a0",
"success": true,
"name": "Market Analyst",
"description": "An expert in market analysis",
"temperature": 0.5,
"outputs": {
"content": "# AI Startup Landscape 2025\n...",
"role": "assistant"
},
"usage": {
"input_tokens": 980,
"output_tokens": 4120,
"total_tokens": 5100
},
"timestamp": "2025-05-10T18:35:31.842Z"
}
]
```
## Error Handling
The API uses standard HTTP status codes to indicate success or failure:
| Status Code | Meaning |
|-------------|---------|
| 200 | Success |
| 400 | Bad Request - Check your request parameters |
| 401 | Unauthorized - Invalid or missing API key |
| 403 | Forbidden - Insufficient permissions |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Something went wrong on the server |
When an error occurs, the response body will contain additional information:
```json
{
"detail": "Error message explaining what went wrong"
}
```
### Common Errors and Solutions
| Error | Possible Solution |
|-------|-------------------|
| "Invalid API Key" | Verify your API key is correct and properly included in the request headers |
| "Rate limit exceeded" | Reduce the number of requests or contact support to increase your rate limit |
| "Invalid agent configuration" | Check your agent_config parameters for any missing or invalid values |
| "Failed to create agent" | Ensure your system_prompt and model_name are valid |
| "Insufficient credits" | Add credits to your account at https://swarms.world/platform/account |
## Advanced Usage
### Setting Dynamic Temperature
The agent can dynamically adjust its temperature for optimal outputs:
```python
agent_config = {
# Other config options...
"temperature": 0.7,
"dynamic_temperature_enabled": True
}
```
### Using Agent Tools
Agents can utilize various tools to enhance their capabilities:
```python
agent_config = {
# Other config options...
"tools_dictionary": [
{
"name": "web_search",
"description": "Search the web for information",
"parameters": {
"query": "string"
}
},
{
"name": "calculator",
"description": "Perform mathematical calculations",
"parameters": {
"expression": "string"
}
}
]
}
```
## Best Practices
!!! tip "API Key Security"
Store API keys in environment variables or secure vaults, never in code repositories.
```python
# DON'T do this
api_key = "sk-123456789abcdef"
# DO this instead
import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.getenv("SWARMS_API_KEY")
```
!!! info "Agent Naming Conventions"
Use a consistent naming pattern for your agents to make your code more maintainable.
```python
# Good naming convention
agent_configs = {
"market_analyst": {...},
"research_specialist": {...},
"code_reviewer": {...}
}
```
!!! success "Crafting Effective System Prompts"
A well-crafted system prompt acts as your agent's personality and instruction set.
=== "Basic Prompt"
```
You are a research analyst. Analyze the data and provide insights.
```
=== "Enhanced Prompt"
```
You are a Research Analyst with 15+ years of experience in biotech market analysis.
Your task is to:
1. Analyze the provided market data methodically
2. Identify key trends and emerging patterns
3. Highlight potential investment opportunities
4. Assess risks and regulatory considerations
5. Provide actionable recommendations supported by the data
Format your response as a professional report with clear sections,
focusing on data-driven insights rather than generalities.
```
!!! warning "Token Management"
Manage your token usage carefully to control costs.
- Higher token limits provide more complete responses but increase costs
- Consider using different models based on task complexity
- For gpt-4o models, typical settings:
- Simple tasks: 2048 tokens (lower cost)
- Medium complexity: 4096 tokens (balanced)
- Complex analysis: 8192+ tokens (higher cost, more detail)
!!! danger "Error Handling"
Implement comprehensive error handling to make your application resilient.
```python
try:
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload,
timeout=30 # Add timeout to prevent hanging requests
)
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 429:
# Implement exponential backoff for rate limiting
retry_after = int(e.response.headers.get('Retry-After', 5))
time.sleep(retry_after)
return run_agent(payload) # Retry the request
elif e.response.status_code == 401:
logger.error("Authentication failed. Check your API key.")
else:
logger.error(f"HTTP Error: {e.response.status_code} - {e.response.text}")
return {"error": e.response.text}
except requests.exceptions.Timeout:
logger.error("Request timed out. The server might be busy.")
return {"error": "Request timed out"}
except requests.exceptions.RequestException as e:
logger.error(f"Request Error: {e}")
return {"error": str(e)}
```
!!! example "Implementing Caching"
Cache identical requests to improve performance and reduce costs.
```python
import hashlib
import json
from functools import lru_cache
def generate_cache_key(agent_config, task):
"""Generate a unique cache key for an agent request."""
cache_data = json.dumps({"agent_config": agent_config, "task": task}, sort_keys=True)
return hashlib.md5(cache_data.encode()).hexdigest()
@lru_cache(maxsize=100)
def cached_agent_run(cache_key, agent_config, task):
"""Run agent with caching based on config and task."""
# Convert agent_config back to a dictionary if it's a string representation
if isinstance(agent_config, str):
agent_config = json.loads(agent_config)
payload = {
"agent_config": agent_config,
"task": task
}
try:
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload
)
response.raise_for_status()
return response.json()
except Exception as e:
return {"error": str(e)}
def run_agent_with_cache(agent_config, task):
"""Wrapper function to run agent with caching."""
# Generate a cache key
cache_key = generate_cache_key(agent_config, task)
# Convert agent_config to a hashable type for lru_cache
hashable_config = json.dumps(agent_config, sort_keys=True)
# Call the cached function
return cached_agent_run(cache_key, hashable_config, task)
```
!!! abstract "Usage & Cost Monitoring"
Set up a monitoring system to track your API usage and costs.
```python
def log_api_usage(api_call_type, tokens_used, cost_estimate):
"""Log API usage for monitoring."""
with open("api_usage_log.csv", "a") as f:
timestamp = datetime.now().isoformat()
f.write(f"{timestamp},{api_call_type},{tokens_used},{cost_estimate}\n")
def estimate_cost(tokens):
"""Estimate cost based on token usage."""
# Example pricing: $0.002 per 1K tokens (adjust according to current pricing)
return (tokens / 1000) * 0.002
def run_agent_with_logging(agent_config, task):
"""Run agent and log usage."""
result = run_single_agent(agent_config, task)
if "usage" in result:
total_tokens = result["usage"]["total_tokens"]
cost = estimate_cost(total_tokens)
log_api_usage("single_agent", total_tokens, cost)
return result
```
## FAQ
??? question "What's the difference between Single Agent and Batch Agent APIs?"
The Single Agent API (`/v1/agent/completions`) runs one agent with one task, while the Batch Agent API (`/v1/agent/batch/completions`) allows running multiple agents with different configurations and tasks in parallel. Use Batch Agent when you need to process multiple independent tasks efficiently.
??? question "How do I choose the right model for my agent?"
Model selection depends on your task complexity, performance requirements, and budget:
| Model | Best For | Characteristics |
|-------|----------|-----------------|
| gpt-4o | Complex analysis, creative tasks | Highest quality, most expensive |
| gpt-4o-mini | General purpose tasks | Good balance of quality and cost |
| openai/o3-mini | Simple, factual tasks | Fast, economical |
For exploratory work, start with gpt-4o-mini and adjust based on results.
??? question "What should I include in my system prompt?"
A good system prompt should include:
1. **Role definition**: Who the agent is and their expertise
2. **Task instructions**: Specific, clear directions on what to do
3. **Output format**: How results should be structured
4. **Constraints**: Any limitations or requirements
5. **Examples**: Sample inputs and outputs when helpful
Keep prompts focused and avoid contradictory instructions.
??? question "How can I optimize costs when using the Agent API?"
Cost optimization strategies include:
- Use the appropriate model for your task complexity
- Set reasonable token limits based on expected output length
- Implement caching for repeated or similar requests
- Batch related requests together
- Use `max_loops: 1` unless you specifically need iterative refinement
- Monitor usage patterns and adjust configurations accordingly
??? question "What's the maximum number of agents I can run in a batch?"
While there's no hard limit specified, we recommend keeping batch sizes under 20 agents for optimal performance. For very large batches, consider splitting them into multiple calls or contacting support for guidance on handling high-volume processing.
??? question "How do I handle rate limiting?"
Implement exponential backoff in your error handling:
```python
import time
def run_with_backoff(func, max_retries=5, initial_delay=1):
"""Run a function with exponential backoff retry logic."""
retries = 0
delay = initial_delay
while retries < max_retries:
try:
return func()
except requests.exceptions.HTTPError as e:
if e.response.status_code == 429: # Too Many Requests
retry_after = int(e.response.headers.get('Retry-After', delay))
print(f"Rate limited. Retrying after {retry_after} seconds...")
time.sleep(retry_after)
retries += 1
delay *= 2 # Exponential backoff
else:
raise
except Exception as e:
raise
raise Exception(f"Failed after {max_retries} retries")
```
??? question "Can I use tools with my agents?"
Yes, you can enable tools through the `tools_dictionary` parameter in your agent configuration. This allows agents to access external functionality like web searches, calculations, or custom tools.
```python
agent_config = {
# Other configuration...
"tools_dictionary": [
{
"name": "web_search",
"description": "Search the web for current information",
"parameters": {
"query": {
"type": "string",
"description": "The search query"
}
}
}
]
}
```
??? question "How do I debug agent performance issues?"
Debugging steps for agent performance issues:
1. **Check system prompts**: Ensure they're clear and not overly restrictive
2. **Review model selection**: Try a more capable model if output quality is poor
3. **Adjust token limits**: Increase max_tokens if outputs are getting truncated
4. **Examine temperature**: Lower for more deterministic outputs, higher for creativity
5. **Test with simpler tasks**: Isolate whether the issue is with the task complexity
6. **Enable verbose logging**: Add detailed logging to track request/response cycles
7. **Contact support**: For persistent issues, reach out with example payloads and responses
??? question "What's the pricing model for the Agent API?"
The Agent API uses a token-based pricing model:
1. **Input tokens**: Text sent to the API (task, system prompts)
2. **Output tokens**: Text generated by the agent
Pricing varies by model and is calculated per 1,000 tokens. Check the [pricing page](https://swarms.world/platform/pricing) for current rates.
The API also offers a "flex" tier for lower-priority, cost-effective processing.
## Further Resources
[:material-file-document: Swarms.ai Documentation](https://docs.swarms.world){ .md-button }
[:material-application: Swarms.ai Platform](https://swarms.world/platform){ .md-button }
[:material-key: API Key Management](https://swarms.world/platform/api-keys){ .md-button }
[:material-forum: Swarms.ai Community](https://discord.gg/EamjgSaEQf){ .md-button }

204
docs/swarms_cloud/agent_rearrange.md
Unescape View File

@ -1,204 +0,0 @@
# AgentRearrange
*Dynamically reorganizes agents to optimize task performance and efficiency*
**Swarm Type**: `AgentRearrange`
## Overview
The AgentRearrange swarm type dynamically reorganizes the workflow between agents based on task requirements and performance metrics. This architecture is particularly useful when the effectiveness of agents depends on their sequence or arrangement, allowing for optimal task distribution and execution flow.
Key features:
- **Dynamic Reorganization**: Automatically adjusts agent order based on task needs
- **Performance Optimization**: Optimizes workflow for maximum efficiency
- **Adaptive Sequencing**: Learns from execution patterns to improve arrangement
- **Flexible Task Distribution**: Distributes work based on agent capabilities
## Use Cases
- Complex workflows where task order matters
- Multi-step processes requiring optimization
- Tasks where agent performance varies by sequence
- Adaptive workflow management systems
## API Usage
### Basic AgentRearrange Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Document Processing Rearrange",
"description": "Process documents with dynamic agent reorganization",
"swarm_type": "AgentRearrange",
"task": "Analyze this legal document and extract key insights, then summarize findings and identify action items",
"agents": [
{
"agent_name": "Document Analyzer",
"description": "Analyzes document content and structure",
"system_prompt": "You are an expert document analyst. Extract key information, themes, and insights from documents.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Legal Expert",
"description": "Provides legal context and interpretation",
"system_prompt": "You are a legal expert. Analyze documents for legal implications, risks, and compliance issues.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Summarizer",
"description": "Creates concise summaries and action items",
"system_prompt": "You are an expert at creating clear, actionable summaries from complex information.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.4
}
],
"rearrange_flow": "Summarizer -> Legal Expert -> Document Analyzer",
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Document Processing Rearrange",
"description": "Process documents with dynamic agent reorganization",
"swarm_type": "AgentRearrange",
"task": "Analyze this legal document and extract key insights, then summarize findings and identify action items",
"agents": [
{
"agent_name": "Document Analyzer",
"description": "Analyzes document content and structure",
"system_prompt": "You are an expert document analyst. Extract key information, themes, and insights from documents.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Legal Expert",
"description": "Provides legal context and interpretation",
"system_prompt": "You are a legal expert. Analyze documents for legal implications, risks, and compliance issues.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Summarizer",
"description": "Creates concise summaries and action items",
"system_prompt": "You are an expert at creating clear, actionable summaries from complex information.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.4
}
],
"rearrange_flow": "Summarizer -> Legal Expert -> Document Analyzer",
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("AgentRearrange swarm completed successfully!")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Output: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-Uc8R7UcepLmNNPwcU7JC6YPy5wiI",
"status": "success",
"swarm_name": "Document Processing Rearrange",
"description": "Process documents with dynamic agent reorganization",
"swarm_type": "AgentRearrange",
"output": [
{
"role": "Summarizer",
"content": "\"Of course! Please provide the legal document you would like me to analyze, and I'll help extract key insights, summarize findings, and identify any action items.\""
},
{
"role": "Legal Expert",
"content": "\"\"Absolutely! Please upload or describe the legal document you need assistance with, and I'll provide an analysis that highlights key insights, summarizes the findings, and identifies any action items that may be necessary.\"\""
},
{
"role": "Document Analyzer",
"content": "\"Of course! Please provide the legal document you would like me to analyze, and I'll help extract key insights, summarize findings, and identify any action items.\""
}
],
"number_of_agents": 3,
"service_tier": "standard",
"execution_time": 7.898931264877319,
"usage": {
"input_tokens": 22,
"output_tokens": 144,
"total_tokens": 166,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.03,
"input_token_cost": 0.000066,
"output_token_cost": 0.00216,
"token_counts": {
"total_input_tokens": 22,
"total_output_tokens": 144,
"total_tokens": 166
},
"num_agents": 3,
"service_tier": "standard",
"night_time_discount_applied": true
},
"total_cost": 0.032226,
"discount_active": true,
"discount_type": "night_time",
"discount_percentage": 75
}
}
}
```
## Configuration Options
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `rearrange_flow` | string | Instructions for how agents should be rearranged | None |
| `agents` | Array<AgentSpec> | List of agents to be dynamically arranged | Required |
| `max_loops` | integer | Maximum rearrangement iterations | 1 |
## Best Practices
- Provide clear `rearrange_flow` instructions for optimal reorganization
- Design agents with complementary but flexible roles
- Use when task complexity requires adaptive sequencing
- Monitor execution patterns to understand rearrangement decisions
## Related Swarm Types
- [SequentialWorkflow](sequential_workflow.md) - For fixed sequential processing
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic swarm construction
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured agent hierarchies

242
docs/swarms_cloud/api_clients.md
Unescape View File

@ -1,242 +0,0 @@
# Swarms API Clients
*Production-Ready Client Libraries for Every Programming Language*
## Overview
The Swarms API provides official client libraries across multiple programming languages, enabling developers to integrate powerful multi-agent AI capabilities into their applications with ease. Our clients are designed for production use, featuring robust error handling, comprehensive documentation, and seamless integration with existing codebases.
Whether you're building enterprise applications, research prototypes, or innovative AI products, our client libraries provide the tools you need to harness the full power of the Swarms platform.
## Available Clients
| Language | Status | Repository | Documentation | Description |
|----------|--------|------------|---------------|-------------|
| **Python** | ✅ **Available** | [swarms-sdk](https://github.com/The-Swarm-Corporation/swarms-sdk) | [Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) | Production-grade Python client with comprehensive error handling, retry logic, and extensive examples |
| **TypeScript/Node.js** | ✅ **Available** | [swarms-ts](https://github.com/The-Swarm-Corporation/swarms-ts) | 📚 *Coming Soon* | Modern TypeScript client with full type safety, Promise-based API, and Node.js compatibility |
| **Go** | ✅ **Available** | [swarms-client-go](https://github.com/The-Swarm-Corporation/swarms-client-go) | 📚 *Coming Soon* | High-performance Go client optimized for concurrent operations and microservices |
| **Java** | ✅ **Available** | [swarms-java](https://github.com/The-Swarm-Corporation/swarms-java) | 📚 *Coming Soon* | Enterprise Java client with Spring Boot integration and comprehensive SDK features |
| **Kotlin** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Modern Kotlin client with coroutines support and Android compatibility |
| **Ruby** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Elegant Ruby client with Rails integration and gem packaging |
| **Rust** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | Ultra-fast Rust client with memory safety and zero-cost abstractions |
| **C#/.NET** | 🚧 **Coming Soon** | *In Development* | 📚 *Coming Soon* | .NET client with async/await support and NuGet packaging |
## Client Features
All Swarms API clients are built with the following enterprise-grade features:
### 🔧 **Core Functionality**
| Feature | Description |
|------------------------|--------------------------------------------------------------------|
| **Full API Coverage** | Complete access to all Swarms API endpoints |
| **Type Safety** | Strongly-typed interfaces for all request/response objects |
| **Error Handling** | Comprehensive error handling with detailed error messages |
| **Retry Logic** | Automatic retries with exponential backoff for transient failures |
---
### 🚀 **Performance & Reliability**
| Feature | Description |
|--------------------------|--------------------------------------------------------------------|
| **Connection Pooling** | Efficient HTTP connection management |
| **Rate Limiting** | Built-in rate limit handling and backoff strategies |
| **Timeout Configuration**| Configurable timeouts for different operation types |
| **Streaming Support** | Real-time streaming for long-running operations |
---
### 🛡️ **Security & Authentication**
| Feature | Description |
|------------------------|--------------------------------------------------------------------|
| **API Key Management** | Secure API key handling and rotation |
| **TLS/SSL** | End-to-end encryption for all communications |
| **Request Signing** | Optional request signing for enhanced security |
| **Environment Configuration** | Secure environment-based configuration |
---
### 📊 **Monitoring & Debugging**
| Feature | Description |
|----------------------------|--------------------------------------------------------------------|
| **Comprehensive Logging** | Detailed logging for debugging and monitoring |
| **Request/Response Tracing** | Full request/response tracing capabilities |
| **Metrics Integration** | Built-in metrics for monitoring client performance |
| **Debug Mode** | Enhanced debugging features for development |
## Client-Specific Features
### Python Client
| Feature | Description |
|------------------------|----------------------------------------------------------|
| **Async Support** | Full async/await support with `asyncio` |
| **Pydantic Integration** | Type-safe request/response models |
| **Context Managers** | Resource management with context managers |
| **Rich Logging** | Integration with Python's `logging` module |
---
### TypeScript/Node.js Client
| Feature | Description |
|------------------------|----------------------------------------------------------|
| **TypeScript First** | Built with TypeScript for maximum type safety |
| **Promise-Based** | Modern Promise-based API with async/await |
| **Browser Compatible** | Works in both Node.js and modern browsers |
| **Zero Dependencies** | Minimal dependency footprint |
---
### Go Client
| Feature | Description |
|------------------------|----------------------------------------------------------|
| **Context Support** | Full context.Context support for cancellation |
| **Structured Logging** | Integration with structured logging libraries |
| **Concurrency Safe** | Thread-safe design for concurrent operations |
| **Minimal Allocation** | Optimized for minimal memory allocation |
---
### Java Client
| Feature | Description |
|------------------------|----------------------------------------------------------|
| **Spring Boot Ready** | Built-in Spring Boot auto-configuration |
| **Reactive Support** | Optional reactive streams support |
| **Enterprise Features**| JMX metrics, health checks, and more |
| **Maven & Gradle** | Available on Maven Central |
## Advanced Configuration
### Environment Variables
All clients support standard environment variables for configuration:
```bash
# API Configuration
SWARMS_API_KEY=your_api_key_here
SWARMS_BASE_URL=https://api.swarms.world
# Client Configuration
SWARMS_TIMEOUT=60
SWARMS_MAX_RETRIES=3
SWARMS_LOG_LEVEL=INFO
```
## Community & Support
### 📚 **Documentation & Resources**
| Resource | Link |
|-----------------------------|----------------------------------------------------------------------------------------|
| Complete API Documentation | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/) |
| Python Client Docs | [View Docs](https://docs.swarms.world/en/latest/swarms_cloud/python_client/) |
| API Examples & Tutorials | [View Examples](https://docs.swarms.world/en/latest/examples/) |
---
### 💬 **Community Support**
| Community Channel | Description | Link |
|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| Discord Community | Join our active developer community for real-time support and discussions | [Join Discord](https://discord.gg/EamjgSaEQf) |
| GitHub Discussions | Ask questions and share ideas | [GitHub Discussions](https://github.com/The-Swarm-Corporation/swarms/discussions) |
| Twitter/X | Follow for updates and announcements | [Twitter/X](https://x.com/swarms_corp) |
---
### 🐛 **Issue Reporting & Contributions**
| Contribution Area | Description | Link |
|-----------------------------|---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| Report Bugs | Help us improve by reporting issues | [Report Bugs](https://github.com/The-Swarm-Corporation/swarms/issues) |
| Feature Requests | Suggest new features and improvements | [Feature Requests](https://github.com/The-Swarm-Corporation/swarms/issues) |
| Contributing Guide | Learn how to contribute to the project | [Contributing Guide](https://docs.swarms.world/en/latest/contributors/main/) |
---
### 📧 **Direct Support**
| Support Type | Contact Information |
|-----------------------------|---------------------------------------------------------------------------------------|
| Support Call | [Book a call](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) |
| Enterprise Support | Contact us for dedicated enterprise support options |
## Contributing to Client Development
We welcome contributions to all our client libraries! Here's how you can help:
### 🛠️ **Development**
| Task | Description |
|-----------------------------------------|--------------------------------------------------|
| Implement new features and endpoints | Add new API features and expand client coverage |
| Improve error handling and retry logic | Enhance robustness and reliability |
| Add comprehensive test coverage | Ensure code quality and prevent regressions |
| Optimize performance and memory usage | Improve speed and reduce resource consumption |
---
### 📝 **Documentation**
| Task | Description |
|-----------------------------|-----------------------------------------------------|
| Write tutorials and examples | Create guides and sample code for users |
| Improve API documentation | Clarify and expand reference docs |
| Create integration guides | Help users connect clients to their applications |
| Translate documentation | Make docs accessible in multiple languages |
---
### 🧪 **Testing**
| Task | Description |
|-------------------------------|-----------------------------------------------------|
| Add unit and integration tests | Test individual components and end-to-end flows |
| Test with different language versions | Ensure compatibility across environments |
| Performance benchmarking | Measure and optimize speed and efficiency |
| Security testing | Identify and fix vulnerabilities |
---
### 📦 **Packaging**
| Task | Description |
|-------------------------------|-----------------------------------------------------|
| Package managers (npm, pip, Maven, etc.) | Publish to popular package repositories |
| Distribution optimization | Streamline builds and reduce package size |
| Version management | Maintain clear versioning and changelogs |
| Release automation | Automate build, test, and deployment pipelines |
## Enterprise Features
For enterprise customers, we offer additional features and support:
### 🏢 **Enterprise Client Features**
| Feature | Description |
|--------------------------|----------------------------------------------------------------|
| **Priority Support** | Dedicated support team with SLA guarantees |
| **Custom Integrations** | Tailored integrations for your specific needs |
| **On-Premises Deployment** | Support for on-premises or private cloud deployments |
| **Advanced Security** | Enhanced security features and compliance support |
| **Training & Onboarding**| Comprehensive training for your development team |
### 📞 **Contact Enterprise Sales**
| Contact Type | Details |
|----------------|-----------------------------------------------------------------------------------------|
| **Sales** | [kye@swarms.world](mailto:kye@swarms.world) |
| **Schedule Demo** | [Book a Demo](https://cal.com/swarms/swarms-technical-support?overlayCalendar=true) |
| **Partnership**| [kye@swarms.world](mailto:kye@swarms.world) |
---
*Ready to build the future with AI agents? Start with any of our client libraries and join our growing community of developers building the next generation of intelligent applications.*

198
docs/swarms_cloud/api_pricing.md
Unescape View File

@ -1,198 +0,0 @@
# Swarm Agent API Pricing
!!! success "🎉 Get Started with $20 Free Credits!"
New users receive $20 in free credits when they sign up! [Create your account now](https://swarms.world/platform/account) to start building with our powerful multi-agent platform.
!!! abstract "Overview"
The Swarm Agent API provides a powerful platform for managing multi-agent collaboration at scale and orchestrating swarms of LLM agents in the cloud. Our pricing model is designed to be transparent and cost-effective, enabling you to harness the full potential of your agents with ease.
## Credit System
The Swarm API operates on a credit-based system with the following characteristics:
- **Credits** are the currency used within the platform
- 1 credit = $1 USD
- Credits can be purchased with USD or $swarms Solana tokens
### Credit Types
| Type | Description | Expiration |
|------|-------------|------------|
| Standard Credits | Purchased credits | Never expires |
| Free Credits | Promotional credits | May have expiration dates |
## Pricing Structure
### Base Costs
| Cost Component | Price |
|----------------|-------|
| Base cost per agent | $0.01 per agent |
### Token Usage Costs
| Token Type | Cost |
|------------|------|
| Input tokens | $2.00 per 1M tokens |
| Output tokens | $4.50 per 1M tokens |
### Night-Time Discount
!!! tip "Off-Peak Hours Discount"
To encourage efficient resource usage during off-peak hours, we offer significant discounts for operations performed during California night-time hours:
| Time Period (Pacific Time) | Discount |
|----------------------------|----------|
| 8:00 PM to 6:00 AM | 75% off token costs |
## Cost Calculation
### Formula
The total cost for a swarm execution is calculated as follows:
```math
Total Cost = (Number of Agents × $0.01) +
(Total Input Tokens / 1M × $2.00 × Number of Agents) +
(Total Output Tokens / 1M × $4.50 × Number of Agents)
```
With night-time discount applied:
```math
Input Token Cost = Input Token Cost × 0.25
Output Token Cost = Output Token Cost × 0.25
```
### Example Scenarios
#### Scenario 1: Basic Workflow (Day-time)
!!! example "Basic Workflow Example"
**Parameters:**
- 3 agents
- 10,000 input tokens total
- 25,000 output tokens total
**Calculation:**
- Agent cost: 3 × $0.01 = $0.03
- Input token cost: (10,000 / 1,000,000) × $2.00 × 3 = $0.06
- Output token cost: (25,000 / 1,000,000) × $4.50 × 3 = $0.3375
- **Total cost: $0.4275**
#### Scenario 2: Complex Workflow (Night-time)
!!! example "Complex Workflow Example"
**Parameters:**
- 5 agents
- 50,000 input tokens total
- 125,000 output tokens total
**Calculation:**
- Agent cost: 5 × $0.01 = $0.05
- Input token cost: (50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125
- Output token cost: (125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125
- **Total cost: $0.878125**
## Purchasing Credits
Credits can be purchased through our platform in two ways:
### USD Payment
- Available through our [account page](https://swarms.world/platform/account)
- Secure payment processing
- Minimum purchase: $10
### $swarms Token Payment
- Use Solana-based $swarms tokens
- Tokens can be purchased on supported exchanges
- Connect your Solana wallet on our [account page](https://swarms.world/platform/account)
## Free Credits
!!! info "Free Credit Program"
We occasionally offer free credits to:
- New users (welcome bonus)
- During promotional periods
- For educational and research purposes
**Important Notes:**
- Used before standard credits
- May have expiration dates
- May have usage restrictions
## Billing and Usage Tracking
Track your credit usage through our comprehensive logging and reporting features:
### API Logs
- Access detailed logs via the `/v1/swarm/logs` endpoint
- View cost breakdowns for each execution
### Dashboard
- Real-time credit balance display
- Historical usage graphs
- Detailed cost analysis
- Available at [https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)
## FAQ
??? question "Is there a minimum credit purchase?"
Yes, the minimum credit purchase is $10 USD equivalent.
??? question "Do credits expire?"
Standard credits do not expire. Free promotional credits may have expiration dates.
??? question "How is the night-time discount applied?"
The system automatically detects the execution time based on Pacific Time (America/Los_Angeles) and applies a 75% discount to token costs for executions between 8:00 PM and 6:00 AM.
??? question "What happens if I run out of credits during execution?"
Executions will fail with a 402 Payment Required error if sufficient credits are not available. We recommend maintaining a credit balance appropriate for your usage patterns.
??? question "Can I get a refund for unused credits?"
Please contact our support team for refund requests for unused credits.
??? question "Are there volume discounts available?"
Yes, please contact our sales team for enterprise pricing and volume discounts.
## References
- [Swarm API Documentation](https://docs.swarms.world/en/latest/swarms_cloud/swarms_api/)
- [Account Management Portal](https://swarms.world/platform/account)
- [Swarm Types Reference](https://docs.swarms.world/swarms_cloud/swarm_types)
---
!!! info "Need Help?"
For additional questions or custom pricing options, please contact our support team at [kye@swarms.world](mailto:kye@swarms.world).

55
docs/swarms_cloud/auto.md
Unescape View File

@ -1,55 +0,0 @@
# Auto
*Intelligently selects the most effective swarm architecture for a given task*
**Swarm Type**: `auto` (or `Auto`)
## Overview
The Auto swarm type intelligently selects the most effective swarm architecture for a given task based on context analysis and task requirements. This intelligent system evaluates the task description and automatically chooses the optimal swarm type from all available architectures, ensuring maximum efficiency and effectiveness.
Key features:
- **Intelligent Selection**: Automatically chooses the best swarm type for each task
- **Context Analysis**: Analyzes task requirements to make optimal decisions
- **Adaptive Architecture**: Adapts to different types of problems automatically
- **Zero Configuration**: No manual architecture selection required
## Use Cases
- When unsure about which swarm type to use
- General-purpose task automation
- Rapid prototyping and experimentation
- Simplified API usage for non-experts
## API Usage
## Selection Logic
The Auto swarm type analyzes various factors to make its selection:
| Factor | Consideration |
|--------|---------------|
| **Task Complexity** | Simple → Single agent, Complex → Multi-agent |
| **Sequential Dependencies** | Dependencies → SequentialWorkflow |
| **Parallel Opportunities** | Independent subtasks → ConcurrentWorkflow |
| **Collaboration Needs** | Discussion required → GroupChat |
| **Expertise Diversity** | Multiple domains → MixtureOfAgents |
| **Management Needs** | Oversight required → HierarchicalSwarm |
| **Routing Requirements** | Task distribution → MultiAgentRouter |
## Best Practices
- Provide detailed task descriptions for better selection
- Use `rules` parameter to guide selection criteria
- Review the selected architecture in response metadata
- Ideal for users new to swarm architectures
## Related Swarm Types
Since Auto can select any swarm type, it's related to all architectures:
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic agent generation
- [SequentialWorkflow](sequential_workflow.md) - Often selected for linear tasks
- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel processing needs
- [MixtureOfAgents](mixture_of_agents.md) - For diverse expertise requirements

46
docs/swarms_cloud/auto_swarm_builder.md
Unescape View File

@ -1,46 +0,0 @@
# AutoSwarmBuilder [ Needs an Fix ]
*Automatically configures optimal swarm architectures based on task requirements*
**Swarm Type**: `AutoSwarmBuilder`
## Overview
The AutoSwarmBuilder automatically configures optimal agent architectures based on task requirements and performance metrics, simplifying swarm creation. This intelligent system analyzes the given task and automatically generates the most suitable agent configuration, eliminating the need for manual swarm design.
Key features:
- **Intelligent Configuration**: Automatically designs optimal swarm structures
- **Task-Adaptive**: Adapts architecture based on specific task requirements
- **Performance Optimization**: Selects configurations for maximum efficiency
- **Simplified Setup**: Eliminates manual agent configuration complexity
## Use Cases
- Quick prototyping and experimentation
- Unknown or complex task requirements
- Automated swarm optimization
- Simplified swarm creation for non-experts
## API Usage
## Configuration Options
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `task` | string | Task description for automatic optimization | Required |
| `rules` | string | Additional constraints and guidelines | None |
| `max_loops` | integer | Maximum execution rounds | 1 |
## Best Practices
- Provide detailed, specific task descriptions for better optimization
- Use `rules` parameter to guide the automatic configuration
- Ideal for rapid prototyping and experimentation
- Review generated architecture in response metadata
## Related Swarm Types
- [Auto](auto.md) - For automatic swarm type selection
- [MixtureOfAgents](mixture_of_agents.md) - Often selected by AutoSwarmBuilder
- [HierarchicalSwarm](hierarchical_swarm.md) - For complex structured tasks

170
docs/swarms_cloud/best_practices.md
Unescape View File

@ -1,170 +0,0 @@
# 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<br>- Dynamic resource allocation |
| `MixtureOfAgents` | Diverse expertise | - Cross-domain problems<br>- Comprehensive analysis<br>- Multi-perspective tasks<br>- Research synthesis |
| `SpreadSheetSwarm` | Data processing | - Financial analysis<br>- Data transformation<br>- Batch calculations<br>- Report generation |
| `SequentialWorkflow` | Linear processes | - Document processing<br>- Step-by-step analysis<br>- Quality control<br>- Content pipeline |
| `ConcurrentWorkflow` | Parallel tasks | - Batch processing<br>- Independent analyses<br>- High-throughput needs<br>- Multi-market analysis |
| `GroupChat` | Collaborative solving | - Brainstorming<br>- Decision making<br>- Problem solving<br>- Strategy development |
| `MultiAgentRouter` | Task distribution | - Load balancing<br>- Specialized processing<br>- Resource optimization<br>- Service routing |
| `AutoSwarmBuilder` | Automated setup | - Quick prototyping<br>- Simple tasks<br>- Testing<br>- MVP development |
| `HiearchicalSwarm` | Complex organization | - Project management<br>- Research analysis<br>- Enterprise workflows<br>- Team automation |
| `MajorityVoting` | Consensus needs | - Quality assurance<br>- Decision validation<br>- Risk assessment<br>- Content moderation |
=== "Application Patterns"
!!! tip "Specialized Application Configurations"
| Application | Recommended Swarm | Benefits |
|------------|-------------------|-----------|
| **Team Automation** | `HiearchicalSwarm` | - Automated team coordination<br>- Clear responsibility chain<br>- Scalable team structure |
| **Research Pipeline** | `SequentialWorkflow` | - Structured research process<br>- Quality control at each stage<br>- Comprehensive output |
| **Trading System** | `ConcurrentWorkflow` | - Multi-market coverage<br>- Real-time analysis<br>- Risk distribution |
| **Content Factory** | `MixtureOfAgents` | - Automated content creation<br>- Consistent quality<br>- High throughput |
=== "Cost Optimization"
!!! tip "Advanced 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 |
| Smart Routing | Route to specialized agents | 10-15% cost reduction |
| Prompt Engineering | Optimize input tokens | 15-20% cost reduction |
| Flex Processing | Use flex tier for non-urgent tasks | 75% cost reduction |
=== "Service Tiers"
!!! tip "Choosing the Right Service Tier"
| Tier | Best For | Benefits | Considerations |
|------|----------|----------|----------------|
| Standard | - Real-time processing<br>- Time-sensitive tasks<br>- Critical workflows | - Immediate execution<br>- Higher priority<br>- Predictable timing | - Higher cost<br>- 5-min timeout |
| Flex | - Batch processing<br>- Non-urgent tasks<br>- Cost-sensitive workloads | - 75% cost reduction<br>- Longer timeouts<br>- Auto-retries | - Variable timing<br>- Resource contention |
=== "Industry Solutions"
!!! example "Industry-Specific Swarm Patterns"
| Industry | Use Case | Applications |
|----------|----------|--------------|
| **Finance** | Automated trading desk | - Portfolio management<br>- Risk assessment<br>- Market analysis<br>- Trading execution |
| **Healthcare** | Clinical workflow automation | - Patient analysis<br>- Diagnostic support<br>- Treatment planning<br>- Follow-up care |
| **Legal** | Legal document processing | - Document review<br>- Case analysis<br>- Contract review<br>- Compliance checks |
| **E-commerce** | E-commerce operations | - Product management<br>- Pricing optimization<br>- Customer support<br>- Inventory management |
=== "Error Handling"
!!! warning "Advanced Error Management Strategies"
| Error Code | Strategy | Recovery Pattern |
|------------|----------|------------------|
| 400 | Input Validation | Pre-request validation with fallback |
| 401 | Auth Management | Secure key rotation and storage |
| 429 | Rate Limiting | Exponential backoff with queuing |
| 500 | Resilience | Retry with circuit breaking |
| 503 | High Availability | Multi-region redundancy |
| 504 | Timeout Handling | Adaptive timeouts with partial results |
## 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 Best Practices
### Best Practices Summary
!!! success "Recommended Patterns"
- Use appropriate swarm types for tasks
- Implement robust error handling
- Monitor and log executions
- Cache repeated results
- Rotate API keys regularly
- Choose appropriate service tier based on task urgency
- Use flex processing for batch and non-urgent tasks
!!! danger "Anti-patterns to Avoid"
- Hardcoding API keys
- Ignoring rate limits
- Missing error handling
- Excessive agent count
- Inadequate monitoring
- Using standard tier for non-urgent tasks
- Not implementing retry logic for flex tier
### Performance Benchmarks
!!! note "Typical Performance Metrics"
| Metric | Target Range | Warning Threshold |
|--------|--------------|-------------------|
| Response Time | < 2s (standard)<br>< 15s (flex) | > 5s (standard)<br>> 30s (flex) |
| Success Rate | > 99% | < 95% |
| Cost per Task | < $0.05 (standard)<br>< $0.0125 (flex) | > $0.10 (standard)<br>> $0.025 (flex) |
| Cache Hit Rate | > 80% | < 60% |
| Error Rate | < 1% | > 5% |
| Retry Rate (flex) | < 10% | > 30% |
### Additional Resources
!!! info "Useful Links"
- [Swarms API Documentation](https://docs.swarms.world)
- [API Dashboard](https://swarms.world/platform/api-keys)

195
docs/swarms_cloud/chinese_api_pricing.md
Unescape View File

@ -1,195 +0,0 @@
# Swarm Agent API 定价文档
Swarm Agent API 提供了一个强大的平台，用于大规模管理多代理协作和在云端编排 LLM 代理群。本文档概述了定价模型、成本计算方式以及如何购买和管理您的积分。
我们的定价设计旨在透明且具有成本效益，使您能够轻松发挥代理的全部潜力。成本基于：
- 使用的代理数量
- 输入和输出令牌使用量
- 执行时间
## 积分系统
Swarm API 采用基于积分的系统：
- **积分**是平台内使用的货币
- 1积分 = 1美元
- 积分可以用美元或 $swarms Solana 代币购买
- 两种类型的积分：
- **标准积分**：购买的积分永不过期
- **免费积分**：促销积分，可能有使用限制
## 定价结构
### 基本成本
| 成本组成 | 价格 |
|----------------|-------|
| 每个代理的基本成本 | 每个代理$0.01 |
### 令牌使用成本
| 令牌类型 | 成本 |
|------------|------|
| 输入令牌 | 每百万令牌$2.00 |
| 输出令牌 | 每百万令牌$4.50 |
### 夜间折扣
为了鼓励在非高峰时段高效利用资源，我们在加州夜间时段提供显著折扣：
| 时间段（太平洋时间） | 折扣 |
|----------------------------|----------|
| 晚上8:00至早上6:00 | 令牌成本75%折扣 |
## 成本计算
### 公式
群体执行的总成本计算如下：
```
总成本 = (代理数量 × $0.01) +
(总输入令牌数 / 1M × $2.00 × 代理数量) +
(总输出令牌数 / 1M × $4.50 × 代理数量)
```
应用夜间折扣时：
```
输入令牌成本 = 输入令牌成本 × 0.25
输出令牌成本 = 输出令牌成本 × 0.25
```
### 示例场景
#### 场景1：基本工作流（白天）
- 3个代理
- 总共10,000个输入令牌
- 总共25,000个输出令牌
**计算：**
- 代理成本：3 × $0.01 = $0.03
- 输入令牌成本：(10,000 / 1,000,000) × $2.00 × 3 = $0.06
- 输出令牌成本：(25,000 / 1,000,000) × $4.50 × 3 = $0.3375
- **总成本：$0.4275**
#### 场景2：复杂工作流（夜间）
- 5个代理
- 总共50,000个输入令牌
- 总共125,000个输出令牌
**计算：**
- 代理成本：5 × $0.01 = $0.05
- 输入令牌成本：(50,000 / 1,000,000) × $2.00 × 5 × 0.25 = $0.125
- 输出令牌成本：(125,000 / 1,000,000) × $4.50 × 5 × 0.25 = $0.703125
- **总成本：$0.878125**
## 购买积分
可以通过我们的平台以两种方式购买积分：
1. **美元支付**
- 可通过我们的[账户页面](https://swarms.world/platform/account)使用
- 安全支付处理
- 最低购买额：$10
2. **$swarms 代币支付**
- 使用基于Solana的$swarms代币
- 可在支持的交易所购买代币
- 在我们的[账户页面](https://swarms.world/platform/account)连接您的Solana钱包
## 免费积分
我们偶尔会向以下对象提供免费积分：
- 新用户（欢迎奖励）
- 促销期间
- 教育和研究目的
关于免费积分的说明：
- 在标准积分之前使用
- 可能有过期日期
- 可能有使用限制
## 账单和使用跟踪
通过我们全面的日志和报告功能跟踪您的积分使用情况：
1. **API日志**
- 通过`/v1/swarm/logs`端点访问详细日志
- 查看每次执行的成本明细
2. **仪表板**
- 实时积分余额显示
- 历史使用图表
- 详细成本分析
- 可在[https://swarms.world/platform/dashboard](https://swarms.world/platform/dashboard)访问
## 常见问题
**问：是否有最低积分购买要求？**
答：是的，最低积分购买额为10美元等值。
**问：积分会过期吗？**
答：标准积分不会过期。免费促销积分可能有过期日期。
**问：夜间折扣如何应用？**
答：系统会根据太平洋时间（America/Los_Angeles）自动检测执行时间，并在晚上8:00至早上6:00之间的执行应用75%的令牌成本折扣。
**问：如果我在执行过程中积分用完了会怎样？**
答：如果没有足够的积分，执行将失败并显示402 Payment Required错误。我们建议维持适合您使用模式的积分余额。
**问：我可以获得未使用积分的退款吗？**
答：请联系我们的支持团队处理未使用积分的退款请求。
**问：是否有批量折扣？**
答：是的，请联系我们的销售团队了解企业定价和批量折扣。
## 参考资料
- [Swarm API 文档](https://docs.swarms.world)
- [账户管理门户](https://swarms.world/platform/account)
- [Swarm 类型参考](https://docs.swarms.world/swarm-types)
- [令牌使用指南](https://docs.swarms.world/token-usage)
- [API 参考](https://docs.swarms.world/api-reference)
---
如有其他问题或自定义定价选项，请联系我们的支持团队，邮箱：kye@swarms.world

214
docs/swarms_cloud/concurrent_workflow.md
Unescape View File

@ -1,214 +0,0 @@
# ConcurrentWorkflow
*Runs independent tasks in parallel for faster processing*
**Swarm Type**: `ConcurrentWorkflow`
## Overview
The ConcurrentWorkflow swarm type runs independent tasks in parallel, significantly reducing processing time for complex operations. This architecture is ideal for tasks that can be processed simultaneously without dependencies, allowing multiple agents to work on different aspects of a problem at the same time.
Key features:
- **Parallel Execution**: Multiple agents work simultaneously
- **Reduced Processing Time**: Faster completion through parallelization
- **Independent Tasks**: Agents work on separate, non-dependent subtasks
- **Scalable Performance**: Performance scales with the number of agents
## Use Cases
- Independent data analysis tasks
- Parallel content generation
- Multi-source research projects
- Distributed problem solving
## API Usage
### Basic ConcurrentWorkflow Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Market Research Concurrent",
"description": "Parallel market research across different sectors",
"swarm_type": "ConcurrentWorkflow",
"task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
"agents": [
{
"agent_name": "AI Market Analyst",
"description": "Analyzes AI market trends and opportunities",
"system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Healthcare Market Analyst",
"description": "Analyzes healthcare market trends",
"system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Fintech Market Analyst",
"description": "Analyzes fintech market opportunities",
"system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "E-commerce Market Analyst",
"description": "Analyzes e-commerce market trends",
"system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
}
],
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Market Research Concurrent",
"description": "Parallel market research across different sectors",
"swarm_type": "ConcurrentWorkflow",
"task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
"agents": [
{
"agent_name": "AI Market Analyst",
"description": "Analyzes AI market trends and opportunities",
"system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Healthcare Market Analyst",
"description": "Analyzes healthcare market trends",
"system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Fintech Market Analyst",
"description": "Analyzes fintech market opportunities",
"system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "E-commerce Market Analyst",
"description": "Analyzes e-commerce market trends",
"system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
}
],
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("ConcurrentWorkflow swarm completed successfully!")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Parallel results: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-S17nZFDesmLHxCRoeyF3NVYvPaXk",
"status": "success",
"swarm_name": "Market Research Concurrent",
"description": "Parallel market research across different sectors",
"swarm_type": "ConcurrentWorkflow",
"output": [
{
"role": "E-commerce Market Analyst",
"content": "To analyze market opportunities in the AI, healthcare, fintech, and e-commerce sectors, we can break down each sector's current trends, consumer behavior, and emerging platforms. Here's an overview of each sector with a focus on e-commerce....."
},
{
"role": "AI Market Analyst",
"content": "The artificial intelligence (AI) landscape presents numerous opportunities across various sectors, particularly in healthcare, fintech, and e-commerce. Here's a detailed analysis of each sector:\n\n### Healthcare....."
},
{
"role": "Healthcare Market Analyst",
"content": "As a Healthcare Market Analyst, I will focus on analyzing market opportunities within the healthcare sector, particularly in the realm of AI and digital health. The intersection of healthcare with fintech and e-commerce also presents unique opportunities. Here's an overview of key trends and growth areas:...."
},
{
"role": "Fintech Market Analyst",
"content": "Certainly! Let's break down the market opportunities in the fintech sector, focusing on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments:\n\n### 1. Financial Technology Trends....."
}
],
"number_of_agents": 4,
"service_tier": "standard",
"execution_time": 23.360230922698975,
"usage": {
"input_tokens": 35,
"output_tokens": 2787,
"total_tokens": 2822,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.04,
"input_token_cost": 0.000105,
"output_token_cost": 0.041805,
"token_counts": {
"total_input_tokens": 35,
"total_output_tokens": 2787,
"total_tokens": 2822
},
"num_agents": 4,
"service_tier": "standard",
"night_time_discount_applied": true
},
"total_cost": 0.08191,
"discount_active": true,
"discount_type": "night_time",
"discount_percentage": 75
}
}
}
```
## Best Practices
- Design independent tasks that don't require sequential dependencies
- Use for tasks that can be parallelized effectively
- Ensure agents have distinct, non-overlapping responsibilities
- Ideal for time-sensitive analysis requiring multiple perspectives
## Related Swarm Types
- [SequentialWorkflow](sequential_workflow.md) - For ordered execution
- [MixtureOfAgents](mixture_of_agents.md) - For collaborative analysis
- [MultiAgentRouter](multi_agent_router.md) - For intelligent task distribution

189
docs/swarms_cloud/group_chat.md
Unescape View File

@ -1,189 +0,0 @@
# GroupChat
*Enables dynamic collaboration through chat-based interaction*
**Swarm Type**: `GroupChat`
## Overview
The GroupChat swarm type enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. Agents participate in a conversational workflow where they can build upon each other's contributions, debate ideas, and reach consensus through natural dialogue.
Key features:
- **Interactive Dialogue**: Agents communicate through natural conversation
- **Dynamic Collaboration**: Real-time information sharing and building upon ideas
- **Consensus Building**: Agents can debate and reach decisions collectively
- **Flexible Participation**: Agents can contribute when relevant to the discussion
## Use Cases
- Brainstorming and ideation sessions
- Multi-perspective problem analysis
- Collaborative decision-making processes
- Creative content development
## API Usage
### Basic GroupChat Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Product Strategy Discussion",
"description": "Collaborative chat to develop product strategy",
"swarm_type": "GroupChat",
"task": "Discuss and develop a go-to-market strategy for a new AI-powered productivity tool targeting small businesses",
"agents": [
{
"agent_name": "Product Manager",
"description": "Leads product strategy and development",
"system_prompt": "You are a senior product manager. Focus on product positioning, features, user needs, and market fit. Ask probing questions and build on others ideas.",
"model_name": "gpt-4o",
"max_loops": 3,
},
{
"agent_name": "Marketing Strategist",
"description": "Develops marketing and positioning strategy",
"system_prompt": "You are a marketing strategist. Focus on target audience, messaging, channels, and competitive positioning. Contribute marketing insights to the discussion.",
"model_name": "gpt-4o",
"max_loops": 3,
},
{
"agent_name": "Sales Director",
"description": "Provides sales and customer perspective",
"system_prompt": "You are a sales director with small business experience. Focus on pricing, sales process, customer objections, and market adoption. Share practical sales insights.",
"model_name": "gpt-4o",
"max_loops": 3,
},
{
"agent_name": "UX Researcher",
"description": "Represents user experience and research insights",
"system_prompt": "You are a UX researcher specializing in small business tools. Focus on user behavior, usability, adoption barriers, and design considerations.",
"model_name": "gpt-4o",
"max_loops": 3,
}
],
"max_loops": 3
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Product Strategy Discussion",
"description": "Collaborative chat to develop product strategy",
"swarm_type": "GroupChat",
"task": "Discuss and develop a go-to-market strategy for a new AI-powered productivity tool targeting small businesses",
"agents": [
{
"agent_name": "Product Manager",
"description": "Leads product strategy and development",
"system_prompt": "You are a senior product manager. Focus on product positioning, features, user needs, and market fit. Ask probing questions and build on others ideas.",
"model_name": "gpt-4o",
"max_loops": 3,
},
{
"agent_name": "Marketing Strategist",
"description": "Develops marketing and positioning strategy",
"system_prompt": "You are a marketing strategist. Focus on target audience, messaging, channels, and competitive positioning. Contribute marketing insights to the discussion.",
"model_name": "gpt-4o",
"max_loops": 3,
},
{
"agent_name": "Sales Director",
"description": "Provides sales and customer perspective",
"system_prompt": "You are a sales director with small business experience. Focus on pricing, sales process, customer objections, and market adoption. Share practical sales insights.",
"model_name": "gpt-4o",
"max_loops": 3,
},
{
"agent_name": "UX Researcher",
"description": "Represents user experience and research insights",
"system_prompt": "You are a UX researcher specializing in small business tools. Focus on user behavior, usability, adoption barriers, and design considerations.",
"model_name": "gpt-4o",
"max_loops": 3,
}
],
"max_loops": 3
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("GroupChat swarm completed successfully!")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Chat discussion: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-2COVtf3k0Fz7jU1BOOHF3b5nuL2x",
"status": "success",
"swarm_name": "Product Strategy Discussion",
"description": "Collaborative chat to develop product strategy",
"swarm_type": "GroupChat",
"output": "User: \n\nSystem: \n Group Chat Name: Product Strategy Discussion\nGroup Chat Description: Collaborative chat to develop product strategy\n Agents in your Group Chat: Available Agents for Team: None\n\n\n\n[Agent 1]\nName: Product Manager\nDescription: Leads product strategy and development\nRole.....",
"number_of_agents": 4,
"service_tier": "standard",
"execution_time": 47.36732482910156,
"usage": {
"input_tokens": 30,
"output_tokens": 1633,
"total_tokens": 1663,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.04,
"input_token_cost": 0.00009,
"output_token_cost": 0.024495,
"token_counts": {
"total_input_tokens": 30,
"total_output_tokens": 1633,
"total_tokens": 1663
},
"num_agents": 4,
"service_tier": "standard",
"night_time_discount_applied": false
},
"total_cost": 0.064585,
"discount_active": false,
"discount_type": "none",
"discount_percentage": 0
}
}
}
```
## Best Practices
- Set clear discussion goals and objectives
- Use diverse agent personalities for richer dialogue
- Allow multiple conversation rounds for idea development
- Encourage agents to build upon each other's contributions
## Related Swarm Types
- [MixtureOfAgents](mixture_of_agents.md) - For complementary expertise
- [MajorityVoting](majority_voting.md) - For consensus decision-making
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic discussion setup

252
docs/swarms_cloud/hierarchical_swarm.md
Unescape View File

@ -1,252 +0,0 @@
# HiearchicalSwarm
*Implements structured, multi-level task management with clear authority*
**Swarm Type**: `HiearchicalSwarm`
## Overview
The HiearchicalSwarm implements a structured, multi-level approach to task management with clear lines of authority and delegation. This architecture organizes agents in a hierarchical structure where manager agents coordinate and oversee worker agents, enabling efficient task distribution and quality control.
Key features:
- **Structured Hierarchy**: Clear organizational structure with managers and workers
- **Delegated Authority**: Manager agents distribute tasks to specialized workers
- **Quality Oversight**: Multi-level review and validation processes
- **Scalable Organization**: Efficient coordination of large agent teams
## Use Cases
- Complex projects requiring management oversight
- Large-scale content production workflows
- Multi-stage validation and review processes
- Enterprise-level task coordination
## API Usage
### Basic HiearchicalSwarm Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Market Research ",
"description": "Parallel market research across different sectors",
"swarm_type": "HiearchicalSwarm",
"task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
"agents": [
{
"agent_name": "AI Market Analyst",
"description": "Analyzes AI market trends and opportunities",
"system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Healthcare Market Analyst",
"description": "Analyzes healthcare market trends",
"system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Fintech Market Analyst",
"description": "Analyzes fintech market opportunities",
"system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "E-commerce Market Analyst",
"description": "Analyzes e-commerce market trends",
"system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
}
],
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Market Research ",
"description": "Parallel market research across different sectors",
"swarm_type": "HiearchicalSwarm",
"task": "Research and analyze market opportunities in AI, healthcare, fintech, and e-commerce sectors",
"agents": [
{
"agent_name": "AI Market Analyst",
"description": "Analyzes AI market trends and opportunities",
"system_prompt": "You are an AI market analyst. Focus on artificial intelligence market trends, opportunities, key players, and growth projections.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Healthcare Market Analyst",
"description": "Analyzes healthcare market trends",
"system_prompt": "You are a healthcare market analyst. Focus on healthcare market trends, digital health opportunities, regulatory landscape, and growth areas.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Fintech Market Analyst",
"description": "Analyzes fintech market opportunities",
"system_prompt": "You are a fintech market analyst. Focus on financial technology trends, digital payment systems, blockchain opportunities, and regulatory developments.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "E-commerce Market Analyst",
"description": "Analyzes e-commerce market trends",
"system_prompt": "You are an e-commerce market analyst. Focus on online retail trends, marketplace opportunities, consumer behavior, and emerging platforms.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
}
],
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("HiearchicalSwarm completed successfully!")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Project plan: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-JIrcIAfs2d75xrXGaAL94uWyYJ8V",
"status": "success",
"swarm_name": "Market Research Auto",
"description": "Parallel market research across different sectors",
"swarm_type": "HiearchicalSwarm",
"output": [
{
"role": "System",
"content": "These are the agents in your team. Each agent has a specific role and expertise to contribute to the team's objectives.\nTotal Agents: 4\n\nBelow is a summary of your team members and their primary responsibilities:\n| Agent Name | Description |\n|------------|-------------|\n| AI Market Analyst | Analyzes AI market trends and opportunities |\n| Healthcare Market Analyst | Analyzes healthcare market trends |\n| Fintech Market Analyst | Analyzes fintech market opportunities |\n| E-commerce Market Analyst | Analyzes e-commerce market trends |\n\nEach agent is designed to handle tasks within their area of expertise. Collaborate effectively by assigning tasks according to these roles."
},
{
"role": "Director",
"content": [
{
"role": "Director",
"content": [
{
"function": {
"arguments": "{\"plan\":\"Conduct a comprehensive analysis of market opportunities in the AI, healthcare, fintech, and e-commerce sectors. Each market analyst will focus on their respective sector, gathering data on current trends, growth opportunities, and potential challenges. The findings will be compiled into a report for strategic decision-making.\",\"orders\":[{\"agent_name\":\"AI Market Analyst\",\"task\":\"Research current trends in the AI market, identify growth opportunities, and analyze potential challenges.\"},{\"agent_name\":\"Healthcare Market Analyst\",\"task\":\"Analyze the healthcare market for emerging trends, growth opportunities, and possible challenges.\"},{\"agent_name\":\"Fintech Market Analyst\",\"task\":\"Investigate the fintech sector for current trends, identify opportunities for growth, and assess challenges.\"},{\"agent_name\":\"E-commerce Market Analyst\",\"task\":\"Examine e-commerce market trends, identify growth opportunities, and analyze potential challenges.\"}]}",
"name": "ModelMetaclass"
},
"id": "call_GxiyzIRb2oGQXokbbkeaeVry",
"type": "function"
}
]
}
]
},
{
"role": "AI Market Analyst",
"content": "### AI Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the AI Market:\n\n1. **Increased Adoption Across Industries**..."
},
{
"role": "Healthcare Market Analyst",
"content": "### Healthcare Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the Healthcare Market:\n\n1. **Telehealth Expansion**..."
},
{
"role": "Fintech Market Analyst",
"content": "### Fintech Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the Fintech Market:\n\n1. **Digital Payments Proliferation**...."
},
{
"role": "E-commerce Market Analyst",
"content": "### E-commerce Market Analysis: Trends, Opportunities, and Challenges\n\n#### Current Trends in the E-commerce Market:\n\n1. **Omnichannel Retailing**...."
},
{
"role": "Director",
"content": "### Feedback for Worker Agents\n\n#### AI Market Analyst\n\n**Strengths:**\n- Comprehensive coverage of current trends, growth opportunities, and challenges in the AI market.\n- Clear categorization of insights, making it easy to follow and understand.\n\n**Weaknesses....."
},
{
"role": "System",
"content": "--- Loop 1/1 completed ---"
}
],
"number_of_agents": 4,
"service_tier": "standard",
"execution_time": 94.07934331893921,
"usage": {
"input_tokens": 35,
"output_tokens": 3827,
"total_tokens": 3862,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.04,
"input_token_cost": 0.000105,
"output_token_cost": 0.057405,
"token_counts": {
"total_input_tokens": 35,
"total_output_tokens": 3827,
"total_tokens": 3862
},
"num_agents": 4,
"service_tier": "standard",
"night_time_discount_applied": false
},
"total_cost": 0.09751,
"discount_active": false,
"discount_type": "none",
"discount_percentage": 0
}
}
}
```
## Configuration Options
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `role` | string | Agent role: "manager" or "worker" | "worker" |
| `agents` | Array<AgentSpec> | Mix of manager and worker agents | Required |
| `max_loops` | integer | Coordination rounds for managers | 1 |
## Best Practices
- Clearly define manager and worker roles using the `role` parameter
- Give managers higher `max_loops` for coordination activities
- Design worker agents with specialized, focused responsibilities
- Use for complex projects requiring oversight and coordination
## Related Swarm Types
- [SequentialWorkflow](sequential_workflow.md) - For linear task progression
- [MultiAgentRouter](multi_agent_router.md) - For intelligent task routing
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic hierarchy creation

0
docs/swarms_cloud/index.md
Unescape View File

369
docs/swarms_cloud/launch.md
Unescape View File

@ -1,369 +0,0 @@
# Swarms Cloud API Client Documentation
## Overview
The Swarms Cloud API Client is a production-grade Python library for interacting with the Swarms Cloud Agent API. It provides a comprehensive interface for managing, executing, and monitoring cloud-based agents.
## Installation
```bash
pip install swarms-cloud
```
## Quick Start
```python
from swarms_cloud import SwarmCloudAPI, AgentCreate
# Initialize the client
client = SwarmCloudAPI(
base_url="https://swarmcloud-285321057562.us-central1.run.app",
api_key="your_api_key_here"
)
# Create an agent
agent_data = AgentCreate(
name="TranslateAgent",
description="Translates text between languages",
code="""
def main(request, store):
text = request.payload.get('text', '')
return f'Translated: {text}'
""",
requirements="requests==2.25.1",
envs="DEBUG=True"
)
new_agent = client.create_agent(agent_data)
print(f"Created agent with ID: {new_agent.id}")
```
## Client Configuration
### Constructor Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|----------|-------------|
| base_url | str | No | https://swarmcloud-285321057562.us-central1.run.app | The base URL of the SwarmCloud API |
| api_key | str | Yes | None | Your SwarmCloud API key |
| timeout | float | No | 10.0 | Request timeout in seconds |
## Data Models
### AgentCreate
Model for creating new agents.
| Field | Type | Required | Default | Description |
|-------|------|----------|----------|-------------|
| name | str | Yes | - | Name of the agent |
| description | str | No | None | Description of the agent's purpose |
| code | str | Yes | - | Python code that defines the agent's behavior |
| requirements | str | No | None | Python package requirements (pip format) |
| envs | str | No | None | Environment variables for the agent |
| autoscaling | bool | No | False | Enable/disable concurrent execution scaling |
### AgentUpdate
Model for updating existing agents.
| Field | Type | Required | Default | Description |
|-------|------|----------|----------|-------------|
| name | str | No | None | Updated name of the agent |
| description | str | No | None | Updated description |
| code | str | No | None | Updated Python code |
| requirements | str | No | None | Updated package requirements |
| autoscaling | bool | No | None | Updated autoscaling setting |
## API Methods
### List Agents
Retrieve all available agents.
```python
agents = client.list_agents()
for agent in agents:
print(f"Agent: {agent.name} (ID: {agent.id})")
```
**Returns**: List[AgentOut]
### Create Agent
Create a new agent with the specified configuration.
```python
agent_data = AgentCreate(
name="DataProcessor",
description="Processes incoming data streams",
code="""
def main(request, store):
data = request.payload.get('data', [])
return {'processed': len(data)}
""",
requirements="pandas==1.4.0\nnumpy==1.21.0",
envs="PROCESSING_MODE=fast",
autoscaling=True
)
new_agent = client.create_agent(agent_data)
```
**Returns**: AgentOut
### Get Agent
Retrieve details of a specific agent.
```python
agent = client.get_agent("agent_id_here")
print(f"Agent details: {agent}")
```
**Parameters**:
- agent_id (str): The unique identifier of the agent
**Returns**: AgentOut
### Update Agent
Update an existing agent's configuration.
```python
update_data = AgentUpdate(
name="UpdatedProcessor",
description="Enhanced data processing capabilities",
code="def main(request, store):\n return {'status': 'updated'}"
)
updated_agent = client.update_agent("agent_id_here", update_data)
```
**Parameters**:
- agent_id (str): The unique identifier of the agent
- update (AgentUpdate): The update data
**Returns**: AgentOut
### Execute Agent
Manually execute an agent with optional payload data.
```python
# Execute with payload
result = client.execute_agent(
"agent_id_here",
payload={"text": "Hello, World!"}
)
# Execute without payload
result = client.execute_agent("agent_id_here")
```
**Parameters**:
- agent_id (str): The unique identifier of the agent
- payload (Optional[Dict[str, Any]]): Execution payload data
**Returns**: Dict[str, Any]
### Get Agent History
Retrieve the execution history and logs for an agent.
```python
history = client.get_agent_history("agent_id_here")
for execution in history.executions:
print(f"[{execution.timestamp}] {execution.log}")
```
**Parameters**:
- agent_id (str): The unique identifier of the agent
**Returns**: AgentExecutionHistory
### Batch Execute Agents
Execute multiple agents simultaneously with the same payload.
```python
# Get list of agents
agents = client.list_agents()
# Execute batch with payload
results = client.batch_execute_agents(
agents=agents[:3], # Execute first three agents
payload={"data": "test"}
)
print(f"Batch execution results: {results}")
```
**Parameters**:
- agents (List[AgentOut]): List of agents to execute
- payload (Optional[Dict[str, Any]]): Shared execution payload
**Returns**: List[Any]
### Health Check
Check the API's health status.
```python
status = client.health()
print(f"API Status: {status}")
```
**Returns**: Dict[str, Any]
## Error Handling
The client uses exception handling to manage various error scenarios:
```python
from swarms_cloud import SwarmCloudAPI
import httpx
try:
client = SwarmCloudAPI(api_key="your_api_key_here")
agents = client.list_agents()
except httpx.HTTPError as http_err:
print(f"HTTP error occurred: {http_err}")
except Exception as err:
print(f"An unexpected error occurred: {err}")
finally:
client.close()
```
## Context Manager Support
The client can be used with Python's context manager:
```python
with SwarmCloudAPI(api_key="your_api_key_here") as client:
status = client.health()
print(f"API Status: {status}")
# Client automatically closes after the with block
```
## Best Practices
1. Always close the client when finished:
```python
client = SwarmCloudAPI(api_key="your_api_key_here")
try:
# Your code here
finally:
client.close()
```
2. Use context managers for automatic cleanup:
```python
with SwarmCloudAPI(api_key="your_api_key_here") as client:
# Your code here
```
3. Handle errors appropriately:
```python
try:
result = client.execute_agent("agent_id", payload={"data": "test"})
except httpx.HTTPError as e:
logger.error(f"HTTP error: {e}")
# Handle error appropriately
```
4. Set appropriate timeouts for your use case:
```python
client = SwarmCloudAPI(
api_key="your_api_key_here",
timeout=30.0 # Longer timeout for complex operations
)
```
## Complete Example
Here's a complete example showcasing various features of the client:
```python
from swarms_cloud import SwarmCloudAPI, AgentCreate, AgentUpdate
import httpx
def main():
with SwarmCloudAPI(api_key="your_api_key_here") as client:
# Create an agent
agent_data = AgentCreate(
name="DataAnalyzer",
description="Analyzes incoming data streams",
code="""
def main(request, store):
data = request.payload.get('data', [])
return {
'count': len(data),
'summary': 'Data processed successfully'
}
""",
requirements="pandas==1.4.0",
autoscaling=True
)
try:
# Create the agent
new_agent = client.create_agent(agent_data)
print(f"Created agent: {new_agent.name} (ID: {new_agent.id})")
# Execute the agent
result = client.execute_agent(
new_agent.id,
payload={"data": [1, 2, 3, 4, 5]}
)
print(f"Execution result: {result}")
# Update the agent
update_data = AgentUpdate(
description="Enhanced data analysis capabilities"
)
updated_agent = client.update_agent(new_agent.id, update_data)
print(f"Updated agent: {updated_agent.name}")
# Get execution history
history = client.get_agent_history(new_agent.id)
print(f"Execution history: {history}")
except httpx.HTTPError as e:
print(f"HTTP error occurred: {e}")
except Exception as e:
print(f"Unexpected error: {e}")
if __name__ == "__main__":
main()
```
## Logging
The client uses the `loguru` library for logging. You can configure the logging level and format:
```python
from loguru import logger
# Configure logging
logger.add("swarmcloud.log", rotation="500 MB")
client = SwarmCloudAPI(api_key="your_api_key_here")
```
## Performance Considerations
1. **Connection Reuse**: The client reuses HTTP connections by default, improving performance for multiple requests.
2. **Timeout Configuration**: Set appropriate timeouts based on your use case:
```python
client = SwarmCloudAPI(
api_key="your_api_key_here",
timeout=5.0 # Shorter timeout for time-sensitive operations
)
```
3. **Batch Operations**: Use batch_execute_agents for multiple agent executions:
```python
results = client.batch_execute_agents(
agents=agents,
payload=shared_payload
)
```
## Rate Limiting
The client respects API rate limits but does not implement retry logic. Implement your own retry mechanism if needed:
```python
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10))
def execute_with_retry(client, agent_id, payload):
return client.execute_agent(agent_id, payload)
```
## Thread Safety
The client is not thread-safe by default. For concurrent usage, create separate client instances for each thread or implement appropriate synchronization mechanisms.

249
docs/swarms_cloud/majority_voting.md
Unescape View File

@ -1,249 +0,0 @@
# MajorityVoting
*Implements robust decision-making through consensus and voting*
**Swarm Type**: `MajorityVoting`
## Overview
The MajorityVoting swarm type implements robust decision-making through consensus mechanisms, ideal for tasks requiring collective intelligence or verification. Multiple agents independently analyze the same problem and vote on the best solution, ensuring high-quality, well-validated outcomes through democratic consensus.
Key features:
- **Consensus-Based Decisions**: Multiple agents vote on the best solution
- **Quality Assurance**: Reduces individual agent bias through collective input
- **Democratic Process**: Fair and transparent decision-making mechanism
- **Robust Validation**: Multiple perspectives ensure thorough analysis
## Use Cases
- Critical decision-making requiring validation
- Quality assurance and verification tasks
- Complex problem solving with multiple viable solutions
- Risk assessment and evaluation scenarios
## API Usage
### Basic MajorityVoting Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Investment Decision Voting",
"description": "Multiple financial experts vote on investment recommendations",
"swarm_type": "MajorityVoting",
"task": "Evaluate whether to invest $1M in a renewable energy startup. Consider market potential, financial projections, team strength, and competitive landscape.",
"agents": [
{
"agent_name": "Growth Investor",
"description": "Focuses on growth potential and market opportunity",
"system_prompt": "You are a growth-focused venture capitalist. Evaluate investments based on market size, scalability, and growth potential. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Financial Analyst",
"description": "Analyzes financial metrics and projections",
"system_prompt": "You are a financial analyst specializing in startups. Evaluate financial projections, revenue models, and unit economics. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Technical Due Diligence",
"description": "Evaluates technology and product viability",
"system_prompt": "You are a technical due diligence expert. Assess technology viability, intellectual property, product-market fit, and technical risks. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Market Analyst",
"description": "Analyzes market conditions and competition",
"system_prompt": "You are a market research analyst. Evaluate market dynamics, competitive landscape, regulatory environment, and market timing. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Risk Assessor",
"description": "Identifies and evaluates investment risks",
"system_prompt": "You are a risk assessment specialist. Identify potential risks, evaluate mitigation strategies, and assess overall risk profile. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
}
],
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Investment Decision Voting",
"description": "Multiple financial experts vote on investment recommendations",
"swarm_type": "MajorityVoting",
"task": "Evaluate whether to invest $1M in a renewable energy startup. Consider market potential, financial projections, team strength, and competitive landscape.",
"agents": [
{
"agent_name": "Growth Investor",
"description": "Focuses on growth potential and market opportunity",
"system_prompt": "You are a growth-focused venture capitalist. Evaluate investments based on market size, scalability, and growth potential. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Financial Analyst",
"description": "Analyzes financial metrics and projections",
"system_prompt": "You are a financial analyst specializing in startups. Evaluate financial projections, revenue models, and unit economics. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Technical Due Diligence",
"description": "Evaluates technology and product viability",
"system_prompt": "You are a technical due diligence expert. Assess technology viability, intellectual property, product-market fit, and technical risks. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Market Analyst",
"description": "Analyzes market conditions and competition",
"system_prompt": "You are a market research analyst. Evaluate market dynamics, competitive landscape, regulatory environment, and market timing. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Risk Assessor",
"description": "Identifies and evaluates investment risks",
"system_prompt": "You are a risk assessment specialist. Identify potential risks, evaluate mitigation strategies, and assess overall risk profile. Provide a recommendation with confidence score.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
}
],
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("MajorityVoting completed successfully!")
print(f"Final decision: {result['output']['consensus_decision']}")
print(f"Vote breakdown: {result['metadata']['vote_breakdown']}")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-1WFsSJU2KcvY11lxRMjdQNWFHArI",
"status": "success",
"swarm_name": "Investment Decision Voting",
"description": "Multiple financial experts vote on investment recommendations",
"swarm_type": "MajorityVoting",
"output": [
{
"role": "Financial Analyst",
"content": [
"To evaluate the potential investment in a renewable energy startup, we will assess the technology viability, intellectual property, product-market fit, and technical risks, along with the additional factors of market ....."
]
},
{
"role": "Technical Due Diligence",
"content": [
"To evaluate the potential investment in a renewable energy startup, we will analyze the relevant market dynamics, competitive landscape, regulatory environment, and market timing. Here's the breakdown of the assessment......."
]
},
{
"role": "Market Analyst",
"content": [
"To evaluate the potential investment in a renewable energy startup, let's break down the key factors:\n\n1. **Market Potential........"
]
},
{
"role": "Growth Investor",
"content": [
"To evaluate the potential investment in a renewable energy startup, we need to assess various risk factors and mitigation strategies across several key areas: market potential, financial projections, team strength, and competitive landscape.\n\n### 1. Market Potential\n**Risks:**\n- **Regulatory Changes................"
]
},
{
"role": "Risk Assessor",
"content": [
"To provide a comprehensive evaluation of whether to invest $1M in the renewable energy startup, let's break down the key areas.........."
]
},
{
"role": "Risk Assessor",
"content": "To evaluate the potential investment in a renewable energy startup, we need to assess various risk factors and mitigation strategies across several key areas....."
}
],
"number_of_agents": 5,
"service_tier": "standard",
"execution_time": 61.74853563308716,
"usage": {
"input_tokens": 39,
"output_tokens": 8468,
"total_tokens": 8507,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.05,
"input_token_cost": 0.000117,
"output_token_cost": 0.12702,
"token_counts": {
"total_input_tokens": 39,
"total_output_tokens": 8468,
"total_tokens": 8507
},
"num_agents": 5,
"service_tier": "standard",
"night_time_discount_applied": false
},
"total_cost": 0.177137,
"discount_active": false,
"discount_type": "none",
"discount_percentage": 0
}
}
}
```
## Best Practices
- Use odd numbers of agents to avoid tie votes
- Design agents with different perspectives for robust evaluation
- Include confidence scores in agent prompts for weighted decisions
- Ideal for high-stakes decisions requiring validation
## Related Swarm Types
- [GroupChat](group_chat.md) - For discussion-based consensus
- [MixtureOfAgents](mixture_of_agents.md) - For diverse expertise collaboration
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured decision-making

342
docs/swarms_cloud/mcp.md
Unescape View File

@ -1,342 +0,0 @@
# Swarms API as MCP
- Launch MCP server as a tool
- Put `SWARMS_API_KEY` in `.env`
- Client side code below
## Server Side
```python
# server.py
from datetime import datetime
import os
from typing import Any, Dict, List, Optional
import requests
import httpx
from fastmcp import FastMCP
from pydantic import BaseModel, Field
from swarms import SwarmType
from dotenv import load_dotenv
load_dotenv()
class AgentSpec(BaseModel):
agent_name: Optional[str] = Field(
description="The unique name assigned to the agent, which identifies its role and functionality within the swarm.",
)
description: Optional[str] = Field(
description="A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.",
)
system_prompt: Optional[str] = Field(
description="The initial instruction or context provided to the agent, guiding its behavior and responses during execution.",
)
model_name: Optional[str] = Field(
default="gpt-4o-mini",
description="The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4o-mini, openai/o3-mini",
)
auto_generate_prompt: Optional[bool] = Field(
default=False,
description="A flag indicating whether the agent should automatically create prompts based on the task requirements.",
)
max_tokens: Optional[int] = Field(
default=8192,
description="The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.",
)
temperature: Optional[float] = Field(
default=0.5,
description="A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses.",
)
role: Optional[str] = Field(
default="worker",
description="The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.",
)
max_loops: Optional[int] = Field(
default=1,
description="The maximum number of times the agent is allowed to repeat its task, enabling iterative processing if necessary.",
)
# New fields for RAG functionality
rag_collection: Optional[str] = Field(
None,
description="The Qdrant collection name for RAG functionality. If provided, this agent will perform RAG queries.",
)
rag_documents: Optional[List[str]] = Field(
None,
description="Documents to ingest into the Qdrant collection for RAG. (List of text strings)",
)
tools: Optional[List[Dict[str, Any]]] = Field(
None,
description="A dictionary of tools that the agent can use to complete its task.",
)
class AgentCompletion(BaseModel):
"""
Configuration for a single agent that works together as a swarm to accomplish tasks.
"""
agent: AgentSpec = Field(
...,
description="The agent to run.",
)
task: Optional[str] = Field(
...,
description="The task to run.",
)
img: Optional[str] = Field(
None,
description="An optional image URL that may be associated with the swarm's task or representation.",
)
output_type: Optional[str] = Field(
"list",
description="The type of output to return.",
)
class AgentCompletionResponse(BaseModel):
"""
Response from an agent completion.
"""
agent_id: str = Field(
...,
description="The unique identifier for the agent that completed the task.",
)
agent_name: str = Field(
...,
description="The name of the agent that completed the task.",
)
agent_description: str = Field(
...,
description="The description of the agent that completed the task.",
)
messages: Any = Field(
...,
description="The messages from the agent completion.",
)
cost: Dict[str, Any] = Field(
...,
description="The cost of the agent completion.",
)
class Agents(BaseModel):
"""Configuration for a collection of agents that work together as a swarm to accomplish tasks."""
agents: List[AgentSpec] = Field(
description="A list containing the specifications of each agent that will participate in the swarm, detailing their roles and functionalities."
)
class ScheduleSpec(BaseModel):
scheduled_time: datetime = Field(
...,
description="The exact date and time (in UTC) when the swarm is scheduled to execute its tasks.",
)
timezone: Optional[str] = Field(
"UTC",
description="The timezone in which the scheduled time is defined, allowing for proper scheduling across different regions.",
)
class SwarmSpec(BaseModel):
name: Optional[str] = Field(
None,
description="The name of the swarm, which serves as an identifier for the group of agents and their collective task.",
max_length=100,
)
description: Optional[str] = Field(
None,
description="A comprehensive description of the swarm's objectives, capabilities, and intended outcomes.",
)
agents: Optional[List[AgentSpec]] = Field(
None,
description="A list of agents or specifications that define the agents participating in the swarm.",
)
max_loops: Optional[int] = Field(
default=1,
description="The maximum number of execution loops allowed for the swarm, enabling repeated processing if needed.",
)
swarm_type: Optional[SwarmType] = Field(
None,
description="The classification of the swarm, indicating its operational style and methodology.",
)
rearrange_flow: Optional[str] = Field(
None,
description="Instructions on how to rearrange the flow of tasks among agents, if applicable.",
)
task: Optional[str] = Field(
None,
description="The specific task or objective that the swarm is designed to accomplish.",
)
img: Optional[str] = Field(
None,
description="An optional image URL that may be associated with the swarm's task or representation.",
)
return_history: Optional[bool] = Field(
True,
description="A flag indicating whether the swarm should return its execution history along with the final output.",
)
rules: Optional[str] = Field(
None,
description="Guidelines or constraints that govern the behavior and interactions of the agents within the swarm.",
)
schedule: Optional[ScheduleSpec] = Field(
None,
description="Details regarding the scheduling of the swarm's execution, including timing and timezone information.",
)
tasks: Optional[List[str]] = Field(
None,
description="A list of tasks that the swarm should complete.",
)
messages: Optional[List[Dict[str, Any]]] = Field(
None,
description="A list of messages that the swarm should complete.",
)
# rag_on: Optional[bool] = Field(
# None,
# description="A flag indicating whether the swarm should use RAG.",
# )
# collection_name: Optional[str] = Field(
# None,
# description="The name of the collection to use for RAG.",
# )
stream: Optional[bool] = Field(
False,
description="A flag indicating whether the swarm should stream its output.",
)
class SwarmCompletionResponse(BaseModel):
"""
Response from a swarm completion.
"""
status: str = Field(..., description="The status of the swarm completion.")
swarm_name: str = Field(..., description="The name of the swarm.")
description: str = Field(..., description="Description of the swarm.")
swarm_type: str = Field(..., description="The type of the swarm.")
task: str = Field(
..., description="The task that the swarm is designed to accomplish."
)
output: List[Dict[str, Any]] = Field(
..., description="The output generated by the swarm."
)
number_of_agents: int = Field(
..., description="The number of agents involved in the swarm."
)
# "input_config": Optional[Dict[str, Any]] = Field(None, description="The input configuration for the swarm.")
BASE_URL = "https://swarms-api-285321057562.us-east1.run.app"
# Create an MCP server
mcp = FastMCP("swarms-api")
# Add an addition tool
@mcp.tool(name="swarm_completion", description="Run a swarm completion.")
def swarm_completion(swarm: SwarmSpec) -> Dict[str, Any]:
api_key = os.getenv("SWARMS_API_KEY")
headers = {"x-api-key": api_key, "Content-Type": "application/json"}
payload = swarm.model_dump()
response = requests.post(f"{BASE_URL}/v1/swarm/completions", json=payload, headers=headers)
return response.json()
@mcp.tool(name="swarms_available", description="Get the list of available swarms.")
async def swarms_available() -> Any:
"""
Get the list of available swarms.
"""
headers = {"Content-Type": "application/json"}
async with httpx.AsyncClient() as client:
response = await client.get(f"{BASE_URL}/v1/models/available", headers=headers)
response.raise_for_status() # Raise an error for bad responses
return response.json()
if __name__ == "__main__":
mcp.run(transport="sse")
```
## Client side
- Call the tool with it's name and the payload config
```python
import asyncio
from fastmcp import Client
swarm_config = {
"name": "Simple Financial Analysis",
"description": "A swarm to analyze financial data",
"agents": [
{
"agent_name": "Data Analyzer",
"description": "Looks at financial data",
"system_prompt": "Analyze the data.",
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 1000,
"temperature": 0.5,
"auto_generate_prompt": False,
},
{
"agent_name": "Risk Analyst",
"description": "Checks risk levels",
"system_prompt": "Evaluate the risks.",
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 1000,
"temperature": 0.5,
"auto_generate_prompt": False,
},
{
"agent_name": "Strategy Checker",
"description": "Validates strategies",
"system_prompt": "Review the strategy.",
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 1000,
"temperature": 0.5,
"auto_generate_prompt": False,
},
],
"max_loops": 1,
"swarm_type": "SequentialWorkflow",
"task": "Analyze the financial data and provide insights.",
"return_history": False, # Added required field
"stream": False, # Added required field
"rules": None, # Added optional field
"img": None, # Added optional field
}
async def swarm_completion():
"""Connect to a server over SSE and fetch available swarms."""
async with Client(
transport="http://localhost:8000/sse"
) as client:
# Basic connectivity testing
# print("Ping check:", await client.ping())
# print("Available tools:", await client.list_tools())
# print("Swarms available:", await client.call_tool("swarms_available", None))
result = await client.call_tool("swarm_completion", {"swarm": swarm_config})
print("Swarm completion:", result)
# Execute the function
if __name__ == "__main__":
asyncio.run(swarm_completion())
```

727
docs/swarms_cloud/mcs_api.md
Unescape View File

@ -1,727 +0,0 @@
# Medical Coder Swarm API Documentation
Base URL: `https://mcs-285321057562.us-central1.run.app`
## Table of Contents
- [Authentication](#authentication)
- [Rate Limits](#rate-limits)
- [Endpoints](#endpoints)
- [Health Check](#health-check)
- [Run Medical Coder](#run-medical-coder)
- [Run Batch Medical Coder](#run-batch-medical-coder)
- [Get Patient Data](#get-patient-data)
- [Get All Patients](#get-all-patients)
- [Code Examples](#code-examples)
- [Error Handling](#error-handling)
## Authentication
Authentication details will be provided by the MCS team. Contact support for API credentials.
## Rate Limits
| Endpoint | GET Rate Limit Status |
|----------|----------------------|
| `GET /rate-limits` | Returns current rate limit status for your IP address |
## Endpoints
### Health Check
Check if the API is operational.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/health` | Returns 200 OK if service is running |
### Run Medical Coder
Process a single patient case through the Medical Coder Swarm.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/medical-coder/run` | Process a single patient case |
**Request Body Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| patient_id | string | Yes | Unique identifier for the patient |
| case_description | string | Yes | Medical case details to be processed |
**Response Schema:**
| Field | Type | Description |
|-------|------|-------------|
| patient_id | string | Patient identifier |
| case_data | string | Processed case data |
### Run Batch Medical Coder
Process multiple patient cases in a single request.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/v1/medical-coder/run-batch` | Process multiple patient cases |
**Request Body Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| cases | array | Yes | Array of PatientCase objects |
### Get Patient Data
Retrieve data for a specific patient.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/medical-coder/patient/{patient_id}` | Get patient data by ID |
**Path Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| patient_id | string | Yes | Patient identifier |
### Get All Patients
Retrieve data for all patients.
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/v1/medical-coder/patients` | Get all patient data |
## Code Examples
### Python
```python
import requests
import json
class MCSClient:
def __init__(self, base_url="https://mcs.swarms.ai", api_key=None):
self.base_url = base_url
self.headers = {
"Content-Type": "application/json",
"Authorization": f"Bearer {api_key}" if api_key else None
}
def run_medical_coder(self, patient_id, case_description):
endpoint = f"{self.base_url}/v1/medical-coder/run"
payload = {
"patient_id": patient_id,
"case_description": case_description
}
response = requests.post(endpoint, json=payload, headers=self.headers)
return response.json()
def run_batch(self, cases):
endpoint = f"{self.base_url}/v1/medical-coder/run-batch"
payload = {"cases": cases}
response = requests.post(endpoint, json=payload, headers=self.headers)
return response.json()
# Usage example
client = MCSClient(api_key="your_api_key")
result = client.run_medical_coder("P123", "Patient presents with...")
```
### Next.js (TypeScript)
```typescript
// types.ts
interface PatientCase {
patient_id: string;
case_description: string;
}
interface QueryResponse {
patient_id: string;
case_data: string;
}
// api.ts
export class MCSApi {
private baseUrl: string;
private apiKey: string;
constructor(apiKey: string, baseUrl = 'https://mcs.swarms.ai') {
this.baseUrl = baseUrl;
this.apiKey = apiKey;
}
private async fetchWithAuth(endpoint: string, options: RequestInit = {}) {
const response = await fetch(`${this.baseUrl}${endpoint}`, {
...options,
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${this.apiKey}`,
...options.headers,
},
});
return response.json();
}
async runMedicalCoder(patientCase: PatientCase): Promise<QueryResponse> {
return this.fetchWithAuth('/v1/medical-coder/run', {
method: 'POST',
body: JSON.stringify(patientCase),
});
}
async getPatientData(patientId: string): Promise<QueryResponse> {
return this.fetchWithAuth(`/v1/medical-coder/patient/${patientId}`);
}
}
// Usage in component
const mcsApi = new MCSApi(process.env.MCS_API_KEY);
export async function ProcessPatientCase({ patientId, caseDescription }) {
const result = await mcsApi.runMedicalCoder({
patient_id: patientId,
case_description: caseDescription,
});
return result;
}
```
### Go
```go
package mcs
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type MCSClient struct {
BaseURL string
APIKey string
Client *http.Client
}
type PatientCase struct {
PatientID string `json:"patient_id"`
CaseDescription string `json:"case_description"`
}
type QueryResponse struct {
PatientID string `json:"patient_id"`
CaseData string `json:"case_data"`
}
func NewMCSClient(apiKey string) *MCSClient {
return &MCSClient{
BaseURL: "https://mcs.swarms.ai",
APIKey: apiKey,
Client: &http.Client{},
}
}
func (c *MCSClient) RunMedicalCoder(patientCase PatientCase) (*QueryResponse, error) {
payload, err := json.Marshal(patientCase)
if err != nil {
return nil, err
}
req, err := http.NewRequest("POST",
fmt.Sprintf("%s/v1/medical-coder/run", c.BaseURL),
bytes.NewBuffer(payload))
if err != nil {
return nil, err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey))
resp, err := c.Client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var result QueryResponse
if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
return nil, err
}
return &result, nil
}
// Usage example
func main() {
client := NewMCSClient("your_api_key")
result, err := client.RunMedicalCoder(PatientCase{
PatientID: "P123",
CaseDescription: "Patient presents with...",
})
if err != nil {
panic(err)
}
fmt.Printf("Result: %+v\n", result)
}
```
## C Sharp
```txt
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
namespace MedicalCoderSwarm
{
public class PatientCase
{
public string PatientId { get; set; }
public string CaseDescription { get; set; }
}
public class QueryResponse
{
public string PatientId { get; set; }
public string CaseData { get; set; }
}
public class MCSClient : IDisposable
{
private readonly HttpClient _httpClient;
private readonly string _baseUrl;
public MCSClient(string apiKey, string baseUrl = "https://mcs-285321057562.us-central1.run.app")
{
_baseUrl = baseUrl;
_httpClient = new HttpClient();
_httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
_httpClient.DefaultRequestHeaders.Add("Content-Type", "application/json");
}
public async Task<QueryResponse> RunMedicalCoderAsync(string patientId, string caseDescription)
{
var payload = new PatientCase
{
PatientId = patientId,
CaseDescription = caseDescription
};
var content = new StringContent(
JsonSerializer.Serialize(payload),
Encoding.UTF8,
"application/json"
);
var response = await _httpClient.PostAsync(
$"{_baseUrl}/v1/medical-coder/run",
content
);
response.EnsureSuccessStatusCode();
var responseContent = await response.Content.ReadAsStringAsync();
return JsonSerializer.Deserialize<QueryResponse>(responseContent);
}
public async Task<QueryResponse> GetPatientDataAsync(string patientId)
{
var response = await _httpClient.GetAsync(
$"{_baseUrl}/v1/medical-coder/patient/{patientId}"
);
response.EnsureSuccessStatusCode();
var responseContent = await response.Content.ReadAsStringAsync();
return JsonSerializer.Deserialize<QueryResponse>(responseContent);
}
public async Task<bool> HealthCheckAsync()
{
var response = await _httpClient.GetAsync($"{_baseUrl}/health");
return response.IsSuccessStatusCode;
}
public void Dispose()
{
_httpClient?.Dispose();
}
}
// Example usage
public class Program
{
public static async Task Main()
{
try
{
using var client = new MCSClient("your_api_key");
// Check API health
var isHealthy = await client.HealthCheckAsync();
Console.WriteLine($"API Health: {(isHealthy ? "Healthy" : "Unhealthy")}");
// Process a single case
var result = await client.RunMedicalCoderAsync(
"P123",
"Patient presents with acute respiratory symptoms..."
);
Console.WriteLine($"Processed case for patient {result.PatientId}");
Console.WriteLine($"Case data: {result.CaseData}");
// Get patient data
var patientData = await client.GetPatientDataAsync("P123");
Console.WriteLine($"Retrieved data for patient {patientData.PatientId}");
}
catch (HttpRequestException ex)
{
Console.WriteLine($"API request failed: {ex.Message}");
}
catch (Exception ex)
{
Console.WriteLine($"An error occurred: {ex.Message}");
}
}
}
}
```
## Error Handling
The API uses standard HTTP status codes and returns detailed error messages in JSON format.
**Common Status Codes:**
| Status Code | Description |
|-------------|-------------|
| 200 | Success |
| 400 | Bad Request - Invalid input |
| 401 | Unauthorized - Invalid or missing API key |
| 422 | Validation Error - Request validation failed |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
**Error Response Format:**
```json
{
"detail": [
{
"loc": ["body", "patient_id"],
"msg": "field required",
"type": "value_error.missing"
}
]
}
```
# MCS Python Client Documentation
## Installation
```bash
pip install mcs
```
## Quick Start
```python
from mcs import MCSClient, PatientCase
# Using context manager (recommended)
with MCSClient() as client:
# Process a single case
response = client.run_medical_coder(
patient_id="P123",
case_description="Patient presents with acute respiratory symptoms..."
)
print(f"Processed case: {response.case_data}")
# Process multiple cases
cases = [
PatientCase("P124", "Case 1 description..."),
PatientCase("P125", "Case 2 description...")
]
batch_response = client.run_batch(cases)
```
## Client Configuration
### Constructor Arguments
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| api_key | str | Yes | - | Authentication API key |
| base_url | str | No | "https://mcs.swarms.ai" | API base URL |
| timeout | int | No | 30 | Request timeout in seconds |
| max_retries | int | No | 3 | Maximum retry attempts |
| logger_name | str | No | "mcs" | Name for the logger instance |
### Example Configuration
```python
client = MCSClient(
base_url="https://custom-url.example.com",
timeout=45,
max_retries=5,
logger_name="custom_logger"
)
```
## Data Models
### PatientCase
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| patient_id | str | Yes | Unique identifier for the patient |
| case_description | str | Yes | Medical case details |
### QueryResponse
| Field | Type | Description |
|-------|------|-------------|
| patient_id | str | Patient identifier |
| case_data | str | Processed case data |
## Methods
### run_medical_coder
Process a single patient case.
```python
def run_medical_coder(
self,
patient_id: str,
case_description: str
) -> QueryResponse:
```
**Arguments:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| patient_id | str | Yes | Patient identifier |
| case_description | str | Yes | Case details |
**Example:**
```python
response = client.run_medical_coder(
patient_id="P123",
case_description="Patient presents with..."
)
print(response.case_data)
```
### run_batch
Process multiple patient cases in batch.
```python
def run_batch(
self,
cases: List[PatientCase]
) -> List[QueryResponse]:
```
**Arguments:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| cases | List[PatientCase] | Yes | List of patient cases |
**Example:**
```python
cases = [
PatientCase("P124", "Case 1 description..."),
PatientCase("P125", "Case 2 description...")
]
responses = client.run_batch(cases)
for response in responses:
print(f"Patient {response.patient_id}: {response.case_data}")
```
### get_patient_data
Retrieve data for a specific patient.
```python
def get_patient_data(
self,
patient_id: str
) -> QueryResponse:
```
**Example:**
```python
patient_data = client.get_patient_data("P123")
print(f"Patient data: {patient_data.case_data}")
```
### get_all_patients
Retrieve data for all patients.
```python
def get_all_patients(self) -> List[QueryResponse]:
```
**Example:**
```python
all_patients = client.get_all_patients()
for patient in all_patients:
print(f"Patient {patient.patient_id}: {patient.case_data}")
```
### get_rate_limits
Get current rate limit status.
```python
def get_rate_limits(self) -> Dict[str, Any]:
```
**Example:**
```python
rate_limits = client.get_rate_limits()
print(f"Rate limit status: {rate_limits}")
```
### health_check
Check if the API is operational.
```python
def health_check(self) -> bool:
```
**Example:**
```python
is_healthy = client.health_check()
print(f"API health: {'Healthy' if is_healthy else 'Unhealthy'}")
```
## Error Handling
### Exception Hierarchy
| Exception | Description |
|-----------|-------------|
| MCSClientError | Base exception for all client errors |
| RateLimitError | Raised when API rate limit is exceeded |
| AuthenticationError | Raised when API authentication fails |
| ValidationError | Raised when request validation fails |
### Example Error Handling
```python
from mcs import MCSClient, MCSClientError, RateLimitError
with MCSClient() as client:
try:
response = client.run_medical_coder("P123", "Case description...")
except RateLimitError:
print("Rate limit exceeded. Please wait before retrying.")
except MCSClientError as e:
print(f"An error occurred: {str(e)}")
```
## Advanced Usage
### Retry Configuration
The client implements two levels of retry logic:
1. Connection-level retries (using `HTTPAdapter`):
```python
client = MCSClient(
,
max_retries=5 # Adjusts connection-level retries
)
```
2. Application-level retries (using `tenacity`):
```python
from tenacity import retry, stop_after_attempt
@retry(stop=stop_after_attempt(5))
def process_with_custom_retries():
with MCSClient() as client:
return client.run_medical_coder("P123", "Case description...")
```
### Batch Processing with Progress Tracking
```python
from tqdm import tqdm
with MCSClient() as client:
cases = [
PatientCase(f"P{i}", f"Case description {i}")
for i in range(100)
]
# Process in smaller batches
batch_size = 10
results = []
for i in tqdm(range(0, len(cases), batch_size)):
batch = cases[i:i + batch_size]
batch_results = client.run_batch(batch)
results.extend(batch_results)
```
## Best Practices
1. **Always use context managers:**
```python
with MCSClient() as client:
# Your code here
pass
```
2. **Handle rate limits appropriately:**
```python
from time import sleep
def process_with_rate_limit_handling():
with MCSClient() as client:
try:
return client.run_medical_coder("P123", "Case...")
except RateLimitError:
sleep(60) # Wait before retry
return client.run_medical_coder("P123", "Case...")
```
3. **Implement proper logging:**
```python
from loguru import logger
logger.add("mcs.log", rotation="500 MB")
with MCSClient() as client:
try:
response = client.run_medical_coder("P123", "Case...")
except Exception as e:
logger.exception(f"Error processing case: {str(e)}")
```
4. **Monitor API health:**
```python
def ensure_healthy_api():
with MCSClient() as client:
if not client.health_check():
raise SystemExit("API is not healthy")
```

222
docs/swarms_cloud/mixture_of_agents.md
Unescape View File

@ -1,222 +0,0 @@
# MixtureOfAgents
*Builds diverse teams of specialized agents for complex problem solving*
**Swarm Type**: `MixtureOfAgents`
## Overview
The MixtureOfAgents swarm type combines multiple agent types with different specializations to tackle diverse aspects of complex problems. Each agent contributes unique skills and perspectives, making this architecture ideal for tasks requiring multiple types of expertise working in harmony.
Key features:
- **Diverse Expertise**: Combines agents with different specializations
- **Collaborative Problem Solving**: Agents work together leveraging their unique strengths
- **Comprehensive Coverage**: Ensures all aspects of complex tasks are addressed
- **Balanced Perspectives**: Multiple viewpoints for robust decision-making
## Use Cases
- Complex research projects requiring multiple disciplines
- Business analysis needing various functional perspectives
- Content creation requiring different expertise areas
- Strategic planning with multiple considerations
## API Usage
### Basic MixtureOfAgents Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Business Strategy Mixture",
"description": "Diverse team analyzing business strategy from multiple perspectives",
"swarm_type": "MixtureOfAgents",
"task": "Develop a comprehensive market entry strategy for a new AI product in the healthcare sector",
"agents": [
{
"agent_name": "Market Research Analyst",
"description": "Analyzes market trends and opportunities",
"system_prompt": "You are a market research expert specializing in healthcare technology. Analyze market size, trends, and competitive landscape.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Financial Analyst",
"description": "Evaluates financial viability and projections",
"system_prompt": "You are a financial analyst expert. Assess financial implications, ROI, and cost structures for business strategies.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Regulatory Expert",
"description": "Analyzes compliance and regulatory requirements",
"system_prompt": "You are a healthcare regulatory expert. Analyze compliance requirements, regulatory pathways, and potential barriers.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.1
},
{
"agent_name": "Technology Strategist",
"description": "Evaluates technical feasibility and strategy",
"system_prompt": "You are a technology strategy expert. Assess technical requirements, implementation challenges, and scalability.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
}
],
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Business Strategy Mixture",
"description": "Diverse team analyzing business strategy from multiple perspectives",
"swarm_type": "MixtureOfAgents",
"task": "Develop a comprehensive market entry strategy for a new AI product in the healthcare sector",
"agents": [
{
"agent_name": "Market Research Analyst",
"description": "Analyzes market trends and opportunities",
"system_prompt": "You are a market research expert specializing in healthcare technology. Analyze market size, trends, and competitive landscape.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Financial Analyst",
"description": "Evaluates financial viability and projections",
"system_prompt": "You are a financial analyst expert. Assess financial implications, ROI, and cost structures for business strategies.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Regulatory Expert",
"description": "Analyzes compliance and regulatory requirements",
"system_prompt": "You are a healthcare regulatory expert. Analyze compliance requirements, regulatory pathways, and potential barriers.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.1
},
{
"agent_name": "Technology Strategist",
"description": "Evaluates technical feasibility and strategy",
"system_prompt": "You are a technology strategy expert. Assess technical requirements, implementation challenges, and scalability.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
}
],
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("MixtureOfAgents swarm completed successfully!")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Output: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-kBZaJg1uGTkRbLCAsGztL2jrp5Mj",
"status": "success",
"swarm_name": "Business Strategy Mixture",
"description": "Diverse team analyzing business strategy from multiple perspectives",
"swarm_type": "MixtureOfAgents",
"output": [
{
"role": "System",
"content": "Team Name: Business Strategy Mixture\nTeam Description: Diverse team analyzing business strategy from multiple perspectives\nThese are the agents in your team. Each agent has a specific role and expertise to contribute to the team's objectives.\nTotal Agents: 4\n\nBelow is a summary of your team members and their primary responsibilities:\n| Agent Name | Description |\n|------------|-------------|\n| Market Research Analyst | Analyzes market trends and opportunities |\n| Financial Analyst | Evaluates financial viability and projections |\n| Regulatory Expert | Analyzes compliance and regulatory requirements |\n| Technology Strategist | Evaluates technical feasibility and strategy |\n\nEach agent is designed to handle tasks within their area of expertise. Collaborate effectively by assigning tasks according to these roles."
},
{
"role": "Market Research Analyst",
"content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we will leverage the expertise of each team member to cover all critical aspects of the strategy. Here's how each agent will contribute......."
},
{
"role": "Technology Strategist",
"content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we'll need to collaborate effectively with the team, leveraging each member's expertise. Here's how each agent can contribute to the strategy, along with a focus on the technical requirements, implementation challenges, and scalability from the technology strategist's perspective....."
},
{
"role": "Financial Analyst",
"content": "Developing a comprehensive market entry strategy for a new AI product in the healthcare sector involves a multidisciplinary approach. Each agent in the Business Strategy Mixture team will play a crucial role in ensuring a successful market entry. Here's how the team can collaborate........"
},
{
"role": "Regulatory Expert",
"content": "To develop a comprehensive market entry strategy for a new AI product in the healthcare sector, we need to leverage the expertise of each agent in the Business Strategy Mixture team. Below is an outline of how each team member can contribute to this strategy......"
},
{
"role": "Aggregator Agent",
"content": "As the Aggregator Agent, I've observed and analyzed the responses from the Business Strategy Mixture team regarding the development of a comprehensive market entry strategy for a new AI product in the healthcare sector. Here's a summary of the key points ......"
}
],
"number_of_agents": 4,
"service_tier": "standard",
"execution_time": 30.230480670928955,
"usage": {
"input_tokens": 30,
"output_tokens": 3401,
"total_tokens": 3431,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.04,
"input_token_cost": 0.00009,
"output_token_cost": 0.051015,
"token_counts": {
"total_input_tokens": 30,
"total_output_tokens": 3401,
"total_tokens": 3431
},
"num_agents": 4,
"service_tier": "standard",
"night_time_discount_applied": true
},
"total_cost": 0.091105,
"discount_active": true,
"discount_type": "night_time",
"discount_percentage": 75
}
}
}
```
## Best Practices
- Select agents with complementary and diverse expertise
- Ensure each agent has a clear, specialized role
- Use for complex problems requiring multiple perspectives
- Design tasks that benefit from collaborative analysis
## Related Swarm Types
- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel task execution
- [GroupChat](group_chat.md) - For collaborative discussion
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic team assembly

211
docs/swarms_cloud/multi_agent_router.md
Unescape View File

@ -1,211 +0,0 @@
# MultiAgentRouter
*Intelligent task dispatcher distributing work based on agent capabilities*
**Swarm Type**: `MultiAgentRouter`
## Overview
The MultiAgentRouter acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. This architecture analyzes incoming tasks and automatically routes them to the most suitable agents, optimizing both efficiency and quality of outcomes.
Key features:
- **Intelligent Routing**: Automatically assigns tasks to best-suited agents
- **Capability Matching**: Matches task requirements with agent specializations
- **Load Balancing**: Distributes workload efficiently across available agents
- **Dynamic Assignment**: Adapts routing based on agent performance and availability
## Use Cases
- Customer service request routing
- Content categorization and processing
- Technical support ticket assignment
- Multi-domain question answering
## API Usage
### Basic MultiAgentRouter Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Support Router",
"description": "Route customer inquiries to specialized support agents",
"swarm_type": "MultiAgentRouter",
"task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question",
"agents": [
{
"agent_name": "Billing Specialist",
"description": "Handles billing, payments, and account issues",
"system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Technical Support",
"description": "Resolves technical issues and troubleshooting",
"system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Sales Consultant",
"description": "Provides product recommendations and sales support",
"system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.4
},
{
"agent_name": "Policy Advisor",
"description": "Explains company policies and procedures",
"system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.1
}
],
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Customer Support Router",
"description": "Route customer inquiries to specialized support agents",
"swarm_type": "MultiAgentRouter",
"task": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question",
"agents": [
{
"agent_name": "Billing Specialist",
"description": "Handles billing, payments, and account issues",
"system_prompt": "You are a billing specialist. Handle all billing inquiries, payment issues, refunds, and account-related questions with empathy and accuracy.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Technical Support",
"description": "Resolves technical issues and troubleshooting",
"system_prompt": "You are a technical support specialist. Diagnose and resolve technical issues, provide step-by-step troubleshooting, and escalate complex problems.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
},
{
"agent_name": "Sales Consultant",
"description": "Provides product recommendations and sales support",
"system_prompt": "You are a sales consultant. Provide product recommendations, explain features and benefits, and help customers find the right solutions.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.4
},
{
"agent_name": "Policy Advisor",
"description": "Explains company policies and procedures",
"system_prompt": "You are a policy advisor. Explain company policies, terms of service, return procedures, and compliance requirements clearly.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.1
}
],
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("MultiAgentRouter completed successfully!")
print(f"Routing decisions: {result['metadata']['routing_decisions']}")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Customer responses: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-OvOZHubprE3thzLmRdNBZAxA6om4",
"status": "success",
"swarm_name": "Customer Support Router",
"description": "Route customer inquiries to specialized support agents",
"swarm_type": "MultiAgentRouter",
"output": [
{
"role": "user",
"content": "Handle multiple customer inquiries: 1) Billing question about overcharge, 2) Technical issue with mobile app login, 3) Product recommendation for enterprise client, 4) Return policy question"
},
{
"role": "Agent Router",
"content": "selected_agent='Billing Specialist' reasoning='The task involves multiple inquiries, but the first one is about a billing question regarding an overcharge. Billing issues often require immediate attention to ensure customer satisfaction and prevent further complications. Therefore, the Billing Specialist is the most appropriate agent to handle this task. They can address the billing question directly and potentially coordinate with other agents for the remaining inquiries.' modified_task='Billing question about overcharge'"
},
{
"role": "Billing Specialist",
"content": "Of course, I'd be happy to help you with your billing question regarding an overcharge. Could you please provide me with more details about the charge in question, such as the date it occurred and the amount? This information will help me look into your account and resolve the issue as quickly as possible."
}
],
"number_of_agents": 4,
"service_tier": "standard",
"execution_time": 7.800086975097656,
"usage": {
"input_tokens": 28,
"output_tokens": 221,
"total_tokens": 249,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.04,
"input_token_cost": 0.000084,
"output_token_cost": 0.003315,
"token_counts": {
"total_input_tokens": 28,
"total_output_tokens": 221,
"total_tokens": 249
},
"num_agents": 4,
"service_tier": "standard",
"night_time_discount_applied": true
},
"total_cost": 0.043399,
"discount_active": true,
"discount_type": "night_time",
"discount_percentage": 75
}
}
}
```
## Best Practices
- Define agents with clear, distinct specializations
- Use descriptive agent names and descriptions for better routing
- Ideal for handling diverse task types that require different expertise
- Monitor routing decisions to optimize agent configurations
## Related Swarm Types
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured task management
- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel task processing
- [AutoSwarmBuilder](auto_swarm_builder.md) - For automatic routing setup

319
docs/swarms_cloud/production_deployment.md
Unescape View File

@ -1,319 +0,0 @@
# Enterprise Guide to High-Performance Multi-Agent LLM Deployments
-------
As large language models (LLMs) continue to advance and enable a wide range of powerful applications, enterprises are increasingly exploring multi-agent architectures to leverage the collective capabilities of multiple LLMs. However, coordinating and optimizing the performance of these complex multi-agent systems presents significant challenges.
This comprehensive guide provides enterprise architects, engineering leaders, and technical decision-makers with a strategic framework for maximizing performance across multi-agent LLM deployments. Developed through extensive research and collaboration with industry partners, this guide distills best practices, proven techniques, and cutting-edge methodologies into seven core principles.
By implementing the recommendations outlined in this guide, organizations can achieve superior latency, throughput, and resource utilization while ensuring scalability, cost-effectiveness, and optimal user experiences. Whether powering customer-facing conversational agents, driving internal knowledge management systems, or fueling mission-critical decision support tools, high-performance multi-agent LLM deployments will be pivotal to unlocking the full potential of this transformative technology.
## Introduction
The rise of large language models (LLMs) has ushered in a new era of human-machine interaction, enabling enterprises to develop sophisticated natural language processing (NLP) applications that can understand, generate, and reason with human-like text. However, as the complexity and scale of LLM deployments grow, traditional monolithic architectures are increasingly challenged to meet the stringent performance, scalability, and cost requirements of enterprise environments.
Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLMs, have emerged as a powerful paradigm for addressing these challenges. By distributing workloads across a cohort of agents, each optimized for specific tasks or domains, multi-agent systems can deliver superior performance, resilience, and adaptability compared to single-model solutions.
However, realizing the full potential of multi-agent LLM deployments requires a strategic approach to system design, optimization, and ongoing management. This guide presents a comprehensive framework for maximizing performance across seven core principles, each underpinned by a range of proven techniques and methodologies.
Whether you are architecting a customer-facing conversational agent, building an internal knowledge management platform, or developing a mission-critical decision support system, this guide will equip you with the insights and best practices necessary to unlock the full potential of multi-agent LLM deployments within your enterprise.
## Principle 1: Distribute Token Processing
----------------------------------------
At the heart of every LLM deployment lies the fundamental challenge of optimizing token processing -- the rate at which the model consumes and generates text inputs and outputs. In multi-agent architectures, distributing and parallelizing token processing across multiple agents is a critical performance optimization strategy.
### Agent Specialization
One of the key advantages of multi-agent architectures is the ability to dedicate specific agents to specialized tasks or domains. By carefully matching agents to the workloads they are optimized for, enterprises can maximize overall throughput and minimize latency.
For example, in a conversational agent deployment, one agent may be optimized for intent recognition and query understanding, while another is fine-tuned for generating coherent, context-aware responses. In a document processing pipeline, separate agents could be dedicated to tasks such as named entity recognition, sentiment analysis, and summarization.
To effectively leverage agent specialization, enterprises should:
- Conduct a thorough analysis of their application's workflow and identify distinct tasks or domains that could benefit from dedicated agents.
- Evaluate the strengths and weaknesses of available LLM models and agents, and map them to the identified tasks or domains based on their capabilities and performance characteristics.
- Implement continuous monitoring and performance tuning processes to ensure agents remain optimized for their assigned workloads as models evolve and domain requirements shift.
### Load Balancing
Even with a well-designed allocation of tasks across specialized agents, fluctuations in workload and demand can create bottlenecks and performance degradation. Effective load balancing strategies are essential to ensure that token processing capacity is dynamically distributed across available agents based on real-time conditions.
Load balancing in multi-agent LLM deployments can be accomplished through a combination of techniques, including:
- **Round-Robin**: Distributing incoming requests across agents in a cyclical fashion, ensuring an even distribution of workload.
- **Least Connections**: Routing requests to the agent with the fewest active connections or outstanding tasks, minimizing the risk of overloading any single agent.
- **Response Time Monitoring**: Continuously monitoring the response times of each agent and dynamically adjusting request routing to favor faster-responding agents.
- **Resource-Based Routing**: Factoring in agent-level resource consumption (e.g., CPU, memory) when making routing decisions, ensuring that overloaded agents are relieved of additional workload.
Implementing effective load balancing requires careful consideration of the specific characteristics and requirements of your multi-agent deployment, as well as the integration of robust monitoring and analytics capabilities to inform dynamic routing decisions.
### Horizontal Scaling
While load balancing optimizes the utilization of existing agent resources, horizontal scaling strategies enable organizations to dynamically provision additional token processing capacity to meet demand spikes or handle larger overall workloads.
In multi-agent LLM deployments, horizontal scaling can be achieved through:
- **Agent Replication**: Spin up additional instances of existing agents to increase parallel processing capacity for specific tasks or domains.
- **Hybrid Scaling**: Combine agent replication with the dynamic provisioning of additional compute resources (e.g., CPU, GPU) to support the increased agent count.
- **Serverless Deployment**: Leverage serverless computing platforms (e.g., AWS Lambda, Google Cloud Functions) to automatically scale agent instances based on real-time demand, minimizing idle resource consumption.
Effective horizontal scaling requires robust orchestration and management capabilities, as well as seamless integration with load balancing mechanisms to ensure that incoming workloads are efficiently distributed across the dynamically scaled agent pool.
## Principle 2: Optimize Agent Communication
-----------------------------------------
In multi-agent LLM deployments, efficient inter-agent communication is crucial for coordinating tasks, exchanging context and intermediate results, and maintaining overall system coherence. However, communication overhead can quickly become a performance bottleneck if not carefully managed.
### Minimizing Overhead
Reducing the volume and complexity of information exchanged between agents is a key strategy for optimizing communication performance. Techniques for minimizing overhead include:
- **Data Compression**: Applying lossless or lossy compression algorithms to reduce the size of data payloads exchanged between agents, lowering bandwidth requirements and transmission latencies.
- **Information Summarization**: Distilling and summarizing context, results, or other data exchanged between agents to its essential elements, minimizing redundant or non-critical information.
- **Differential Updates**: Rather than transmitting entire data payloads, agents can exchange only the differential updates or deltas required to synchronize their respective states.
Implementing these techniques requires careful analysis of the specific data exchange patterns and communication requirements within your multi-agent deployment, as well as the integration of appropriate compression, summarization, and differential update algorithms.
### Prioritizing Critical Information
In scenarios where communication bandwidth or latency constraints cannot be fully alleviated through overhead reduction techniques, enterprises can prioritize the exchange of critical information over non-essential data.
This can be achieved through:
- **Prioritized Queuing**: Implementing queuing mechanisms that prioritize the transmission of high-priority, time-sensitive data over lower-priority, non-critical information.
- **Selective Communication**: Dynamically determining which agents require specific pieces of information based on their roles and responsibilities, and selectively transmitting data only to those agents that truly need it.
- **Progressive Information Exchange**: Exchanging information in a progressive or staged manner, with critical elements transmitted first, followed by supplementary or contextual data as bandwidth becomes available.
Effective prioritization requires a deep understanding of the interdependencies and information flow within your multi-agent system, as well as the ability to dynamically assess and prioritize data based on its criticality and urgency.
### Caching and Reusing Context
In many multi-agent LLM deployments, agents frequently exchange or operate on shared context, such as user profiles, conversation histories, or domain-specific knowledge bases. Caching and reusing this context information can significantly reduce redundant communication and processing overhead.
Strategies for optimizing context caching and reuse include:
- **Agent-Level Caching**: Implementing caching mechanisms within individual agents to store and retrieve frequently accessed context data, minimizing the need for inter-agent communication.
- **Centralized Context Management**: Deploying a dedicated context management service or data store that agents can query and update, ensuring consistent access to the latest context information across the system.
- **Context Versioning and Invalidation**: Implementing versioning and invalidation mechanisms to ensure that cached context data remains fresh and consistent, avoiding stale or outdated information from propagating through the system.
### Principle 3: Leverage Agent Specialization
------------------------------------------
One of the key advantages of multi-agent architectures is the ability to optimize individual agents for specific tasks, domains, or capabilities. By leveraging agent specialization, enterprises can ensure that each component of their LLM system is finely tuned for maximum performance and quality.
### Task-Specific Optimization
Within a multi-agent LLM deployment, different agents may be responsible for distinct tasks such as language understanding, knowledge retrieval, response generation, or post-processing. Optimizing each agent for its designated task can yield significant performance gains and quality improvements.
Techniques for task-specific optimization include:
- **Prompt Engineering**: Crafting carefully designed prompts that provide the necessary context, instructions, and examples to guide an agent towards optimal performance for its assigned task.
- **Fine-Tuning**: Adapting a pre-trained LLM to a specific task or domain by fine-tuning it on a curated dataset, allowing the agent to specialize and improve its performance on that particular workload.
- **Model Distillation**: Transferring the knowledge and capabilities of a larger, more capable LLM into a smaller, more efficient model specialized for a specific task, balancing performance and quality trade-offs.
Implementing these optimization techniques requires a deep understanding of the capabilities and requirements of each task within your multi-agent system, as well as access to relevant training data and computational resources for fine-tuning and distillation processes.
### Domain Adaptation
Many enterprise applications operate within specific domains or verticals, such as finance, healthcare, or legal. Adapting agents to these specialized domains can significantly improve their performance, accuracy, and compliance within the target domain.
Strategies for domain adaptation include:
- **Domain-Specific Pre-Training**: Leveraging domain-specific corpora to pre-train LLM agents, imbuing them with a foundational understanding of the language, concepts, and nuances specific to the target domain.
- **Transfer Learning**: Fine-tuning agents that have been pre-trained on general or adjacent domains, transferring their existing knowledge and capabilities to the target domain while optimizing for its specific characteristics.
- **Domain Persona Injection**: Injecting domain-specific personas, traits, or constraints into agents during fine-tuning or deployment, shaping their behavior and outputs to align with domain-specific norms and requirements.
Effective domain adaptation requires access to high-quality, domain-specific training data, as well as close collaboration with subject matter experts to ensure that agents are properly calibrated to meet the unique demands of the target domain.
### Ensemble Techniques
In complex multi-agent deployments, individual agents may excel at specific subtasks or aspects of the overall workflow. Ensemble techniques that combine the outputs or predictions of multiple specialized agents can often outperform any single agent, leveraging the collective strengths of the ensemble.
Common ensemble techniques for multi-agent LLM systems include:
- **Voting**: Combining the outputs or predictions of multiple agents through majority voting, weighted voting, or other consensus mechanisms.
- **Stacking**: Training a meta-agent to combine and optimize the outputs of multiple base agents, effectively learning to leverage their collective strengths.
- **Blending**: Combining the outputs of multiple agents through weighted averaging, linear interpolation, or other blending techniques, allowing for nuanced integration of diverse perspectives.
Implementing effective ensemble techniques requires careful analysis of the strengths, weaknesses, and complementary capabilities of individual agents, as well as the development of robust combination strategies that can optimally leverage the ensemble's collective intelligence.
### Principle 4: Implement Dynamic Scaling
--------------------------------------
The demand and workload patterns of enterprise LLM deployments can be highly dynamic, with significant fluctuations driven by factors such as user activity, data ingestion schedules, or periodic batch processing. Implementing dynamic scaling strategies allows organizations to optimally provision and allocate resources in response to these fluctuations, ensuring consistent performance while minimizing unnecessary costs.
### Autoscaling
Autoscaling is a core capability that enables the automatic adjustment of compute resources (e.g., CPU, GPU, memory) and agent instances based on real-time demand patterns and workload metrics. By dynamically scaling resources up or down, enterprises can maintain optimal performance and resource utilization, avoiding both over-provisioning and under-provisioning scenarios.
Effective autoscaling in multi-agent LLM deployments requires:
- **Monitoring and Metrics**: Implementing robust monitoring and metrics collection mechanisms to track key performance indicators (KPIs) such as request rates, response times, resource utilization, and agent-level metrics.
- **Scaling Policies**: Defining scaling policies that specify the conditions and thresholds for triggering automatic scaling actions, such as provisioning additional agents or compute resources when certain KPIs are breached.
- **Scaling Orchestration**: Integrating autoscaling capabilities with resource orchestration and management tools (e.g., Kubernetes, AWS Auto Scaling) to seamlessly provision, configure, and integrate new resources into the existing multi-agent deployment.
By automating the scaling process, enterprises can respond rapidly to workload fluctuations, ensuring consistent performance and optimal resource utilization without the need for manual intervention.
### Spot Instance Utilization
Many cloud providers offer spot instances or preemptible resources at significantly discounted prices compared to on-demand or reserved instances. While these resources may be reclaimed with little notice, they can be leveraged judiciously within multi-agent LLM deployments to reduce operational costs.
Strategies for leveraging spot instances include:
- **Fault-Tolerant Agent Deployment**: Deploying certain agents or components of the multi-agent system on spot instances, while ensuring that these components can be rapidly and seamlessly replaced or migrated in the event of instance preemption.
- **Batch Workload Offloading**: Offloading batch processing workloads or non-time-sensitive tasks to spot instances, leveraging their cost-effectiveness while minimizing the impact of potential disruptions.
- **Hybrid Provisioning**: Implementing a hybrid approach that combines on-demand or reserved instances for mission-critical components with spot instances for more flexible or elastic workloads.
Effective spot instance utilization requires careful architectural considerations to ensure fault tolerance and minimize the impact of potential disruptions, as well as robust monitoring and automation capabilities to seamlessly replace or migrate workloads in response to instance preemption events.
### Serverless Deployments
Serverless computing platforms, such as AWS Lambda, Google Cloud Functions, or Azure Functions, offer a compelling alternative to traditional server-based deployments. By automatically scaling compute resources based on real-time demand and charging only for the resources consumed, serverless architectures can provide significant cost savings and operational simplicity.
Leveraging serverless deployments for multi-agent LLM systems can be achieved through:
- **Function-as-a-Service (FaaS) Agents**: Deploying individual agents or components of the multi-agent system as serverless functions, allowing for rapid and automatic scaling in response to fluctuating workloads.
- **Event-Driven Architectures**: Designing the multi-agent system to operate in an event-driven manner, with agents triggered and executed in response to specific events or data ingestion, aligning with the serverless execution model.
- **Hybrid Deployments**: Combining serverless components with traditional server-based components, leveraging the strengths and cost advantages of each deployment model for different aspects of the multi-agent system.
Adopting serverless architectures requires careful consideration of factors such as execution duration limits, cold start latencies, and integration with other components of the multi-agent deployment. However, when implemented effectively, serverless deployments can provide unparalleled scalability, cost-efficiency, and operational simplicity for dynamic, event-driven workloads.
### Principle 5: Employ Selective Execution
---------------------------------------
Not every input or request within a multi-agent LLM deployment requires the full execution of all agents or the complete processing pipeline. Selectively invoking agents or tasks based on input characteristics or intermediate results can significantly optimize performance by avoiding unnecessary computation and resource consumption.
### Input Filtering
Implementing input filtering mechanisms allows enterprises to reject or bypass certain inputs before they are processed by the multi-agent system. This can be achieved through techniques such as:
- **Blacklisting/Whitelisting**: Maintaining lists of inputs (e.g., specific phrases, URLs, or content types) that should be automatically rejected or allowed, based on predefined criteria.
- **Rules-Based Filtering**: Defining a set of rules or heuristics to assess the suitability or relevance of an input for further processing, based on factors such as language, content, or metadata.
- **Confidence Thresholding**: Leveraging pre-processing agents or models to assess the likelihood that an input is relevant or valuable, and filtering out inputs that fall below a predetermined confidence threshold.
Effective input filtering requires careful consideration of the specific requirements, constraints, and objectives of your multi-agent deployment, as well as ongoing monitoring and adjustment of filtering rules and thresholds to maintain optimal performance and accuracy.
### Early Stopping
In many multi-agent LLM deployments, intermediate results or predictions generated by early-stage agents can be used to determine whether further processing is required or valuable. Early stopping mechanisms allow enterprises to terminate execution pipelines when specific conditions or thresholds are met, avoiding unnecessary downstream processing.
Techniques for implementing early stopping include:
- **Confidence-Based Stopping**: Monitoring the confidence scores or probabilities associated with intermediate results, and terminating execution if a predefined confidence threshold is exceeded.
- **Exception-Based Stopping**: Defining specific intermediate results or conditions that indicate that further processing is unnecessary or undesirable, and terminating execution upon encountering these exceptions.
- **Adaptive Stopping**: Employing machine learning models or reinforcement learning agents to dynamically determine when to terminate execution based on learned patterns and trade-offs between accuracy, latency, and resource consumption.
Effective early stopping requires a deep understanding of the interdependencies and decision points within your multi-agent workflow, as well as careful tuning and monitoring to ensure that stopping conditions are calibrated to maintain an optimal balance between performance and accuracy.
### Conditional Branching
Rather than executing a linear, fixed pipeline of agents, conditional branching allows multi-agent systems to dynamically invoke different agents or execution paths based on input characteristics or intermediate results. This can significantly optimize resource utilization by ensuring that only the necessary agents and processes are executed for a given input or scenario.
Implementing conditional branching involves:
- **Decision Points**: Identifying key points within the multi-agent workflow where branching decisions can be made based on input or intermediate data.
- **Branching Logic**: Defining the rules, conditions, or machine learning models that will evaluate the input or intermediate data and determine the appropriate execution path or agent invocation.
- **Execution Routing**: Integrating mechanisms to dynamically route inputs or intermediate data to the appropriate agents or processes based on the branching decision.
Conditional branching can be particularly effective in scenarios where inputs or workloads exhibit distinct characteristics or require significantly different processing pipelines, allowing enterprises to optimize resource allocation and minimize unnecessary computation.
### Principle 6: Optimize User Experience
-------------------------------------
While many of the principles outlined in this guide focus on optimizing backend performance and resource utilization, delivering an exceptional user experience is also a critical consideration for enterprise multi-agent LLM deployments. By minimizing perceived wait times and providing real-time progress updates, organizations can ensure that users remain engaged and satisfied, even during periods of high workload or resource constraints.
### Streaming Responses
One of the most effective techniques for minimizing perceived wait times is to stream responses or outputs to users as they are generated, rather than waiting for the entire response to be completed before delivering it. This approach is particularly valuable in conversational agents, document summarization, or other scenarios where outputs can be naturally segmented and delivered incrementally.
Implementing streaming responses requires:
- **Partial Output Generation**: Modifying agents or models to generate and emit outputs in a streaming or incremental fashion, rather than producing the entire output in a single, monolithic operation.
- **Streaming Data Pipelines**: Integrating streaming data pipelines and message queues to enable the efficient and reliable transmission of partial outputs from agents to user-facing interfaces or applications.
- **Incremental Rendering**: Updating user interfaces and displays to incrementally render or populate with newly streamed output segments, providing a seamless and real-time experience for end-users.
By delivering outputs as they are generated, streaming responses can significantly improve the perceived responsiveness and interactivity of multi-agent LLM deployments, even in scenarios where the overall processing time remains unchanged.
### Progress Indicators
In cases where streaming responses may not be feasible or appropriate, providing visual or textual indicators of ongoing processing and progress can help manage user expectations and improve the overall experience. Progress indicators can be implemented through techniques such as:
- **Loader Animations**: Displaying simple animations or spinner graphics to indicate that processing is underway and provide a sense of activity and progress.
- **Progress Bars**: Rendering progress bars or completion indicators based on estimated or actual progress through multi-agent workflows or processing pipelines.
- **Status Updates**: Periodically updating user interfaces with textual status messages or descriptions of the current processing stage, providing users with a more detailed understanding of the system's activities.
Effective progress indicators require careful integration with monitoring and telemetry capabilities to accurately track and communicate the progress of multi-agent workflows, as well as thoughtful user experience design to ensure that indicators are clear, unobtrusive, and aligned with user expectations.
### Chunked Delivery
In scenarios where outputs or responses cannot be effectively streamed or rendered incrementally, chunked delivery can provide a middle ground between delivering the entire output at once and streaming individual tokens or characters. By breaking larger outputs into smaller, more manageable chunks and delivering them individually, enterprises can improve perceived responsiveness and provide a more engaging user experience.
Implementing chunked delivery involves:
- **Output Segmentation**: Identifying logical breakpoints or segmentation boundaries within larger outputs, such as paragraphs, sections, or other structural elements.
- **Chunking Mechanisms**: Integrating mechanisms to efficiently break outputs into individual chunks and transmit or render them sequentially, with minimal delay between chunks.
- **Chunk Rendering**: Updating user interfaces or displays to seamlessly render or append new output chunks as they are received, providing a sense of continuous progress and minimizing the perception of extended waiting periods.
Chunked delivery can be particularly effective in scenarios where outputs are inherently structured or segmented, such as document generation, report creation, or multi-step instructions or workflows.
## Principle 7: Leverage Hybrid Approaches
---------------------------------------
While multi-agent LLM architectures offer numerous advantages, they should not be viewed as a one-size-fits-all solution. In many cases, combining LLM agents with traditional techniques, optimized components, or external services can yield superior performance, cost-effectiveness, and resource utilization compared to a pure LLM-based approach.
### Task Offloading
Certain tasks or subtasks within a larger multi-agent workflow may be more efficiently handled by dedicated, optimized components or external services, rather than relying solely on LLM agents. Task offloading involves identifying these opportunities and integrating the appropriate components or services into the overall architecture.
Examples of task offloading in multi-agent LLM deployments include:
- **Regular Expression Matching**: Offloading pattern matching or text extraction tasks to dedicated regular expression engines, which can often outperform LLM-based approaches in terms of speed and efficiency.
- **Structured Data Processing**: Leveraging specialized data processing engines or databases for tasks involving structured data, such as querying, filtering, or transforming tabular or relational data.
- **External APIs and Services**: Integrating with external APIs or cloud services for specific tasks, such as speech recognition, translation, or knowledge base lookup, leveraging the specialized capabilities and optimizations of these dedicated services.
Effective task offloading requires a thorough understanding of the strengths and limitations of both LLM agents and traditional components, as well as careful consideration of integration points, data flows, and performance trade-offs within the overall multi-agent architecture.
### Caching and Indexing
While LLMs excel at generating dynamic, context-aware outputs, they can be less efficient when dealing with static or frequently accessed information or knowledge. Caching and indexing strategies can help mitigate this limitation by minimizing redundant LLM processing and enabling faster retrieval of commonly accessed data.
Techniques for leveraging caching and indexing in multi-agent LLM deployments include:
**Output Caching**: Caching the outputs or responses generated by LLM agents, allowing for rapid retrieval and reuse in cases where the same or similar input is encountered in the future.
**Knowledge Base Indexing**: Indexing domain-specific knowledge bases, data repositories, or other static information sources using traditional search and information retrieval techniques. This allows LLM agents to efficiently query and incorporate relevant information into their outputs, without needing to process or generate this content from scratch.
**Contextual Caching**: Caching not only outputs but also the contextual information and intermediate results generated during multi-agent workflows. This enables more efficient reuse and continuation of previous processing in scenarios where contexts are long-lived or recurring.
Implementing effective caching and indexing strategies requires careful consideration of data freshness, consistency, and invalidation mechanisms, as well as seamless integration with LLM agents and multi-agent workflows to ensure that cached or indexed data is appropriately leveraged and updated.
### Pre-computation and Lookup
In certain scenarios, especially those involving constrained or well-defined inputs, pre-computing and lookup strategies can be leveraged to minimize or entirely avoid the need for real-time LLM processing. By generating and storing potential outputs or responses in advance, enterprises can significantly improve performance and reduce resource consumption.
Approaches for pre-computation and lookup include:
**Output Pre-generation**: For inputs or scenarios with a limited set of potential outputs, pre-generating and storing all possible responses, allowing for rapid retrieval and delivery without the need for real-time LLM execution.
**Retrieval-Based Responses**: Developing retrieval models or techniques that can identify and surface pre-computed or curated responses based on input characteristics, leveraging techniques such as nearest neighbor search, embedding-based retrieval, or example-based generation.
**Hybrid Approaches**: Combining pre-computed or retrieved responses with real-time LLM processing, allowing for the generation of dynamic, context-aware content while still leveraging pre-computed components to optimize performance and resource utilization.
Effective implementation of pre-computation and lookup strategies requires careful analysis of input patterns, output distributions, and potential performance gains, as well as robust mechanisms for managing and updating pre-computed data as application requirements or domain knowledge evolves.
# Conclusion
----------
As enterprises increasingly embrace the transformative potential of large language models, optimizing the performance, scalability, and cost-effectiveness of these deployments has become a critical imperative. Multi-agent architectures, which coordinate the collective capabilities of multiple specialized LLM agents, offer a powerful paradigm for addressing these challenges.
By implementing the seven principles outlined in this guide -- distributing token processing, optimizing agent communication, leveraging agent specialization, implementing dynamic scaling, employing selective execution, optimizing user experience, and leveraging hybrid approaches -- organizations can unlock the full potential of multi-agent LLM deployments.
However, realizing these benefits requires a strategic and holistic approach that accounts for the unique requirements, constraints, and objectives of each enterprise. From task-specific optimizations and domain adaptation to dynamic scaling and user experience considerations, maximizing the performance of multi-agent LLM systems demands a deep understanding of the underlying technologies, as well as the ability to navigate the inherent complexities of these sophisticated architectures.
To learn more about how Swarm Corporation can assist your organization in architecting, deploying, and optimizing high-performance multi-agent LLM solutions, we invite you to book a consultation with one of our agent specialists. Visit <https://calendly.com/swarm-corp/30min> to schedule a 30-minute call and explore how our expertise and cutting-edge technologies can drive transformative outcomes for your business.
In the rapidly evolving landscape of artificial intelligence and natural language processing, staying ahead of the curve is essential. Partner with Swarm Corporation, and unlock the full potential of multi-agent LLM deployments, today.
[Book a call with us now:](https://calendly.com/swarm-corp/30min)

779
docs/swarms_cloud/python_client.md
Unescape View File

@ -1,779 +0,0 @@
# Swarms Cloud API Client Documentation
## Introduction
The Swarms Cloud API client is a production-grade Python package for interacting with the Swarms API. It provides both synchronous and asynchronous interfaces, making it suitable for a wide range of applications from simple scripts to high-performance, scalable services.
Key features include:
- Connection pooling and efficient session management
- Automatic retries with exponential backoff
- Circuit breaker pattern for improved reliability
- In-memory caching for frequently accessed resources
- Comprehensive error handling with detailed exceptions
- Full support for asynchronous operations
- Type checking with Pydantic
This documentation covers all available client methods with detailed descriptions, parameter references, and usage examples.
## Installation
```bash
pip install swarms-client
```
## Authentication
To use the Swarms API, you need an API key. You can obtain your API key from the [Swarms Platform API Keys page](https://swarms.world/platform/api-keys).
## Client Initialization
The `SwarmsClient` is the main entry point for interacting with the Swarms API. It can be initialized with various configuration options to customize its behavior.
```python
from swarms_client import SwarmsClient
# Initialize with default settings
client = SwarmsClient(api_key="your-api-key")
# Or with custom settings
client = SwarmsClient(
api_key="your-api-key",
base_url="https://swarms-api-285321057562.us-east1.run.app",
timeout=60,
max_retries=3,
retry_delay=1,
log_level="INFO",
pool_connections=100,
pool_maxsize=100,
keep_alive_timeout=5,
max_concurrent_requests=100,
circuit_breaker_threshold=5,
circuit_breaker_timeout=60,
enable_cache=True
)
```
### Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `api_key` | `str` | Environment variable `SWARMS_API_KEY` | API key for authentication |
| `base_url` | `str` | `"https://swarms-api-285321057562.us-east1.run.app"` | Base URL for the API |
| `timeout` | `int` | `60` | Timeout for API requests in seconds |
| `max_retries` | `int` | `3` | Maximum number of retry attempts for failed requests |
| `retry_delay` | `int` | `1` | Initial delay between retries in seconds (uses exponential backoff) |
| `log_level` | `str` | `"INFO"` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
| `pool_connections` | `int` | `100` | Number of connection pools to cache |
| `pool_maxsize` | `int` | `100` | Maximum number of connections to save in the pool |
| `keep_alive_timeout` | `int` | `5` | Keep-alive timeout for connections in seconds |
| `max_concurrent_requests` | `int` | `100` | Maximum number of concurrent requests |
| `circuit_breaker_threshold` | `int` | `5` | Failure threshold for the circuit breaker |
| `circuit_breaker_timeout` | `int` | `60` | Reset timeout for the circuit breaker in seconds |
| `enable_cache` | `bool` | `True` | Whether to enable in-memory caching |
## Client Methods
### clear_cache
Clears the in-memory cache used for caching API responses.
```python
client.clear_cache()
```
## Agent Resource
The Agent resource provides methods for creating and managing agent completions.
<a name="agent-create"></a>
### create
Creates an agent completion.
```python
response = client.agent.create(
agent_config={
"agent_name": "Researcher",
"description": "Conducts in-depth research on topics",
"model_name": "gpt-4o",
"temperature": 0.7
},
task="Research the latest advancements in quantum computing and summarize the key findings"
)
print(f"Agent ID: {response.id}")
print(f"Output: {response.outputs}")
```
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `agent_config` | `dict` or `AgentSpec` | Yes | Configuration for the agent |
| `task` | `str` | Yes | The task for the agent to complete |
| `history` | `dict` | No | Optional conversation history |
The `agent_config` parameter can include the following fields:
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `agent_name` | `str` | Required | Name of the agent |
| `description` | `str` | `None` | Description of the agent's purpose |
| `system_prompt` | `str` | `None` | System prompt to guide the agent's behavior |
| `model_name` | `str` | `"gpt-4o-mini"` | Name of the model to use |
| `auto_generate_prompt` | `bool` | `False` | Whether to automatically generate a prompt |
| `max_tokens` | `int` | `8192` | Maximum tokens in the response |
| `temperature` | `float` | `0.5` | Temperature for sampling (0-1) |
| `role` | `str` | `None` | Role of the agent |
| `max_loops` | `int` | `1` | Maximum number of reasoning loops |
| `tools_dictionary` | `List[Dict]` | `None` | Tools available to the agent |
#### Returns
`AgentCompletionResponse` object with the following properties:
- `id`: Unique identifier for the completion
- `success`: Whether the completion was successful
- `name`: Name of the agent
- `description`: Description of the agent
- `temperature`: Temperature used for the completion
- `outputs`: Output from the agent
- `usage`: Token usage information
- `timestamp`: Timestamp of the completion
<a name="agent-create_batch"></a>
### create_batch
Creates multiple agent completions in batch.
```python
responses = client.agent.create_batch([
{
"agent_config": {
"agent_name": "Researcher",
"model_name": "gpt-4o-mini",
"temperature": 0.5
},
"task": "Summarize the latest quantum computing research"
},
{
"agent_config": {
"agent_name": "Writer",
"model_name": "gpt-4o",
"temperature": 0.7
},
"task": "Write a blog post about AI safety"
}
])
for i, response in enumerate(responses):
print(f"Agent {i+1} ID: {response.id}")
print(f"Output: {response.outputs}")
print("---")
```
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `completions` | `List[Dict or AgentCompletion]` | Yes | List of agent completion requests |
Each item in the `completions` list should have the same structure as the parameters for the `create` method.
#### Returns
List of `AgentCompletionResponse` objects with the same properties as the return value of the `create` method.
<a name="agent-acreate"></a>
### acreate
Creates an agent completion asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient(api_key="your-api-key") as client:
response = await client.agent.acreate(
agent_config={
"agent_name": "Researcher",
"description": "Conducts in-depth research",
"model_name": "gpt-4o"
},
task="Research the impact of quantum computing on cryptography"
)
print(f"Agent ID: {response.id}")
print(f"Output: {response.outputs}")
asyncio.run(main())
```
#### Parameters
Same as the `create` method.
#### Returns
Same as the `create` method.
<a name="agent-acreate_batch"></a>
### acreate_batch
Creates multiple agent completions in batch asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient(api_key="your-api-key") as client:
responses = await client.agent.acreate_batch([
{
"agent_config": {
"agent_name": "Researcher",
"model_name": "gpt-4o-mini"
},
"task": "Summarize the latest quantum computing research"
},
{
"agent_config": {
"agent_name": "Writer",
"model_name": "gpt-4o"
},
"task": "Write a blog post about AI safety"
}
])
for i, response in enumerate(responses):
print(f"Agent {i+1} ID: {response.id}")
print(f"Output: {response.outputs}")
print("---")
asyncio.run(main())
```
#### Parameters
Same as the `create_batch` method.
#### Returns
Same as the `create_batch` method.
## Swarm Resource
The Swarm resource provides methods for creating and managing swarm completions.
<a name="swarm-create"></a>
### create
Creates a swarm completion.
```python
response = client.swarm.create(
name="Research Swarm",
description="A swarm for research tasks",
swarm_type="SequentialWorkflow",
task="Research quantum computing advances in 2024 and summarize the key findings",
agents=[
{
"agent_name": "Researcher",
"description": "Conducts in-depth research",
"model_name": "gpt-4o",
"temperature": 0.5
},
{
"agent_name": "Critic",
"description": "Evaluates arguments for flaws",
"model_name": "gpt-4o-mini",
"temperature": 0.3
}
],
max_loops=3,
return_history=True
)
print(f"Job ID: {response.job_id}")
print(f"Status: {response.status}")
print(f"Output: {response.output}")
```
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `str` | No | Name of the swarm |
| `description` | `str` | No | Description of the swarm |
| `agents` | `List[Dict or AgentSpec]` | No | List of agent specifications |
| `max_loops` | `int` | No | Maximum number of loops (default: 1) |
| `swarm_type` | `str` | No | Type of swarm (see available types) |
| `task` | `str` | Conditional | The task to complete (required if tasks and messages are not provided) |
| `tasks` | `List[str]` | Conditional | List of tasks for batch processing (required if task and messages are not provided) |
| `messages` | `List[Dict]` | Conditional | List of messages to process (required if task and tasks are not provided) |
| `return_history` | `bool` | No | Whether to return the execution history (default: True) |
| `rules` | `str` | No | Rules for the swarm |
| `schedule` | `Dict` | No | Schedule specification for delayed execution |
| `stream` | `bool` | No | Whether to stream the response (default: False) |
| `service_tier` | `str` | No | Service tier ('standard' or 'flex', default: 'standard') |
#### Returns
`SwarmCompletionResponse` object with the following properties:
- `job_id`: Unique identifier for the job
- `status`: Status of the job
- `swarm_name`: Name of the swarm
- `description`: Description of the swarm
- `swarm_type`: Type of swarm used
- `output`: Output from the swarm
- `number_of_agents`: Number of agents in the swarm
- `service_tier`: Service tier used
- `tasks`: List of tasks processed (if applicable)
- `messages`: List of messages processed (if applicable)
<a name="swarm-create_batch"></a>
### create_batch
Creates multiple swarm completions in batch.
```python
responses = client.swarm.create_batch([
{
"name": "Research Swarm",
"swarm_type": "auto",
"task": "Research quantum computing advances",
"agents": [
{"agent_name": "Researcher", "model_name": "gpt-4o"}
]
},
{
"name": "Writing Swarm",
"swarm_type": "SequentialWorkflow",
"task": "Write a blog post about AI safety",
"agents": [
{"agent_name": "Writer", "model_name": "gpt-4o"},
{"agent_name": "Editor", "model_name": "gpt-4o-mini"}
]
}
])
for i, response in enumerate(responses):
print(f"Swarm {i+1} Job ID: {response.job_id}")
print(f"Status: {response.status}")
print(f"Output: {response.output}")
print("---")
```
#### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `swarms` | `List[Dict or SwarmSpec]` | Yes | List of swarm specifications |
Each item in the `swarms` list should have the same structure as the parameters for the `create` method.
#### Returns
List of `SwarmCompletionResponse` objects with the same properties as the return value of the `create` method.
<a name="swarm-list_types"></a>
### list_types
Lists available swarm types.
```python
response = client.swarm.list_types()
print(f"Available swarm types:")
for swarm_type in response.swarm_types:
print(f"- {swarm_type}")
```
#### Returns
`SwarmTypesResponse` object with the following properties:
- `success`: Whether the request was successful
- `swarm_types`: List of available swarm types
<a name="swarm-alist_types"></a>
### alist_types
Lists available swarm types asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient(api_key="your-api-key") as client:
response = await client.swarm.alist_types()
print(f"Available swarm types:")
for swarm_type in response.swarm_types:
print(f"- {swarm_type}")
asyncio.run(main())
```
#### Returns
Same as the `list_types` method.
<a name="swarm-acreate"></a>
### acreate
Creates a swarm completion asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient(api_key="your-api-key") as client:
response = await client.swarm.acreate(
name="Research Swarm",
swarm_type="SequentialWorkflow",
task="Research quantum computing advances in 2024",
agents=[
{
"agent_name": "Researcher",
"description": "Conducts in-depth research",
"model_name": "gpt-4o"
},
{
"agent_name": "Critic",
"description": "Evaluates arguments for flaws",
"model_name": "gpt-4o-mini"
}
]
)
print(f"Job ID: {response.job_id}")
print(f"Status: {response.status}")
print(f"Output: {response.output}")
asyncio.run(main())
```
#### Parameters
Same as the `create` method.
#### Returns
Same as the `create` method.
<a name="swarm-acreate_batch"></a>
### acreate_batch
Creates multiple swarm completions in batch asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient(api_key="your-api-key") as client:
responses = await client.swarm.acreate_batch([
{
"name": "Research Swarm",
"swarm_type": "auto",
"task": "Research quantum computing",
"agents": [
{"agent_name": "Researcher", "model_name": "gpt-4o"}
]
},
{
"name": "Writing Swarm",
"swarm_type": "SequentialWorkflow",
"task": "Write a blog post about AI safety",
"agents": [
{"agent_name": "Writer", "model_name": "gpt-4o"}
]
}
])
for i, response in enumerate(responses):
print(f"Swarm {i+1} Job ID: {response.job_id}")
print(f"Status: {response.status}")
print(f"Output: {response.output}")
print("---")
asyncio.run(main())
```
#### Parameters
Same as the `create_batch` method.
#### Returns
Same as the `create_batch` method.
## Models Resource
The Models resource provides methods for retrieving information about available models.
<a name="models-list"></a>
### list
Lists available models.
```python
response = client.models.list()
print(f"Available models:")
for model in response.models:
print(f"- {model}")
```
#### Returns
`ModelsResponse` object with the following properties:
- `success`: Whether the request was successful
- `models`: List of available model names
<a name="models-alist"></a>
### alist
Lists available models asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient(api_key="your-api-key") as client:
response = await client.models.alist()
print(f"Available models:")
for model in response.models:
print(f"- {model}")
asyncio.run(main())
```
#### Returns
Same as the `list` method.
## Logs Resource
The Logs resource provides methods for retrieving API request logs.
<a name="logs-list"></a>
### list
Lists API request logs.
```python
response = client.logs.list()
print(f"Found {response.count} logs:")
for log in response.logs:
print(f"- ID: {log.id}, Created at: {log.created_at}")
print(f" Data: {log.data}")
```
#### Returns
`LogsResponse` object with the following properties:
- `status`: Status of the request
- `count`: Number of logs
- `logs`: List of log entries
- `timestamp`: Timestamp of the request
Each log entry is a `LogEntry` object with the following properties:
- `id`: Unique identifier for the log entry
- `api_key`: API key used for the request
- `data`: Request data
- `created_at`: Timestamp when the log entry was created
<a name="logs-alist"></a>
### alist
Lists API request logs asynchronously.
```python
import asyncio
from swarms_client import SwarmsClient
async def main():
async with SwarmsClient() as client:
response = await client.logs.alist()
print(f"Found {response.count} logs:")
for log in response.logs:
print(f"- ID: {log.id}, Created at: {log.created_at}")
print(f" Data: {log.data}")
asyncio.run(main())
```
#### Returns
Same as the `list` method.
## Error Handling
The Swarms API client provides detailed error handling with specific exception types for different error scenarios. All exceptions inherit from the base `SwarmsError` class.
```python
from swarms_client import SwarmsClient, SwarmsError, AuthenticationError, RateLimitError, APIError
try:
client = SwarmsClient(api_key="invalid-api-key")
response = client.agent.create(
agent_config={"agent_name": "Researcher", "model_name": "gpt-4o"},
task="Research quantum computing"
)
except AuthenticationError as e:
print(f"Authentication error: {e}")
except RateLimitError as e:
print(f"Rate limit exceeded: {e}")
except APIError as e:
print(f"API error: {e}")
except SwarmsError as e:
print(f"Swarms error: {e}")
```
### Exception Types
| Exception | Description |
|-----------|-------------|
| `SwarmsError` | Base exception for all Swarms API errors |
| `AuthenticationError` | Raised when there's an issue with authentication |
| `RateLimitError` | Raised when the rate limit is exceeded |
| `APIError` | Raised when the API returns an error |
| `InvalidRequestError` | Raised when the request is invalid |
| `InsufficientCreditsError` | Raised when the user doesn't have enough credits |
| `TimeoutError` | Raised when a request times out |
| `NetworkError` | Raised when there's a network issue |
## Advanced Features
### Connection Pooling
The Swarms API client uses connection pooling to efficiently manage HTTP connections, which can significantly improve performance when making multiple requests.
```python
client = SwarmsClient(
api_key="your-api-key",
pool_connections=100, # Number of connection pools to cache
pool_maxsize=100, # Maximum number of connections to save in the pool
keep_alive_timeout=5 # Keep-alive timeout for connections in seconds
)
```
### Circuit Breaker Pattern
The client implements the circuit breaker pattern to prevent cascading failures when the API is experiencing issues.
```python
client = SwarmsClient(
api_key="your-api-key",
circuit_breaker_threshold=5, # Number of failures before the circuit opens
circuit_breaker_timeout=60 # Time in seconds before attempting to close the circuit
)
```
### Caching
The client includes in-memory caching for frequently accessed resources to reduce API calls and improve performance.
```python
client = SwarmsClient(
api_key="your-api-key",
enable_cache=True # Enable in-memory caching
)
# Clear the cache manually if needed
client.clear_cache()
```
## Complete Example
Here's a complete example that demonstrates how to use the Swarms API client to create a research swarm and process its output:
```python
import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv
# Load API key from environment
load_dotenv()
api_key = os.getenv("SWARMS_API_KEY")
# Initialize client
client = SwarmsClient(api_key=api_key)
# Create a research swarm
try:
# Define the agents
researcher = {
"agent_name": "Researcher",
"description": "Conducts thorough research on specified topics",
"model_name": "gpt-4o",
"temperature": 0.5,
"system_prompt": "You are a diligent researcher focused on finding accurate and comprehensive information."
}
analyst = {
"agent_name": "Analyst",
"description": "Analyzes research findings and identifies key insights",
"model_name": "gpt-4o",
"temperature": 0.3,
"system_prompt": "You are an insightful analyst who can identify patterns and extract meaningful insights from research data."
}
summarizer = {
"agent_name": "Summarizer",
"description": "Creates concise summaries of complex information",
"model_name": "gpt-4o-mini",
"temperature": 0.4,
"system_prompt": "You specialize in distilling complex information into clear, concise summaries."
}
# Create the swarm
response = client.swarm.create(
name="Quantum Computing Research Swarm",
description="A swarm for researching and analyzing quantum computing advancements",
swarm_type="SequentialWorkflow",
task="Research the latest advancements in quantum computing in 2024, analyze their potential impact on cryptography and data security, and provide a concise summary of the findings.",
agents=[researcher, analyst, summarizer],
max_loops=2,
return_history=True
)
# Process the response
print(f"Job ID: {response.job_id}")
print(f"Status: {response.status}")
print(f"Number of agents: {response.number_of_agents}")
print(f"Swarm type: {response.swarm_type}")
# Print the output
if "final_output" in response.output:
print("\nFinal Output:")
print(response.output["final_output"])
else:
print("\nOutput:")
print(response.output)
# Access agent-specific outputs if available
if "agent_outputs" in response.output:
print("\nAgent Outputs:")
for agent, output in response.output["agent_outputs"].items():
print(f"\n{agent}:")
print(output)
except Exception as e:
print(f"Error: {e}")
```
This example creates a sequential workflow swarm with three agents to research quantum computing, analyze the findings, and create a summary of the results.

1165
docs/swarms_cloud/quickstart.md
View File

File diff suppressed because it is too large Load Diff

196
docs/swarms_cloud/rate_limits.md
Unescape View File

@ -1,196 +0,0 @@
# Swarms API Rate Limits
The Swarms API implements a comprehensive rate limiting system that tracks API requests across multiple time windows and enforces various limits to ensure fair usage and system stability.
## Rate Limits Summary
| Rate Limit Type | Free Tier | Premium Tier | Time Window | Description |
|----------------|-----------|--------------|-------------|-------------|
| **Requests per Minute** | 100 | 2,000 | 1 minute | Maximum API calls per minute |
| **Requests per Hour** | 50 | 10,000 | 1 hour | Maximum API calls per hour |
| **Requests per Day** | 1,200 | 100,000 | 24 hours | Maximum API calls per day |
| **Tokens per Agent** | 200,000 | 2,000,000 | Per request | Maximum tokens per agent |
| **Prompt Length** | 200,000 | 200,000 | Per request | Maximum input tokens per request |
| **Batch Size** | 10 | 10 | Per request | Maximum agents in batch requests |
| **IP-based Fallback** | 100 | 100 | 60 seconds | For requests without API keys |
## Detailed Rate Limit Explanations
### 1. **Request Rate Limits**
These limits control how many API calls you can make within specific time windows.
#### **Per-Minute Limit**
| Tier | Requests per Minute | Reset Interval | Applies To |
|--------------|--------------------|------------------------|--------------------|
| Free | 100 | Every minute (sliding) | All API endpoints |
| Premium | 2,000 | Every minute (sliding) | All API endpoints |
#### **Per-Hour Limit**
- **Free Tier**: 50 requests per hour
- **Premium Tier**: 10,000 requests per hour
- **Reset**: Every hour (sliding window)
- **Applies to**: All API endpoints
#### **Per-Day Limit**
- **Free Tier**: 1,200 requests per day (50 × 24)
- **Premium Tier**: 100,000 requests per day
- **Reset**: Every 24 hours (sliding window)
- **Applies to**: All API endpoints
### 2. **Token Limits**
These limits control the amount of text processing allowed per request.
#### **Tokens per Agent**
- **Free Tier**: 200,000 tokens per agent
- **Premium Tier**: 2,000,000 tokens per agent
- **Applies to**: Individual agent configurations
- **Includes**: System prompts, task descriptions, and agent names
#### **Prompt Length Limit**
- **All Tiers**: 200,000 tokens maximum
- **Applies to**: Combined input text (task + history + system prompts)
- **Error**: Returns 400 error if exceeded
- **Message**: "Prompt is too long. Please provide a prompt that is less than 10000 tokens."
### 3. **Batch Processing Limits**
These limits control concurrent processing capabilities.
#### **Batch Size Limit**
- **All Tiers**: 10 agents maximum per batch
- **Applies to**: `/v1/agent/batch/completions` endpoint
- **Error**: Returns 400 error if exceeded
- **Message**: "ERROR: BATCH SIZE EXCEEDED - You can only run up to 10 batch agents at a time."
## How Rate Limiting Works
### Database-Based Tracking
The system uses a database-based approach for API key requests:
1. **Request Logging**: Every API request is logged to the `swarms_api_logs` table
2. **Time Window Queries**: The system queries for requests in the last minute, hour, and day
3. **Limit Comparison**: Current counts are compared against configured limits
4. **Request Blocking**: Requests are blocked if any limit is exceeded
### Sliding Windows
Rate limits use sliding windows rather than fixed windows:
- **Minute**: Counts requests in the last 60 seconds
- **Hour**: Counts requests in the last 60 minutes
- **Day**: Counts requests in the last 24 hours
This provides more accurate rate limiting compared to fixed time windows.
## Checking Your Rate Limits
### API Endpoint
Use the `/v1/rate/limits` endpoint to check your current usage:
```bash
curl -H "x-api-key: your-api-key" \
https://api.swarms.world/v1/rate/limits
```
### Response Format
```json
{
"success": true,
"rate_limits": {
"minute": {
"count": 5,
"limit": 100,
"exceeded": false,
"remaining": 95,
"reset_time": "2024-01-15T10:30:00Z"
},
"hour": {
"count": 25,
"limit": 50,
"exceeded": false,
"remaining": 25,
"reset_time": "2024-01-15T11:00:00Z"
},
"day": {
"count": 150,
"limit": 1200,
"exceeded": false,
"remaining": 1050,
"reset_time": "2024-01-16T10:00:00Z"
}
},
"limits": {
"maximum_requests_per_minute": 100,
"maximum_requests_per_hour": 50,
"maximum_requests_per_day": 1200,
"tokens_per_agent": 200000
},
"timestamp": "2024-01-15T10:29:30Z"
}
```
## Handling Rate Limit Errors
### Error Response
When rate limits are exceeded, you'll receive a 429 status code:
```json
{
"detail": "Rate limit exceeded for minute window(s). Upgrade to Premium for increased limits (2,000/min, 10,000/hour, 100,000/day) at https://swarms.world/platform/account for just $99/month."
}
```
### Best Practices
1. **Monitor Usage**: Regularly check your rate limits using the `/v1/rate/limits` endpoint
2. **Implement Retry Logic**: Use exponential backoff when hitting rate limits
3. **Optimize Requests**: Combine multiple operations into single requests when possible
4. **Upgrade When Needed**: Consider upgrading to Premium for higher limits
## Premium Tier Benefits
Upgrade to Premium for significantly higher limits:
- **20x more requests per minute** (2,000 vs 100)
- **200x more requests per hour** (10,000 vs 50)
- **83x more requests per day** (100,000 vs 1,200)
- **10x more tokens per agent** (2M vs 200K)
Visit [Swarms Platform Account](https://swarms.world/platform/account) to upgrade for just $99/month.
## Performance Considerations
- Database queries are optimized to only count request IDs
- Rate limit checks are cached per request
- Fallback mechanisms ensure system reliability
- Minimal impact on request latency
- Persistent tracking across server restarts

732
docs/swarms_cloud/rust_client.md
Unescape View File

@ -1,732 +0,0 @@
# Swarms Client - Production Grade Rust SDK
A high-performance, production-ready Rust client for the Swarms API with comprehensive features for building multi-agent AI systems.
## Features
- **🚀 High Performance**: Built with `reqwest` and `tokio` for maximum throughput
- **🔄 Connection Pooling**: Automatic HTTP connection reuse and pooling
- **⚡ Circuit Breaker**: Automatic failure detection and recovery
- **💾 Intelligent Caching**: TTL-based in-memory caching with concurrent access
- **📊 Rate Limiting**: Configurable concurrent request limits
- **🔄 Retry Logic**: Exponential backoff with jitter
- **📝 Comprehensive Logging**: Structured logging with `tracing`
- **✅ Type Safety**: Full compile-time type checking with `serde`
## Installation
Install `swarms-rs` globally using cargo:
```bash
cargo install swarms-rs
```
## Quick Start
```rust
use swarms_client::SwarmsClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Initialize the client with API key from environment
let client = SwarmsClient::builder()
.unwrap()
.from_env()? // Loads API key from SWARMS_API_KEY environment variable
.timeout(std::time::Duration::from_secs(60))
.max_retries(3)
.build()?;
// Make a simple swarm completion request
let response = client.swarm()
.completion()
.name("My First Swarm")
.swarm_type(SwarmType::Auto)
.task("Analyze the pros and cons of quantum computing")
.agent(|agent| {
agent
.name("Researcher")
.description("Conducts in-depth research")
.model("gpt-4o")
})
.send()
.await?;
println!("Swarm output: {}", response.output);
Ok(())
}
```
## API Reference
### SwarmsClient
The main client for interacting with the Swarms API.
#### Constructor Methods
##### `SwarmsClient::builder()`
Creates a new client builder for configuring the client.
**Returns**: `Result<ClientBuilder, SwarmsError>`
**Example**:
```rust
let client = SwarmsClient::builder()
.unwrap()
.api_key("your-api-key")
.timeout(Duration::from_secs(60))
.build()?;
```
##### `SwarmsClient::with_config(config: ClientConfig)`
Creates a client with custom configuration.
| Parameter | Type | Description |
|-----------|------|-------------|
| `config` | `ClientConfig` | Client configuration settings |
**Returns**: `Result<SwarmsClient, SwarmsError>`
**Example**:
```rust
let config = ClientConfig {
api_key: "your-api-key".to_string(),
base_url: "https://api.swarms.com/".parse().unwrap(),
timeout: Duration::from_secs(120),
max_retries: 5,
..Default::default()
};
let client = SwarmsClient::with_config(config)?;
```
#### Resource Access Methods
| Method | Returns | Description |
|--------|---------|-------------|
| `agent()` | `AgentResource` | Access agent-related operations |
| `swarm()` | `SwarmResource` | Access swarm-related operations |
| `models()` | `ModelsResource` | Access model listing operations |
| `logs()` | `LogsResource` | Access logging operations |
#### Cache Management Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `clear_cache()` | None | `()` | Clears all cached responses |
| `cache_stats()` | None | `Option<(usize, usize)>` | Returns (valid_entries, total_entries) |
### ClientBuilder
Builder for configuring the Swarms client.
#### Configuration Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `new()` | None | `ClientBuilder` | Creates a new builder with defaults |
| `from_env()` | None | `Result<ClientBuilder, SwarmsError>` | Loads API key from environment |
| `api_key(key)` | `String` | `ClientBuilder` | Sets the API key |
| `base_url(url)` | `&str` | `Result<ClientBuilder, SwarmsError>` | Sets the base URL |
| `timeout(duration)` | `Duration` | `ClientBuilder` | Sets request timeout |
| `max_retries(count)` | `usize` | `ClientBuilder` | Sets maximum retry attempts |
| `retry_delay(duration)` | `Duration` | `ClientBuilder` | Sets retry delay duration |
| `max_concurrent_requests(count)` | `usize` | `ClientBuilder` | Sets concurrent request limit |
| `enable_cache(enabled)` | `bool` | `ClientBuilder` | Enables/disables caching |
| `cache_ttl(duration)` | `Duration` | `ClientBuilder` | Sets cache TTL |
| `build()` | None | `Result<SwarmsClient, SwarmsError>` | Builds the client |
**Example**:
```rust
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.timeout(Duration::from_secs(120))
.max_retries(5)
.max_concurrent_requests(50)
.enable_cache(true)
.cache_ttl(Duration::from_secs(600))
.build()?;
```
### SwarmResource
Resource for swarm-related operations.
#### Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `completion()` | None | `SwarmCompletionBuilder` | Creates a new swarm completion builder |
| `create(request)` | `SwarmSpec` | `Result<SwarmCompletionResponse, SwarmsError>` | Creates a swarm completion directly |
| `create_batch(requests)` | `Vec<SwarmSpec>` | `Result<Vec<SwarmCompletionResponse>, SwarmsError>` | Creates multiple swarm completions |
| `list_types()` | None | `Result<SwarmTypesResponse, SwarmsError>` | Lists available swarm types |
### SwarmCompletionBuilder
Builder for creating swarm completion requests.
#### Configuration Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `name(name)` | `String` | `SwarmCompletionBuilder` | Sets the swarm name |
| `description(desc)` | `String` | `SwarmCompletionBuilder` | Sets the swarm description |
| `swarm_type(type)` | `SwarmType` | `SwarmCompletionBuilder` | Sets the swarm type |
| `task(task)` | `String` | `SwarmCompletionBuilder` | Sets the main task |
| `agent(builder_fn)` | `Fn(AgentSpecBuilder) -> AgentSpecBuilder` | `SwarmCompletionBuilder` | Adds an agent using a builder function |
| `max_loops(count)` | `u32` | `SwarmCompletionBuilder` | Sets maximum execution loops |
| `service_tier(tier)` | `String` | `SwarmCompletionBuilder` | Sets the service tier |
| `send()` | None | `Result<SwarmCompletionResponse, SwarmsError>` | Sends the request |
### AgentResource
Resource for agent-related operations.
#### Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `completion()` | None | `AgentCompletionBuilder` | Creates a new agent completion builder |
| `create(request)` | `AgentCompletion` | `Result<AgentCompletionResponse, SwarmsError>` | Creates an agent completion directly |
| `create_batch(requests)` | `Vec<AgentCompletion>` | `Result<Vec<AgentCompletionResponse>, SwarmsError>` | Creates multiple agent completions |
### AgentCompletionBuilder
Builder for creating agent completion requests.
#### Configuration Methods
| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `agent_name(name)` | `String` | `AgentCompletionBuilder` | Sets the agent name |
| `task(task)` | `String` | `AgentCompletionBuilder` | Sets the task |
| `model(model)` | `String` | `AgentCompletionBuilder` | Sets the AI model |
| `description(desc)` | `String` | `AgentCompletionBuilder` | Sets the agent description |
| `system_prompt(prompt)` | `String` | `AgentCompletionBuilder` | Sets the system prompt |
| `temperature(temp)` | `f32` | `AgentCompletionBuilder` | Sets the temperature (0.0-1.0) |
| `max_tokens(tokens)` | `u32` | `AgentCompletionBuilder` | Sets maximum tokens |
| `max_loops(loops)` | `u32` | `AgentCompletionBuilder` | Sets maximum loops |
| `send()` | None | `Result<AgentCompletionResponse, SwarmsError>` | Sends the request |
### SwarmType Enum
Available swarm types for different execution patterns.
| Variant | Description |
|---------|-------------|
| `AgentRearrange` | Agents can be rearranged based on task requirements |
| `MixtureOfAgents` | Combines multiple agents with different specializations |
| `SpreadSheetSwarm` | Organized like a spreadsheet with structured data flow |
| `SequentialWorkflow` | Agents execute in a sequential order |
| `ConcurrentWorkflow` | Agents execute concurrently |
| `GroupChat` | Agents interact in a group chat format |
| `MultiAgentRouter` | Routes tasks between multiple agents |
| `AutoSwarmBuilder` | Automatically builds swarm structure |
| `HiearchicalSwarm` | Hierarchical organization of agents |
| `Auto` | Automatically selects the best swarm type |
| `MajorityVoting` | Agents vote on decisions |
| `Malt` | Multi-Agent Language Tasks |
## Detailed Examples
### 1. Simple Agent Completion
```rust
use swarms_client::{SwarmsClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.build()?;
let response = client.agent()
.completion()
.agent_name("Content Writer")
.task("Write a blog post about sustainable technology")
.model("gpt-4o")
.temperature(0.7)
.max_tokens(2000)
.description("An expert content writer specializing in technology topics")
.system_prompt("You are a professional content writer with expertise in technology and sustainability. Write engaging, informative content that is well-structured and SEO-friendly.")
.send()
.await?;
println!("Agent Response: {}", response.outputs);
println!("Tokens Used: {}", response.usage.total_tokens);
Ok(())
}
```
### 2. Multi-Agent Research Swarm
```rust
use swarms_client::{SwarmsClient, SwarmType};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.timeout(Duration::from_secs(300)) // 5 minutes for complex tasks
.build()?;
let response = client.swarm()
.completion()
.name("AI Research Swarm")
.description("A comprehensive research team analyzing AI trends and developments")
.swarm_type(SwarmType::SequentialWorkflow)
.task("Conduct a comprehensive analysis of the current state of AI in healthcare, including recent developments, challenges, and future prospects")
// Data Collection Agent
.agent(|agent| {
agent
.name("Data Collector")
.description("Gathers comprehensive data and recent developments")
.model("gpt-4o")
.system_prompt("You are a research data collector specializing in AI and healthcare. Your job is to gather the most recent and relevant information about AI applications in healthcare, including clinical trials, FDA approvals, and industry developments.")
.temperature(0.3)
.max_tokens(3000)
})
// Technical Analyst
.agent(|agent| {
agent
.name("Technical Analyst")
.description("Analyzes technical aspects and implementation details")
.model("gpt-4o")
.system_prompt("You are a technical analyst with deep expertise in AI/ML technologies. Analyze the technical feasibility, implementation challenges, and technological requirements of AI solutions in healthcare.")
.temperature(0.4)
.max_tokens(3000)
})
// Market Analyst
.agent(|agent| {
agent
.name("Market Analyst")
.description("Analyzes market trends, adoption rates, and economic factors")
.model("gpt-4o")
.system_prompt("You are a market research analyst specializing in healthcare technology markets. Analyze market size, growth projections, key players, investment trends, and economic factors affecting AI adoption in healthcare.")
.temperature(0.5)
.max_tokens(3000)
})
// Regulatory Expert
.agent(|agent| {
agent
.name("Regulatory Expert")
.description("Analyzes regulatory landscape and compliance requirements")
.model("gpt-4o")
.system_prompt("You are a regulatory affairs expert with deep knowledge of healthcare regulations and AI governance. Analyze regulatory challenges, compliance requirements, ethical considerations, and policy developments affecting AI in healthcare.")
.temperature(0.3)
.max_tokens(3000)
})
// Report Synthesizer
.agent(|agent| {
agent
.name("Report Synthesizer")
.description("Synthesizes all analyses into a comprehensive report")
.model("gpt-4o")
.system_prompt("You are an expert report writer and strategic analyst. Synthesize all the previous analyses into a comprehensive, well-structured executive report with clear insights, recommendations, and future outlook.")
.temperature(0.6)
.max_tokens(4000)
})
.max_loops(1)
.service_tier("premium")
.send()
.await?;
println!("Research Report:");
println!("{}", response.output);
println!("\nSwarm executed with {} agents", response.number_of_agents);
Ok(())
}
```
### 3. Financial Analysis Swarm (From Example)
```rust
use swarms_client::{SwarmsClient, SwarmType};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.timeout(Duration::from_secs(120))
.max_retries(3)
.build()?;
let response = client.swarm()
.completion()
.name("Financial Health Analysis Swarm")
.description("A sequential workflow of specialized financial agents analyzing company health")
.swarm_type(SwarmType::ConcurrentWorkflow)
.task("Analyze the financial health of Apple Inc. (AAPL) based on their latest quarterly report")
// Financial Data Collector Agent
.agent(|agent| {
agent
.name("Financial Data Collector")
.description("Specializes in gathering and organizing financial data from various sources")
.model("gpt-4o")
.system_prompt("You are a financial data collection specialist. Your role is to gather and organize relevant financial data, including revenue, expenses, profit margins, and key financial ratios. Present the data in a clear, structured format.")
.temperature(0.7)
.max_tokens(2000)
})
// Financial Ratio Analyzer Agent
.agent(|agent| {
agent
.name("Ratio Analyzer")
.description("Analyzes key financial ratios and metrics")
.model("gpt-4o")
.system_prompt("You are a financial ratio analysis expert. Your role is to calculate and interpret key financial ratios such as P/E ratio, debt-to-equity, current ratio, and return on equity. Provide insights on what these ratios indicate about the company's financial health.")
.temperature(0.7)
.max_tokens(2000)
})
// Additional agents...
.agent(|agent| {
agent
.name("Investment Advisor")
.description("Provides investment recommendations based on analysis")
.model("gpt-4o")
.system_prompt("You are an investment advisory specialist. Your role is to synthesize the analysis from previous agents and provide clear, actionable investment recommendations. Consider both short-term and long-term investment perspectives.")
.temperature(0.7)
.max_tokens(2000)
})
.max_loops(1)
.service_tier("standard")
.send()
.await?;
println!("Financial Analysis Results:");
println!("{}", response.output);
Ok(())
}
```
### 4. Batch Processing
```rust
use swarms_client::{SwarmsClient, AgentCompletion, AgentSpec};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.max_concurrent_requests(20) // Allow more concurrent requests for batch
.build()?;
// Create multiple agent completion requests
let requests = vec![
AgentCompletion {
agent_config: AgentSpec {
agent_name: "Content Creator 1".to_string(),
model_name: "gpt-4o-mini".to_string(),
temperature: 0.7,
max_tokens: 1000,
..Default::default()
},
task: "Write a social media post about renewable energy".to_string(),
history: None,
},
AgentCompletion {
agent_config: AgentSpec {
agent_name: "Content Creator 2".to_string(),
model_name: "gpt-4o-mini".to_string(),
temperature: 0.8,
max_tokens: 1000,
..Default::default()
},
task: "Write a social media post about electric vehicles".to_string(),
history: None,
},
// Add more requests...
];
// Process all requests in batch
let responses = client.agent()
.create_batch(requests)
.await?;
for (i, response) in responses.iter().enumerate() {
println!("Response {}: {}", i + 1, response.outputs);
println!("Tokens used: {}\n", response.usage.total_tokens);
}
Ok(())
}
```
### 5. Custom Configuration with Error Handling
```rust
use swarms_client::{SwarmsClient, SwarmsError, ClientConfig};
use std::time::Duration;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Custom configuration for production use
let config = ClientConfig {
api_key: std::env::var("SWARMS_API_KEY")?,
base_url: "https://swarms-api-285321057562.us-east1.run.app/".parse()?,
timeout: Duration::from_secs(180),
max_retries: 5,
retry_delay: Duration::from_secs(2),
max_concurrent_requests: 50,
circuit_breaker_threshold: 10,
circuit_breaker_timeout: Duration::from_secs(120),
enable_cache: true,
cache_ttl: Duration::from_secs(600),
};
let client = SwarmsClient::with_config(config)?;
// Example with comprehensive error handling
match client.swarm()
.completion()
.name("Production Swarm")
.swarm_type(SwarmType::Auto)
.task("Analyze market trends for Q4 2024")
.agent(|agent| {
agent
.name("Market Analyst")
.model("gpt-4o")
.temperature(0.5)
})
.send()
.await
{
Ok(response) => {
println!("Success! Job ID: {}", response.job_id);
println!("Output: {}", response.output);
},
Err(SwarmsError::Authentication { message, .. }) => {
eprintln!("Authentication error: {}", message);
},
Err(SwarmsError::RateLimit { message, .. }) => {
eprintln!("Rate limit exceeded: {}", message);
// Implement backoff strategy
},
Err(SwarmsError::InsufficientCredits { message, .. }) => {
eprintln!("Insufficient credits: {}", message);
},
Err(SwarmsError::CircuitBreakerOpen) => {
eprintln!("Circuit breaker is open - service temporarily unavailable");
},
Err(e) => {
eprintln!("Other error: {}", e);
}
}
Ok(())
}
```
### 6. Monitoring and Observability
```rust
use swarms_client::SwarmsClient;
use tracing::{info, warn, error};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Initialize tracing for observability
tracing_subscriber::init();
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.enable_cache(true)
.build()?;
// Monitor cache performance
if let Some((valid, total)) = client.cache_stats() {
info!("Cache stats: {}/{} entries valid", valid, total);
}
// Make request with monitoring
let start = std::time::Instant::now();
let response = client.swarm()
.completion()
.name("Monitored Swarm")
.task("Analyze system performance metrics")
.agent(|agent| {
agent
.name("Performance Analyst")
.model("gpt-4o-mini")
})
.send()
.await?;
let duration = start.elapsed();
info!("Request completed in {:?}", duration);
if duration > Duration::from_secs(30) {
warn!("Request took longer than expected: {:?}", duration);
}
// Clear cache periodically in production
client.clear_cache();
Ok(())
}
```
## Error Handling
The client provides comprehensive error handling with specific error types:
### SwarmsError Types
| Error Type | Description | Recommended Action |
|------------|-------------|-------------------|
| `Authentication` | Invalid API key or authentication failure | Check API key and permissions |
| `RateLimit` | Rate limit exceeded | Implement exponential backoff |
| `InvalidRequest` | Malformed request parameters | Validate input parameters |
| `InsufficientCredits` | Not enough credits for operation | Check account balance |
| `Api` | General API error | Check API status and retry |
| `Network` | Network connectivity issues | Check internet connection |
| `Timeout` | Request timeout | Increase timeout or retry |
| `CircuitBreakerOpen` | Circuit breaker preventing requests | Wait for recovery period |
| `Serialization` | JSON serialization/deserialization error | Check data format |
### Error Handling Best Practices
```rust
use swarms_client::{SwarmsClient, SwarmsError};
async fn handle_swarm_request(client: &SwarmsClient, task: &str) -> Result<String, SwarmsError> {
match client.swarm()
.completion()
.task(task)
.agent(|agent| agent.name("Worker").model("gpt-4o-mini"))
.send()
.await
{
Ok(response) => Ok(response.output.to_string()),
Err(SwarmsError::RateLimit { .. }) => {
// Implement exponential backoff
tokio::time::sleep(Duration::from_secs(5)).await;
Err(SwarmsError::RateLimit {
message: "Rate limited - should retry".to_string(),
status: Some(429),
request_id: None,
})
},
Err(e) => Err(e),
}
}
```
## Performance Features
### Connection Pooling
The client automatically manages HTTP connection pooling for optimal performance:
```rust
// Connections are automatically pooled and reused
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.max_concurrent_requests(100) // Allow up to 100 concurrent requests
.build()?;
```
### Caching
Intelligent caching reduces redundant API calls:
```rust
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.enable_cache(true)
.cache_ttl(Duration::from_secs(300)) // 5-minute TTL
.build()?;
// GET requests are automatically cached
let models = client.models().list().await?; // First call hits API
let models_cached = client.models().list().await?; // Second call uses cache
```
### Circuit Breaker
Automatic failure detection and recovery:
```rust
let client = SwarmsClient::builder()
.unwrap()
.from_env()?
.build()?;
// Circuit breaker automatically opens after 5 failures
// and recovers after 60 seconds
```
## Configuration Reference
### ClientConfig Structure
| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `api_key` | `String` | `""` | Swarms API key |
| `base_url` | `Url` | `https://swarms-api-285321057562.us-east1.run.app/` | API base URL |
| `timeout` | `Duration` | `60s` | Request timeout |
| `max_retries` | `usize` | `3` | Maximum retry attempts |
| `retry_delay` | `Duration` | `1s` | Base retry delay |
| `max_concurrent_requests` | `usize` | `100` | Concurrent request limit |
| `circuit_breaker_threshold` | `usize` | `5` | Failure threshold for circuit breaker |
| `circuit_breaker_timeout` | `Duration` | `60s` | Circuit breaker recovery time |
| `enable_cache` | `bool` | `true` | Enable response caching |
| `cache_ttl` | `Duration` | `300s` | Cache time-to-live |
## Environment Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `SWARMS_API_KEY` | Your Swarms API key | `sk-xxx...` |
| `SWARMS_BASE_URL` | Custom API base URL (optional) | `https://api.custom.com/` |
## Testing
Run the test suite:
```bash
cargo test
```
Run specific tests:
```bash
cargo test test_cache
cargo test test_circuit_breaker
```
## Contributing
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
This project is licensed under the MIT License - see the LICENSE file for details.

214
docs/swarms_cloud/sequential_workflow.md
Unescape View File

@ -1,214 +0,0 @@
# SequentialWorkflow
*Executes tasks in a strict, predefined order for step-by-step processing*
**Swarm Type**: `SequentialWorkflow`
## Overview
The SequentialWorkflow swarm type executes tasks in a strict, predefined order where each step depends on the completion of the previous one. This architecture is perfect for workflows that require a linear progression of tasks, ensuring that each agent builds upon the work of the previous agent.
Key features:
- **Ordered Execution**: Agents execute in a specific, predefined sequence
- **Step Dependencies**: Each step builds upon previous results
- **Predictable Flow**: Clear, linear progression through the workflow
- **Quality Control**: Each agent can validate and enhance previous work
## Use Cases
- Document processing pipelines
- Multi-stage analysis workflows
- Content creation and editing processes
- Data transformation and validation pipelines
## API Usage
### Basic SequentialWorkflow Example
=== "Shell (curl)"
```bash
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Content Creation Pipeline",
"description": "Sequential content creation from research to final output",
"swarm_type": "SequentialWorkflow",
"task": "Create a comprehensive blog post about the future of renewable energy",
"agents": [
{
"agent_name": "Research Specialist",
"description": "Conducts thorough research on the topic",
"system_prompt": "You are a research specialist. Gather comprehensive, accurate information on the given topic from reliable sources.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Content Writer",
"description": "Creates engaging written content",
"system_prompt": "You are a skilled content writer. Transform research into engaging, well-structured articles that are informative and readable.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.6
},
{
"agent_name": "Editor",
"description": "Reviews and polishes the content",
"system_prompt": "You are a professional editor. Review content for clarity, grammar, flow, and overall quality. Make improvements while maintaining the author's voice.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.4
},
{
"agent_name": "SEO Optimizer",
"description": "Optimizes content for search engines",
"system_prompt": "You are an SEO expert. Optimize content for search engines while maintaining readability and quality.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
}
],
"max_loops": 1
}'
```
=== "Python (requests)"
```python
import requests
import json
API_BASE_URL = "https://api.swarms.world"
API_KEY = "your_api_key_here"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
swarm_config = {
"name": "Content Creation Pipeline",
"description": "Sequential content creation from research to final output",
"swarm_type": "SequentialWorkflow",
"task": "Create a comprehensive blog post about the future of renewable energy",
"agents": [
{
"agent_name": "Research Specialist",
"description": "Conducts thorough research on the topic",
"system_prompt": "You are a research specialist. Gather comprehensive, accurate information on the given topic from reliable sources.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.3
},
{
"agent_name": "Content Writer",
"description": "Creates engaging written content",
"system_prompt": "You are a skilled content writer. Transform research into engaging, well-structured articles that are informative and readable.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.6
},
{
"agent_name": "Editor",
"description": "Reviews and polishes the content",
"system_prompt": "You are a professional editor. Review content for clarity, grammar, flow, and overall quality. Make improvements while maintaining the author's voice.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.4
},
{
"agent_name": "SEO Optimizer",
"description": "Optimizes content for search engines",
"system_prompt": "You are an SEO expert. Optimize content for search engines while maintaining readability and quality.",
"model_name": "gpt-4o",
"max_loops": 1,
"temperature": 0.2
}
],
"max_loops": 1
}
response = requests.post(
f"{API_BASE_URL}/v1/swarm/completions",
headers=headers,
json=swarm_config
)
if response.status_code == 200:
result = response.json()
print("SequentialWorkflow swarm completed successfully!")
print(f"Cost: ${result['metadata']['billing_info']['total_cost']}")
print(f"Execution time: {result['metadata']['execution_time_seconds']} seconds")
print(f"Final output: {result['output']}")
else:
print(f"Error: {response.status_code} - {response.text}")
```
**Example Response**:
```json
{
"job_id": "swarms-pbM8wqUwxq8afGeROV2A4xAcncd1",
"status": "success",
"swarm_name": "Content Creation Pipeline",
"description": "Sequential content creation from research to final output",
"swarm_type": "SequentialWorkflow",
"output": [
{
"role": "Research Specialist",
"content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we navigate the complexities of the 21st century, the transition to renewable energy stands out as a critical endeavor to ensure a sustainable future......"
},
{
"role": "SEO Optimizer",
"content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nThe transition to renewable energy is crucial as we face the challenges of the 21st century, including climate change and dwindling fossil fuel resources......."
},
{
"role": "Editor",
"content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we confront the challenges of the 21st century, transitioning to renewable energy is essential for a sustainable future. With climate change concerns escalating and fossil fuel reserves depleting, renewable energy is not just an option but a necessity...."
},
{
"role": "Content Writer",
"content": "\"**Title: The Future of Renewable Energy: Charting a Sustainable Path Forward**\n\nAs we face the multifaceted challenges of the 21st century, transitioning to renewable energy emerges as not just an option but an essential step toward a sustainable future...."
}
],
"number_of_agents": 4,
"service_tier": "standard",
"execution_time": 72.23084282875061,
"usage": {
"input_tokens": 28,
"output_tokens": 3012,
"total_tokens": 3040,
"billing_info": {
"cost_breakdown": {
"agent_cost": 0.04,
"input_token_cost": 0.000084,
"output_token_cost": 0.04518,
"token_counts": {
"total_input_tokens": 28,
"total_output_tokens": 3012,
"total_tokens": 3040
},
"num_agents": 4,
"service_tier": "standard",
"night_time_discount_applied": true
},
"total_cost": 0.085264,
"discount_active": true,
"discount_type": "night_time",
"discount_percentage": 75
}
}
}
```
## Best Practices
- Design agents with clear, sequential dependencies
- Ensure each agent builds meaningfully on the previous work
- Use for linear workflows where order matters
- Validate outputs at each step before proceeding
## Related Swarm Types
- [ConcurrentWorkflow](concurrent_workflow.md) - For parallel execution
- [AgentRearrange](agent_rearrange.md) - For dynamic sequencing
- [HierarchicalSwarm](hierarchical_swarm.md) - For structured workflows

128
docs/swarms_cloud/subscription_tiers.md
Unescape View File

@ -1,128 +0,0 @@
# Swarms Cloud Subscription Tiers
!!! abstract "Overview"
Choose the perfect plan for your agent infrastructure needs. All plans include our core features with additional benefits as you scale up.
## Pricing Plans
### Free Tier
!!! example "Free"
**$0/year**
Perfect for getting started with AI development.
[Get Started](https://swarms.world/platform/account){ .md-button .md-button--primary }
**What's Included:**
- [x] Sign up Bonus!
- [x] Basic Access
- [x] Pay-Per-Use Pricing
- [x] Community Support
- [x] Standard Processing Speed
### Premium Tier
!!! success "Premium"
**Monthly $100/month**
**Yearly $1,020/year** (Save 15% on annual billing)
[Subscribe Now](https://swarms.world/platform/account){ .md-button .md-button--primary }
**Everything in Free, plus:**
- [x] Full Access to Explorer and Agents
- [x] Access to Premium Multi-Modality Models
- [x] Priority Access to Swarms
- [x] High-Performance Infrastructure
- [x] Exclusive Webinars and Tutorials
- [x] Priority Support
- [x] Enhanced Security Features
- [x] Early Access to New Models and Features
### Enterprise Tier
!!! tip "Enterprise"
**Contact for more Information**
[Book a Call](https://cal.com/swarms){ .md-button .md-button--primary }
**Everything in Premium, plus:**
- [x] High-Performance Infrastructure
- [x] Batch API
- [x] Early Access to New Swarms
- [x] Dedicated 24/7 Support
- [x] Custom Solutions Engineering
- [x] Advanced Security Features
- [x] Onsite Training and Onboarding
- [x] Custom Model Training
- [x] Priority Support
- [x] Pay-Per-Use Pricing
- [x] Enterprise Telemetry Platform
- [x] Regular Check-In Strategy Sessions
## Feature Comparison
| Feature | Free | Premium | Enterprise |
|---------|------|---------|------------|
| Sign up Bonus | ✅ | ✅ | ✅ |
| Basic Access | ✅ | ✅ | ✅ |
| Pay-Per-Use Pricing | ✅ | ✅ | ✅ |
| Community Support | ✅ | ✅ | ✅ |
| Standard Processing Speed | ✅ | ✅ | ✅ |
| Full Access to Explorer and Agents | ❌ | ✅ | ✅ |
| Premium Multi-Modality Models | ❌ | ✅ | ✅ |
| Priority Access to Swarms | ❌ | ✅ | ✅ |
| High-Performance GPUs | ❌ | ✅ | ✅ |
| Exclusive Webinars and Tutorials | ❌ | ✅ | ✅ |
| Priority Support | ❌ | ✅ | ✅ |
| Enhanced Security Features | ❌ | ✅ | ✅ |
| Early Access to New Models | ❌ | ✅ | ✅ |
| Batch API | ❌ | ❌ | ✅ |
| Dedicated 24/7 Support | ❌ | ❌ | ✅ |
| Custom Solutions Engineering | ❌ | ❌ | ✅ |
| Onsite Training and Onboarding | ❌ | ❌ | ✅ |
| Custom Model Training | ❌ | ❌ | ✅ |
## Rate Limits
!!! info "Rate Limit Increases"
- **Premium**: 100% increase in rate limits
- **Enterprise**: Custom rate limits based on your needs (contact us for details)
## Getting Started
1. Choose your plan
2. Create your account
3. Start building with Swarms!
!!! success "Need Help?"
- For general questions: [Contact Support](mailto:kye@swarms.world)
- For enterprise inquiries: [Book a Call](https://cal.com/swarms)
- Upgrade Your Membership: [Upgrade Now](https://swarms.world/platform/account)

28
docs/swarms_cloud/swarm_types.md
Unescape View File

@ -1,28 +0,0 @@
# Multi-Agent Architectures
Each multi-agent architecture type is designed for specific use cases and can be combined to create powerful multi-agent systems. Below is an overview of each available swarm type:
| Swarm Type | Description | Learn More |
|----------------------|------------------------------------------------------------------------------|------------|
| AgentRearrange | Dynamically reorganizes agents to optimize task performance and efficiency. Useful when agent effectiveness depends on their sequence or arrangement. | [Learn More](agent_rearrange.md) |
| MixtureOfAgents | Builds diverse teams of specialized agents, each contributing unique skills to solve complex problems. Excels at tasks requiring multiple types of expertise. | [Learn More](mixture_of_agents.md) |
| SequentialWorkflow | Executes tasks in a strict, predefined order. Perfect for workflows where each step depends on the completion of the previous one. | [Learn More](sequential_workflow.md) |
| ConcurrentWorkflow | Runs independent tasks in parallel, significantly reducing processing time for complex operations. Ideal for tasks that can be processed simultaneously. | [Learn More](concurrent_workflow.md) |
| GroupChat | Enables dynamic collaboration between agents through a chat-based interface, facilitating real-time information sharing and decision-making. | [Learn More](group_chat.md) |
| HierarchicalSwarm | Implements a structured, multi-level approach to task management, with clear lines of authority and delegation. | [Learn More](hierarchical_swarm.md) |
| MultiAgentRouter | Acts as an intelligent task dispatcher, distributing work across agents based on their capabilities and current workload. | [Learn More](multi_agent_router.md) |
| MajorityVoting | Implements robust decision-making through consensus, ideal for tasks requiring collective intelligence or verification. | [Learn More](majority_voting.md) |
<!-- | AutoSwarmBuilder | Automatically configures agent architectures based on task requirements and performance metrics, simplifying swarm creation. | [Learn More](auto_swarm_builder.md) |
<!-- | Auto | Intelligently selects the most effective swarm architecture for a given task based on context. | [Learn More](auto.md) | -->
# Learn More
To explore Swarms architecture and how different swarm types work together, check out our comprehensive guides:
- [Introduction to Multi-Agent Architectures](/swarms/concept/swarm_architectures)
- [How to Choose the Right Multi-Agent Architecture](/swarms/concept/how_to_choose_swarms)
- [Framework Architecture Overview](/swarms/concept/framework_architecture)
- [Building Custom Swarms](/swarms/structs/custom_swarm)

1271
docs/swarms_cloud/swarms_api.md
View File

File diff suppressed because it is too large Load Diff

382
docs/swarms_cloud/swarms_api_tools.md
Unescape View File

@ -1,382 +0,0 @@
# Swarms API with Tools Guide
Swarms API allows you to create and manage AI agent swarms with optional tool integration. This guide will walk you through setting up and using the Swarms API with tools.
## Prerequisites
- Python 3.7+
- Swarms API key
- Required Python packages:
- `requests`
- `python-dotenv`
## Installation & Setup
1. Install required packages:
```bash
pip install requests python-dotenv
```
2. Create a `.env` file in your project root:
```bash
SWARMS_API_KEY=your_api_key_here
```
3. Basic setup code:
```python
import os
import requests
from dotenv import load_dotenv
import json
load_dotenv()
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
```
## Creating a Swarm with Tools
### Step-by-Step Guide
1. Define your tool dictionary:
```python
tool_dictionary = {
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct an in-depth search on a specified topic",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth (1-3)"
},
"detailed_queries": {
"type": "array",
"items": {
"type": "string",
"description": "Specific search queries"
}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
```
2. Create agent configurations:
```python
agent_config = {
"agent_name": "Market Analyst",
"description": "Analyzes market trends",
"system_prompt": "You are a financial analyst expert.",
"model_name": "openai/gpt-4",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False,
"tools_dictionary": [tool_dictionary] # Optional: Add tools if needed
}
```
3. Create the swarm payload:
```python
payload = {
"name": "Your Swarm Name",
"description": "Swarm description",
"agents": [agent_config],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Your task description",
"output_type": "dict"
}
```
4. Make the API request:
```python
def run_swarm(payload):
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload
)
return response.json()
```
## FAQ
### Do all agents need tools?
No, tools are optional for each agent. You can choose which agents have tools based on your specific needs. Simply omit the `tools_dictionary` field for agents that don't require tools.
### What types of tools can I use?
Currently, the API supports function-type tools. Each tool must have:
- A unique name
- A clear description
- Well-defined parameters with types and descriptions
### Can I mix agents with and without tools?
Yes, you can create swarms with a mix of tool-enabled and regular agents. This allows for flexible swarm architectures.
### What's the recommended number of tools per agent?
While there's no strict limit, it's recommended to:
- Keep tools focused and specific
- Only include tools that the agent needs
- Consider the complexity of tool interactions
## Example Implementation
Here's a complete example of a financial analysis swarm:
```python
def run_financial_analysis_swarm():
payload = {
"name": "Financial Analysis Swarm",
"description": "Market analysis swarm",
"agents": [
{
"agent_name": "Market Analyst",
"description": "Analyzes market trends",
"system_prompt": "You are a financial analyst expert.",
"model_name": "openai/gpt-4",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False,
"tools_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct market research",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth (1-3)"
},
"detailed_queries": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
}
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Analyze top performing tech ETFs",
"output_type": "dict"
}
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload
)
return response.json()
```
## Health Check
Always verify the API status before running swarms:
```python
def check_api_health():
response = requests.get(f"{BASE_URL}/health", headers=headers)
return response.json()
```
## Best Practices
1. **Error Handling**: Always implement proper error handling:
```python
def safe_run_swarm(payload):
try:
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"Error running swarm: {e}")
return None
```
2. **Environment Variables**: Never hardcode API keys
3. **Tool Design**: Keep tools simple and focused
4. **Testing**: Validate swarm configurations before production use
## Troubleshooting
Common issues and solutions:
1. **API Key Issues**
- Verify key is correctly set in `.env`
- Check key permissions
2. **Tool Execution Errors**
- Validate tool parameters
- Check tool function signatures
3. **Response Timeout**
- Consider reducing max_tokens
- Simplify tool complexity
```python
import os
import requests
from dotenv import load_dotenv
import json
load_dotenv()
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
def run_health_check():
response = requests.get(f"{BASE_URL}/health", headers=headers)
return response.json()
def run_single_swarm():
payload = {
"name": "Financial Analysis Swarm",
"description": "Market analysis swarm",
"agents": [
{
"agent_name": "Market Analyst",
"description": "Analyzes market trends",
"system_prompt": "You are a financial analyst expert.",
"model_name": "openai/gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False,
"tools_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct an in-depth search on a specified topic or subtopic, generating a comprehensive array of highly detailed search queries tailored to the input parameters.",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Indicates the level of thoroughness for the search. Values range from 1 to 3, where 1 represents a superficial search and 3 signifies an exploration of the topic.",
},
"detailed_queries": {
"type": "array",
"description": "An array of highly specific search queries that are generated based on the input query and the specified depth. Each query should be designed to elicit detailed and relevant information from various sources.",
"items": {
"type": "string",
"description": "Each item in this array should represent a unique search query that targets a specific aspect of the main topic, ensuring a comprehensive exploration of the subject matter.",
},
},
},
"required": ["depth", "detailed_queries"],
},
},
},
],
},
{
"agent_name": "Economic Forecaster",
"description": "Predicts economic trends",
"system_prompt": "You are an expert in economic forecasting.",
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False,
"tools_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct an in-depth search on a specified topic or subtopic, generating a comprehensive array of highly detailed search queries tailored to the input parameters.",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Indicates the level of thoroughness for the search. Values range from 1 to 3, where 1 represents a superficial search and 3 signifies an exploration of the topic.",
},
"detailed_queries": {
"type": "array",
"description": "An array of highly specific search queries that are generated based on the input query and the specified depth. Each query should be designed to elicit detailed and relevant information from various sources.",
"items": {
"type": "string",
"description": "Each item in this array should represent a unique search query that targets a specific aspect of the main topic, ensuring a comprehensive exploration of the subject matter.",
},
},
},
"required": ["depth", "detailed_queries"],
},
},
},
],
},
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "What are the best etfs and index funds for ai and tech?",
"output_type": "dict",
}
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload,
)
print(response)
print(response.status_code)
# return response.json()
output = response.json()
return json.dumps(output, indent=4)
if __name__ == "__main__":
result = run_single_swarm()
print("Swarm Result:")
print(result)
```
Write Preview
Loading…
Cancel
Save