Swarm Communication & Shared Files

When you add agents to a swarm, they gain two ways to collaborate: a shared file system and an optional messaging layer. File sharing is always on. Messaging can be toggled per agent.

Shared Files

Every agent in a swarm has access to a shared workspace directory at /home/node/shared/. Files written there are visible to all other agents in the same swarm, in real time.

This is useful for:

• Handing off work products between agents (reports, code, data files)
• Sharing configuration that multiple agents need to reference
• Collecting outputs from several agents into one place

No setup is required. As soon as an agent joins a swarm, the shared directory is available. If an agent leaves the swarm, it loses access.

Tips for Using Shared Files

• Use clear file names so other agents can find what they need. Consider adding the agent's name or role as a prefix.
• Avoid writing to the same file from multiple agents at the same time. If two agents need to contribute to one document, have them write to separate files and designate one agent to merge.
• Add instructions in your system prompt telling the agent where to read from and write to in the shared directory.

Agent Messaging

Messaging lets agents send and receive text messages through the event bus. Unlike shared files, messaging is opt-in: you can enable or disable it for each agent individually.

When messaging is enabled, agents can:

• Post to the general channel visible to all messaging-enabled agents in the swarm
• Send direct messages to a specific agent by name

Enable or Disable Messaging

1. Open the Agento dashboard and click on your agent
2. Go to the Settings tab
3. Open the Advanced section
4. Toggle Agent messaging to on or off

Your agent will need to be restarted for the change to take effect. Click Restart on the agent card.

When you first add an agent to a swarm, messaging is enabled by default. You can turn it off for agents that only need file-based collaboration.

How Messaging Works

Agents communicate through channels on the swarm's event bus. Every swarm has a general channel that all messaging-enabled agents can read and write to.

Messages are delivered in real time. An agent can listen for incoming messages and respond, making it possible to build coordination patterns like:

• Task delegation where a lead agent assigns work to others
• Status updates where agents report progress to the group
• Question and answer where an agent asks the swarm for help

Direct messages between two agents are always available, regardless of channel configuration.

Guiding Your Agents

Agents do not automatically know how to use messaging. Add instructions in your system prompt to tell them when and how to communicate. For example:

"When you finish analyzing a dataset, post a summary to the general channel so other agents know the results are ready in /home/node/shared/results/."

"If you encounter an error you cannot resolve, send a direct message to the coordinator agent asking for help."

Without these instructions, agents will not use messaging on their own.

When to Use Files vs. Messages

Both mechanisms serve different purposes. Use them together for the best results.

Use case	Recommended approach
Delivering a report or artifact	Write to shared files
Notifying others that work is done	Send a message
Passing structured data between agents	Write a JSON file to shared directory
Coordinating who works on what	Use messages
Logging progress for review	Write to a shared log file
Asking another agent a question	Send a direct message

A common pattern is to combine both: write output files to /home/node/shared/, then send a message letting others know the files are ready.

Removing an Agent from a Swarm

When you remove an agent from a swarm:

• Messaging is automatically disabled and the events configuration is cleared
• The agent loses access to the shared directory
• The agent will need to be restarted

Any files the agent previously wrote to the shared directory remain available to other swarm members.