Agency Swarm: a guide to the multi-agent AI framework

Agency Swarm is a framework for orchestrating multiple AI agents, built on the OpenAI Assistants API. It was created by Arsenii Shatokhin (VRSEN), and its main goal is to support fully automated AI agencies, with a set of tools for managing tasks in different domains.

What Agency Swarm does

Agency Swarm responds to the needs of companies and developers looking for more efficient and scalable ways to automate their work:

• it coordinates several AI agents at the same time and lets them communicate and work together,
• it has a role-based system in which you define each agent's responsibilities,
• it has lightweight state management, suitable for production environments.

System architecture

Main components

• Customisable agent roles: assign responsibilities and tasks to each agent according to your requirements.
• Communication between agents: agents talk to each other without a rigid hierarchy.
• State management: settings.json tracks the state of the assistants, so each task keeps its context.
• Handoffs: tasks pass from one agent to another.

State management

• The framework stores the assistants' states in a JSON file to keep them consistent.
• Tasks run statelessly, which reduces memory overhead.
• Context is managed so that each agent works with the relevant data, which helps avoid confusion and “hallucinations”.

Distinctive features

Communication

• A dedicated SendMessage tool orchestrates the agents.
• Communication is uniform and non-hierarchical, so agents can collaborate more freely.
• You can define your own communication flows, which helps in complex workflows with many tasks and stakeholders.

Asynchronous modes

• async_mode='threading': asynchronous communication between agents.
• async_mode='tools_threading': parallel execution of agent tools, for faster results.
• Agents can also share files, which makes it easier to work together on large projects.

Practical applications

WebDevCrafters

An agency specialising in Next.js, React and MUI uses Agency Swarm to automate development tasks, from generating boilerplate code to QA checks, so that developers can focus on creative problem-solving.

CodeGuardiansAgency

This team integrated Agency Swarm with GitHub Actions to automate code reviews and check that code is consistent and follows standard operating procedures (SOP). It also produces documentation, which lowers the risk of missing important details.

Advantages over other frameworks

Compared with other multi-agent frameworks, Agency Swarm:

1. Avoids extra model calls: unlike some competitors, it does not need additional model calls just to decide which agent should speak next.
2. Gives more control over the task flow: you decide how tasks are distributed among the agents.
3. Lowers the risk of hallucination: type validation and fewer dependencies reduce the chance that the AI strays from valid data.

Compared with CrewAI

• No LangChain dependency: less complexity and overhead.
• Stronger validation: fewer errors and less confusion.
• Simpler communication: agents interact in a simpler way, which makes adoption easier for smaller teams.

Settings and extensions

Execution control

• Temperature and token parameters let you tailor each agent's output.
• Truncation strategies stop tasks from running out of control.
• Individual agents can be tuned for specialised roles, such as drafting blog posts or analysing data.

Developer tools

• Integration with Instructor for type validation, which reduces inconsistencies.
• Automatic error correction, which catches issues before they escalate.
• Custom tools that extend the framework, for domain-specific functions or connections to external APIs.

Business benefits

Operational efficiency

• Faster task execution saves the team time.
• Resource allocation lets agents handle the most important tasks first.
• Routine processes are automated, which frees people for other work.

Scalability

• New agents can be added as needs grow, without rebuilding the whole system.
• The architecture adapts to changing workflows and business goals.
• Deployment to production is straightforward, which suits companies that want to scale quickly.

Challenges and limitations

Technical

• Configuration requires basic programming knowledge.
• The official documentation can be sparse, which makes the learning curve steeper.
• The initial setup may put off teams that are new to multi-agent frameworks.

Operational

• Dependence on the OpenAI API means you need to track usage and costs.
• Agents need ongoing monitoring and management, especially as the number of tasks grows.
• API costs can spike if agents run large or frequent tasks.

Planned development

Agency Swarm is still being developed. Planned improvements include:

• more integrations with AI and workflow platforms,
• better interfaces for managing agents, to reduce complexity,
• more automation features for multi-agent systems in real business settings.

Who it is for

Agency Swarm suits organisations that want to coordinate several AI agents and add more of them over time, provided someone on the team can configure it in code.