- Structured Outputs — enforce a JSON schema on the LLM’s response using
llm_args.response_format - Tools / Function Calling — provide tool definitions the LLM can invoke using
tools_list_dictionary
tools_list_dictionary is one of three separate tool mechanisms the API exposes. The other two — the built-in auto_search/web_scraper tools (tools_enabled) and the autonomous looper’s tools (selected_tools, only used when max_loops is "auto") — are documented on the Tools page.Structured Outputs
Structured outputs guarantee that an agent’s response conforms to a JSON schema you define. This uses the model provider’s nativeresponse_format parameter (e.g., OpenAI’s structured outputs), passed through llm_args in the agent config.
How It Works
Add aresponse_format object inside llm_args in your agent configuration. The API passes this directly to the underlying LLM via LiteLLM.
{
"agent_config": {
"agent_name": "Data Extractor",
"model_name": "gpt-4o",
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "your_schema",
"strict": true,
"schema": {
"type": "object",
"properties": {
"field_name": { "type": "string" }
},
"required": ["field_name"],
"additionalProperties": false
}
}
}
}
}
}
Example: JSON Schema Mode
Extract structured data from unstructured text by defining the exact fields you want.- Python
- TypeScript
- cURL
import requests
import json
import os
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json={
"agent_config": {
"agent_name": "Company Extractor",
"description": "Extracts structured company info from text",
"system_prompt": "Extract the requested information from the provided text. Return only the JSON output.",
"model_name": "gpt-4.1",
"max_tokens": 4096,
"temperature": 0.0,
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "company_info",
"strict": True,
"schema": {
"type": "object",
"properties": {
"company_name": {
"type": "string",
"description": "The name of the company"
},
"industry": {
"type": "string",
"description": "The industry the company operates in"
},
"founded_year": {
"type": "integer",
"description": "The year the company was founded"
},
"key_products": {
"type": "array",
"items": {"type": "string"},
"description": "Main products or services"
}
},
"required": ["company_name", "industry", "founded_year", "key_products"],
"additionalProperties": False
}
}
}
}
},
"task": "Anthropic is an AI safety company founded in 2021. They are known for building Claude, a family of large language models, and for their research on AI alignment and interpretability."
}
)
print(json.dumps(response.json(), indent=2))
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
const response = await fetch(`${BASE_URL}/v1/agent/completions`, {
method: "POST",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
agent_config: {
agent_name: "Company Extractor",
description: "Extracts structured company info from text",
system_prompt: "Extract the requested information from the provided text. Return only the JSON output.",
model_name: "gpt-4.1",
max_tokens: 4096,
temperature: 0.0,
llm_args: {
response_format: {
type: "json_schema",
json_schema: {
name: "company_info",
strict: true,
schema: {
type: "object",
properties: {
company_name: {
type: "string",
description: "The name of the company"
},
industry: {
type: "string",
description: "The industry the company operates in"
},
founded_year: {
type: "integer",
description: "The year the company was founded"
},
key_products: {
type: "array",
items: { type: "string" },
description: "Main products or services"
}
},
required: ["company_name", "industry", "founded_year", "key_products"],
additionalProperties: false
}
}
}
}
},
task: "Anthropic is an AI safety company founded in 2021. They are known for building Claude, a family of large language models, and for their research on AI alignment and interpretability."
})
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));
curl -X POST "https://api.swarms.world/v1/agent/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_config": {
"agent_name": "Company Extractor",
"description": "Extracts structured company info from text",
"system_prompt": "Extract the requested information from the provided text. Return only the JSON output.",
"model_name": "gpt-4.1",
"max_tokens": 4096,
"temperature": 0.0,
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "company_info",
"strict": true,
"schema": {
"type": "object",
"properties": {
"company_name": {
"type": "string",
"description": "The name of the company"
},
"industry": {
"type": "string",
"description": "The industry the company operates in"
},
"founded_year": {
"type": "integer",
"description": "The year the company was founded"
},
"key_products": {
"type": "array",
"items": {"type": "string"},
"description": "Main products or services"
}
},
"required": ["company_name", "industry", "founded_year", "key_products"],
"additionalProperties": false
}
}
}
}
},
"task": "Anthropic is an AI safety company founded in 2021. They are known for building Claude, a family of large language models, and for their research on AI alignment and interpretability."
}'
Expected Response
The agent’soutputs field contains the structured JSON in the content field:
{
"job_id": "agent-a563cb00f8034d13bbb0401257cc3f7a",
"success": true,
"name": "Company Extractor",
"outputs": [
{
"role": "Company Extractor",
"content": "{\"company_name\":\"Anthropic\",\"industry\":\"AI safety and research\",\"founded_year\":2021,\"key_products\":[\"Claude language models\",\"AI alignment research\",\"AI interpretability research\"]}"
}
],
"usage": {
"input_tokens": 85,
"output_tokens": 95,
"total_tokens": 180,
"total_cost": 0.00231
}
}
The
content field is a JSON string. Parse it in your application to get the structured object.Structured Outputs in a Swarm
Use structured outputs with multiple agents in a ConcurrentWorkflow. Each agent can have its ownresponse_format schema.
- Python
- TypeScript
- cURL
import requests
import json
import os
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json={
"name": "Market Analysis Swarm",
"description": "Parallel market analysis with structured output",
"agents": [
{
"agent_name": "Risk Assessor",
"description": "Evaluates investment risk",
"system_prompt": "You are a risk assessment expert. Evaluate the investment risk based on the provided information.",
"model_name": "gpt-4.1",
"max_tokens": 4096,
"temperature": 0.0,
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "risk_assessment",
"strict": True,
"schema": {
"type": "object",
"properties": {
"risk_level": {"type": "string"},
"risk_score": {"type": "number"},
"factors": {
"type": "array",
"items": {"type": "string"}
},
"recommendation": {"type": "string"}
},
"required": ["risk_level", "risk_score", "factors", "recommendation"],
"additionalProperties": False
}
}
}
}
},
{
"agent_name": "Growth Analyst",
"description": "Projects growth potential",
"system_prompt": "You are a growth analysis expert. Project the growth potential based on the provided information.",
"model_name": "gpt-4.1",
"max_tokens": 4096,
"temperature": 0.0,
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "growth_projection",
"strict": True,
"schema": {
"type": "object",
"properties": {
"growth_potential": {"type": "string"},
"projected_roi_percent": {"type": "number"},
"time_horizon_months": {"type": "integer"},
"catalysts": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["growth_potential", "projected_roi_percent", "time_horizon_months", "catalysts"],
"additionalProperties": False
}
}
}
}
}
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Analyze NVIDIA as an investment opportunity given their dominance in AI GPU market, recent earnings beat, and current P/E ratio of 65."
}
)
print(json.dumps(response.json(), indent=2))
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
const response = await fetch(`${BASE_URL}/v1/swarm/completions`, {
method: "POST",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Market Analysis Swarm",
description: "Parallel market analysis with structured output",
agents: [
{
agent_name: "Risk Assessor",
description: "Evaluates investment risk",
system_prompt: "You are a risk assessment expert. Evaluate the investment risk based on the provided information.",
model_name: "gpt-4.1",
max_tokens: 4096,
temperature: 0.0,
llm_args: {
response_format: {
type: "json_schema",
json_schema: {
name: "risk_assessment",
strict: true,
schema: {
type: "object",
properties: {
risk_level: { type: "string" },
risk_score: { type: "number" },
factors: { type: "array", items: { type: "string" } },
recommendation: { type: "string" }
},
required: ["risk_level", "risk_score", "factors", "recommendation"],
additionalProperties: false
}
}
}
}
},
{
agent_name: "Growth Analyst",
description: "Projects growth potential",
system_prompt: "You are a growth analysis expert. Project the growth potential based on the provided information.",
model_name: "gpt-4.1",
max_tokens: 4096,
temperature: 0.0,
llm_args: {
response_format: {
type: "json_schema",
json_schema: {
name: "growth_projection",
strict: true,
schema: {
type: "object",
properties: {
growth_potential: { type: "string" },
projected_roi_percent: { type: "number" },
time_horizon_months: { type: "integer" },
catalysts: { type: "array", items: { type: "string" } }
},
required: ["growth_potential", "projected_roi_percent", "time_horizon_months", "catalysts"],
additionalProperties: false
}
}
}
}
}
],
max_loops: 1,
swarm_type: "ConcurrentWorkflow",
task: "Analyze NVIDIA as an investment opportunity given their dominance in AI GPU market, recent earnings beat, and current P/E ratio of 65."
})
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Market Analysis Swarm",
"description": "Parallel market analysis with structured output",
"agents": [
{
"agent_name": "Risk Assessor",
"description": "Evaluates investment risk",
"system_prompt": "You are a risk assessment expert.",
"model_name": "gpt-4.1",
"max_tokens": 4096,
"temperature": 0.0,
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "risk_assessment",
"strict": true,
"schema": {
"type": "object",
"properties": {
"risk_level": {"type": "string"},
"risk_score": {"type": "number"},
"factors": {"type": "array", "items": {"type": "string"}},
"recommendation": {"type": "string"}
},
"required": ["risk_level", "risk_score", "factors", "recommendation"],
"additionalProperties": false
}
}
}
}
},
{
"agent_name": "Growth Analyst",
"description": "Projects growth potential",
"system_prompt": "You are a growth analysis expert.",
"model_name": "gpt-4.1",
"max_tokens": 4096,
"temperature": 0.0,
"llm_args": {
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "growth_projection",
"strict": true,
"schema": {
"type": "object",
"properties": {
"growth_potential": {"type": "string"},
"projected_roi_percent": {"type": "number"},
"time_horizon_months": {"type": "integer"},
"catalysts": {"type": "array", "items": {"type": "string"}}
},
"required": ["growth_potential", "projected_roi_percent", "time_horizon_months", "catalysts"],
"additionalProperties": false
}
}
}
}
}
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Analyze NVIDIA as an investment opportunity given their dominance in AI GPU market, recent earnings beat, and current P/E ratio of 65."
}'
Expected Response
Each agent returns its own structured output in theoutput array:
{
"job_id": "swarm-3e54b3f41f8f461cbd05bf30d8eaecf8",
"status": "success",
"swarm_name": "Market Analysis Swarm",
"swarm_type": "ConcurrentWorkflow",
"output": [
{
"role": "Risk Assessor",
"content": "{\"risk_level\":\"Moderate\",\"risk_score\":6.5,\"factors\":[\"Dominance in AI GPU market provides a strong competitive advantage.\",\"Recent earnings beat indicates strong financial performance.\",\"High P/E ratio of 65 suggests the stock may be overvalued.\"],\"recommendation\":\"Consider as a growth investment, but monitor the high valuation closely.\"}"
},
{
"role": "Growth Analyst",
"content": "{\"growth_potential\":\"Strong growth due to AI and GPU leadership.\",\"projected_roi_percent\":15,\"time_horizon_months\":12,\"catalysts\":[\"Continued demand for AI and machine learning applications\",\"Expansion in data center and cloud computing markets\",\"New product launches and technological advancements\"]}"
}
],
"number_of_agents": 2
}
Tools / Function Calling
Tools let the LLM invoke functions during execution. This is separate from structured outputs — tools define actions the model can take, while structured outputs control the format of the model’s response. Usetools_list_dictionary in the agent config to define available tools using the OpenAI function calling schema. This is for your own functions — for the API’s built-in auto_search/web_scraper tools or the autonomous looper’s tools, see the Tools page instead.
Defining Tools
Each tool follows the OpenAI function calling format:{
"type": "function",
"function": {
"name": "tool_name",
"description": "What this tool does",
"parameters": {
"type": "object",
"properties": {
"param_name": {
"type": "string",
"description": "Parameter description"
}
},
"required": ["param_name"]
}
}
}
Example: Agent with Tools
- Python
- TypeScript
- cURL
import requests
import json
import os
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json={
"agent_config": {
"agent_name": "Market Analyst",
"description": "Analyzes market trends using search tools",
"system_prompt": "You are a financial analyst expert. Use the search tool to gather information before providing analysis.",
"model_name": "openai/gpt-4.1",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct an in-depth search on a specified topic",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth (1-3)"
},
"detailed_queries": {
"type": "array",
"items": {
"type": "string",
"description": "Specific search queries"
}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
},
"task": "What are the best ETFs and index funds for AI and tech?"
}
)
print(json.dumps(response.json(), indent=2))
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
const response = await fetch(`${BASE_URL}/v1/agent/completions`, {
method: "POST",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
agent_config: {
agent_name: "Market Analyst",
description: "Analyzes market trends using search tools",
system_prompt: "You are a financial analyst expert. Use the search tool to gather information before providing analysis.",
model_name: "openai/gpt-4.1",
max_loops: 1,
max_tokens: 8192,
temperature: 0.5,
tools_list_dictionary: [
{
type: "function",
function: {
name: "search_topic",
description: "Conduct an in-depth search on a specified topic",
parameters: {
type: "object",
properties: {
depth: {
type: "integer",
description: "Search depth (1-3)"
},
detailed_queries: {
type: "array",
items: {
type: "string",
description: "Specific search queries"
}
}
},
required: ["depth", "detailed_queries"]
}
}
}
]
},
task: "What are the best ETFs and index funds for AI and tech?"
})
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));
curl -X POST "https://api.swarms.world/v1/agent/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agent_config": {
"agent_name": "Market Analyst",
"description": "Analyzes market trends using search tools",
"system_prompt": "You are a financial analyst expert. Use the search tool to gather information before providing analysis.",
"model_name": "openai/gpt-4.1",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct an in-depth search on a specified topic",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth (1-3)"
},
"detailed_queries": {
"type": "array",
"items": {"type": "string", "description": "Specific search queries"}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
},
"task": "What are the best ETFs and index funds for AI and tech?"
}'
Expected Response
When the model calls a tool, thecontent field contains the tool call arguments:
{
"job_id": "agent-f424ee9035fb41b99b72459a55683eeb",
"success": true,
"name": "Market Analyst",
"outputs": [
{
"role": "Market Analyst",
"content": [
{
"function": {
"arguments": "{\"depth\":2,\"detailed_queries\":[\"best ETFs for AI and technology\",\"top index funds for technology sector\"]}",
"name": "search_topic"
},
"id": "call_efaxUkKmjKYHryMKZMnQBvdi",
"type": "function"
}
]
}
],
"usage": {
"input_tokens": 115,
"output_tokens": 146,
"total_tokens": 261,
"total_cost": 0.003448
}
}
Parsing Tool Call Responses
When an agent calls a tool, thecontent field is an array of tool call objects (not a plain string like structured outputs). Each object contains:
| Field | Type | Description |
|---|---|---|
function.name | string | The name of the tool the model wants to call |
function.arguments | string | A JSON-encoded string containing the tool call arguments |
id | string | A unique identifier for this tool call |
type | string | Always "function" |
The
arguments field is a JSON string, not a parsed object. You must parse it with json.loads() (Python) or JSON.parse() (JavaScript) before using the values.Step-by-Step Parsing
- Python
- TypeScript
import requests
import json
import os
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
# 1. Send the request with tool definitions
response = requests.post(
f"{BASE_URL}/v1/agent/completions",
headers=headers,
json={
"agent_config": {
"agent_name": "Weather Assistant",
"description": "Gets weather information",
"system_prompt": "You are a weather assistant. Use the get_weather tool to answer questions.",
"model_name": "gpt-4.1",
"max_loops": 1,
"max_tokens": 4096,
"temperature": 0.0,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a given location",
"parameters": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name, e.g. San Francisco, CA"
},
"unit": {
"type": "string",
"enum": ["celsius", "fahrenheit"],
"description": "Temperature unit"
}
},
"required": ["location"]
}
}
}
]
},
"task": "What is the weather in San Francisco?"
}
)
data = response.json()
# 2. Extract tool calls from the response
agent_output = data["outputs"][0]
tool_calls = agent_output["content"] # This is a list of tool call objects
# 3. Parse each tool call
for tool_call in tool_calls:
function_name = tool_call["function"]["name"]
call_id = tool_call["id"]
# Parse the arguments JSON string into a Python dict
arguments = json.loads(tool_call["function"]["arguments"])
print(f"Tool: {function_name}")
print(f"Call ID: {call_id}")
print(f"Arguments: {arguments}")
# 4. Use the parsed arguments in your application
if function_name == "get_weather":
location = arguments["location"]
unit = arguments.get("unit", "fahrenheit")
print(f" → Fetching weather for {location} in {unit}")
# Call your actual weather API here
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
// 1. Send the request with tool definitions
const response = await fetch(`${BASE_URL}/v1/agent/completions`, {
method: "POST",
headers: {
"x-api-key": API_KEY!,
"Content-Type": "application/json"
},
body: JSON.stringify({
agent_config: {
agent_name: "Weather Assistant",
description: "Gets weather information",
system_prompt: "You are a weather assistant. Use the get_weather tool to answer questions.",
model_name: "gpt-4.1",
max_loops: 1,
max_tokens: 4096,
temperature: 0.0,
tools_list_dictionary: [
{
type: "function",
function: {
name: "get_weather",
description: "Get the current weather for a given location",
parameters: {
type: "object",
properties: {
location: {
type: "string",
description: "City name, e.g. San Francisco, CA"
},
unit: {
type: "string",
enum: ["celsius", "fahrenheit"],
description: "Temperature unit"
}
},
required: ["location"]
}
}
}
]
},
task: "What is the weather in San Francisco?"
})
});
const data = await response.json();
// 2. Extract tool calls from the response
const agentOutput = data.outputs[0];
const toolCalls = agentOutput.content; // Array of tool call objects
// 3. Parse each tool call
for (const toolCall of toolCalls) {
const functionName = toolCall.function.name;
const callId = toolCall.id;
// Parse the arguments JSON string into an object
const args = JSON.parse(toolCall.function.arguments);
console.log(`Tool: ${functionName}`);
console.log(`Call ID: ${callId}`);
console.log(`Arguments:`, args);
// 4. Use the parsed arguments in your application
if (functionName === "get_weather") {
const location = args.location;
const unit = args.unit ?? "fahrenheit";
console.log(` → Fetching weather for ${location} in ${unit}`);
// Call your actual weather API here
}
}
Example Output
Tool: get_weather
Call ID: call_VPqXFY3bgFsTJHLQeeQYY230
Arguments: {'location': 'San Francisco, CA'}
→ Fetching weather for San Francisco, CA in fahrenheit
Detecting tool calls vs. text responses: When the agent uses tools,
content is an array of objects. When the agent responds with plain text, content is a string. Check the type to handle both cases:content = data["outputs"][0]["content"]
if isinstance(content, list):
# Agent made tool call(s) — parse them
for tool_call in content:
args = json.loads(tool_call["function"]["arguments"])
elif isinstance(content, str):
# Agent responded with text
print(content)
Multi-Agent Swarm with Tools
Combine multiple tool-enabled agents in a swarm. Each agent can have its own set of tools.- Python
- TypeScript
- cURL
import requests
import json
import os
API_KEY = os.getenv("SWARMS_API_KEY")
BASE_URL = "https://api.swarms.world"
headers = {
"x-api-key": API_KEY,
"Content-Type": "application/json"
}
response = requests.post(
f"{BASE_URL}/v1/swarm/completions",
headers=headers,
json={
"name": "Financial Analysis Swarm",
"description": "Multi-agent financial analysis with tools",
"agents": [
{
"agent_name": "Market Analyst",
"description": "Analyzes market trends",
"system_prompt": "You are a financial analyst expert.",
"model_name": "openai/gpt-4.1",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct market research",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth (1-3)"
},
"detailed_queries": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
},
{
"agent_name": "Economic Forecaster",
"description": "Predicts economic trends",
"system_prompt": "You are an expert in economic forecasting.",
"model_name": "gpt-4.1",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct economic research",
"parameters": {
"type": "object",
"properties": {
"depth": {
"type": "integer",
"description": "Search depth (1-3)"
},
"detailed_queries": {
"type": "array",
"items": {"type": "string"}
}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
}
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Analyze top performing tech ETFs and their growth potential"
}
)
print(json.dumps(response.json(), indent=2))
const API_KEY = process.env.SWARMS_API_KEY;
const BASE_URL = "https://api.swarms.world";
const response = await fetch(`${BASE_URL}/v1/swarm/completions`, {
method: "POST",
headers: {
"x-api-key": API_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Financial Analysis Swarm",
description: "Multi-agent financial analysis with tools",
agents: [
{
agent_name: "Market Analyst",
description: "Analyzes market trends",
system_prompt: "You are a financial analyst expert.",
model_name: "openai/gpt-4.1",
max_loops: 1,
max_tokens: 8192,
temperature: 0.5,
tools_list_dictionary: [
{
type: "function",
function: {
name: "search_topic",
description: "Conduct market research",
parameters: {
type: "object",
properties: {
depth: { type: "integer", description: "Search depth (1-3)" },
detailed_queries: { type: "array", items: { type: "string" } }
},
required: ["depth", "detailed_queries"]
}
}
}
]
},
{
agent_name: "Economic Forecaster",
description: "Predicts economic trends",
system_prompt: "You are an expert in economic forecasting.",
model_name: "gpt-4.1",
max_loops: 1,
max_tokens: 8192,
temperature: 0.5,
tools_list_dictionary: [
{
type: "function",
function: {
name: "search_topic",
description: "Conduct economic research",
parameters: {
type: "object",
properties: {
depth: { type: "integer", description: "Search depth (1-3)" },
detailed_queries: { type: "array", items: { type: "string" } }
},
required: ["depth", "detailed_queries"]
}
}
}
]
}
],
max_loops: 1,
swarm_type: "ConcurrentWorkflow",
task: "Analyze top performing tech ETFs and their growth potential"
})
});
const result = await response.json();
console.log(JSON.stringify(result, null, 2));
curl -X POST "https://api.swarms.world/v1/swarm/completions" \
-H "x-api-key: $SWARMS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Financial Analysis Swarm",
"description": "Multi-agent financial analysis with tools",
"agents": [
{
"agent_name": "Market Analyst",
"description": "Analyzes market trends",
"system_prompt": "You are a financial analyst expert.",
"model_name": "openai/gpt-4.1",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct market research",
"parameters": {
"type": "object",
"properties": {
"depth": {"type": "integer", "description": "Search depth (1-3)"},
"detailed_queries": {"type": "array", "items": {"type": "string"}}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
},
{
"agent_name": "Economic Forecaster",
"description": "Predicts economic trends",
"system_prompt": "You are an expert in economic forecasting.",
"model_name": "gpt-4.1",
"max_loops": 1,
"max_tokens": 8192,
"temperature": 0.5,
"tools_list_dictionary": [
{
"type": "function",
"function": {
"name": "search_topic",
"description": "Conduct economic research",
"parameters": {
"type": "object",
"properties": {
"depth": {"type": "integer", "description": "Search depth (1-3)"},
"detailed_queries": {"type": "array", "items": {"type": "string"}}
},
"required": ["depth", "detailed_queries"]
}
}
}
]
}
],
"max_loops": 1,
"swarm_type": "ConcurrentWorkflow",
"task": "Analyze top performing tech ETFs and their growth potential"
}'
Expected Response
{
"job_id": "swarm-884b618ebadc4b2a9c80a0660a3fb928",
"status": "success",
"swarm_name": "Financial Analysis Swarm",
"swarm_type": "ConcurrentWorkflow",
"output": [
{
"role": "Market Analyst",
"content": "[{\"function\": {\"arguments\": \"{\\\"depth\\\":3,\\\"detailed_queries\\\":[\\\"Top performing tech ETFs\\\",\\\"Growth potential of tech ETFs\\\"]}\", \"name\": \"search_topic\"}, \"type\": \"function\"}]"
},
{
"role": "Economic Forecaster",
"content": "[{\"function\": {\"arguments\": \"{\\\"depth\\\":2,\\\"detailed_queries\\\":[\\\"Top performing tech ETFs\\\",\\\"Factors influencing tech ETF performance\\\"]}\", \"name\": \"search_topic\"}, \"type\": \"function\"}]"
}
],
"number_of_agents": 2
}
Parsing Swarm Tool Calls
Swarm responses differ from single-agent responses in two ways:- The response key is
output(notoutputs) - The
contentfield is a string (serialized Python representation), not a native array
ast.literal_eval in Python to safely parse the content string:
- Python
- TypeScript
import ast
import json
data = response.json()
for agent_output in data["output"]:
agent_name = agent_output["role"]
content = agent_output["content"]
# Swarm content is a string — parse it into a list
if isinstance(content, str):
tool_calls = ast.literal_eval(content)
else:
tool_calls = content
for tool_call in tool_calls:
function_name = tool_call["function"]["name"]
arguments = json.loads(tool_call["function"]["arguments"])
print(f"[{agent_name}] Tool: {function_name}")
print(f" Arguments: {arguments}")
const data = await response.json();
for (const agentOutput of data.output) {
const agentName = agentOutput.role;
let content = agentOutput.content;
// Swarm content is a string — parse it into an array
let toolCalls: any[];
if (typeof content === "string") {
// Replace Python-style single quotes with double quotes for JSON parsing
const jsonString = content.replace(/'/g, '"');
toolCalls = JSON.parse(jsonString);
} else {
toolCalls = content;
}
for (const toolCall of toolCalls) {
const functionName = toolCall.function.name;
const args = JSON.parse(toolCall.function.arguments);
console.log(`[${agentName}] Tool: ${functionName}`);
console.log(` Arguments:`, args);
}
}
FAQ
What is the difference between structured outputs and tools?
What is the difference between structured outputs and tools?
Structured outputs (
llm_args.response_format) control the format of the model’s response — you define a JSON schema and the model’s output is guaranteed to match it.Tools (tools_list_dictionary) define actions the model can invoke — the model decides when to call a function and with what arguments.You can use both on the same agent if needed.Do all agents need tools?
Do all agents need tools?
No, tools are optional for each agent. Simply omit the
tools_list_dictionary field for agents that don’t require tools.Which models support structured outputs?
Which models support structured outputs?
Structured outputs via
response_format work with models that support OpenAI’s structured output format, including gpt-4.1, gpt-4.1-mini, and gpt-4o. The feature is passed through LiteLLM, so any LiteLLM-supported model with response_format support will work.Can I use structured outputs and tools together?
Can I use structured outputs and tools together?
Yes. Set
llm_args.response_format for the output format and tools_list_dictionary for available tools on the same agent.How is tools_list_dictionary different from tools_enabled and selected_tools?
How is tools_list_dictionary different from tools_enabled and selected_tools?
tools_list_dictionary defines your own custom functions using an OpenAI-style schema — the model decides when to call them, and your application executes them.tools_enabled (on the request body, alongside agent_config) turns on the API’s two built-in tools, auto_search and web_scraper, which the API executes for you.selected_tools (in agent_config) restricts the autonomous execution loop’s own tool set (planning, file, and sub-agent tools), and only applies when agent_config.max_loops is "auto".All three can be combined on the same request. See the Tools page for the built-in and autonomous-loop mechanisms.