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

What This Example Shows

Both edge syntaxes the Graph Workflow endpoint actually accepts — and the list/tuple forms it rejects
Side-by-side examples where each format produces the same three-agent DAG
How to express multi-target (fan-out) edges and conditional gating
A summary table for picking the right format for the job
One end-to-end runnable workflow that mixes formats in a single edges array

The Graph Workflow endpoint (POST /v1/graph-workflow/completions) is a premium-only feature available on Pro, Ultra, and Premium plans. Free-tier keys receive a 403. Upgrade your account to run production DAGs.

Why This Matters

Most teams adopt Graph Workflow with one edge format in mind — usually the dict form {"source": "A", "target": "B"} — then run into friction when their DAG grows or when ops needs to tag specific edges. The API accepts two interchangeable formats: the plain dict form and the dict form with a metadata block. List and tuple shorthands like ["A", "B"] are rejected by request validation before the workflow runs. This reference walks each accepted format end to end against the same target DAG so you can see the trade-offs in one place, and shows how to compose multi-target fan-outs and prompt-level conditional gating without inventing a syntax the API doesn’t actually support.

Step 1: Setup

Install dependencies and load your API key.

pip install requests python-dotenv

import os

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

Step 2: Define the Shared Agent Pool

Every example below reuses the same three-agent pool so only the edges change between formats.

agents = [
    {
        "agent_name": "Agent1",
        "description": "First agent in the workflow",
        "system_prompt": "You are Agent 1. Process the initial task.",
        "model_name": "gpt-4.1",
        "max_tokens": 4000,
        "temperature": 0.3,
        "max_loops": 1,
    },
    {
        "agent_name": "Agent2",
        "description": "Second agent in the workflow",
        "system_prompt": "You are Agent 2. Process data from Agent 1.",
        "model_name": "gpt-4.1",
        "max_tokens": 4000,
        "temperature": 0.3,
        "max_loops": 1,
    },
    {
        "agent_name": "Agent3",
        "description": "Third agent in the workflow",
        "system_prompt": "You are Agent 3. Process data from Agent 2.",
        "model_name": "gpt-4.1",
        "max_tokens": 4000,
        "temperature": 0.3,
        "max_loops": 1,
    },
]

The baseline target DAG for both formats is the same linear pipeline:

[Agent1] --> [Agent2] --> [Agent3]

Step 3: Format 1 — Dict Form

The canonical and most common format. Each edge is a dictionary with explicit source and target keys. Verbose but extremely readable in code reviews — most production codebases standardize on this.

edges_dict = [
    {"source": "Agent1", "target": "Agent2"},
    {"source": "Agent2", "target": "Agent3"},
]

workflow_input = {
    "name": "Edge-Format-1-Dict",
    "description": "Linear pipeline declared with explicit dict edges.",
    "agents": agents,
    "edges": edges_dict,
    "entry_points": ["Agent1"],
    "end_points": ["Agent3"],
    "max_loops": 1,
    "task": "Process a simple task through a three-agent pipeline.",
    "auto_compile": True,
    "verbose": False,
}

response = requests.post(
    f"{BASE_URL}/v1/graph-workflow/completions",
    headers=headers,
    json=workflow_input,
    timeout=300,
)
response.raise_for_status()
print(response.json().get("status"))

Step 4: Format 2 — Dict with Metadata

The dict form plus an optional metadata field — a free-form dictionary you can attach to any edge for routing hints, priority labels, telemetry tags, retry policies, or downstream business rules. The metadata travels with the edge through the compiler.

edges_dict_metadata = [
    {
        "source": "Agent1",
        "target": "Agent2",
        "metadata": {
            "priority": "high",
            "data_type": "processed_data",
        },
    },
    {
        "source": "Agent2",
        "target": "Agent3",
        "metadata": {
            "priority": "high",
            "data_type": "processed_data",
            "audit_tag": "regulated",
        },
    },
]

workflow_input = {
    "name": "Edge-Format-2-Dict-Metadata",
    "description": "Linear pipeline with metadata attached to every edge.",
    "agents": agents,
    "edges": edges_dict_metadata,
    "entry_points": ["Agent1"],
    "end_points": ["Agent3"],
    "max_loops": 1,
    "task": "Process a simple task through a three-agent pipeline with edge metadata.",
    "auto_compile": True,
    "verbose": False,
}

response = requests.post(
    f"{BASE_URL}/v1/graph-workflow/completions",
    headers=headers,
    json=workflow_input,
    timeout=300,
)
response.raise_for_status()
print(response.json().get("status"))

Metadata keys are unconstrained — use whatever your ops or audit tooling expects. Common patterns: priority, retry_on_failure, audit_tag, data_type, timeout, cost_center. See Tagging Graph Workflow Edges with Metadata for the full production playbook.

