Skip to main content

​
What This Example Shows

  • How to call POST /v1/agents/auto-generate with just a task string
  • The shape of the returned agent_config and how to feed it directly into /v1/agent/completions
  • A two-step prototype loop: generate config → run task — no manual prompt engineering
  • The distinction between /v1/agents/auto-generate (single agent) and /v1/auto-swarm-builder/completions (full multi-agent swarm)
/v1/agents/auto-generate is the fastest way to bootstrap a single agent from a task description. You hand it a goal in English, and it returns the agent_name, description, system_prompt, and recommended model_name — everything you need to call /v1/agent/completions.

​
Why This Matters

The slowest part of building an agent isn’t writing code — it’s writing the system prompt. A good system prompt is two to four paragraphs of role, expertise, output format, and constraints, and getting it right is the difference between a useful agent and a generic one. /v1/agents/auto-generate collapses that authoring step into a single API call so you can prototype in minutes: type the task you want done, get a tuned config back, run it, iterate. It exists for exploration and scaffolding — once a config performs the way you want, you copy it into version control and stop calling the endpoint at runtime.

​
Step 1: Setup

import json
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: Generate an Agent Config from a Task Description

The endpoint takes a single field: task. Describe what you want the agent to do, and the service returns a full agent specification. 
def auto_generate_agent(task: str) -> dict:
    payload = {"task": task}
    response = requests.post(
        f"{BASE_URL}/v1/agents/auto-generate",
        headers=headers,
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()


generated = auto_generate_agent(
    task=(
        "Create a comprehensive market analysis report for AI companies, "
        "including financial metrics, growth potential, and competitive analysis."
    )
)

print(json.dumps(generated, indent=2))
You’ll get back something shaped like this — an agent_config with the system prompt, name, description, and model already populated: 
{
    "agent_config": {
        "agent_name": "AI Market Analyst",
        "description": "Synthesizes financial, growth, and competitive data on AI companies.",
        "system_prompt": "You are a senior equity research analyst covering the AI sector...",
        "model_name": "gpt-4.1",
        "max_loops": 1,
        "max_tokens": 8192,
        "temperature": 0.3
    }
}
The exact field set in the response may evolve over time. Always inspect what the endpoint returns before piping it forward — at minimum you’ll get agent_name, description, system_prompt, and model_name.

​
Step 3: Pipe the Generated Config Straight into /v1/agent/completions

The point of the endpoint is that its output is the input shape /v1/agent/completions already expects. No translation needed. 
def run_generated_agent(generated: dict, task: str) -> dict:
    # Pull out the agent_config the auto-generate endpoint produced.
    agent_config = generated.get("agent_config") or generated

    payload = {
        "agent_config": agent_config,
        "task": task,
    }

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


result = run_generated_agent(
    generated=generated,
    task="Produce a one-page memo on NVIDIA's Q4 outlook vs. AMD.",
)

print(json.dumps(result, indent=2))
That’s the full loop: one call to author the agent, one call to use it. Once you’re happy with the config, save it to your codebase and skip the first call going forward.

​
Step 4: Iterate by Re-Generating with a Sharper Task

If the first config isn’t quite right, the fastest fix is usually to make the task description more specific and re-generate, rather than hand-editing the system prompt. 
# First attempt — too vague, system prompt comes out generic.
v1 = auto_generate_agent(task="Analyze SEC filings.")

# Second attempt — concrete role, concrete output, concrete audience.
v2 = auto_generate_agent(
    task=(
        "Read 10-K filings for mid-cap SaaS companies and produce a 5-bullet "
        "risk summary aimed at a long/short hedge fund analyst. Cite section "
        "numbers and dollar figures. Skip boilerplate disclosures."
    )
)
The richer the task description, the more useful the generated system_prompt.

​
/v1/agents/auto-generate vs. /v1/auto-swarm-builder/completions

These two endpoints sound similar — they are not. Pick by how many agents you need.
/v1/agents/auto-generate/v1/auto-swarm-builder/completions
ReturnsA single agent_configA full multi-agent swarm + (optionally) executes it
Use whenYou need one specialist for one taskThe task needs a team — multiple roles, a workflow, a coordinator
Output shapeOne agent spec — paste into /v1/agent/completionsA list of agent specs plus a swarm_type and flow — runs via /v1/swarm/completions
ExecutionAuthoring only — you run it yourselfCan author and execute in one call
Cost profileOne small LLM call to generate the configGenerates N agents and (typically) runs them, so the call is heavier
Typical task”Build me a contract reviewer.""Build me a due-diligence team that covers legal, financial, and technical risk.”
Rule of thumb: if you’d describe the result as “an agent,” use /v1/agents/auto-generate. If you’d describe it as “a team,” “a pipeline,” or “a workflow,” use /v1/auto-swarm-builder/completions.
Yes. The returned agent_config is just a dict — mutate model_name, max_tokens, or any other field before calling /v1/agent/completions. Common pattern: auto-generate with the default, then swap model_name to anthropic/claude-opus-4-8 for production.
No — the same task will return slightly different configs across calls. For production, generate once, review the prompt, commit it to your repo, and load it from there. The endpoint is for authoring, not for runtime config lookup.
/v1/agents/auto-generate produces a vanilla single-agent config. If you need tool use, MCP servers, or vision, add those fields yourself after generation, or describe them explicitly in the task (“…the agent should call a web search tool…”).

​
Next Steps