API Architecture

Documentation Index

Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

Architecture Tiers

​

Tier 1: Individual Agents

• Single Agent: One AI model per agent
• Focused Purpose: Specialized for specific tasks
• Customizable: Full control over system prompts, tools, and behavior
• Efficient: Optimized for direct task execution
• Scalable: Can be combined into larger systems

• Content generation (articles, code, reports)
• Data analysis and processing
• Customer service responses
• Creative tasks (writing, design)
• Simple Q&A and information retrieval
• Tool execution and automation

import requests

payload = {
    "agent_config": {
        "agent_name": "content-writer",
        "description": "Professional content writer for technical articles",
        "system_prompt": "You are an expert technical writer...",
        "model_name": "gpt-4o",
        "max_tokens": 4000,
        "temperature": 0.7
    },
    "task": "Write a comprehensive guide on API security best practices"
}

response = requests.post(
    "https://api.swarms.world/v1/agent/completions",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

​

Tier 2: Reasoning Agents

• Reasoning-Focused: Built for complex logical and analytical tasks
• Multi-Perspective: Can approach problems from different angles
• Iterative: Capable of refinement and improvement cycles
• Specialized Types: 7 different reasoning agent types available
• Internal Coordination: May use sub-agents for specialized reasoning

• Mathematical proofs and complex calculations
• Logical consistency validation
• Research and analysis tasks
• Cross-domain problem solving
• Bias detection and ethical analysis
• Iterative improvement scenarios

payload = {
    "agent_name": "math-reasoner",
    "description": "Mathematical problem solver using dual perspectives",
    "model_name": "claude-sonnet-4-20250514-20240620",
    "system_prompt": "You are an expert mathematical reasoning agent...",
    "max_loops": 1,
    "swarm_type": "reasoning-duo",
    "task": "Prove that the sum of any three consecutive integers is divisible by 3"
}

response = requests.post(
    "https://api.swarms.world/v1/reasoning-agent/completions",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

​

Tier 3: Multi-Agent Swarms

• Massive Scale: 3 to 10,000+ agents per swarm
• Coordinated Workflows: Agents work together in structured processes
• Multiple Swarm Types: 12+ different swarm architectures available
• Enterprise-Grade: Built for complex business applications
• Dynamic Routing: Intelligent task distribution and agent selection

• Enterprise process automation
• Large-scale data processing
• Complex decision-making systems
• Research and development workflows
• Customer service automation
• Content creation pipelines
• Quality assurance systems
• Dynamic resource allocation

payload = {
    "name": "Enterprise Content Pipeline",
    "description": "Multi-stage content creation and review system",
    "agents": [
        {
            "agent_name": "researcher",
            "description": "Research and gather information",
            "model_name": "gpt-4o",
            "role": "researcher"
        },
        {
            "agent_name": "writer",
            "description": "Create initial content",
            "model_name": "claude-sonnet-4-20250514-20240620",
            "role": "writer"
        },
        {
            "agent_name": "editor",
            "description": "Review and improve content",
            "model_name": "gpt-4o",
            "role": "editor"
        },
        {
            "agent_name": "fact-checker",
            "description": "Verify accuracy and sources",
            "model_name": "claude-sonnet-4-20250514-20240620",
            "role": "validator"
        }
    ],
    "max_loops": 1,
    "swarm_type": "SequentialWorkflow",
    "task": "Create a comprehensive industry report on AI trends in 2024"
}

response = requests.post(
    "https://api.swarms.world/v1/swarm/completions",
    headers={"x-api-key": "your-api-key"},
    json=payload
)

​

Architecture Comparison

​

Choosing the Right Architecture

​

When to Use Individual Agents

• ✅ Single, well-defined tasks
• ✅ Quick prototyping and testing
• ✅ Resource-constrained environments
• ✅ Simple automation needs
• ✅ Cost-sensitive applications

​

When to Use Reasoning Agents

• ✅ Complex problem-solving tasks
• ✅ Tasks requiring multiple perspectives
• ✅ Logical consistency validation
• ✅ Research and analysis work
• ✅ Tasks requiring iterative improvement

​

When to Use Multi-Agent Swarms

• ✅ Complex business processes
• ✅ Large-scale automation
• ✅ Multi-step workflows
• ✅ Enterprise applications
• ✅ Tasks requiring multiple expertise areas
• ✅ Dynamic, adaptive systems

​

Integration Patterns

​

Hybrid Approaches

1. Individual + Reasoning: Use individual agents for data collection, reasoning agents for analysis
2. Reasoning + Swarms: Use reasoning agents within swarms for complex decision-making
3. All Three Tiers: Individual agents for data processing, reasoning agents for analysis, swarms for orchestration

​

Migration Paths

• Start Simple: Begin with individual agents, upgrade to reasoning agents for complex tasks
• Scale Up: Move from reasoning agents to swarms for enterprise needs
• Optimize: Use reasoning agents within swarms for enhanced decision-making

​

Performance Considerations

​

Individual Agents

• Latency: 1-5 seconds
• Throughput: High (1000+ requests/minute)
• Cost: $0.01-0.10 per request
• Memory: Minimal

​

Reasoning Agents

• Latency: 5-30 seconds
• Throughput: Medium (100-500 requests/minute)
• Cost: $0.05-0.50 per request
• Memory: Moderate

​

Multi-Agent Swarms

• Latency: 30 seconds - 10 minutes
• Throughput: Variable (10-100 requests/minute)
• Cost: $0.10-5.00 per request
• Memory: High

​

Best Practices

​

1. Start with the Right Tier

• Begin with individual agents for simple tasks
• Upgrade to reasoning agents when complexity increases
• Use swarms only when necessary for scale

​

2. Optimize for Your Use Case

• Match agent capabilities to task requirements
• Consider cost vs. performance trade-offs
• Plan for scalability from the start

​

3. Monitor and Iterate

• Track performance metrics across all tiers
• Optimize based on usage patterns
• Consider hybrid approaches for complex needs

​

Getting Started

​

Quick Start Guide

1. Get API Key: https://swarms.world/platform/api-keys
2. Choose Your Tier: Start with individual agents for simple tasks
3. Build and Test: Create your first agent and test functionality
4. Scale Up: Move to reasoning agents or swarms as needed

​

Support and Community

• Technical Support: Book a Call
• Community: Join our Discord
• Updates: Follow us on Twitter