Swarms API Documentation - Build AI Agents & Multi-Agent Systems

Discover the different types of reasoning agents available in the Swarms API. The /v1/reasoning-agent/types endpoint provides information about specialized reasoning architectures designed for different problem-solving approaches.

Premium Tier Required: The /v1/reasoning-agent/completions endpoint is restricted to Pro, Ultra, and Premium plan subscribers. Free tier users will receive a 403 error. Upgrade your account to access advanced reasoning capabilities.

Reasoning agents use advanced techniques like self-consistency, majority voting, and iterative refinement to improve answer quality and reliability.

Quick Start

Python
JavaScript
cURL

import requests
import json
import os
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"
}

def get_reasoning_agent_types():
    """Get all available reasoning agent types"""
    response = requests.get(
        f"{BASE_URL}/v1/reasoning-agent/types",
        headers=headers
    )

    if response.status_code == 200:
        return response.json()
    else:
        print(f"Error: {response.status_code} - {response.text}")
        return None

# Get reasoning agent types
reasoning_data = get_reasoning_agent_types()
if reasoning_data:
    print("✅ Reasoning agent types retrieved successfully!")
    print(json.dumps(reasoning_data, indent=2))

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"
};

async function getReasoningAgentTypes() {
    try {
        const response = await fetch(`${BASE_URL}/v1/reasoning-agent/types`, {
            method: 'GET',
            headers: headers
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        const data = await response.json();
        console.log("✅ Reasoning agent types retrieved successfully!");
        console.log(JSON.stringify(data, null, 2));
        return data;
    } catch (error) {
        console.error('Error:', error);
        return null;
    }
}

// Get reasoning agent types
getReasoningAgentTypes();

# Get reasoning agent types
curl -X GET "https://api.swarms.world/v1/reasoning-agent/types" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json"

# Example response:
# {
#   "status": "success",
#   "agent_types": [
#     "reasoning-duo",
#     "self-consistency",
#     "ire",
#     "reasoning-agent",
#     "consistency-agent",
#     "ire-agent",
#     "ReflexionAgent",
#     "GKPAgent",
#     "AgentJudge"
#   ]
# }

Reasoning Agent Type Comparison

The /v1/reasoning-agent/types endpoint currently returns 9 reasoning agent types:

Type	Description	Best For	Samples	Quality Focus
reasoning-agent	Basic reasoning with structured thinking	Simple reasoning tasks	1	Balanced
reasoning-duo	Two agents with different approaches	Comparative analysis	2	Diversity
self-consistency	Multiple samples for consistency checking	High-stakes decisions	3-5	Consistency
ire / ire-agent	Iterative refinement through multiple passes	Complex problem-solving	Variable	Accuracy
consistency-agent	Focus on logical consistency	Mathematical/logical problems	3	Logical rigor
ReflexionAgent	Self-critiques and revises its own output across iterations	Tasks that benefit from self-correction	Variable	Self-improvement
GKPAgent	Generated Knowledge Prompting — generates supporting knowledge before answering	Knowledge-intensive tasks	Variable	Grounding
AgentJudge	Evaluates and scores candidate outputs	Output evaluation / grading	Variable	Evaluation

Request Parameters

Send these fields in the JSON body of POST /v1/reasoning-agent/completions (the ReasoningAgentSpec schema):

Parameter	Type	Default	Description
`agent_name`	`string`	`"reasoning-agent"`	The unique name assigned to the reasoning agent
`description`	`string`	`"A reasoning agent that can answer questions and help with tasks."`	A detailed explanation of the reasoning agent’s purpose and capabilities
`model_name`	`string`	`"claude-sonnet-4-20250514"`	The name of the AI model that the reasoning agent will utilize
`system_prompt`	`string`	`None`	The initial instruction or context provided to the reasoning agent
`max_loops`	`integer`	`1`	Maximum number of times the agent repeats its task (ignored for `ire` / `ire-agent`, which manage iteration internally)
`swarm_type`	`string`	`"reasoning_duo"`	The reasoning agent type — pass one of the 9 values listed above
`num_samples`	`integer`	`1`	The number of samples to generate for the reasoning agent
`output_type`	`string`	`"dict-all-except-first"`	Accepted for schema compatibility but ignored by the server — responses are always returned in `dict-all-except-first` format
`num_knowledge_items`	`integer`	`None`	The number of knowledge items to use for the reasoning agent
`memory_capacity`	`integer`	`None`	The memory capacity for the reasoning agent
`task`	`string`	`None`	The task to be completed by the reasoning agent

The schema default for swarm_type is the underscore spelling "reasoning_duo", which is not itself one of the 9 accepted values — the enum only contains the hyphenated "reasoning-duo". If you set swarm_type explicitly, use one of the 9 hyphenated/listed values above; the underscore form is rejected.

Response Format

POST /v1/reasoning-agent/completions returns a ReasoningAgentCompletionOutput object:

Field	Type	Description
`job_id`	`string`	Unique identifier for the reasoning agent run
`status`	`string`	Status of the run, `"success"` on completion
`outputs`	`any`	The output generated by the reasoning agent — shape varies by reasoning type
`timestamp`	`string`	ISO-formatted timestamp of when the run was executed
`agent_name`	`string`	Name of the agent
`agent_type`	`string`	Type of the agent (the `swarm_type` used)
`agent_id`	`string`	Unique identifier for the agent instance
`usage`	`object`	Token usage: `input_tokens`, `output_tokens`, `total_tokens`

Usage Examples

Basic Reasoning Agent
Self-Consistency Agent
Iterative Refinement Agent
Reasoning Duo

payload = {
    "agent_name": "Basic Reasoner",
    "model_name": "gpt-4.1",
    "system_prompt": "You are a logical reasoning assistant.",
    "max_loops": 1,
    "swarm_type": "reasoning-agent",
    "num_samples": 1,
    "task": "Solve this logic puzzle: If all bloops are razzes and some razzes are fizzles, are all bloops fizzles?"
}

payload = {
    "agent_name": "Consistent Reasoner",
    "model_name": "gpt-4.1",
    "system_prompt": "You are a reasoning agent that values consistency.",
    "max_loops": 1,
    "swarm_type": "self-consistency",
    "num_samples": 3,
    "task": "Determine the most logical conclusion from these premises: All humans are mortal. Socrates is human. Therefore..."
}

payload = {
    "agent_name": "Refinement Agent",
    "model_name": "gpt-4.1",
    "system_prompt": "You are an agent that improves through iteration.",
    "swarm_type": "ire",  # manages its refinement iterations internally; max_loops is ignored
    "num_samples": 2,
    "task": "Design a more efficient algorithm for sorting a list of numbers."
}

payload = {
    "agent_name": "Dual Reasoner",
    "model_name": "gpt-4.1",
    "system_prompt": "You are a dual reasoning system.",
    "max_loops": 1,
    "swarm_type": "reasoning-duo",
    "num_samples": 2,
    "task": "Debate the pros and cons of renewable energy adoption."
}

Advanced Configuration

Custom Sample Count
Multi-Iteration Reasoning
Knowledge Integration

payload = {
    "agent_name": "High Consistency Agent",
    "model_name": "gpt-4.1",
    "max_loops": 1,
    "swarm_type": "self-consistency",
    "num_samples": 5,  # Higher sample count for better consistency
    "task": "Analyze the potential risks of artificial general intelligence."
}

payload = {
    "agent_name": "Deep Analysis Agent",
    "model_name": "gpt-4.1",
    "max_loops": 5,  # Multiple refinement iterations
    "swarm_type": "ReflexionAgent",
    "num_samples": 3,
    "task": "Develop a comprehensive business strategy for a tech startup."
}

payload = {
    "agent_name": "Knowledge Agent",
    "model_name": "gpt-4.1",
    "max_loops": 1,
    "swarm_type": "consistency-agent",
    "num_samples": 3,
    "num_knowledge_items": 5,  # Include knowledge base
    "memory_capacity": 10,
    "task": "Integrate these research findings into a coherent theory."
}

Output Format

The output_type request field is accepted by the schema but ignored by the server — the reasoning agent always runs with dict-all-except-first, which returns every reasoning step after the initial prompt as role/content entries in the outputs field. Passing "dict", "list", or "final" validates but has no effect on the response.

result = response.json()

# outputs is a list of role/content entries for most reasoning types
outputs = result["outputs"]
if isinstance(outputs, list):
    for entry in outputs:
        print(f"{entry.get('role', '')}: {entry.get('content', '')}")
else:
    # Some types (e.g. AgentJudge) return a plain string
    print(outputs)

Performance Optimization

Quality vs Speed
Cost Optimization

def optimize_reasoning_config(task_complexity, time_constraint):
    """Optimize reasoning configuration based on requirements"""

    if time_constraint == "fast":
        return {
            "swarm_type": "reasoning-agent",
            "num_samples": 1,
            "max_loops": 1,
            "model_name": "gpt-4.1-mini"
        }
    elif task_complexity == "high":
        return {
            "swarm_type": "ReflexionAgent",
            "num_samples": 5,
            "max_loops": 3,
            "model_name": "gpt-4.1"
        }
    else:  # balanced
        return {
            "swarm_type": "self-consistency",
            "num_samples": 3,
            "max_loops": 1,
            "model_name": "gpt-4.1"
        }

def optimize_reasoning_cost(budget, quality_requirement):
    """Optimize for cost while maintaining quality"""

    if budget < 0.1:
        return {
            "swarm_type": "reasoning-agent",
            "model_name": "gpt-4.1-mini",
            "num_samples": 1
        }
    elif quality_requirement == "high":
        return {
            "swarm_type": "self-consistency",
            "model_name": "gpt-4.1",
            "num_samples": 3
        }
    else:
        return {
            "swarm_type": "reasoning-duo",
            "model_name": "gpt-4.1-mini",
            "num_samples": 2
        }

Use Cases by Domain

Scientific Research
Business Strategy
Legal Analysis
Technical Problem Solving

payload = {
    "agent_name": "Scientific Reasoner",
    "swarm_type": "ire",
    "num_samples": 3,
    "task": "Design an experiment to test the hypothesis that X causes Y."
}

payload = {
    "agent_name": "Strategy Consultant",
    "swarm_type": "reasoning-duo",
    "num_samples": 2,
    "task": "Evaluate three potential market entry strategies for our product."
}

payload = {
    "agent_name": "Legal Analyst",
    "swarm_type": "self-consistency",
    "num_samples": 5,
    "task": "Analyze the legal implications of this contract clause."
}

payload = {
    "agent_name": "Technical Expert",
    "swarm_type": "consistency-agent",
    "num_samples": 3,
    "task": "Debug this software issue and propose a solution."
}

Best Practices

Configuration Guidelines

Task Complexity: Match reasoning type to task complexity
Sample Count: Use more samples for high-stakes decisions
Iteration Count: Increase iterations for complex refinement
Model Selection: Choose appropriate model based on requirements

Quality Assurance

Consistency Checking: Use self-consistency for critical decisions
Diverse Perspectives: Leverage reasoning-duo for balanced analysis
Iterative Improvement: Apply IRE for complex problem-solving
Validation: Always validate reasoning outputs

Performance Considerations

Resource Usage: Monitor token usage and costs
Response Time: Balance quality with response speed
Scalability: Consider parallel processing for multiple tasks
Caching: Cache reasoning results when appropriate

Error Handling

Fallback Logic: Implement fallback to simpler reasoning types
Timeout Handling: Set appropriate timeouts for long-running tasks
Result Validation: Validate reasoning outputs for correctness
Logging: Log reasoning processes for debugging

Getting Started

Agent Capabilities

Multi-Agent Architectures

Finance & Investing

Healthcare & Life Sciences

Legal, M&A & Diligence

Customer Operations

Defense, Gov & Supply Chain

Marketing, Content & Founder Tools

API Utilities

Migration Guides

Resources

Production

Compatibility & Benchmarks

Tutorials & Integrations

Reasoning Agent Types

Quick Start

Reasoning Agent Type Comparison

Request Parameters

Response Format

Usage Examples

Advanced Configuration

Output Format

Performance Optimization

Use Cases by Domain

Best Practices

Configuration Guidelines

Quality Assurance

Performance Considerations

Error Handling

​Quick Start

​Reasoning Agent Type Comparison

​Request Parameters

​Response Format

​Usage Examples

​Advanced Configuration

​Output Format

​Performance Optimization

​Use Cases by Domain

​Best Practices

​Configuration Guidelines

​Quality Assurance

​Performance Considerations

​Error Handling

Quick Start

Reasoning Agent Type Comparison

Request Parameters

Response Format

Usage Examples

Advanced Configuration

Output Format

Performance Optimization

Use Cases by Domain

Best Practices

Configuration Guidelines

Quality Assurance

Performance Considerations

Error Handling