> ## 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.

# API Architecture

> The Swarms API provides a comprehensive multi-tier architecture for building collaborative agentic systems.

The Swarms API provides a comprehensive multi-tier architecture for building intelligent AI systems. The platform is designed around three distinct agent paradigms, each optimized for different types of tasks and complexity levels.

### Architecture Tiers

| Tier | Name | Agent Count | Complexity | Primary Use | Example Use Cases | API Endpoint |
| - | - | - | - | - | - | - |
| **Tier 1** | Individual Agents | 1 | Low-Medium | Focused tasks | Content generation, data analysis, Q\&A | `/v1/agent/completions` |
| **Tier 2** | Reasoning Agents | 1-2 (internal) | Medium-High | Complex reasoning | Mathematical proofs, logical validation, research | `/v1/reasoning-agent/completions` |
| **Tier 3** | Multi-Agent Swarms | 1-2,000 | High | Enterprise workflows | Process automation, large-scale systems, R\&D | `/v1/swarm/completions` |

#### Tier 1: Individual Agents

**Single-purpose AI agents for focused tasks**

Individual agents are the foundation of the Swarms ecosystem. These are custom-built, single-purpose AI agents designed to handle specific tasks with high precision and efficiency.

**Key Characteristics**

* **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

**Use Cases**

* 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

**Example Implementation**

