Overview

Agency in Agency Swarm is a collection of agents that can collaborate with one another.

Benefits of Using an Agency

Utilizing an Agency consisting of multiple agents offers several benefits:

Fewer Hallucinations

Agents within an agency can supervise each other, reducing mistakes and handling unexpected scenarios more effectively.

Complex Tasks

Adding more agents allows for longer sequences of actions, enabling the completion of more complex tasks before delivering results to the user.

Scalability

Agencies allow you to scale your solutions seamlessly by adding more agents, as the complexity of your system grows.

Start with a minimal number of agents. Fine-tune them to ensure they function correctly before adding more. Introducing too many agents initially can make debugging and understanding interactions challenging.

In the latest version, the Agency class orchestrates a collection of Agent instances based on a defined structure. It provides enhanced thread management, persistence hooks, and improved communication patterns between agents.

Agency Parameters

Overview of parameters in the new Agency class:

Name	Parameter	Description
Entry Points	`*entry_points_args`	Positional arguments representing Agent instances that serve as entry points for external interaction. These agents can be directly messaged by users.
Communication Flows (optional)	`communication_flows`	List of (sender, receiver) tuples defining allowed agent-to-agent message paths. Example: `[(ceo, dev), (ceo, va)]`. Default: `None`
Name (optional)	`name`	A name for the agency instance. Default: `None`
Shared Instructions (optional)	`shared_instructions`	Instructions prepended to all agents’ system prompts in a string format or a path to markdown file. Default: `None`
Shared Tools (optional)	`shared_tools`	List of tool instances or BaseTool classes to add to all agents. Default: `None`
Shared Tools Folder (optional)	`shared_tools_folder`	Path to a folder containing tool files to load and share with all agents. Default: `None`
Shared Files Folder (optional)	`shared_files_folder`	Path to a folder of files to upload and share with all agents via a common vector store. Default: `None`
Shared MCP Servers (optional)	`shared_mcp_servers`	List of MCP server instances to attach to all agents. Default: `None`
Send Message Tool Class (optional)	`send_message_tool_class`	Fallback SendMessage tool class when a `communication_flows` entry does not specify its own tool. Prefer configuring SendMessage variants directly through `communication_flows`. Default: `None`
Load Threads Callback (optional)	`load_threads_callback`	A callable to load conversation threads for persistence. Default: `None`
Save Threads Callback (optional)	`save_threads_callback`	A callable to save conversation threads for persistence. Default: `None`
User Context (optional)	`user_context`	Initial shared context accessible to all agents during runs. Default: `None`

Example

Quick example of how to create an agency with 3 agents using the new structure:

from datetime import datetime
from agency_swarm import Agency, function_tool
from .ceo import CEO
from .developer import Developer
from .virtual_assistant import VirtualAssistant

ceo = CEO()
dev = Developer()
va = VirtualAssistant()

@function_tool
def get_current_time() -> str:
    """Get the current time."""
    return datetime.now().isoformat()

# New structure: entry points as positional args, communication flows as keyword arg
agency = Agency(
    ceo, dev,  # Entry points - these agents can interact with users
    communication_flows=[
        (ceo, dev),  # CEO can initiate communication with Developer
        (ceo, va),   # CEO can initiate communication with Virtual Assistant
        (dev, va)    # Developer can initiate communication with Virtual Assistant
    ],
    shared_instructions="./shared_instructions.md",
    shared_tools=[get_current_time],  # Available to all agents
    user_context={"project_type": "web_application"}
)

Next Steps

Make sure to learn more about Communication Flows and Running an Agency.

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Benefits of Using an Agency

Fewer Hallucinations

Complex Tasks

Scalability

Agency Parameters

Example

Next Steps

​Benefits of Using an Agency

Fewer Hallucinations

Complex Tasks

Scalability

​Agency Parameters

​Example

​Next Steps

Benefits of Using an Agency

Agency Parameters

Example

Next Steps