Foundations: Your First Agent

The Swarms API is a hosted platform for building and orchestrating AI agents. You describe an agent (its name, instructions, and model) in JSON, send it a task over HTTPS, and the platform runs it on managed infrastructure. There is nothing to deploy, no GPU to rent, and no framework to install: every capability is an HTTP endpoint.

The platform is organized in three tiers, and this course follows them in order:

• Single agents: one agent, one task. The POST /v1/agent/completions endpoint. This is where Part 1 and Part 2 live.
• Multi-agent swarms: multiple agents collaborating under an orchestration pattern such as SequentialWorkflow, ConcurrentWorkflow, or HierarchicalSwarm. Covered in Part 3.
• Production operations: batch execution, rate limits, cost controls, and observability. Covered in Part 4.

Everything runs against a single base URL:

https://api.swarms.world

Every request is authenticated with an API key. Create one in the Swarms Platform under API Keys at swarms.world/platform/api-keys. Copy the key once it is shown; treat it like a password.

Store the key as an environment variable instead of hardcoding it. Create a .env file in your project:

SWARMS_API_KEY="your-api-key-here"

Then install the two libraries used throughout this course:

pip install requests python-dotenv

Before running any agent, confirm that your key and connection work. The health endpoint is free and requires no body:

import os
import requests
from dotenv import load_dotenv

load_dotenv()

BASE_URL = "https://api.swarms.world"
headers = {
    "x-api-key": os.getenv("SWARMS_API_KEY"),
    "Content-Type": "application/json",
}

response = requests.get(f"{BASE_URL}/health", headers=headers)
print(response.status_code)  # 200
print(response.json())

A 200 response means you are authenticated and the service is operational. If you get 401, your key is missing or wrong; check that load_dotenv() ran and that the variable name matches your .env file.

You can run this request right here. Paste your API key below (it is stored only in your browser and sent only to api.swarms.world), and every other trial in this course will reuse it:

An agent is defined by an agent_config object (the AgentSpec schema). It tells the platform who the agent is, how it should behave, and which model to run. These are the fields you will use in almost every request:

The system_prompt is the most important field. Be specific about the agent's expertise, the shape of the output you expect, and what it should refuse to guess at. A precise prompt outperforms a clever one.

Now put it together. An agent completion request has two parts: the agent_config describing the agent, and a task string describing the work:

import os
import requests
from dotenv import load_dotenv

load_dotenv()

BASE_URL = "https://api.swarms.world"
headers = {
    "x-api-key": os.getenv("SWARMS_API_KEY"),
    "Content-Type": "application/json",
}

payload = {
    "agent_config": {
        "agent_name": "Research Analyst",
        "description": "Analyzes topics and produces structured summaries",
        "system_prompt": (
            "You are a research analyst. Analyze the given topic, "
            "identify the three most important trends, and present "
            "them as a numbered list with one supporting fact each."
        ),
        "model_name": "claude-sonnet-4-20250514",
        "max_loops": 1,
        "max_tokens": 4096,
        "temperature": 0.7,
    },
    "task": "What are the key trends in renewable energy adoption?",
}

response = requests.post(
    f"{BASE_URL}/v1/agent/completions", headers=headers, json=payload
)
result = response.json()
print(result["outputs"])
print(result["usage"])

The response contains the agent's output plus metadata you should get in the habit of reading:

• id: unique identifier for this completion, useful when correlating logs
• outputs: the agent's answer, including the conversation structure
• usage: token counts for the request; this is what you are billed on
• name: the agent name you configured, echoed back

Run a real agent completion now. The body below is editable: change the task, the system prompt, or the temperature and watch the output change.

Two read-only endpoints round out the foundations. First, list every model you can pass as model_name:

response = requests.get(
    f"{BASE_URL}/v1/models/available", headers=headers
)
print(response.json())

Second, check your credit balance. Completions consume credits based on token usage, so this is the number to watch while you learn:

response = requests.get(
    f"{BASE_URL}/v1/account/credits", headers=headers
)
print(response.json())  # regular, free, and referral credits

Production habits start on day one, so learn to read the whole response now. A successful agent completion contains more than the answer:

Failures arrive as HTTP status codes, and each one tells you something different:

response = requests.post(
    f"{BASE_URL}/v1/agent/completions", headers=headers, json=payload
)

if response.status_code == 200:
    result = response.json()
    print(result["outputs"])
elif response.status_code == 401:
    raise SystemExit("Check your SWARMS_API_KEY.")
elif response.status_code == 402:
    raise SystemExit("Out of credits: top up at swarms.world.")
else:
    print(response.status_code, response.text)