Migration Guide: v0.x to v1.x

Agency Swarm v1.x is a complete rewrite built on the OpenAI Agents SDK, bringing significant improvements and new capabilities.

Installation

pip install "agency-swarm<1.0.0"

v0.x documentation remains available at the current site until v1.0 reaches general availability.

What’s New in v1.x

Latest AI Models

Full support for reasoning modelsWeb Search and Computer Use capabilities

Better Performance

Async-first architecture with direct conversation control

Enhanced Tools

Simple @function_tool decorator replaces complex BaseTool classes

Direct Control

No more black-box Assistants API - full control over threads and runs

📋 Complete Feature Comparison

🏗️ Understanding the Migration

Step-by-Step Migration

🔧 Agency & Agent Updates

Agency Constructor

def load_threads(chat_id):
    return load_threads_from_db(chat_id)  # Returns thread IDs

def save_threads(new_threads):
    save_threads_to_db(new_threads)  # Saves thread IDs

agency = Agency(
    agency_chart=[agent1, [agent1, agent2]],  # Will show warning
    threads_callbacks={
        'load': lambda: load_threads(chat_id),
        'save': lambda new_threads: save_threads(new_threads)
    }
)

Data Format Change: Your callbacks now need to store complete conversation histories instead of just thread IDs. Refer to examples/custom_persistence.py to see the example implementation.

Agent Configuration

agent = Agent(
    name="MyAgent",
    temperature=0.7,
    max_completion_tokens=1000,
    response_validator=my_validator
)

🛠️ Tool Migration

Simple Tool Conversion

This step is optional. Agency Swarm will keep maintaining the BaseTool approach for tool definition as well.

class ProcessData(BaseTool):
    """Processes input data."""
    input_data: str = Field(..., description="Data to process")

    def run(self):
        return f"Processed: {self.input_data}"

Tool with Context Access

class AdvancedTool(BaseTool):
    data: str = Field(..., description="Input data")

    def run(self):
        # Access shared state
        shared_data = self._shared_state.get("key", "default")
        return f"Result: {self.data} + {shared_data}"

🔒 Validation & Outputs

Response Validation

class TestAgent(Agent):
    def __init__(self):
        super().__init__(
            name="TestAgent",
            description="..."
        )

    @override
    def response_validator(self, message):
        # User-defined validation function
        if self.check_errors(message):
            raise ValueError("Error processing message")

        # Returns original message if no errors are raised
        return message

Structured Outputs

result = agency.get_completion(
    "Analyze this data",
    response_format={"type": "json_schema", "json_schema": {...}}
)

🔄 Interaction Updates

Complete Migration Example

from agency_swarm import Agency, Agent, BaseTool
from pydantic import Field

class DataProcessor(BaseTool):
    """Processes data."""
    data: str = Field(..., description="Input data")

    def run(self):
        return f"Processed: {self.data}"

class Analyst(Agent):
    def __init__(self):
        super().__init__(
            name="Analyst",
            description="Analyzes data",
            tools=[DataProcessor],
            temperature=0.7
        )

    def response_validator(self, message):
        if "error" in message.lower():
            raise ValueError("Invalid response")
        return message

agency = Agency(
    agency_chart=[Analyst()],
    shared_instructions="Be helpful and accurate."
)

result = agency.get_completion("Analyze sample data")

Reference Tables

📚 API changes overview

Agency Methods

v0.x	Status	v1.x alternative
`get_completion()`	✅ Backward compatible	`get_response()` (async)
`get_completion_stream()`	❌ Removed	`get_response_stream()` (async)
`agency_chart`	⚠️ Deprecated	Positional args + `communication_flows`
`threads_callbacks`	❌ Breaking change	`load_threads_callback` + `save_threads_callback`

Agent Parameters

v0.x	Status	v1.x alternative
`temperature`, `top_p`, etc.	⚠️ Individual params deprecated	`model_settings=ModelSettings(...)`
`response_validator`	❌ Removed	`output_guardrails`, `input_guardrails`
`response_format`	❌ Removed	`output_type`
`examples`	⚠️ Deprecated	Auto-prepended to `instructions`

Tools

v0.x	Status	v1.x alternative
`BaseTool` classes	⚠️ BaseTool still works	`@function_tool` decorator (recommended)
`run()` method	✅ Simplified	Direct function body implementation
`_shared_state`	✅ Enhanced	`ctx.context`

Getting Help

Examples

Working v1.x examples with detailed comments

Issues

Report v1.x issues with the v1.x label

OpenAI Agents SDK

Official OpenAI Agents SDK documentation

v0.x Docs

Current production documentation

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Migration Guide: v0.x to v1.x

Installation

What’s New in v1.x

Latest AI Models

Better Performance

Enhanced Tools

Direct Control

New Capabilities

Architectural Improvements

Enhanced Developer Experience

Execution Core

State Management

Agent Definition

Conversation History Persistence

Step-by-Step Migration

Agency Constructor

Agent Configuration

Simple Tool Conversion

Tool with Context Access

Response Validation

Structured Outputs

Getting Agency Response

Complete Migration Example

Reference Tables

Agency Methods

Agent Parameters

Tools

Getting Help

Examples

Issues

OpenAI Agents SDK

v0.x Docs

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

​Installation

​What’s New in v1.x

Latest AI Models

Better Performance

Enhanced Tools

Direct Control

​Step-by-Step Migration

​Complete Migration Example

​Reference Tables

​Getting Help

Examples

Issues

OpenAI Agents SDK

v0.x Docs

Installation

What’s New in v1.x

Step-by-Step Migration

Complete Migration Example

Reference Tables

Getting Help