> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured Outputs

> Get schema-enforced JSON output from your agents using response_format, and integrate tools for function calling

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.

```json theme={null}
{
    "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.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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));
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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."
      }'
    ```
  </Tab>
</Tabs>

#### Expected Response

The agent's `outputs` field contains the structured JSON in the `content` field:

```json theme={null}
{
  "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
  }
}
```

<Note>
  The `content` field is a JSON string. Parse it in your application to get the structured object.
</Note>

***

### Structured Outputs in a Swarm

Use structured outputs with multiple agents in a ConcurrentWorkflow. Each agent can have its own `response_format` schema.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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));
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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."
      }'
    ```
  </Tab>
</Tabs>

#### Expected Response

Each agent returns its own structured output in the `output` array:

```json theme={null}
{
  "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:

```json theme={null}
{
    "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

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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));
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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?"
      }'
    ```
  </Tab>
</Tabs>

#### Expected Response

When the model calls a tool, the `content` field contains the tool call arguments:

```json theme={null}
{
  "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:

| 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"`                                      |

<Warning>
  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.
</Warning>

#### Step-by-Step Parsing

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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
        }
    }
    ```
  </Tab>
</Tabs>

#### Example Output

```
Tool: get_weather
Call ID: call_VPqXFY3bgFsTJHLQeeQYY230
Arguments: {'location': 'San Francisco, CA'}
  → Fetching weather for San Francisco, CA in fahrenheit
```

<Tip>
  **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:

  ```python theme={null}
  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)
  ```
</Tip>

***

### Multi-Agent Swarm with Tools

Combine multiple tool-enabled agents in a swarm. Each agent can have its own set of tools.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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))
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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));
    ```
  </Tab>

  <Tab title="cURL">
    ```bash theme={null}
    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"
      }'
    ```
  </Tab>
</Tabs>

#### Expected Response

```json theme={null}
{
  "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:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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);
        }
    }
    ```
  </Tab>
</Tabs>

***

## FAQ

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>