Agency Swarm

Organizes multiple AI agents into a hierarchical structure defined by an agency chart that specifies which agents can communicate with which other agents. The Agency class serves as the central orchestrator that creates and initializes agents, establishes dedicated communication threads between agents according to the chart topology, and routes messages through the defined hierarchy. This enables complex multi-agent workflows where agents delegate tasks up/down the chain of command rather than all agents communicating freely.

Enables agents to delegate tasks to other agents through a thread-based message passing system where each agent pair has a dedicated Thread object that manages the conversation history and tool execution. When an agent needs to delegate work, it sends a message through the thread to another agent, which processes the message, executes tools if needed, and returns results back through the same thread. The Thread class handles OpenAI Assistants API integration, tool call processing, and maintains full conversation context.

Manages agent state including instructions, tools, model configuration, and conversation history. Agents maintain their own state objects that persist across interactions, storing role definitions, tool assignments, and model parameters. The framework enables agents to be configured once and reused across multiple conversations without reconfiguration.

Provides observability into agent execution through callback handlers that track agent actions, tool calls, and message flows. The framework includes LocalCallbackHandler for local logging and TrackingManager for centralized execution tracking. Callbacks are invoked at key points in the execution flow (agent initialization, message processing, tool execution) enabling monitoring and debugging of agent behavior.

Provides Genesis Agency as a pre-built template agency that can be used as a starting point for creating custom agencies. Genesis Agency comes with pre-configured agents and communication patterns that can be extended or modified. This enables developers to start with a working multi-agent system and customize it rather than building from scratch.

Enables agents to be defined with natural language instructions and role descriptions that guide their behavior. Agents are instantiated with a name, description, and detailed instructions that specify their responsibilities, decision-making criteria, and interaction patterns. These instructions are sent to the OpenAI Assistants API and influence how the agent responds to messages and uses tools.

Provides a BaseTool class that agents can inherit from to define custom tools with Pydantic model-based input validation and automatic schema generation. Tools are defined as Python classes where the run() method contains the implementation, and Pydantic models define the input parameters with type hints and validation rules. The framework automatically converts these tool definitions into OpenAI function-calling schemas that agents can invoke, ensuring type safety and input validation before tool execution.

Provides a ToolFactory class that dynamically discovers and instantiates tools from Python modules or class definitions, enabling agents to access tools without explicit registration. The factory introspects tool classes, validates they inherit from BaseTool, and creates instances with proper initialization. This allows tools to be discovered at runtime from directories or module paths, reducing boilerplate tool registration code and enabling plugin-like tool loading patterns.

Provides deep integration with OpenAI's Assistants API, handling agent-to-API communication, function calling schema management, and tool execution result processing. The Agent class wraps the Assistants API, sending agent instructions and tools as function definitions, receiving function calls from the model, executing the corresponding tools, and feeding results back to the API. This abstraction handles the request-response loop, error handling, and schema conversion between Pydantic tool definitions and OpenAI function-calling format.

Integrates with the Model Context Protocol to enable agents to access tools and resources exposed through MCP servers. The framework can connect to MCP servers, discover available tools and resources, and expose them to agents as callable functions. This allows agents to leverage tools from external systems (databases, APIs, file systems) that implement the MCP standard without requiring custom tool wrappers.

Provides a pre-built BrowsingAgent class that specializes in web search and content retrieval tasks. The agent comes pre-configured with tools for searching the web, fetching page content, and extracting information from web sources. This enables agents to research topics, gather information from the internet, and incorporate web data into agent workflows without requiring custom tool implementation.

Provides both Thread (synchronous) and ThreadAsync (asynchronous) classes for processing agent messages and tool calls. The synchronous Thread class processes messages sequentially and waits for responses, while ThreadAsync enables concurrent message processing and tool execution. Both classes handle the OpenAI Assistants API interaction loop, tool call detection, tool execution, and result injection back into the conversation.

Integrates OpenAI's file search capabilities through FileSearch and Retrieval tools, enabling agents to search through uploaded documents and retrieve relevant content. Agents can upload files to OpenAI, search for content within those files, and retrieve specific passages. The framework handles file upload, indexing, and search query processing through the OpenAI API.

Provides multiple interfaces for interacting with agencies: terminal CLI for command-line interaction, web UI (Gradio-based) for browser-based interaction, and programmatic Python API for integration into other systems. The Agency class exposes methods that work across all interfaces, allowing the same agent system to be accessed through different channels without code changes.