Step 5: List and Tuple Edges Are Rejected

Each edge in the request schema must be an object (an EdgeSpec or a dictionary with source and target keys). Terse list shorthands — [source, target] or [source, target, metadata], and their Python tuple equivalents — fail request validation with a 422 Unprocessable Entity before the workflow ever runs.

# These payloads are REJECTED with a 422 validation error:
edges_list = [
    ["Agent1", "Agent2"],
    ["Agent2", "Agent3"],
]
edges_list_metadata = [
    ["Agent1", "Agent2", {"priority": "high", "data_type": "processed_data"}],
    ["Agent2", "Agent3", {"priority": "high", "audit_tag": "regulated"}],
]

# The accepted equivalents:
edges = [
    {"source": "Agent1", "target": "Agent2"},
    {"source": "Agent2", "target": "Agent3", "metadata": {"audit_tag": "regulated"}},
]

If you prefer writing arrow-like pairs in your own code, keep them as local shorthand and convert before submission:

pairs = [("Agent1", "Agent2"), ("Agent2", "Agent3")]
edges = [{"source": s, "target": t} for s, t in pairs]

Step 6: Multi-Target (Fan-Out) Edges

There is no dedicated multi-target syntax in the API — you express a fan-out by writing one edge per downstream target, all sharing the same source. The compiler builds the parallel branches and runs them concurrently. This is the same expressive power as a hypothetical "A -> [B, C]" shorthand, just stated explicitly.

# Agent1 fans out to Agent2 and Agent3 in parallel.
edges_fanout = [
    {"source": "Agent1", "target": "Agent2"},
    {"source": "Agent1", "target": "Agent3"},
]

workflow_input = {
    "name": "Edge-Format-Fan-Out",
    "description": "Fan-out from one source to two parallel downstream targets.",
    "agents": agents,
    "edges": edges_fanout,
    "entry_points": ["Agent1"],
    "end_points": ["Agent2", "Agent3"],
    "max_loops": 1,
    "task": "Send the same input to two downstream agents in parallel.",
    "auto_compile": True,
    "verbose": False,
}

response = requests.post(
    f"{BASE_URL}/v1/graph-workflow/completions",
    headers=headers,
    json=workflow_input,
    timeout=300,
)
response.raise_for_status()
print(response.json().get("status"))

The same trick scales — N edges with the same source produce an N-way fan-out, and N edges with the same target produce an N-way fan-in. The full DAG is just a list of pairwise edges; structure emerges from the edge set.

Step 7: Conditional Edges via Prompt-Level Gating

The Graph Workflow endpoint does not expose a schema-level condition field on edges — every declared edge fires when its upstream node completes. To implement a conditional path, encode the gate in the downstream node’s prompt:

gated_agents = [
    {
        "agent_name": "Triage",
        "description": "Decides whether to escalate or pass through.",
        "system_prompt": (
            "You are a triage agent. Inspect the input and output exactly one "
            "token at the end of your response: `ESCALATE` if the situation "
            "warrants escalation, otherwise `PASS`. Be conservative — only "
            "escalate on clear signals."
        ),
        "model_name": "gpt-4.1",
        "max_tokens": 1500,
        "temperature": 0.1,
        "max_loops": 1,
    },
    {
        "agent_name": "HumanEscalation",
        "description": "Drafts an escalation note for a human operator.",
        "system_prompt": (
            "You receive an upstream Triage agent's output. If the upstream "
            "output ends with `PASS`, respond with the single token `SKIPPED` "
            "and stop. If it ends with `ESCALATE`, draft a 3-bullet escalation "
            "note for a human operator."
        ),
        "model_name": "gpt-4.1",
        "max_tokens": 1500,
        "temperature": 0.2,
        "max_loops": 1,
    },
]

gated_edges = [
    {"source": "Triage", "target": "HumanEscalation"},
]

The HumanEscalation node runs every time, but produces a SKIPPED no-op when the upstream emits PASS. Downstream consumers (or a final synthesis node) check for SKIPPED and ignore the branch. See Graph Workflows for Production Pipelines for the full SKIP-gating pattern in a real DAG.

Step 8: Mix Formats in One Workflow

The API accepts heterogeneous edges in the same edges array. Sketch the trunk of the graph with plain dict edges and add a metadata block only on the edges ops actually cares about.

edges_mixed = [
    {"source": "Agent1", "target": "Agent2"},  # plain dict for a routine link
    {
        "source": "Agent2",
        "target": "Agent3",
        "metadata": {
            "audit_tag": "regulatory",
            "priority": "high",
        },
    },  # dict-with-metadata for the regulated step
]

