🐝 Agency Swarm

!Framework.jpg?alt=media&token=8c681331-2a7a-4a69-b21b-3ab1f9bf1a23)

Overview

The Agency Swarm is a framework for building multi-agent applications. It leverages and extends the OpenAI Agents SDK, providing specialized features for creating, orchestrating, and managing collaborative swarms of AI agents.

This framework continues the original vision of Arsenii Shatokhin (aka VRSEN) to simplify the creation of AI agencies by thinking about automation in terms of real-world organizational structures, making it intuitive for both agents and users.

Migrating from v0.x? Please see our Migration Guide for details on adapting your project to this new SDK-based version.

pip install -U agency-swarm

Migrating from v0.x? See the Migration Guide.

Compatibility

• Python: 3.12+
• Model backends:

• OS: macOS, Linux, Windows

Getting Started

Recommended: Start with the Agency Starter Template before you customize anything.

1. Set Your OpenAI Key:

export OPENAI_API_KEY="YOUR_API_KEY"

1. Create Tools:

from agency_swarm import function_tool
@function_tool
    def my_custom_tool(example_field: str) -> str:
        """A brief description of what the custom tool does."""
        return f"Result: {example_field}"

or with BaseTool:

from agency_swarm.tools import BaseTool
    from pydantic import Field
class MyCustomTool(BaseTool):
        """
        A brief description of what the custom tool does.
        The docstring should clearly explain the tool's purpose and functionality.
        It will be used by the agent to determine when to use this tool.
        """
# Define the fields with descriptions using Pydantic Field
        example_field: str = Field(
            ..., description="Description of the example field, explaining its purpose and usage for the Agent."
        )
def run(self):
            """
            The implementation of the run method, where the tool's main functionality is executed.
            """
            # Your custom tool logic goes here
            # do_something(self.example_field)
# Return the result of the tool's operation
            return "Result of MyCustomTool operation"

or convert from OpenAPI schemas:

from agency_swarm.tools import ToolFactory
# using local file
    with open("schemas/your_schema.json") as f:
        tools = ToolFactory.from_openapi_schema(
            f.read(),
        )
# using requests
    import requests
tools = ToolFactory.from_openapi_schema(
        requests.get("https://api.example.com/openapi.json").json(),
    )

1. Define Agent Roles: Start by defining the roles of your agents. For example, a CEO agent for managing tasks and a developer agent for executing tasks.

from agency_swarm import Agent, ModelSettings
ceo = Agent(
        name="CEO",
        description="Responsible for client communication, task planning and management.",
        instructions="You must converse with other agents to ensure complete task execution.",  # can be a file like ./instructions.md
        files_folder="./files",  # files to be uploaded to OpenAI
        schemas_folder="./schemas",  # OpenAPI schemas to be converted into tools
        tools=[my_custom_tool],  # FunctionTool returned by @function_tool (or adapt BaseTool via ToolFactory)
        model="gpt-5.6-luna",
        model_settings=ModelSettings(
            max_tokens=25000,
        ),
    )

Working from examples:

- Browse ./examples for runnable demos and patterns you can adapt. - Use the .cursorrules file at the repo root with your AI coding agent (Cursor, Claude Code, etc.). - Follow the Cursor IDE guide: https://agency-swarm.ai/welcome/getting-started/cursor-ide

1. Define Agency Communication Flows:

from agency_swarm import Agency
# if importing from local files
    from Developer import Developer
    from VirtualAssistant import VirtualAssistant
dev = Developer()
    va = VirtualAssistant()
agency = Agency(
        ceo,  # CEO will be the entry point for communication with the user
        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="agency_manifesto.md",  # shared instructions for all agents
    )

In Agency Swarm, communication flows are directional. The > operator defines allowed initiations (left can initiate a chat with right).

1. Run a Demo

agency.copilot_demo()

Terminal:

agency.tui()

On first run, Agency Swarm sets up the terminal app automatically, shows a short setup message, and reuses it on later runs.

See the terminal workflow guide: https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli

Programmatic (async):

import asyncio

async def main():
    resp = await agency.get_response("Create a project skeleton.")
    print(resp.final_output)
asyncio.run(main())

Need sync? agency.get_response_sync(...) exists, but async is recommended.

Folder Structure

Recommended agent folder structure:

/your-specified-path/
│
├── agency_manifesto.md or .txt # Agency's guiding principles (created if not present)
└── AgentName/                  # Directory for the specific agent
    ├── files/                  # Directory for files that will be uploaded to OpenAI
    ├── schemas/                # Directory for OpenAPI schemas to be converted into tools
    ├── tools/                  # Directory for tools to be imported by default.
    ├── AgentName.py            # The main agent class file
    ├── __init__.py             # Initializes the agent folder as a Python package
    ├── instructions.md or .txt # Instruction document for the agent
    └── tools.py                # Custom tools specific to the agent's role.

This structure ensures that each agent has its dedicated space with all necessary files to start working on its specific tasks. The tools.py can be customized to include tools and functionalities specific to the agent's role.

Learn More

• Installation: https://agency-swarm.ai/welcome/installation
• From Scratch guide: https://agency-swarm.ai/welcome/getting-started/from-scratch
• Cursor IDE workflow: https://agency-swarm.ai/welcome/getting-started/cursor-ide
• Tools overview: https://agency-swarm.ai/core-framework/tools/overview
• Agents overview: https://agency-swarm.ai/core-framework/agents/overview
• Agencies overview: https://agency-swarm.ai/core-framework/agencies/overview
• Communication flows: https://agency-swarm.ai/core-framework/agencies/communication-flows
• Running an agency: https://agency-swarm.ai/core-framework/agencies/running-agency
• Agent Swarm CLI: https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli
• Observability: https://agency-swarm.ai/additional-features/observability

Contributing

For details on how to contribute to Agency Swarm, please refer to the Contributing Guide.

License

Agency Swarm is open-source and licensed under MIT.

Need Help?

If you need help creating custom agent swarms for your business, check out our Agents-as-a-Service subscription, or schedule a consultation with me at https://calendly.com/vrsen/ai-readiness-call