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.

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" / "string" — the full conversation as one string
"str-all-except-first" (default) — the conversation, excluding the first (system prompt) message, joined into one string
"final" / "last" — just the content of the last message (a plain string) — this is usually what you want when you also configure a list_base_models/tool_schema, since the model’s final response text is where schema-shaped JSON ends up
"json" — the full conversation history serialized as a JSON string (an array of {"role", "content", ...} message dicts, not a single schema-shaped object)
"dict" / "dictionary" — the full conversation history as a Python list of message dicts (despite the name, this is a list, not a single dict)
"list" — the conversation as a list of message dicts
"yaml" — the conversation history as a YAML string
"xml" — the conversation history as an XML string
"all" — the conversation as a string (same as "string")
"dict-all-except-first" — all messages except the first, as a list of message dicts. This is the default output_type used internally by several multi-agent harnesses (HeavySwarm, HierarchicalSwarm, SwarmRouter, 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

from swarms import Agent

# String output (default is "str-all-except-first")
agent = Agent(output_type="str")

# 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")

# XML output
agent = Agent(output_type="xml")

# Just the agent's final response as a plain string — pair this with
# list_base_models / tool_schema to get back schema-shaped JSON text
agent = Agent(output_type="final")

JSON Schema Output

Basic JSON Schema

Use Pydantic models to define structured output schemas:

from swarms import Agent
from pydantic import BaseModel, Field
from typing import List

class CompanyAnalysis(BaseModel):
    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="claude-sonnet-4-6",
    max_loops=1,
    list_base_models=[CompanyAnalysis],  # Adds the schema to the agent's memory as guidance
    output_type="final",                # Return just the model's final text response
)

result = agent.run(
    "Analyze Tesla as an investment opportunity"
)

# `list_base_models` only tells the LLM what shape to respond in — it does not
# parse or validate the response for you. `result` is a plain string; if the
# model complied with the schema, it will be JSON text you can parse yourself.
import json
data = json.loads(result)
analysis = CompanyAnalysis(**data)
print(analysis.company_name)

Multiple Output Schemas

Define multiple possible output formats:

from pydantic import BaseModel, Field
from typing import List

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

class ComparisonReport(BaseModel):
    products: List[str]
    winner: str
    reasoning: str
    price_comparison: dict

agent = Agent(
    agent_name="Product-Reviewer",
    model_name="claude-sonnet-4-6",
    list_base_models=[ProductReview, ComparisonReport],
    output_type="final",
)

# Both schemas are described in the agent's memory; the model picks
# whichever shape fits the task when it writes its final text response.
# Parse the result yourself against whichever schema you expect.
review = agent.run("Review the iPhone 15 Pro")
comparison = agent.run("Compare iPhone 15 Pro vs Samsung S24 Ultra")

Tool Schema

Using tool_schema Parameter

Define output structure using tool_schema:

from pydantic import BaseModel, Field

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,   # Adds the schema to the agent's memory as guidance
    output_type="final",      # Return the model's raw final text (expected to be JSON)
)

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

# `tool_schema` guides the model to respond in this shape; it does not parse
# the response for you. Parse the JSON text yourself:
import json
email = json.loads(result)
print(f"Subject: {email['subject']}")
print(f"To: {', '.join(email['recipients'])}")
print(f"Body: {email['body']}")

Complex Output Structures

Nested Models

