Migration Guide: v0.x to v1.x

Guide for migrating from Agency Swarm v0.x to v1.x (OpenAI Agents SDK based)

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

Installation

v0.x (Previous)

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 models

Web 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

New Capabilities

• Web Search & Computer Use: Native OpenAI Responses API integration
• Latest Models: Full support for o3, o4-mini, and future OpenAI models via Responses API
• Third-Party Models: Use any Chat Completions API-compatible provider
• Direct Thread Control: No more black-box Assistants API limitations
• Full Conversation Persistence: Complete history management (not just thread IDs)
• Enhanced Validation: output_guardrails and input_guardrails system

Architectural Improvements

• Orchestrator Pattern on New Foundation: Agency Swarm’s proven orchestrator-workers pattern now runs on the OpenAI Agents SDK foundation
• Async-first: Native async execution for better performance
• Enhanced Communication: Defined communication_flows for coordinated multi-agent execution
• Better State Management: Complete conversation history persistence

Enhanced Developer Experience

• Structured Outputs: Native Pydantic model support for agent outputs via output_type
• Modern Tool System: @function_tool decorator replaces BaseTool classes for cleaner tool definitions
• Better Validation: output_guardrails and input_guardrails replace the old response_validator system
• Real-time Streaming: Improved streaming capabilities with async response handling

🏗️ Understanding the Migration

The migration from v0.x to v1.x represents a fundamental shift in how Agency Swarm operates:

Execution Core

• v0.x: Used OpenAI Assistants API runs directly
• v1.x: Uses agents.Runner from OpenAI Agents SDK for more control

State Management

• v0.x: Relied on Assistant/Thread objects managed by OpenAI
• v1.x: Uses ThreadManager and MessageStore managed via RunHooks and shared MasterContext

Agent Definition

• v0.x: Custom Agent class with Assistants API integration
• v1.x: agency_swarm.Agent extends agents.Agent, incorporating tools, subagent registration, and file handling

Conversation History Persistence

This is an important architectural difference between versions:

• v0.x (Assistants API): Required thread callbacks for production to persist OpenAI Assistant/Thread IDs. OpenAI managed conversation history server-side.
• v1.x (Agents SDK): Required thread callbacks for production to persist complete conversation histories locally. You manage the full conversation state.

Key Changes:

• Callback Structure: threads_callbacks dict → separate load_threads_callback and save_threads_callback parameters
• Data Format: Thread IDs only → Complete conversation histories
• Callback Signatures: Unchanged (both use no-parameter callbacks with closure)

Step-by-Step Migration

🔧 Agency & Agent Updates

Agency Constructor

v0.x

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

v0.x

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.

v0.x

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

v0.x

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

v0.x

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

v0.x

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

🔄 Interaction Updates

Getting Agency Response

v0.x

# Synchronous (still works but deprecated)
result = agency.get_completion("Hello")

# Streaming (removed)
stream = agency.get_completion_stream("Hello")

Complete Migration Example

Before (v0.x)

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
model (global default)	❌ Removed	Configure each Agent via model_settings
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