agency-swarm

Organizes multiple AI agents into a hierarchical agency structure where agents are assigned specific roles, descriptions, and instructions that define their responsibilities. The Agency class serves as a central orchestrator that creates and initializes agents, establishes communication threads between them according to a defined agency chart, and routes user inputs through the appropriate agent chain. This hierarchical approach enables clear separation of concerns and scalable multi-agent systems where agents collaborate through structured message flows rather than direct peer-to-peer communication.

Implements a Thread system that creates and manages dedicated conversation channels between agents using OpenAI's API. Each thread maintains a message history and handles tool call execution, with messages flowing between agents according to the agency chart. The framework supports both synchronous (Thread class) and asynchronous (ThreadAsync class) communication modes, allowing agents to exchange messages, process tool results, and maintain context across multi-turn conversations. This abstraction decouples agent communication from the underlying OpenAI API details.

The ToolFactory class dynamically generates OpenAI-compatible tool schemas from Python functions or classes without requiring manual JSON schema authoring. It introspects Python type hints and Pydantic models to automatically create function calling schemas that OpenAI's API can understand. This eliminates the error-prone process of manually writing JSON schemas and keeps tool definitions co-located with implementation. The factory handles complex types, nested models, and optional parameters, converting Python's type system directly to OpenAI's schema format.

Implements a message-passing system where agents communicate through structured messages that flow through threads. When an agent needs to use a tool, the framework intercepts the tool call, executes it, and returns the result back to the agent through the message stream. This enables agents to collaborate by calling tools and sharing results without direct coupling. The system handles tool call parsing, execution, and result formatting, abstracting away the complexity of OpenAI's function calling protocol.

Enables developers to create custom agents by subclassing the Agent class and defining custom tools, instructions, and behaviors. Agents can be composed with specific tool sets and instructions that define their capabilities and expertise. The framework provides base classes and patterns for extending agents with domain-specific functionality, allowing teams to build reusable agent templates. Custom agents can override methods to customize initialization, message handling, or tool execution without modifying the core framework.

Provides a BaseTool class that serves as the foundation for all agent tools, using Pydantic models for input validation and type checking. Tools are defined as Python classes inheriting from BaseTool, with method signatures automatically converted to OpenAI function schemas. The ToolFactory class dynamically generates tool definitions from Python functions or classes, handling schema generation and validation. This approach ensures type safety at the agent-tool boundary and enables automatic schema generation for OpenAI's function calling API without manual JSON schema writing.

Provides pre-built agent implementations like BrowsingAgent and Genesis Agency that come with pre-configured tools and instructions for common tasks. BrowsingAgent includes web browsing capabilities, while Genesis Agency provides code generation and file manipulation tools. These specialized agents can be instantiated directly or extended through inheritance, reducing boilerplate for common use cases. The framework includes agents like Devid with FileWriter tools, demonstrating the pattern of agents bundled with domain-specific tool sets.

Integrates with the Model Context Protocol (MCP) standard, enabling agents to access tools and resources exposed through MCP servers. The framework includes MCP integration that allows agents to discover and call tools from external MCP-compatible services without requiring custom tool implementations. This enables agents to leverage existing tool ecosystems and third-party integrations through a standardized protocol, extending agent capabilities beyond built-in tools.

Allows developers to define agent behavior through customizable instructions, names, and descriptions that shape how agents interpret tasks and interact with tools. Each Agent class accepts a description and instructions parameter that define the agent's role, expertise, and behavioral guidelines. These instructions are passed to OpenAI's Assistants API as system prompts, enabling fine-grained control over agent personality, reasoning style, and decision-making without code changes. This approach separates agent behavior definition from implementation, enabling prompt engineering and behavioral tuning.

Provides multiple ways to interact with an agency: terminal-based CLI interface for command-line usage, web UI (Gradio-based) for browser-based interaction, and programmatic API for integration into applications. The Agency class exposes methods that can be called directly from Python code, while the framework also includes CLI utilities and web interface wrappers. This multi-interface approach enables the same agency to be deployed across different channels without reimplementation, supporting different user preferences and deployment scenarios.

Implements ThreadAsync class alongside the synchronous Thread class, enabling non-blocking agent execution and message processing. Agents can process multiple tasks concurrently using Python's asyncio, with the framework handling async context management and concurrent message flows. This enables building responsive applications where agent processing doesn't block user interactions, and multiple agents can work in parallel. The async implementation maintains the same message routing and tool execution semantics as the synchronous version.

Includes a tracking system with LocalCallbackHandler that captures agent execution events, tool calls, and message flows for observability and debugging. The TrackingManager coordinates callback handlers that log or process agent activities, enabling developers to monitor agent behavior, debug issues, and collect metrics. This abstraction allows plugging in different tracking backends (local logging, remote telemetry, etc.) without modifying agent code, supporting both development debugging and production monitoring.

Manages agent state including configuration, tools, instructions, and model settings through the Agent class. Agents maintain their own state and configuration that persists across message exchanges, enabling stateful interactions where agents remember their role and capabilities. The framework handles agent initialization with OpenAI's Assistants API, creating persistent assistant instances that maintain state server-side. This enables agents to be paused, resumed, and reused across sessions without losing context or configuration.