workflow_input = {
    "name": "Edge-Format-Mixed",
    "description": "Mixed-format edges in a single workflow.",
    "agents": agents,
    "edges": edges_mixed,
    "entry_points": ["Agent1"],
    "end_points": ["Agent3"],
    "max_loops": 1,
    "task": "Process a simple task through a three-agent pipeline.",
    "auto_compile": True,
    "verbose": False,
}

response = requests.post(
    f"{BASE_URL}/v1/graph-workflow/completions",
    headers=headers,
    json=workflow_input,
    timeout=300,
)
response.raise_for_status()
print(response.json().get("status"))

Step 9: Read the Per-Node Output

Regardless of which edge format you submit, the response shape is identical. Outputs are keyed by agent_name.

result = response.json()

outputs = result.get("outputs", {})
for name in ["Agent1", "Agent2", "Agent3"]:
    if name in outputs:
        print(f"\n[{name}]")
        print(str(outputs[name])[:300])

usage = result.get("usage", {})
print(f"\nTotal cost: ${usage.get('total_cost', 0):.4f}")
print(f"Total tokens: {usage.get('total_tokens', 0)}")

Choosing the Right Format

Format	Best for	Pros	Cons
Dict form `{"source": ..., "target": ...}`	Most production codebases	Explicit, lints cleanly, easy to refactor	Verbose for large graphs
Dict with metadata	Edges that need routing hints, audit labels, or retry policy	Carries ops and business context with the edge	Most verbose; only worth it when you consume the metadata
List/tuple forms `[source, target]`	Not accepted — rejected with a 422	—	Convert to dict form before submission
Multi-target fan-out	One upstream feeding many parallel downstreams	Pure composition — no new syntax	Verbose for very wide fan-outs
Conditional gating	Skipping branches based on upstream signal	No new syntax; pure prompt engineering	Downstream node still consumes tokens to emit `SKIPPED`

A common production convention: use the plain dict form everywhere, and add a metadata block only on edges that participate in audit, retry, or routing logic.

Common Pitfalls

422 error: edge fails request validation

The API expects each edge to be an object — an EdgeSpec or a dict with source and target keys. List/tuple shorthands like ["Agent1", "Agent2"] and strings like "Agent1 -> Agent2" are rejected with a 422 before the workflow runs. Convert them to the dict form.

400 error: source node '...' does not exist

Every edge’s source and target must match an agent_name in the agents array exactly. Watch for whitespace, casing, and trailing punctuation — the comparison is exact.

A downstream node never runs

Check that the downstream node appears as the target of at least one edge whose source actually executes. A node with no incoming edge and no entry in entry_points will never fire.

Next Steps

Tagging Graph Workflow Edges with Metadata — production patterns for routing hints, telemetry tags, and audit labels
Graph Workflows for Production Pipelines — a fan-out/fan-in SDR enrichment DAG using the dict form end to end
Graph Workflow Example — additional DAG shapes including localization and code review

Getting Started

MCP Server Tutorials

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

Graph Workflow Edge Formats Reference

What This Example Shows

Why This Matters

Step 1: Setup

Step 2: Define the Shared Agent Pool

Step 3: Format 1 — Dict Form

Step 4: Format 2 — Dict with Metadata

Step 5: List and Tuple Edges Are Rejected

Step 6: Multi-Target (Fan-Out) Edges

Step 7: Conditional Edges via Prompt-Level Gating

Step 8: Mix Formats in One Workflow

Step 9: Read the Per-Node Output

Choosing the Right Format

Common Pitfalls

Next Steps

​What This Example Shows

​Why This Matters

​Step 1: Setup

​Step 2: Define the Shared Agent Pool

​Step 3: Format 1 — Dict Form

​Step 4: Format 2 — Dict with Metadata

​Step 5: List and Tuple Edges Are Rejected

​Step 6: Multi-Target (Fan-Out) Edges

​Step 7: Conditional Edges via Prompt-Level Gating

​Step 8: Mix Formats in One Workflow

​Step 9: Read the Per-Node Output

​Choosing the Right Format

​Common Pitfalls

​Next Steps

What This Example Shows

Why This Matters

Step 1: Setup

Step 2: Define the Shared Agent Pool

Step 3: Format 1 — Dict Form

Step 4: Format 2 — Dict with Metadata

Step 5: List and Tuple Edges Are Rejected

Step 6: Multi-Target (Fan-Out) Edges

Step 7: Conditional Edges via Prompt-Level Gating

Step 8: Mix Formats in One Workflow

Step 9: Read the Per-Node Output

Choosing the Right Format

Common Pitfalls

Next Steps