Structured Outputs

Structured outputs enable agents to return responses in a specific format, such as JSON objects, lists, or Pydantic models. This is essential for integrating agents into applications and workflows. There are two separate controls:

output_type decides how agent.run() formats the conversation it returns.
A function-calling schema in tools_list_dictionary makes the model answer with arguments that match your schema.

Output Types

Swarms supports multiple output formats through the output_type parameter. output_type controls how the conversation transcript (agent.short_memory) is formatted when agent.run() returns — it is not a schema parser. In particular:

"str-all-except-first" (default) — every message after the system prompt and the first input, contents joined into one string without role labels. In a plain run the first input is your task, so you get the agent’s answer
"final" / "last" — just the content of the last message. This is a string for a text answer, and a list of tool-call dicts when the model answered with a function call
"str" / "string" / "all" — the full conversation as one string, with a timestamp and role label on each message
"list" — the conversation as a list of {"role", "content"} dicts
"dict" / "dictionary" — the full conversation history as a Python list of message dicts, including each message’s timestamp and message_id (despite the name, this is a list, not a single dict)
"json" — the full conversation history serialized as a JSON string (an array of message dicts, not a single schema-shaped object)
"yaml" — the conversation history as a YAML string
"dict-all-except-first" — every message after the system prompt and the first input, as a list of message dicts. This is the default output_type of several multi-agent harnesses (HeavySwarm, HierarchicalSwarm, ConcurrentWorkflow, LLMCouncil, PlannerWorkerSwarm, and others)
"list-final" — the content of the last message, wrapped in a single-item list
"dict-final" — the content of the last message, as a (content, content) tuple

The "xml" output type was removed. "basemodel" is still accepted by the type hint, but the formatter does not handle it: a run with output_type="basemodel" raises ValueError after the model has answered. Use "final" and validate with Pydantic yourself, as shown below.

from swarms import Agent

# The agent's answer as a string (the default)
agent = Agent(output_type="str-all-except-first")

# Just the last message
agent = Agent(output_type="final")

# Full conversation history as JSON
agent = Agent(output_type="json")

# Full conversation history as a list of message dicts
agent = Agent(output_type="dict")

# List output
agent = Agent(output_type="list")

# YAML output
agent = Agent(output_type="yaml")

Function-Calling Schemas

The reliable way to get schema-shaped data is to give the agent a function schema in tools_list_dictionary and no Python callable to run. The model answers with a function call whose arguments follow your schema, and the agent returns that call to you instead of executing anything. With output_type="final", run() returns a list of tool-call dicts:

[
    {
        "id": "call_abc123",
        "type": "function",
        "function": {
            "name": "CompanyAnalysis",
            "arguments": '{"company_name": "Tesla", ...}',  # a JSON string
        },
    }
]

Basic JSON Schema

Define the shape with a Pydantic model and convert it with BaseTool().base_model_to_dict(), which returns an OpenAI tool schema:

import json
from typing import List

from pydantic import BaseModel, Field

from swarms import Agent, BaseTool


class CompanyAnalysis(BaseModel):
    """Record an investment analysis of one company."""

    company_name: str = Field(description="Name of the company")
    industry: str = Field(description="Primary industry")
    revenue: float = Field(description="Annual revenue in millions")
    growth_rate: float = Field(description="Year-over-year growth rate")
    strengths: List[str] = Field(description="Key strengths")
    risks: List[str] = Field(description="Main risk factors")
    recommendation: str = Field(description="Investment recommendation")


agent = Agent(
    agent_name="Financial-Analyst",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=[BaseTool().base_model_to_dict(CompanyAnalysis)],
    output_type="final",
)

result = agent.run(
    "Analyze Tesla as an investment opportunity. "
    "Record your analysis with the CompanyAnalysis function."
)

if isinstance(result, list):
    data = json.loads(result[0]["function"]["arguments"])
    analysis = CompanyAnalysis(**data)
    print(analysis.company_name, analysis.recommendation)
else:
    print("The model answered in text:", result)

The request is sent with tool_choice="auto", so the model may still answer in plain text. Name the function in your task or system prompt, and check whether the result is a list before parsing it. Keep max_loops=1. No callable runs the function, so a later loop only sees a (no result recorded ...) placeholder for the call.

Multiple Output Schemas

Give the agent several schemas and branch on the function the model chose:

import json
from typing import List

from pydantic import BaseModel, Field

from swarms import Agent, BaseTool


class ProductReview(BaseModel):
    """Review a single product."""

    product_name: str
    rating: float = Field(ge=0, le=5)
    pros: List[str]
    cons: List[str]
    verdict: str


