Migration Guide: v0.x to v1.x

​

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

​

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

• 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.

• 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)

​

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)
    }
)

​

Agent Configuration

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

​

Simple Tool Conversion

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

​

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": {...}}
)

​

Getting Agency Response

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

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

​

Agency Methods

​

Agent Parameters

​

Tools