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 initializes agents, establishes dedicated threads for inter-agent communication, and routes messages according to the defined communication topology. This architecture enables complex multi-agent workflows where agents delegate tasks through explicit communication channels rather than all agents having direct access to all other agents.

Implements inter-agent communication via dedicated Thread objects that manage OpenAI Assistants API conversations between specific agent pairs. Each communication channel maintains its own message history and context, with the Thread class handling message routing, tool call execution, and response processing. Messages flow through these threads with full context preservation, allowing agents to reference previous exchanges and build on prior work without losing conversation state.

Implements a complete tool execution pipeline where agents request tool calls, the framework validates inputs against Pydantic schemas, executes the tool, and returns results back to the agent for further processing. The pipeline handles error cases, type conversions, and result formatting transparently. Tool results are automatically fed back into the agent's message stream, enabling agents to use tool outputs for subsequent decisions.

Provides a Genesis Agency that can autonomously create new agents based on task requirements. This meta-agent analyzes tasks, determines what agent types are needed, and generates agent configurations including instructions, tools, and parameters. The Genesis Agency enables dynamic agent creation without manual agent definition, allowing swarms to adapt to new requirements at runtime.

Integrates OpenAI's file search and retrieval tools (FileSearch, Retrieval) that enable agents to search through uploaded documents and retrieve relevant information. These tools leverage OpenAI's vector search capabilities to find semantically relevant content from large document collections. Agents can use these tools to answer questions about documents without loading entire files into context.

Provides a standardized framework for creating custom tools by subclassing BaseTool and implementing the execute method. Tools are registered with agents at initialization time, and the framework automatically generates OpenAI function schemas from Python type hints and docstrings. Custom tools can access agent context, call other tools, and integrate with external systems through a consistent interface.

Provides a BaseTool abstract class that agents use to define and execute discrete capabilities. Tools are defined as Python classes inheriting from BaseTool with Pydantic models for input validation, enabling type-safe tool execution with automatic schema generation for OpenAI's function-calling API. The ToolFactory class dynamically generates tool schemas from Python type hints and docstrings, converting them into OpenAI-compatible function definitions that agents can invoke during execution.

Supports both blocking synchronous execution (Thread class) and non-blocking asynchronous execution (ThreadAsync class) for agent operations. The framework provides parallel execution capabilities where multiple agents can process tasks concurrently, with async mode enabling efficient handling of I/O-bound operations like API calls without blocking the event loop. Both modes maintain the same message passing semantics and tool execution patterns while differing in how they handle execution flow and concurrency.

Integrates with the Model Context Protocol to expose external tools and services as agent capabilities without requiring custom tool wrapper code. MCP servers provide standardized tool definitions that Agency Swarm automatically discovers and makes available to agents, enabling seamless integration with external systems like file systems, databases, and third-party APIs through a unified protocol interface.

Provides pre-built agent classes like BrowsingAgent with domain-specific tools and instructions baked in. These specialized agents come with curated tool sets and system prompts optimized for specific tasks (e.g., web browsing, file operations), reducing boilerplate code for common use cases. Developers can extend these specialized agents or use them as templates for creating new domain-specific agent types.

Exposes agency functionality through multiple interface layers: terminal CLI for interactive testing, web UI (Gradio-based) for user-friendly interaction, and programmatic Python API for integration into applications. The Agency class provides methods for all three modes, allowing the same agent swarm to be accessed through different interfaces without code changes. This enables flexible deployment scenarios from development to production.

Includes built-in observability through LocalCallbackHandler and TrackingManager that log agent execution, tool invocations, and message flows. The framework captures execution traces showing which agents were invoked, what tools they called, and what results were returned, enabling debugging and monitoring of multi-agent workflows. Tracking data can be exported for analysis and auditing purposes.

Enables defining agent behavior through natural language instructions and role descriptions that are passed to OpenAI's Assistants API as system prompts. Each agent has a name, description, and detailed instructions that guide its decision-making and tool usage. The framework automatically incorporates these instructions into the agent's system context, allowing fine-grained control over agent behavior without modifying code.

Manages agent state including model selection, temperature, max tokens, and other OpenAI API parameters through Agent class properties. The framework maintains agent configuration across multiple interactions, allowing consistent behavior and enabling parameter tuning for different use cases. State is preserved across message exchanges within a thread, enabling agents to maintain context and make decisions based on prior interactions.