class ComparisonReport(BaseModel):
    """Compare two or more products."""

    products: List[str]
    winner: str
    reasoning: str


tool = BaseTool()
agent = Agent(
    agent_name="Product-Reviewer",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=[
        tool.base_model_to_dict(ProductReview),
        tool.base_model_to_dict(ComparisonReport),
    ],
    output_type="final",
)

result = agent.run("Compare the iPhone 15 Pro and the Samsung S24 Ultra.")

if isinstance(result, list):
    call = result[0]["function"]
    data = json.loads(call["arguments"])
    if call["name"] == "ComparisonReport":
        print(ComparisonReport(**data).winner)
    else:
        print(ProductReview(**data).verdict)

Hand-Written JSON Schemas

You can also pass an OpenAI tool schema as a plain dict:

from swarms import Agent

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_stock_price",
            "description": "Retrieve the current stock price for a company.",
            "parameters": {
                "type": "object",
                "properties": {
                    "ticker": {
                        "type": "string",
                        "description": "Stock ticker symbol, e.g. AAPL.",
                    },
                    "include_history": {
                        "type": "boolean",
                        "description": "Whether to include historical prices.",
                    },
                },
                "required": ["ticker", "include_history"],
            },
        },
    }
]

agent = Agent(
    agent_name="Financial-Analysis-Agent",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=tools,
    output_type="final",
)

out = agent.run("What is the current stock price for Apple? Include history.")
print(out)

Tool Schema

Using tool_schema Parameter

tool_schema takes a single Pydantic model and writes its schema into the agent’s memory as guidance. It does not send a function to the model and does not parse the reply, so you get the model’s text back and parse it yourself:

import json

from pydantic import BaseModel, Field

from swarms import Agent


class EmailDraft(BaseModel):
    subject: str = Field(description="Email subject line")
    body: str = Field(description="Email body content")
    recipients: list[str] = Field(description="List of recipient email addresses")
    cc: list[str] = Field(default=[], description="CC recipients")
    priority: str = Field(default="normal", description="Email priority: low, normal, high")


agent = Agent(
    agent_name="Email-Assistant",
    model_name="claude-sonnet-4-6",
    tool_schema=EmailDraft,
    output_type="final",
    system_prompt="Reply with a single JSON object that matches the schema. No prose, no code fences.",
)

result = agent.run(
    "Draft an email to the engineering team about the new feature release"
)

email = EmailDraft(**json.loads(result))
print(f"Subject: {email.subject}")
print(f"To: {', '.join(email.recipients)}")

Use output_type="final" with tool_schema. The schema is stored as the first message after the system prompt, so the default "str-all-except-first" returns your task followed by the answer. If the model wraps its JSON in prose or code fences, json.loads fails; prefer tools_list_dictionary when you need guaranteed structure.

list_base_models raises TypeError when the agent is constructed in swarms 15.0.3, so you cannot use it to pass several Pydantic models. Pass several schemas through tools_list_dictionary instead, as in Multiple Output Schemas.

Complex Output Structures

Nested Models

Nested models and enums become $defs references in the generated schema:

import json
from typing import List, Optional

from pydantic import BaseModel, Field

from swarms import Agent, BaseTool


class Task(BaseModel):
    title: str
    description: str
    priority: str = Field(pattern="^(low|medium|high|critical)$")
    estimated_hours: float
    assigned_to: Optional[str] = None


class Milestone(BaseModel):
    name: str
    deadline: str
    tasks: List[Task]
    status: str = Field(pattern="^(planning|in_progress|completed)$")


class ProjectPlan(BaseModel):
    """Record a project plan."""

    project_name: str
    description: str
    start_date: str
    end_date: str
    milestones: List[Milestone]
    budget: float
    team_size: int


agent = Agent(
    agent_name="Project-Manager",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=[BaseTool().base_model_to_dict(ProjectPlan)],
    output_type="final",
)

result = agent.run(
    """
    Create a 3-month project plan for building a mobile app with the following requirements:
    - User authentication
    - Real-time chat
    - Push notifications
    - Payment integration
    Record it with the ProjectPlan function.
    """
)

project = ProjectPlan(**json.loads(result[0]["function"]["arguments"]))

for milestone in project.milestones:
    print(f"\nMilestone: {milestone.name}")
    for task in milestone.tasks:
        print(f"  - {task.title} ({task.priority} priority)")

Lists and Arrays

import json
from typing import List

from pydantic import BaseModel, Field

from swarms import Agent, BaseTool


class StockRecommendation(BaseModel):
    ticker: str = Field(description="Stock ticker symbol")
    company_name: str
    current_price: float
    target_price: float
    action: str = Field(pattern="^(buy|sell|hold)$")
    confidence: float = Field(ge=0, le=100)
    reasoning: str


