← Back to Agent
Agent Communication
Inter-agent messaging system — view message history, manage the inbox, send messages, and visualize communication topology.
Overview
For Everyone
The Communication tab is your agent's messaging center. Agents don't work in isolation — they need to coordinate with each other. This tab shows all the messages an agent has sent and received, lets you send messages on its behalf, and shows a map of which agents talk to each other the most.
For Developers
Three endpoints power this section:
GET /messages?agentId=…&orgId=…&limit=50 — Full message history (sent + received).GET /messages/inbox/:agentId?orgId=… — Unread/pending messages for this agent.GET /messages/topology?agentId=…&orgId=… — Communication graph edges showing message counts between agent pairs.
Sending a message calls POST /messages with fromAgentId, toAgentId, orgId, subject, content, and priority. Marking as read uses POST /messages/:id/read.
How It Works
- Load — All three data sources (messages, inbox, topology) are fetched on mount.
- Browse — Use the three tabs to switch views. "All Messages" shows full history, "Inbox" shows unread messages, "Topology" shows communication partners.
- Send — Click "Send Message" to open a modal. Select a recipient agent, write a subject and content, choose a priority, and send.
- Read — In the Inbox tab, unread messages appear in bold. Click "Mark Read" to acknowledge them.
- Refresh — Refreshes only the current tab's data source.
Key Concepts
All Messages Tab
A complete chronological history of messages involving this agent. Each row shows:
- Time — When the message was created.
- Direction — Sent or Received. Determined by comparing
fromAgentId with the current agent.
- From / To — Agent badges showing who sent and received the message.
- Subject — Truncated to 200px width.
- Type — Message type badge (e.g., task, notification, query).
- Priority — Color-coded priority level.
Inbox Tab
Shows messages awaiting this agent's attention. Key differences from All Messages:
- Only shows inbound messages.
- Displays read/unread status with a badge.
- Provides a "Mark Read" button for unread messages.
- Unread messages appear in bold (fontWeight: 500).
Topology Tab
A visual overview of this agent's communication partners. For each agent this one communicates with, you see:
- Agent Badge — The partner agent's identity.
- Sent Count — Number of messages sent to this partner (in blue).
- Received Count — Number of messages received from this partner (in green).
The topology is derived from the graph edges returned by the topology API. Edges where this agent is the from node count as sent; edges where this agent is the to node count as received.
Sending Messages
The Send Message modal includes:
- To Agent — A dropdown of all agents in the system except the current one. Shows display name and email.
- Subject — Required. Describe the purpose clearly.
- Content — The message body (textarea, min-height 120px).
- Priority — Low, Normal, High, or Urgent.
After sending, the modal closes and all three data sources are refreshed.
Priority Levels
| Priority | Badge | Use Case |
|---|
| Urgent | Urgent | Immediate attention required. Time-sensitive actions. |
| High | High | Important but not time-critical. Should be handled soon. |
| Normal | Normal | Standard priority. Processed in order. |
| Low | Low | Background tasks. Handle when convenient. |
Best Practices
- Use priority levels meaningfully — Priority helps agents triage incoming messages. Reserve "Urgent" for truly time-sensitive items.
- Write clear subjects — Agents parse subjects to understand message intent. "Process Q4 report" is better than "Hey".
- Monitor topology for anomalies — If an agent is sending hundreds of messages to one partner, it might indicate a loop or misconfiguration.
- Check inbox regularly — Unread messages may contain pending tasks or important information the agent hasn't processed yet.
- Use messages for coordination, not data transfer — For large data, use shared storage or knowledge bases. Messages are best for coordination signals.
Troubleshooting
Sent message not appearing in recipient's inbox
The inbox only shows messages fetched at load time. The recipient agent's dashboard needs a refresh to see new messages. Messages are delivered immediately at the API level.
"Recipient and subject are required" error
Ensure you've selected an agent from the dropdown and entered a subject. Both fields are mandatory for sending.
Topology shows no data
Communication topology is built from actual message exchanges. If the agent hasn't sent or received any messages yet, the topology will be empty.
Agent not appearing in recipient dropdown
The dropdown excludes the current agent (you can't message yourself). If other agents are missing, they may not be registered in the system. Check the Agents page.