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 |
SendMessageHandoff | Enables unidirectional delegation of tasks or entire interaction flows to specialized agents. When a handoff occurs, the receiving agent takes over the interaction. | 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.
Agent-level send_message_tool_class is deprecated—attach custom tools to the specific flow instead.
from agency_swarm import Agent
from agency_swarm.tools import SendMessageHandoff
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, SendMessageHandoff)])
SendMessageHandoff 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 additional fields using a Pydantic model:
from pydantic import BaseModel, Field
from agency_swarm.tools.send_message import SendMessage
class CustomSendMessage(SendMessage):
"""
Use this tool to facilitate direct, synchronous communication between specialized agents within your agency.
"""
class ExtraParams(BaseModel):
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")
def __init__(self, sender_agent, recipients=None):
super().__init__(sender_agent, recipients)
self.name = "send_message_custom" # Optional: custom name for this tool
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.
For example, name="send_message_formatted" or name="send_message_custom" and so on.
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
from agency_swarm.tools.send_message import SendMessageHandoff
class NoReminderHandoff(SendMessageHandoff):
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
from agency_swarm.tools.send_message import SendMessageHandoff
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, SendMessageHandoff)],
)
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. 