```python theme={null}
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-4.1",
        "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

**Advanced reasoning systems for complex problem-solving**

<Note>
  **Premium Tier Required**: The `/v1/reasoning-agent/completions` endpoint is available only on Pro, Ultra, and Premium plans. [Upgrade your account](https://swarms.world/platform/account) to access advanced reasoning capabilities.
</Note>

Reasoning agents leverage sophisticated reasoning techniques to solve complex problems that require deep analysis, multiple perspectives, and systematic thinking. These agents may internally use 1-2 specialized sub-agents to achieve their reasoning goals.

**Key Characteristics**

* **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**: 9 different reasoning agent types available
* **Internal Coordination**: May use sub-agents for specialized reasoning

**Available Reasoning Agent Types**

| Agent Type | Description | Best For |
| - | - | - |
| **reasoning-duo** | Dual-agent system with perspective synthesis | Mathematical problems, logical proofs |
| **self-consistency** | Multiple reasoning paths with validation | Complex logical problems, consistency checking |
| **ire** | Iterative refinement approach | Complex analysis, research problems |
| **ire-agent** | Iterative refinement approach (agent variant) | Complex analysis, research problems |
| **reasoning-agent** | General-purpose systematic reasoning | Step-by-step problem solving |
| **consistency-agent** | Logical consistency and contradiction detection | Argument validation |
| **ReflexionAgent** | Self-reflection and bias detection | Meta-cognitive tasks |
| **GKPAgent** | Cross-domain knowledge synthesis | Interdisciplinary problems |
| **AgentJudge** | Evaluates and judges agent outputs | Quality assessment, evaluation tasks |

**Use Cases**

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

**Example Implementation**

```python theme={null}
payload = {
    "agent_name": "math-reasoner",
    "description": "Mathematical problem solver using dual perspectives",
    "model_name": "claude-sonnet-4-20250514",
    "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

**Large-scale agent systems for complex workflows**

Multi-agent swarms represent the most sophisticated tier, capable of orchestrating up to 2,000 agents (`SwarmSpec.agents`) working together in coordinated workflows. These systems are designed for enterprise-scale applications and complex business processes.

**Key Characteristics**

* **Large Scale**: Up to 2,000 agents per swarm (`SwarmSpec.agents`), with up to 50 execution loops
* **Coordinated Workflows**: Agents work together in structured processes
* **Multiple Swarm Types**: 14 swarm architectures available via the `swarm_type` field
* **Enterprise-Grade**: Built for complex business applications
* **Dynamic Routing**: Intelligent task distribution and agent selection

**Available Swarm Types**

The `swarm_type` field on `POST /v1/swarm/completions` accepts these 14 values. Call `GET /v1/swarms/available` for the live, full metadata (description, category, best-for use cases, and tuning parameters) for each.

| Swarm Type | Description | Best For |
| - | - | - |
| **SequentialWorkflow** | Linear task progression | Process automation, step-by-step workflows |
| **ConcurrentWorkflow** | Parallel task execution | Parallel processing, independent tasks |
| **GroupChat** | Interactive agent discussions | Collaborative problem solving, brainstorming |
| **MixtureOfAgents** | Specialized agent selection | Complex tasks requiring multiple expertise areas |
| **MajorityVoting** | Consensus-based decision making | Decision making, validation tasks |
| **CouncilAsAJudge** | Expert panel with a final judge model (`council_judge_model_name`) | Expert evaluation, quality assessment |
| **AgentRearrange** | Dynamic agent reordering via a flow expression | Adaptive workflows, optimization |
| **MultiAgentRouter** | Intelligent task routing | Large-scale task distribution |
| **HierarchicalSwarm** | A director agent (`director_model_name`) delegates to workers | Complex organizational structures |
| **HeavySwarm** | Question, worker, and synthesis agents | Deep research, comprehensive analysis |
| **LLMCouncil** | Council of models synthesized by a chairman (`chairman_model`) | Multi-model deliberation, synthesis |
| **DebateWithJudge** | Structured debate with a judge | Argument evaluation, contested questions |
| **RoundRobin** | Agents take turns in rotation | Balanced participation, iterative refinement |
| **PlannerWorkerSwarm** | Planner delegates to workers | Task decomposition, project execution |

<Note>
  Grid-style batch execution (many agents across many tasks) and directed-graph orchestration are separate endpoints rather than `swarm_type` values — see `POST /v1/batched-grid-workflow/completions` and `POST /v1/graph-workflow/completions` (both Premium).
</Note>

**Use Cases**

* 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

**Example Implementation**

```python theme={null}
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-4.1",
            "role": "researcher"
        },
        {
            "agent_name": "writer",
            "description": "Create initial content",
            "model_name": "claude-sonnet-4-20250514",
            "role": "writer"
        },
        {
            "agent_name": "editor",
            "description": "Review and improve content",
            "model_name": "gpt-4.1",
            "role": "editor"
        },
        {
            "agent_name": "fact-checker",
            "description": "Verify accuracy and sources",
            "model_name": "claude-sonnet-4-20250514",
            "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

| Aspect | Individual Agents | Reasoning Agents | Multi-Agent Swarms |
| - | - | - | - |
| **Agent Count** | 1 | 1-2 (internal) | 1-2,000 |
| **Complexity** | Low-Medium | Medium-High | High-Extreme |
| **Use Case** | Focused tasks | Complex reasoning | Enterprise workflows |
| **Setup Time** | Minutes | Minutes-Hours | Hours-Days |
| **Resource Usage** | Low | Medium | High |
| **Scalability** | Individual | Limited | Massive |
| **Cost** | Low | Medium | High |
| **Maintenance** | Simple | Moderate | Complex |

### 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

You can combine different tiers for optimal results:

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

Exact latency and throughput depend on the model, prompt size, and `max_loops` you configure, and are not published as fixed numbers. In general, latency and cost scale with the number of agents and loops in a run:

* **Individual Agents**: One model call per loop. The fastest and cheapest tier for a given task.
* **Reasoning Agents**: 1-2 internal model calls per loop, so latency and cost are typically higher than a single agent call.
* **Multi-Agent Swarms**: Latency and cost scale with `number_of_agents` and `max_loops` (up to 2,000 agents and 50 loops).

Every completion charges a token cost plus, for swarms and workflows, a flat \$0.01 per agent (`swarm_completions_agent_cost`). Token rates are unified across agent and swarm completions: \$6.50 per 1M input tokens, \$18.50 per 1M output tokens, with a 50% night-time discount (8 PM - 6 AM Pacific) on the token component for swarm completions. See <a href="/docs/documentation/resources/pricing">Pricing</a> or call `GET /v1/usage/costs` for the full breakdown, and rate-limit tier (free tokens\_per\_agent=200,000 vs premium 2,000,000) at `GET /v1/rate/limits`.

### 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](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](https://cal.com/swarms/swarms-technical-support)
* **Community**: [Join our Discord](https://discord.gg/EamjgSaEQf)
* **Updates**: [Follow us on Twitter](https://twitter.com/swarms_corp)

For enterprise deployments and custom solutions, contact our team for dedicated support and consultation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.