Quickstart
The Swarms API enables you to create and orchestrate AI agents for both single-agent tasks and multi-agent workflows.
The Swarms API enables you to create and orchestrate AI agents for both single-agent tasks and multi-agent workflows. The platform supports various AI models and provides flexible orchestration patterns for complex problem-solving scenarios.
Key Features
Single Agent Operations: Deploy individual AI agents for specific tasks
Multi-Agent Swarms: Coordinate multiple agents working together
Sequential Workflows: Agents work in ordered sequence, building on previous outputs
Concurrent Workflows: Agents work in parallel for faster processing
Tools Integration: Extend agent capabilities with custom functions
Multiple Model Support: Choose from OpenAI, Anthropic, and Groq models
Getting Started
Prerequisites
Before you begin, ensure you have:
Python 3.7+ or Node.js for JavaScript/TypeScript
An API key from Swarms Platform
Required libraries installed
Installation
Python:
pip install requests python-dotenvJavaScript/TypeScript:
npm install axios dotenvAuthentication
The API uses API key authentication through the x-api-key header. Store your API key securely as an environment variable.
Base URLs:
Production:
https://api.swarms.worldAlternative:
https://swarms-api-285321057562.us-east1.run.app
Security Note: Never hardcode API keys in your code. Always use environment variables or secure configuration management.
Single Agent Usage
Single agents are ideal for focused tasks that don't require collaboration between multiple AI systems.
Basic Health Check
Before making API calls, verify your connection:
Python:
import os
import requests
from dotenv import load_dotenv
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"
}
response = requests.get(f"{BASE_URL}/health", headers=headers)
print(response.json())JavaScript/TypeScript:
import axios from 'axios';
import * as dotenv from 'dotenv';
dotenv.config();
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = 'https://api.swarms.world';
const headers = {
'x-api-key': API_KEY,
'Content-Type': 'application/json'
};
const response = await axios.get(`${BASE_URL}/health`, { headers });
console.log(response.data);Creating a Basic Agent
A single agent requires an agent configuration and a task to execute:
Python:
def run_single_agent():
payload = {
"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."
),
"model_name": "claude-3-5-sonnet-20240620",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 1,
"auto_generate_prompt": False,
"tools_list_dictionary": None,
},
"task": "What are the key trends in renewable energy adoption?",
}
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload
)
return response.json()JavaScript/TypeScript:
async function runSingleAgent() {
const payload = {
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.",
model_name: "claude-3-5-sonnet-20240620",
role: "worker",
max_loops: 1,
max_tokens: 8192,
temperature: 1,
auto_generate_prompt: false,
tools_list_dictionary: null
},
task: "What are the key trends in renewable energy adoption?"
};
const response = await axios.post(
`${BASE_URL}/v1/agent/completions`,
payload,
{ headers }
);
return response.data;
}Agent Configuration Parameters
agent_name: Descriptive name for your agent
description: Brief description of the agent's purpose
system_prompt: Detailed instructions defining the agent's role and capabilities
model_name: AI model to use (see supported models section)
role: Agent role, typically "worker"
max_loops: Maximum number of processing loops
max_tokens: Maximum response length
temperature: Response creativity (0.0 = deterministic, 1.0 = creative)
auto_generate_prompt: Whether to auto-enhance the system prompt
tools_list_dictionary: Optional tools for extended functionality
Maintaining Conversation History
For multi-turn conversations, include previous messages in the history parameter:
Python:
def run_agent_with_history():
payload = {
"agent_config": {
"agent_name": "Conversation Agent",
"description": "An agent that maintains conversation context",
"system_prompt": "You are a helpful assistant that maintains context.",
"model_name": "claude-3-5-sonnet-20240620",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.7,
"auto_generate_prompt": False,
},
"task": "What's the weather like?",
"history": [
{
"role": "user",
"content": "I'm planning a trip to New York."
},
{
"role": "assistant",
"content": "That's great! When are you planning to visit?"
},
{
"role": "user",
"content": "Next week."
}
]
}
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload
)
return response.json()Multi-Agent Swarms
Multi-agent swarms enable complex problem-solving by coordinating multiple AI agents. Swarms support two primary workflow types:
Workflow Types
Sequential Workflow: Agents execute in order, with each agent building upon the previous agent's output. This is ideal for tasks requiring step-by-step processing.
Concurrent Workflow: Agents work simultaneously on the same task, providing parallel processing for faster results and diverse perspectives.
Sequential Workflow Example
Sequential workflows are perfect for analysis pipelines where each step depends on the previous one:
Python:
def run_sequential_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 specializing in market trend analysis.",
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False
},
{
"agent_name": "Economic Forecaster",
"description": "Predicts economic trends",
"system_prompt": "You are an expert in economic forecasting. Use the market analysis to provide economic predictions.",
"model_name": "gpt-4o",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False
}
],
"max_loops": 1,
"swarm_type": "SequentialWorkflow",
"task": "Analyze the current market conditions and provide economic forecasts."
}
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload
)
return response.json()Concurrent Workflow Example
Concurrent workflows are ideal when you need multiple perspectives or parallel processing:
Python:
def run_concurrent_swarm():
payload = {
"name": "Medical Analysis Swarm",
"description": "Analyzes medical data concurrently",
"agents": [
{
"agent_name": "Lab Data Analyzer",
"description": "Analyzes lab report data",
"system_prompt": "You are a medical data analyst specializing in lab results interpretation.",
"model_name": "claude-3-5-sonnet-20240620",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False
},
{
"agent_name": "Clinical Specialist",
"description": "Provides clinical interpretations",
"system_prompt": "You are an expert in clinical diagnosis and patient care recommendations.",
"model_name": "claude-3-5-sonnet-20240620",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"auto_generate_prompt": False
}
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Analyze these lab results and provide clinical interpretations."
}
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json=payload
)
return response.json()Batch Processing
Process multiple swarms in a single request for improved efficiency:
Python:
def run_batch_swarms():
payload = [
{
"name": "Research Swarm",
"description": "Conducts comprehensive research",
"agents": [
{
"agent_name": "Research Agent",
"description": "Conducts initial research",
"system_prompt": "You are a research assistant specializing in comprehensive data gathering.",
"model_name": "gpt-4",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.7,
"auto_generate_prompt": False
},
{
"agent_name": "Analysis Agent",
"description": "Analyzes research data",
"system_prompt": "You are a data analyst who synthesizes research findings.",
"model_name": "gpt-4",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.7,
"auto_generate_prompt": False
}
],
"max_loops": 1,
"swarm_type": "SequentialWorkflow",
"task": "Research recent AI advancements and provide analysis."
}
]
response = requests.post(
f"{BASE_URL}/v1/swarm/batch/completions",
headers=headers,
json=payload
)
return response.json()Advanced Features
Tools Integration
Enhance agent capabilities by providing specialized tools. Tools are defined using OpenAPI-style function specifications:
Python:
def run_agent_with_tools():
tools_dictionary = [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct an in-depth search on a specific topic",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth level (1-3, where 3 is most comprehensive)"
},
"detailed_queries": {
"type": "array",
"description": "List of specific search queries to execute",
"items": {
"type": "string"
}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
payload = {
"agent_config": {
"agent_name": "Research Assistant",
"description": "Expert researcher with advanced search capabilities",
"system_prompt": "You are a research assistant with access to advanced search tools. Use the search_topic function when you need to gather comprehensive information.",
"model_name": "gpt-4",
"role": "worker",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.7,
"auto_generate_prompt": False,
"tools_dictionary": tools_dictionary
},
"task": "Research the latest developments in quantum computing and provide a comprehensive analysis."
}
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload
)
return response.json()Tool Definition Guidelines
When creating tools for your agents:
Clear Names: Use descriptive function names that clearly indicate the tool's purpose
Detailed Descriptions: Provide comprehensive descriptions of what the tool does
Parameter Specifications: Define all parameters with appropriate types and descriptions
Required Fields: Specify which parameters are mandatory
Usage Context: Include guidance in the system prompt about when to use specific tools
Supported Models
Choose the appropriate model based on your use case requirements:
OpenAI Models
gpt-4: High-quality reasoning and complex task handling
gpt-4o: Optimized version with improved performance
gpt-4o-mini: Lightweight version for faster responses
Anthropic Models
claude-3-5-sonnet-20240620: Balanced performance and reasoning
claude-3-7-sonnet-latest: Latest Claude model with enhanced capabilities
Groq Models
groq/llama3-70b-8192: High-performance open-source model
groq/deepseek-r1-distill-llama-70b: Specialized reasoning model
Model Selection Guidelines
Complex Analysis: Use GPT-4 or Claude-3.5-Sonnet for tasks requiring deep reasoning
Fast Responses: Choose GPT-4o-mini for quick, straightforward tasks
Creative Tasks: Higher temperature settings work better with creative models
Factual Tasks: Lower temperature settings provide more consistent, factual responses
API Reference
Endpoints
Single Agent Completions:
POST /v1/agent/completions
Swarm Completions:
POST /v1/swarm/completions
Batch Swarm Completions:
POST /v1/swarm/batch/completions
Health Check:
GET /health
Best Practices
Security
Never commit API keys to version control
Use environment variables for all sensitive configuration
Implement proper access controls in production environments
Regularly rotate API keys
Error Handling
Implement robust error handling for production applications:
Python:
import time
from tenacity import retry, wait_exponential, stop_after_attempt
@retry(
wait=wait_exponential(multiplier=1, min=4, max=10),
stop=stop_after_attempt(3)
)
def make_api_call(payload):
try:
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json=payload,
timeout=30
)
response.raise_for_status()
return response.json()
except requests.exceptions.RequestException as e:
print(f"API call failed: {e}")
raise
def validate_payload(payload):
required_fields = ["agent_config", "task"]
if not all(field in payload for field in required_fields):
raise ValueError("Missing required fields in payload")
agent_config = payload["agent_config"]
required_config_fields = ["agent_name", "system_prompt", "model_name"]
if not all(field in agent_config for field in required_config_fields):
raise ValueError("Missing required fields in agent_config")Rate Limiting
Implement exponential backoff for failed requests
Monitor your API usage to stay within limits
Use batch processing when possible to reduce individual request volume
Performance Optimization
Cache responses when appropriate
Use concurrent workflows for independent tasks
Choose the right model for your specific use case
Optimize token usage by being specific in your prompts
Testing Strategy
Start with simple, single-agent tasks
Test with different models to find the best fit
Gradually increase complexity as you understand the system
Implement comprehensive logging for debugging
Troubleshooting
Common Issues
Authentication Errors:
Verify your API key is correct and active
Check that the
x-api-keyheader is properly setEnsure your API key has the necessary permissions
Timeout Issues:
Increase request timeout values
Consider breaking complex tasks into smaller chunks
Use batch processing for multiple operations
Model Availability:
Check if your requested model is currently available
Have fallback models configured
Monitor model status through the health endpoint
Payload Validation:
Ensure all required fields are present
Validate data types match the expected format
Check that tool definitions follow the correct schema
Getting Help
Community Resources
Documentation: docs.swarms.world
Discord Community: Join Discord
Technical Blog: Medium
Professional Support
Onboarding Sessions: Book with Kye Gomez
Enterprise Support: Contact through the platform
Stay Updated
Twitter: @kyegomez
LinkedIn: The Swarm Corporation
YouTube: Swarms Channel
Community Events: Sign up here
Conclusion
The Swarms API provides a powerful platform for building sophisticated AI agent systems. Whether you're working with single agents for focused tasks or orchestrating complex multi-agent workflows, the platform offers the flexibility and tools needed to create effective AI solutions.
Start with simple implementations and gradually explore more advanced features like tools integration and multi-agent coordination. The community and documentation resources are available to help you succeed in building powerful agent-based applications.
Last updated
Was this helpful?