---
title: "Overview"
description: "Learn how to customize communication flows for your agency."
icon: "globe"
---

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](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)               |
| `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](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)       |


#### Customizing Communication Flows

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

```python
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()`:

```python
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:

1. **FunctionTool Base**: Extends the `FunctionTool` class from the agents SDK, providing async execution and standardized tool interfaces.
2. **Dynamic Initialization**: Tools are created dynamically for specific sender->recipient pairs with custom parameter schemas.
3. **JSON Schema**: Parameters are defined using JSON schema for validation and type safety.
4. **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.

<Warning>
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"`.
</Warning>

### 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`](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py) and [`handoff_reminder`](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py) parameters). Set `handoff_reminder` on the agent that receives the handoff so the message appears in its context:

```python
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)],
)
```

```python
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](./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](https://discord.gg/7HcABDpFPG) so we can all learn from each other.
