v1.0.0

![Framework](https://firebasestorage.googleapis.com/v0/b/vrsen-ai/o/public%2Fgithub%2FLOGO_BG_large_bold_shadow%20(1).jpg?alt=media&token=8c681331-2a7a-4a69-b21b-3ab1f9bf1a23)

**Agency Swarm v1.0: The complete rewrite on the OpenAI Agents SDK and Responses API is now production-ready. This release preserves Agency Swarm’s orchestrator-workers pattern, runs natively async, moves off the legacy Assistants API, and retains production-grade persistence.**

## What's New: Stable Agents SDK + Responses API

* **Production-Ready Orchestrator Pattern**  
  Agency Swarm brings its proven orchestrator-workers pattern to the OpenAI Agents SDK. Agents communicate through defined pathways in `communication_flows`, enabling coordinated multi-agent execution with full thread and run state control.

* **Built on OpenAI Agents SDK** 
  Migrated from OpenAI's Assistants API to the **OpenAI Agents SDK** for explicit thread and run state control.

* **OpenAI Responses API Integration**  
  Uses OpenAI's Responses API by default, enabling support for the latest OpenAI models (including the GPT-5 family). Provides lower latency, more reliable execution, and third-party model compatibility.

* **Continuity & Migration**  
  v1.0 retains core v0.x capabilities where possible and provides warnings and a [migration guide](https://agency-swarm.ai/migration/guide) to ease upgrades.

## Major Features

* **Async-first Architecture**  
  Main methods expose async entry points (e.g., `await agency.get_response()`). Synchronous wrappers remain available, but async is recommended for concurrency.

* **Improved Communication & Multi-Agency Support**
  * `communication_flows` parameter replaces nested lists in `agency_chart`
  * Agents can belong to multiple agencies with improved per-flow handling
  * Customizable `send_message` tool for inter-agent messaging
  * Parent run ID tracking for end-to-end traceability
  * Per-recipient `send_message` blocking to prevent parallel sends to the same recipient while allowing different recipients to run in parallel

* **Modern Tool System**
  * `@function_tool` decorator for concise tool creation (BaseTool` still supported)
  * ToolFactory for dynamic tool creation from OpenAPI schemas
  * Context-aware tools with `RunContextWrapper` access

* **Advanced State Management**
  * Full conversation persistence with complete history management
  * `ThreadManager` and `MessageStore` with `RunHooks`
  * Shared `MasterContext` across agents

* **Improved Validation System**
  * Improves upon the Agents SDK’s Input Guardrails and Output Guardrails; supports Pydantic validators via BaseTool
  * Native Pydantic models via `output_type` for structured outputs
  * Automatic re-tries on output guardrail failures with system guidance (configurable via `validation_attempts`)
  * Surface input guardrail guidance instead of raising (set return_input_guardrail_errors)

* **FastAPI Integration**
  * `run_fastapi` method to expose agencies as authenticated HTTP APIs
  * File upload support with image processing
  * Run logs endpoint and metadata APIs
  * Real-time streaming support

* **Agency Visualization**
  * ReactFlow-based interactive visualization
  * `get_agency_structure`, `plot_agency_chart`, and `visualize` methods
  * HTML templates with agency statistics

* **Model Context Protocol (MCP) Support**
  * `run_mcp` method with FastMCP server integration
  * Terminal demo support with lifecycle management
  * Concurrency control with `one_call_at_a_time`

* **Citation System**
  * Methods to extract vector store citations and direct file annotations
  * Complete file handling with automatic path resolution

## Breaking Changes

**v0.x code requires migration.**

* **Agent.get_response** no longer supports delegation to other agents when used without an Agency context
* `response_validator` → `output_guardrails` and `input_guardrails`
* `response_format` parameter → `output_type` on Agent
* Thread callbacks now handle complete conversation data, not just IDs
* `agency_chart` syntax → positional arguments + `communication_flows`
* `threads_callbacks` dict → separate `load_threads_callback` and `save_threads_callback`

See the [Migration Guide](https://agency-swarm.ai/migration/guide) for detailed code examples.

## New Capabilities

* **Web Search & Computer Use**: Native OpenAI Responses API integration
* **Latest Models**: Support for the GPT-5 family and current OpenAI models
* **Third-Party Models**: Use any LiteLLM-compatible provider (Anthropic, Google, etc.)
* **Direct Thread Control**: Complete control over conversation threads and runs
* **Enhanced Streaming**: Improved real-time streaming with better event ordering

## Usage Examples

The [/examples](https://github.com/VRSEN/agency-swarm/tree/main/examples) directory contains 9 comprehensive examples demonstrating v1.0 capabilities:

* Multi-agent workflows with thread isolation and tool delegation
* Real-time streaming with async response handling  
* File processing & vision using OpenAI's built-in capabilities
* Vector stores & file search with automatic indexing
* Conversation persistence across application restarts
* Response validation with input/output guardrails
* Custom model providers and complex collaboration patterns
* FastAPI web service deployment
* MCP server integration

Each example includes detailed migration patterns and can be run independently.

## Development Journey

This stable release represents 5 months of development through 6 beta releases:
* **Beta.1** (Jun 6): Core Agents SDK foundation
* **Beta.2** (Jun 19): FastAPI, Tool Autoloading, and Better Docs
* **Beta.3** (Jul 1): AG-UI Support, CopilotKit demo, ReactFlow-based Agency Visualization
* **Beta.4** (Jul 5): Agent Schema Fixes, Visualization Rename & Flexible Dependencies
* **Beta.5** (Jul 17): Citation System, FastMCP Integration, and Enhanced Agent Communication
* **Beta.6** (Aug 26): Feature Parity & Stability Improvements

## Quality Assurance

* **All Tests Passing** ✅ (304 tests)
* **Type Safety**: Full MyPy compatibility with comprehensive type annotations
* **Production Tested**: Extensively tested through beta program
* **Documentation**: Complete migration guide and API documentation

## Install

```shell
pip install agency-swarm
```

## Quick Start

```python
import asyncio
from agency_swarm import Agent, Agency, function_tool, ModelSettings

@function_tool
def calculate_sum(a: int, b: int) -> int:
    """Calculates the sum of two numbers."""
    return a + b

ceo = Agent(
    name="CEO",
    description="Manages tasks and coordinates with other agents",
    instructions="You are a helpful CEO agent.",
    model_settings=ModelSettings(model="gpt-5-mini")
)

calculator = Agent(
    name="Calculator", 
    description="Performs calculations",
    tools=[calculate_sum],
    model_settings=ModelSettings(model="gpt-5-mini")
)

agency = Agency(
    ceo,  # Entry point
    communication_flows=[ceo > calculator]
)

async def main():
    response = await agency.get_response("Calculate 15 + 27")
    print(response.final_output)

asyncio.run(main())
```

**Full Changelog**: [v0.7.2...v1.0.0](https://github.com/VRSEN/agency-swarm/compare/v0.7.2...v1.0.0)