class PortfolioRecommendations(BaseModel):
    """Record stock recommendations for a portfolio."""

    recommendations: List[StockRecommendation]
    overall_strategy: str
    risk_level: str = Field(pattern="^(conservative|moderate|aggressive)$")


agent = Agent(
    agent_name="Portfolio-Advisor",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=[BaseTool().base_model_to_dict(PortfolioRecommendations)],
    output_type="final",
)

result = agent.run(
    "Provide 5 stock recommendations for a moderate-risk portfolio. "
    "Record them with the PortfolioRecommendations function."
)

portfolio = PortfolioRecommendations(
    **json.loads(result[0]["function"]["arguments"])
)

for rec in portfolio.recommendations:
    print(f"{rec.ticker}: {rec.action} - {rec.reasoning}")

Validation and Constraints

The schema tells the model what to produce, but nothing checks the reply for you. Validate the parsed arguments with your Pydantic model and handle ValidationError.

Field Validation

import json
from typing import List

from pydantic import BaseModel, Field, ValidationError, field_validator

from swarms import Agent, BaseTool


class FinancialReport(BaseModel):
    """Record a quarterly financial report."""

    quarter: str = Field(pattern="^Q[1-4] 20[0-9]{2}$")
    revenue: float = Field(gt=0, description="Revenue in millions")
    expenses: float = Field(gt=0, description="Total expenses in millions")
    profit_margin: float = Field(ge=0, le=100, description="Profit margin percentage")
    recommendations: List[str] = Field(min_length=1, max_length=10)

    @field_validator("expenses")
    @classmethod
    def expenses_less_than_revenue(cls, v, info):
        revenue = info.data.get("revenue")
        if revenue is not None and v >= revenue:
            raise ValueError("Expenses should be less than revenue for a profitable quarter")
        return v


agent = Agent(
    agent_name="Financial-Reporter",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=[BaseTool().base_model_to_dict(FinancialReport)],
    output_type="final",
)

result = agent.run(
    "Create a financial report for Q4 2024 based on revenue of $100M. "
    "Record it with the FinancialReport function."
)

try:
    report = FinancialReport(**json.loads(result[0]["function"]["arguments"]))
    print(report)
except ValidationError as error:
    print("The model's report failed validation:", error)

Enums and Choices

import json
from enum import Enum
from typing import List

from pydantic import BaseModel

from swarms import Agent, BaseTool


class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"


class Status(str, Enum):
    TODO = "todo"
    IN_PROGRESS = "in_progress"
    REVIEW = "review"
    DONE = "done"


class Bug(BaseModel):
    """File a bug report."""

    title: str
    description: str
    priority: Priority
    status: Status
    affected_components: List[str]
    steps_to_reproduce: List[str]
    expected_behavior: str
    actual_behavior: str


agent = Agent(
    agent_name="Bug-Tracker",
    model_name="gpt-5.4",
    max_loops=1,
    tools_list_dictionary=[BaseTool().base_model_to_dict(Bug)],
    output_type="final",
)

result = agent.run(
    """
    Create a bug report: Users can't login after the latest update.
    Login button is unresponsive on mobile devices.
    File it with the Bug function.
    """
)

bug = Bug(**json.loads(result[0]["function"]["arguments"]))

print(f"Priority: {bug.priority.value}")
print(f"Status: {bug.status.value}")

Output Processing

JSON Output

output_type="json" serializes the entire conversation history (a list of {"role", "content", ...} message dicts) to a JSON string — it does not extract a single task-specific object with your own keys. For a task-specific structured payload, use a schema in tools_list_dictionary with output_type="final", as shown above.

import json

from swarms import Agent

agent = Agent(
    agent_name="Data-Agent",
    model_name="gpt-5.4",
    max_loops=1,
    output_type="json",
)

result = agent.run("List the top 5 programming languages in 2024")
history = json.loads(result)

for message in history:
    print(message["role"], "->", str(message["content"])[:80])

Dictionary Output

output_type="dict" (or "dictionary") returns the full conversation history as a Python list of message dicts, not a single dict keyed by your schema’s fields. Index it as result[-1]["content"] to get the last message, then parse that content yourself.

from swarms import Agent

agent = Agent(
    agent_name="Analyzer",
    model_name="claude-sonnet-4-6",
    max_loops=1,
    output_type="dict",
)

result = agent.run("Analyze sentiment: 'This product is amazing!'")

# result is a list of message dicts; the model's answer is the last one
last_message = result[-1]["content"]
print(last_message)

Working with Responses

