$ show VRSEN/agency-swarm
This repository is a Python library and framework for building and deploying multi-agent AI systems. It provides a structured way to define agents with specific roles, instructions, tools, and communication flows, orchestrated by an Agency. The framework extends the OpenAI Agents SDK with production-grade features: FastAPI web serving with streaming SSE endpoints, realtime voice support via WebSocket and Twilio, MCP (Model Context Protocol) server integration with OAuth authentication, persistent conversation state with load/save callbacks, system reminders for prompt engineering, input/output guardrails, and observability hooks for Langfuse/AgentOps. It also includes CLI tools for scaffolding agents and migrating from OpenAI Assistant configurations. Architecturally, the system is a library that can be used programmatically (create Agent and Agency instances, call get_response) or deployed as a FastAPI application via run_fastapi(). The core data flow involves user messages flowing through an agent's execution pipeline, which may invoke tools (built-in, MCP, OpenAPI, LangChain), hand off to other agents via SendMessage/Handoff, and stream responses back. The ThreadManager provides flat message storage with agent/caller metadata, supporting thread isolation and persistence. The tool system uses Pydantic models for schema generation and supports concurrency control. Key entry points include the Agent and Agency classes for programmatic use, run_fastapi() for web deployment, run_realtime() for voice, run_mcp() for MCP server, and CLI commands (create-agent-template, migrate-agent, import-tool). External dependencies include the OpenAI Agents SDK (pinned), FastAPI, Pydantic, and optional integrations like LiteLLM, LangChain, and MCP SDK. The codebase demonstrates strong engineering practices with extensive test coverage (unit, integration, live API), modular design, and reusable patterns such as the BaseTool class, ToolFactory adapter, ThreadManager message store, and OAuth flow for MCP. However, it has tight coupling to the OpenAI Agents SDK internals, requiring careful maintenance as the SDK evolves.
The LLM identified 5 files worth highlighting for reuse:
Defines a base class for tools using Pydantic models. Subclasses declare fields for parameters and implement a run() method. The framework automatically generates JSON schema from the model, supports concurrency control (one_call_at_a_time), and injects runtime context (_caller_agent, _context). This pattern is reusable for any project needing type-safe, self-documenting tool definitions with minimal boilerplate.
Provides a flat message storage system with agent/caller metadata, supporting thread isolation across multiple agents. Implements callback-based persistence (load_threads_callback/save_threads_callback) and preserves duplicate message IDs for SDK compatibility. This pattern is reusable for any multi-agent chat system needing persistent, isolated conversation histories.
Implements sophisticated message filtering to construct valid API histories. Removes orphaned tool calls (by call_id, approval_request_id, reasoning-chain adjacency), deduplicates messages, and enforces reasoning chain ordering. This is critical for reliable multi-agent communication and is reusable for any system that needs to sanitize LLM conversation histories.
Implements the OAuth authorization code flow for MCP servers, including browser-based redirect, local HTTP callback server, and stdin polling fallback for CLI environments. Supports per-user token storage with path traversal protection. This pattern is reusable for any application needing OAuth authentication for external tool integrations.
Provides utilities for tracking token usage and calculating costs for OpenAI API calls. Includes tiered pricing with cache-aware cost estimation, thread-safe pricing cache, and extraction of usage from SDK run results. Reusable for any application needing cost monitoring of OpenAI API usage.