from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime

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):
    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="claude-sonnet-4-6",
    list_base_models=[ProjectPlan],
    max_loops=1,
    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
    """
)

# Parse the model's JSON text response yourself
import json
project = json.loads(result)

# Access nested structure
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

from pydantic import BaseModel, Field
from typing import List

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):
    recommendations: List[StockRecommendation]
    overall_strategy: str
    risk_level: str = Field(pattern="^(conservative|moderate|aggressive)$")

agent = Agent(
    agent_name="Portfolio-Advisor",
    model_name="claude-sonnet-4-6",
    list_base_models=[PortfolioRecommendations],
    output_type="final",
)

result = agent.run(
    "Provide 5 stock recommendations for a moderate-risk portfolio"
)

import json
portfolio = json.loads(result)

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

Validation and Constraints

Field Validation

from pydantic import BaseModel, Field, validator
from typing import List

class FinancialReport(BaseModel):
    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")
    key_metrics: dict
    recommendations: List[str] = Field(min_items=1, max_items=10)
    
    @validator('expenses')
    def expenses_less_than_revenue(cls, v, values):
        if 'revenue' in values and v >= values['revenue']:
            raise ValueError('Expenses should be less than revenue for profitable quarter')
        return v

agent = Agent(
    agent_name="Financial-Reporter",
    model_name="claude-sonnet-4-6",
    list_base_models=[FinancialReport],
)

report = agent.run(
    "Create a financial report for Q4 2024 based on revenue of $100M"
)

Enums and Choices

from pydantic import BaseModel, Field
from enum import Enum
from typing import List

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):
    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="claude-sonnet-4-6",
    list_base_models=[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.
    """
)

import json
bug = json.loads(result)

print(f"Priority: {bug['priority']}")
print(f"Status: {bug['status']}")

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, combine list_base_models/tool_schema with output_type="final" and parse the model’s final text yourself, as shown below.

import json
from pydantic import BaseModel
from typing import List

class LanguageList(BaseModel):
    languages: List[str]

agent = Agent(
    agent_name="Data-Agent",
    model_name="claude-sonnet-4-6",
    list_base_models=[LanguageList],
    output_type="final",  # Return just the model's final text response
)

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

for lang in data['languages']:
    print(f"- {lang}")

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.

agent = Agent(
    agent_name="Analyzer",
    model_name="claude-sonnet-4-6",
    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

Pydantic Model Response

from pydantic import BaseModel
from typing import List

class Article(BaseModel):
    title: str
    summary: str
    key_points: List[str]
    word_count: int

agent = Agent(
    agent_name="Content-Creator",
    model_name="claude-sonnet-4-6",
    list_base_models=[Article],
    output_type="final",
)

response = agent.run("Write an article about renewable energy")

# `response` is a plain string (the model's final text). If the model
# complied with the Article schema, parse it and validate with Pydantic:
import json
data = json.loads(response)
article = Article(**data)
print(f"Title: {article.title}")
print(f"Summary: {article.summary}")
print(f"Key points: {', '.join(article.key_points)}")

Function Calling Response

When tools are used, responses include function calls:

from swarms import Agent

def calculate(expression: str) -> float:
    """Calculate a mathematical expression"""
    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?")
# Agent calls the tool and returns the result
print(response)

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'")

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
Pydantic integration: swarms/tools/pydantic_to_json.py
Tool/list-base-model schema handling: swarms/structs/agent.py:3059-3087 (handle_tool_schema_ops)

Getting Started

Core Concepts

Agent Development

Reasoning Agents

Multi-Agent Architectures

Deployment & Operations

Integrations

CLI Reference

Changelog

Structured Outputs

Output Types

JSON Schema Output

Basic JSON Schema

Multiple Output 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

Pydantic Model Response

Function Calling Response

Best Practices

1. Use Descriptive Field Names

2. Add Field Descriptions

3. Use Appropriate Constraints

4. Provide Examples in Descriptions

Next Steps

Agent Tools

Creating Agents

Reference

​Output Types

​JSON Schema Output

​Basic JSON Schema

​Multiple Output 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

​Pydantic Model Response

​Function Calling Response

​Best Practices

​1. Use Descriptive Field Names

​2. Add Field Descriptions

​3. Use Appropriate Constraints

​4. Provide Examples in Descriptions

​Next Steps

Agent Tools

Creating Agents

​Reference

Output Types

JSON Schema Output

Basic JSON Schema

Multiple Output 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

Pydantic Model Response

Function Calling Response

Best Practices

1. Use Descriptive Field Names

2. Add Field Descriptions

3. Use Appropriate Constraints

4. Provide Examples in Descriptions

Next Steps

Reference