Function Calling Response

When you pass Python callables in tools, the agent runs the tool calls itself and records their results, so the return value is the conversation formatted by output_type, not raw tool calls:

from swarms import Agent


def calculate(expression: str) -> float:
    """Calculate a mathematical expression.

    Args:
        expression: An arithmetic expression such as "25 * 4 + 10".

    Returns:
        The numeric result.
    """
    return eval(expression)


agent = Agent(
    agent_name="Calculator",
    model_name="claude-sonnet-4-6",
    tools=[calculate],
    max_loops=2,
)

response = agent.run("What is 25 * 4 + 10?")
print(response)

See Agent Tools for callable tools and how their output is summarized.

Best Practices

1. Use Descriptive Field Names

# Good
class UserProfile(BaseModel):
    full_name: str = Field(description="User's full name")
    email_address: str = Field(description="Contact email")
    
# Bad
class UserProfile(BaseModel):
    n: str  # ❌ Not clear
    e: str  # ❌ Not clear

2. Add Field Descriptions

class Product(BaseModel):
    name: str = Field(description="Product name")
    price: float = Field(description="Price in USD", gt=0)
    category: str = Field(description="Product category (electronics, clothing, etc.)")
    in_stock: bool = Field(description="Whether the product is currently available")

3. Use Appropriate Constraints

class Review(BaseModel):
    rating: int = Field(ge=1, le=5, description="Star rating 1-5")
    comment: str = Field(min_length=10, max_length=500)
    verified_purchase: bool

4. Provide Examples in Descriptions

class Address(BaseModel):
    street: str = Field(description="Street address, e.g., '123 Main St'")
    city: str = Field(description="City name, e.g., 'San Francisco'")
    state: str = Field(description="Two-letter state code, e.g., 'CA'")
    zip_code: str = Field(pattern=r"^\d{5}(-\d{4})?$", description="ZIP code, e.g., '94102' or '94102-1234'")

5. Give Each Schema a Docstring

A Pydantic model’s docstring becomes the function description the LLM sees, and the class name becomes the function name. Say what the function records, and name the function in your task.

Next Steps

Agent Tools

Add tools to extend agent capabilities

Creating Agents

Learn how to create agents

Reference

Output type formatting: swarms/utils/history_output_formatter.py; the accepted values are in swarms/utils/output_types.py
Pydantic to tool schema: BaseTool.base_model_to_dict in swarms/tools/base_tool.py, built on swarms/tools/pydantic_to_json.py
Tool-call parsing: ToolManager.parse_response in swarms/agents/tool_manager.py
tool_schema and list_base_models handling: ToolManager.handle_tool_schema_ops in swarms/agents/tool_manager.py

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Structured Outputs

Output Types

Function-Calling Schemas

Basic JSON Schema

Multiple Output Schemas

Hand-Written JSON Schemas

Tool Schema

Using tool_schema Parameter

Complex Output Structures

Nested Models

Lists and Arrays

Validation and Constraints

Field Validation

Enums and Choices

Output Processing

JSON Output

Dictionary Output

Working with Responses

Function Calling Response

Best Practices

1. Use Descriptive Field Names

2. Add Field Descriptions

3. Use Appropriate Constraints

4. Provide Examples in Descriptions

5. Give Each Schema a Docstring

Next Steps

Agent Tools

Creating Agents

Reference

​Output Types

​Function-Calling Schemas

​Basic JSON Schema

​Multiple Output Schemas

​Hand-Written JSON Schemas

​Tool Schema

​Using tool_schema Parameter

​Complex Output Structures

​Nested Models

​Lists and Arrays

​Validation and Constraints

​Field Validation

​Enums and Choices

​Output Processing

​JSON Output

​Dictionary Output

​Working with Responses

​Function Calling Response

​Best Practices

​1. Use Descriptive Field Names

​2. Add Field Descriptions

​3. Use Appropriate Constraints

​4. Provide Examples in Descriptions

​5. Give Each Schema a Docstring

​Next Steps

Agent Tools

Creating Agents

​Reference

Output Types

Function-Calling Schemas

Basic JSON Schema

Multiple Output Schemas

Hand-Written JSON Schemas

Tool Schema

Using tool_schema Parameter

Complex Output Structures

Nested Models

Lists and Arrays

Validation and Constraints

Field Validation

Enums and Choices

Output Processing

JSON Output

Dictionary Output

Working with Responses

Function Calling Response

Best Practices

1. Use Descriptive Field Names

2. Add Field Descriptions

3. Use Appropriate Constraints

4. Provide Examples in Descriptions

5. Give Each Schema a Docstring

Next Steps

Reference