Generate Agent Configurations From a Task
curl --request POST \
--url https://api.swarms.world/v1/auto-agent-builder/completions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '
{
"task": "<string>",
"name": "<string>",
"description": "<string>",
"model_name": "<string>",
"max_agents": 5,
"num_agents": 50,
"system_prompt": "<string>",
"agent_kwargs": {}
}
'import requests
url = "https://api.swarms.world/v1/auto-agent-builder/completions"
payload = {
"task": "<string>",
"name": "<string>",
"description": "<string>",
"model_name": "<string>",
"max_agents": 5,
"num_agents": 50,
"system_prompt": "<string>",
"agent_kwargs": {}
}
headers = {
"x-api-key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
task: '<string>',
name: '<string>',
description: '<string>',
model_name: '<string>',
max_agents: 5,
num_agents: 50,
system_prompt: '<string>',
agent_kwargs: {}
})
};
fetch('https://api.swarms.world/v1/auto-agent-builder/completions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.swarms.world/v1/auto-agent-builder/completions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'task' => '<string>',
'name' => '<string>',
'description' => '<string>',
'model_name' => '<string>',
'max_agents' => 5,
'num_agents' => 50,
'system_prompt' => '<string>',
'agent_kwargs' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.swarms.world/v1/auto-agent-builder/completions"
payload := strings.NewReader("{\n \"task\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"model_name\": \"<string>\",\n \"max_agents\": 5,\n \"num_agents\": 50,\n \"system_prompt\": \"<string>\",\n \"agent_kwargs\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<x-api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.swarms.world/v1/auto-agent-builder/completions")
.header("x-api-key", "<x-api-key>")
.header("Content-Type", "application/json")
.body("{\n \"task\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"model_name\": \"<string>\",\n \"max_agents\": 5,\n \"num_agents\": 50,\n \"system_prompt\": \"<string>\",\n \"agent_kwargs\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.swarms.world/v1/auto-agent-builder/completions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"task\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"model_name\": \"<string>\",\n \"max_agents\": 5,\n \"num_agents\": 50,\n \"system_prompt\": \"<string>\",\n \"agent_kwargs\": {}\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>",
"name": "<string>",
"description": "<string>",
"status": "<string>",
"agents": [
{
"agent_name": "<string>",
"description": "<string>",
"system_prompt": "<string>",
"marketplace_prompt_id": "<string>",
"model_name": "claude-sonnet-5",
"fallback_models": [
"<string>"
],
"fallback_model_name": "<string>",
"auto_generate_prompt": false,
"max_tokens": 16000,
"temperature": 1,
"role": "worker",
"max_loops": 1,
"tools_list_dictionary": [
{}
],
"selected_tools": "<string>",
"mcp_url": "<string>",
"streaming_on": false,
"llm_args": {},
"top_p": 123,
"dynamic_temperature_enabled": false,
"mcp_config": {
"type": "mcp",
"url": "http://localhost:8000/mcp",
"name": "<string>",
"tool_configurations": {},
"authorization_token": "<string>",
"api_key": "<string>",
"api_key_header": "Authorization",
"api_key_prefix": "Bearer",
"oauth": {
"grant_type": "authorization_code",
"client_id": "<string>",
"client_secret": "<string>",
"scopes": [
"<string>"
],
"redirect_uri": "http://127.0.0.1:8765/callback",
"client_name": "Swarms Agent",
"client_uri": "<string>",
"authorization_url": "<string>",
"token_url": "<string>",
"access_token": "<string>",
"refresh_token": "<string>",
"token_storage_path": "<string>",
"use_token_cache": true,
"open_browser": true,
"callback_timeout": 300
},
"transport": "streamable_http",
"headers": {},
"timeout": 30,
"sse_read_timeout": 300,
"tool_timeout": 120,
"command": "<string>",
"args": [
"<string>"
],
"env": {}
},
"mcp_configs": {
"connections": [
{
"type": "mcp",
"url": "http://localhost:8000/mcp",
"name": "<string>",
"tool_configurations": {},
"authorization_token": "<string>",
"api_key": "<string>",
"api_key_header": "Authorization",
"api_key_prefix": "Bearer",
"oauth": {
"grant_type": "authorization_code",
"client_id": "<string>",
"client_secret": "<string>",
"scopes": [
"<string>"
],
"redirect_uri": "http://127.0.0.1:8765/callback",
"client_name": "Swarms Agent",
"client_uri": "<string>",
"authorization_url": "<string>",
"token_url": "<string>",
"access_token": "<string>",
"refresh_token": "<string>",
"token_storage_path": "<string>",
"use_token_cache": true,
"open_browser": true,
"callback_timeout": 300
},
"transport": "streamable_http",
"headers": {},
"timeout": 30,
"sse_read_timeout": 300,
"tool_timeout": 120,
"command": "<string>",
"args": [
"<string>"
],
"env": {}
}
]
},
"tool_call_summary": true,
"thinking_tokens": 123,
"reasoning_enabled": false,
"publish_to_marketplace": false,
"use_cases": [
{}
],
"tags": [
"<string>"
],
"capabilities": [
"<string>"
],
"category": "<string>",
"is_free": true,
"price_usd": 123,
"handoffs": [
"<unknown>"
]
}
],
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"token_cost": 123,
"cost_per_agent": 123
},
"timestamp": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Auto Agent Builder
Generate Agent Configurations From a Task
Generate a roster of agent configurations for a task. A single builder agent designs the team and returns ready-to-post AgentSpec entries — the generated agents are not executed by this endpoint.
POST
/
v1
/
auto-agent-builder
/
completions
Generate Agent Configurations From a Task
curl --request POST \
--url https://api.swarms.world/v1/auto-agent-builder/completions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--data '
{
"task": "<string>",
"name": "<string>",
"description": "<string>",
"model_name": "<string>",
"max_agents": 5,
"num_agents": 50,
"system_prompt": "<string>",
"agent_kwargs": {}
}
'import requests
url = "https://api.swarms.world/v1/auto-agent-builder/completions"
payload = {
"task": "<string>",
"name": "<string>",
"description": "<string>",
"model_name": "<string>",
"max_agents": 5,
"num_agents": 50,
"system_prompt": "<string>",
"agent_kwargs": {}
}
headers = {
"x-api-key": "<x-api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
task: '<string>',
name: '<string>',
description: '<string>',
model_name: '<string>',
max_agents: 5,
num_agents: 50,
system_prompt: '<string>',
agent_kwargs: {}
})
};
fetch('https://api.swarms.world/v1/auto-agent-builder/completions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.swarms.world/v1/auto-agent-builder/completions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'task' => '<string>',
'name' => '<string>',
'description' => '<string>',
'model_name' => '<string>',
'max_agents' => 5,
'num_agents' => 50,
'system_prompt' => '<string>',
'agent_kwargs' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <x-api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.swarms.world/v1/auto-agent-builder/completions"
payload := strings.NewReader("{\n \"task\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"model_name\": \"<string>\",\n \"max_agents\": 5,\n \"num_agents\": 50,\n \"system_prompt\": \"<string>\",\n \"agent_kwargs\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<x-api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.swarms.world/v1/auto-agent-builder/completions")
.header("x-api-key", "<x-api-key>")
.header("Content-Type", "application/json")
.body("{\n \"task\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"model_name\": \"<string>\",\n \"max_agents\": 5,\n \"num_agents\": 50,\n \"system_prompt\": \"<string>\",\n \"agent_kwargs\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.swarms.world/v1/auto-agent-builder/completions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<x-api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"task\": \"<string>\",\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"model_name\": \"<string>\",\n \"max_agents\": 5,\n \"num_agents\": 50,\n \"system_prompt\": \"<string>\",\n \"agent_kwargs\": {}\n}"
response = http.request(request)
puts response.read_body{
"job_id": "<string>",
"name": "<string>",
"description": "<string>",
"status": "<string>",
"agents": [
{
"agent_name": "<string>",
"description": "<string>",
"system_prompt": "<string>",
"marketplace_prompt_id": "<string>",
"model_name": "claude-sonnet-5",
"fallback_models": [
"<string>"
],
"fallback_model_name": "<string>",
"auto_generate_prompt": false,
"max_tokens": 16000,
"temperature": 1,
"role": "worker",
"max_loops": 1,
"tools_list_dictionary": [
{}
],
"selected_tools": "<string>",
"mcp_url": "<string>",
"streaming_on": false,
"llm_args": {},
"top_p": 123,
"dynamic_temperature_enabled": false,
"mcp_config": {
"type": "mcp",
"url": "http://localhost:8000/mcp",
"name": "<string>",
"tool_configurations": {},
"authorization_token": "<string>",
"api_key": "<string>",
"api_key_header": "Authorization",
"api_key_prefix": "Bearer",
"oauth": {
"grant_type": "authorization_code",
"client_id": "<string>",
"client_secret": "<string>",
"scopes": [
"<string>"
],
"redirect_uri": "http://127.0.0.1:8765/callback",
"client_name": "Swarms Agent",
"client_uri": "<string>",
"authorization_url": "<string>",
"token_url": "<string>",
"access_token": "<string>",
"refresh_token": "<string>",
"token_storage_path": "<string>",
"use_token_cache": true,
"open_browser": true,
"callback_timeout": 300
},
"transport": "streamable_http",
"headers": {},
"timeout": 30,
"sse_read_timeout": 300,
"tool_timeout": 120,
"command": "<string>",
"args": [
"<string>"
],
"env": {}
},
"mcp_configs": {
"connections": [
{
"type": "mcp",
"url": "http://localhost:8000/mcp",
"name": "<string>",
"tool_configurations": {},
"authorization_token": "<string>",
"api_key": "<string>",
"api_key_header": "Authorization",
"api_key_prefix": "Bearer",
"oauth": {
"grant_type": "authorization_code",
"client_id": "<string>",
"client_secret": "<string>",
"scopes": [
"<string>"
],
"redirect_uri": "http://127.0.0.1:8765/callback",
"client_name": "Swarms Agent",
"client_uri": "<string>",
"authorization_url": "<string>",
"token_url": "<string>",
"access_token": "<string>",
"refresh_token": "<string>",
"token_storage_path": "<string>",
"use_token_cache": true,
"open_browser": true,
"callback_timeout": 300
},
"transport": "streamable_http",
"headers": {},
"timeout": 30,
"sse_read_timeout": 300,
"tool_timeout": 120,
"command": "<string>",
"args": [
"<string>"
],
"env": {}
}
]
},
"tool_call_summary": true,
"thinking_tokens": 123,
"reasoning_enabled": false,
"publish_to_marketplace": false,
"use_cases": [
{}
],
"tags": [
"<string>"
],
"capabilities": [
"<string>"
],
"category": "<string>",
"is_free": true,
"price_usd": 123,
"handoffs": [
"<unknown>"
]
}
],
"usage": {
"input_tokens": 123,
"output_tokens": 123,
"total_tokens": 123,
"token_cost": 123,
"cost_per_agent": 123
},
"timestamp": "<string>"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Headers
Body
application/json
The task the generated team should be able to handle. This is the only required field.
Minimum string length:
1The name of this auto agent builder run.
The description of this auto agent builder run.
The model backing the builder agent itself — not the models given to the generated agents; the builder chooses those per agent. Defaults to the framework's builder default.
Upper bound on roster size. This is a ceiling, not a target — the builder prefers the smallest roster that covers the task.
Required range:
1 <= x <= 100Exact number of agents to generate. When set, this overrides max_agents and the builder's prefer-fewer guidance.
Required range:
1 <= x <= 100Custom instructions for the builder agent. Defaults to the framework's builder system prompt.
Extra keyword arguments carried on every generated agent, e.g. max_loops or streaming_on. Keys that collide with the fields the builder generates (agent_name, description, system_prompt, model_name) are ignored.
Response
Successful Response
The job ID of the auto agent builder run.
The name of the auto agent builder run.
The description of the auto agent builder run.
The status of the auto agent builder run.
The generated roster. Each entry is a complete AgentSpec that can be posted unmodified to /v1/swarm/completions or the other multi-agent endpoints.
Show child attributes
Show child attributes
The usage of the auto agent builder run.
Show child attributes
Show child attributes
The timestamp of the auto agent builder run.
Was this page helpful?
⌘I