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

What This Example Shows

Creating a single agent with specific expertise
Configuring agent parameters (model, temperature, tokens)
Running agents with structured tasks
Handling agent responses and outputs

Single agents are the building blocks of the Swarms API. Each agent can be configured with specific models, temperatures, and expertise areas.

Quick Start

Python
JavaScript
cURL

import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv
import json

# Load environment variables
load_dotenv()

# Initialize the client
client = SwarmsClient(
api_key=os.getenv("SWARMS_API_KEY"),
)

# Create and run a single agent
result = client.agent.run(
agent_config={
    "agent_name": "Bloodwork Diagnosis Expert",
    "description": "An expert doctor specializing in interpreting and diagnosing blood work results.",
    "system_prompt": (
        "You are an expert medical doctor specializing in the interpretation and diagnosis of blood work. "
        "Your expertise includes analyzing laboratory results, identifying abnormal values, "
        "explaining their clinical significance, and recommending next diagnostic or treatment steps. "
        "Provide clear, evidence-based explanations and consider differential diagnoses based on blood test findings."
    ),
    "model_name": "gpt-4.1",
    "max_loops": 1,
    "max_tokens": 1000,
    "temperature": 0.5,
},
task=(
    "A patient presents with the following blood work results: "
    "Hemoglobin: 10.2 g/dL (low), WBC: 13,000 /µL (high), Platelets: 180,000 /µL (normal), "
    "ALT: 65 U/L (high), AST: 70 U/L (high). "
    "Please provide a detailed interpretation, possible diagnoses, and recommended next steps."
),
)

print(json.dumps(result, indent=4))

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 payload = {
    agent_config: {
        agent_name: "Bloodwork Diagnosis Expert",
        description: "An expert doctor specializing in interpreting and diagnosing blood work results.",
        system_prompt: "You are an expert medical doctor specializing in the interpretation and diagnosis of blood work. Your expertise includes analyzing laboratory results, identifying abnormal values, explaining their clinical significance, and recommending next diagnostic or treatment steps.",
        model_name: "gpt-4.1",
        max_loops: 1,
        max_tokens: 1000,
        temperature: 0.5
    },
    task: "A patient presents with the following blood work results: Hemoglobin: 10.2 g/dL (low), WBC: 13,000 /µL (high), Platelets: 180,000 /µL (normal), ALT: 65 U/L (high), AST: 70 U/L (high). Please provide a detailed interpretation, possible diagnoses, and recommended next steps."
};

fetch(`${BASE_URL}/v1/agent/completions`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(payload)
})
.then(response => response.json())
.then(data => {
    console.log("Agent Result:", JSON.stringify(data, null, 2));
})
.catch(error => console.error('Error:', error));

curl -X POST "https://api.swarms.world/v1/agent/completions" \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "Bloodwork Diagnosis Expert",
      "description": "An expert doctor specializing in interpreting and diagnosing blood work results.",
      "system_prompt": "You are an expert medical doctor specializing in blood work interpretation.",
      "model_name": "gpt-4.1",
      "max_loops": 1,
      "max_tokens": 1000,
      "temperature": 0.5
    },
    "task": "A patient presents with blood work results: Hemoglobin 10.2 (low), WBC 13,000 (high), Platelets 180,000 (normal), ALT 65 (high), AST 70 (high). Please interpret and suggest diagnoses."
  }'

Agent Configuration Explained

agent_name: A descriptive name for your agent
description: What the agent does
system_prompt: The agent’s expertise and behavior instructions
model_name: The AI model to use (supports OpenAI, Anthropic, Groq, and more)
max_loops: Maximum reasoning iterations (1 for single-pass tasks)
max_tokens: Maximum response length
temperature: Creativity level (0.0 = focused, 1.0 = creative)

Expected Output

The agent will provide a structured medical analysis including:

Interpretation of each blood value
Possible diagnoses based on the results
Recommended next steps for the patient
Clinical context and significance

Environment Setup

Create a .env file in your project directory:

SWARMS_API_KEY=your_api_key_here

Customization Ideas

You can adapt this pattern for:

Legal Analysis: Contract review agents
Code Review: Software quality assurance agents
Content Creation: Writing and editing agents
Data Analysis: Business intelligence agents
Customer Support: FAQ and troubleshooting agents

Next Steps

After mastering single agents, explore:

Multi-agent swarms for complex workflows
Batch processing for multiple tasks
Agent chaining for sequential reasoning

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

Single Agent Overview

What This Example Shows

Quick Start

Agent Configuration Explained

Expected Output

Environment Setup

Customization Ideas

Next Steps

​What This Example Shows

​Quick Start

​Agent Configuration Explained

​Expected Output

​Environment Setup

​Customization Ideas

​Next Steps

What This Example Shows

Quick Start

Agent Configuration Explained

Expected Output

Environment Setup

Customization Ideas

Next Steps