Overview

Multi-agent communication is the core functionality of any multi-agent system. Unlike all other frameworks, Agency Swarm not only allows you to define communication flows in any way you want (uniform communication flows), but also to configure the underlying logic for this feature. This means that you can create entirely new types of communication or adjust it to your own needs. Below you will find a guide on how to do all this, along with some common examples.

Pre-Made SendMessage Classes

Agency Swarm contains multiple commonly requested classes for communication flows. Currently, the following classes are available:

Class Name	Description	When to Use	Code Link
`SendMessage` (default)	This is the default class for sending messages to other agents. It uses synchronous communication with basic COT (Chain of Thought) prompting and allows agents to relay files and modify system instructions for each other.	Suitable for most use cases. Balances speed and functionality.	link
`Handoff`	Enables unidirectional transfer of control to a specialized agent. When a handoff occurs, the receiving agent takes over the interaction and continues the conversation. (`SendMessageHandoff` is deprecated.)	Use for routing queries to specialized agents or sequential workflows where control should transfer completely.	link

Customizing Communication Flows

To select your own custom send message tool, simply provide it as the last argument to the communication flow tuple.

from agency_swarm import Agent, Handoff

ceo = Agent(
    name="CeoAgent",
    instructions="You are a helpful assistant.",
)

worker = Agent(
    name="WorkerAgent",
    instructions="You are a helpful assistant.",
)

agency = Agency(ceo, communication_flows=[(ceo > worker, Handoff)])

Here, the Handoff tool will be used specifically for ceo -> worker communication and nowhere else. If there were other agents in the agency connected to ceo, they would be using regular SendMessage for agent-to-agent conversations.

Creating Your Own Unique Communication Flows

To create your own communication flow, you will first need to extend the FunctionTool class from the agents SDK. The SendMessage class is built on top of FunctionTool, providing a flexible foundation for creating custom communication patterns tailored to your specific needs.

Custom SendMessage Class

To customize SendMessage parameters, extend the SendMessage class and declare extra fields directly as class-level annotations with Field():

from pydantic import Field
from agency_swarm import SendMessage

class CustomSendMessage(SendMessage):
    """
    Use this tool to facilitate direct, synchronous communication between specialized agents within your agency.
    """

    tool_name = "send_message_custom"  # Optional: custom name for this tool

    key_moments: str = Field(description="Critical context and decision points relevant to the task")
    decisions: str = Field(description="Specific decisions that guide tool choice and approach")

The fields are automatically discovered and merged into the tool schema.

Key Components

In general, all SendMessage tools have the following components:

FunctionTool Base: Extends the FunctionTool class from the agents SDK, providing async execution and standardized tool interfaces.
Dynamic Initialization: Tools are created dynamically for specific sender->recipient pairs with custom parameter schemas.
JSON Schema: Parameters are defined using JSON schema for validation and type safety.
Async Communication: Uses async/await for non-blocking communication between agents.

When creating your own SendMessage tools, extend FunctionTool and implement the on_invoke_tool method with your custom communication logic.

If you are planning to create an agent that has access to multiple SendMessage tools (using communication flow pattern), each tool must have a unique name, which must start with send_message. Set it via the tool_name class attribute, e.g. tool_name = "send_message_formatted".

Custom Handoff Class

By default, whenever a handoff occurs, prior to transferring the chat, a special system message will be added to the chat history to remind the recipient agent that a handoff has happened. This helps to reduce the amount of hallucinations and agent confusion whenever a chat transfer happens. You can customize the reminder message or disable it entirely by defining a custom Handoff class as follows (see add_reminder and handoff_reminder parameters). Set handoff_reminder on the agent that receives the handoff so the message appears in its context:

from agency_swarm import Agency, Agent, Handoff

class NoReminderHandoff(Handoff):
    add_reminder = False # Set to False to completely remove the extra message

sender = Agent(name="NoReminderSender")
recipient = Agent(name="NoReminderAgent")

agency = Agency(
    sender,
    recipient,
    communication_flows=[(sender > recipient, NoReminderHandoff)],
)

from agency_swarm import Agency, Agent, Handoff

sender = Agent(name="CustomHandoffSender")
recipient = Agent(
    name="CustomHandoffAgent",
    # Delivered to this agent whenever it receives a handoff.
    handoff_reminder="You are now the active agent. Summarize received context and answer user query.",
)

agency = Agency(
    sender,
    recipient,
    communication_flows=[(sender > recipient, Handoff)],
)

Common Use Cases

For detailed Common Use Cases, please refer to the Common Use Cases subpage.

Conclusion

Agency Swarm has been designed to give you, the developer, full control over your systems. It is the only framework that does not hard-code any prompts, parameters, or even worse, agents for you. With this new feature, the last part of the system that you couldn’t fully customize to your own needs is now gone! So, we want to encourage you to keep experimenting and designing your own unique communication flows. While the examples above should serve as a good starting point, they do not even merely scratch the surface of what’s possible here! We are looking forward to seeing what you will create. Please share it in our Discord server so we can all learn from each other.

Welcome

Core Framework

Additional Features

References

Contributing

Migration

FAQ

Pre-Made SendMessage Classes

Customizing Communication Flows

Creating Your Own Unique Communication Flows

Custom SendMessage Class

Key Components

Custom Handoff Class

Common Use Cases

Conclusion

​Pre-Made SendMessage Classes

​Customizing Communication Flows

​Creating Your Own Unique Communication Flows

​Custom SendMessage Class

​Key Components

​Custom Handoff Class

​Common Use Cases

​Conclusion

Pre-Made SendMessage Classes

Customizing Communication Flows

Creating Your Own Unique Communication Flows

Custom SendMessage Class

Key Components

Custom Handoff Class

Common Use Cases

Conclusion