Skip to main content
The Swarms API supports two distinct capabilities for controlling agent output:
  • 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

​
Structured Outputs

Structured outputs guarantee that an agent’s response conforms to a JSON schema you define. This uses the model provider’s native response_format parameter (e.g., OpenAI’s structured outputs), passed through llm_args in the agent config.

​
How It Works

Add a response_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": { ... }
            }
        }
    }
}

​
Example: JSON Schema Mode

Extract structured data from unstructured text by defining the exact fields you want. 
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-4o",
            "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))

​
Expected Response

The agent’s outputs 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 own response_format schema. 
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-4o",
                "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-4o",
                "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))

​
Expected Response

Each agent returns its own structured output in the output 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. Use tools_list_dictionary in the agent config to define available tools using the OpenAI function calling schema.

​
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

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-4o",
            "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))

​
Expected Response

When the model calls a tool, the content 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, the content field is an array of tool call objects (not a plain string like structured outputs). Each object contains:
FieldTypeDescription
function.namestringThe name of the tool the model wants to call
function.argumentsstringA JSON-encoded string containing the tool call arguments
idstringA unique identifier for this tool call
typestringAlways "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

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-4o",
            "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

​
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. 
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-4o",
                "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-4o",
                "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))

​
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:
  1. The response key is output (not outputs)
  2. The content field is a string (serialized Python representation), not a native array
Use ast.literal_eval in Python to safely parse the content string: 
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}")

​
FAQ

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.
No, tools are optional for each agent. Simply omit the tools_list_dictionary field for agents that don’t require tools.
Structured outputs via response_format work with models that support OpenAI’s structured output format, including gpt-4o, gpt-4o-mini, and gpt-4.1. The feature is passed through LiteLLM, so any LiteLLM-supported model with response_format support will work.
Yes. Set llm_args.response_format for the output format and tools_list_dictionary for available tools on the same agent.