Agent Messages

Inter-agent and external communications — message log, topology visualization, and compose interface.

Overview

The Agent Messages page centralizes all inter-agent and external communications into two views:

• Messages — A filterable table of all messages with type, direction, channel, sender/receiver, subject, status, priority, and timestamp
• Topology — A force-directed graph visualization showing communication patterns between agents

How It Works

On load, three API calls execute:

1. /messages?orgId=...&limit=100 — Fetches the last 100 messages
2. /agents — Loads agent list for name/badge resolution
3. /messages/topology?orgId=... — Fetches the communication graph data (nodes + edges + stats)

Key Concepts

Message Types

Direction

Channels

Messages can flow through: email (📧), task (📋), or direct (💬) channels.

Stats Cards

Four stat cards at the top show aggregate counts:

• Total — All messages across all directions
• Internal — Agent-to-agent messages (high internal traffic = healthy collaboration)
• External Out — Messages sent to external recipients (monitor for over-communication)
• External In — Messages received from outside (these trigger agent workflows)

Messages Tab

The messages table supports sub-tab filtering:

• All — Every message
• Internal — Agent-to-agent only
• External — Outbound and inbound external messages
• Messages — Type: message
• Tasks — Type: task
• Handoffs — Type: handoff
• Broadcasts — Type: broadcast

Table columns: Type, Direction, Channel, From, To, Subject, Status, Priority, Time.

Topology Tab

The topology view renders a force-directed graph using a custom physics simulation:

• Nodes — Circles for agents (colored by state: green = running, gray = stopped), rectangles for external contacts (orange)
• Edges — Lines between communicating nodes, with width proportional to message count. Blue = internal, orange = external.

Interactions

• Click a node — Highlights its connections, dims everything else, and shows a detail panel below
• Click again — Deselects the node

Detail Panel

When a node is selected, a card appears showing:

• Agent name, email, and state
• Total messages sent and received
• Top 5 communication partners with message counts

Physics Simulation

The layout uses 200 iterations of:

• Charge repulsion — Nodes push apart (force ∝ 1/distance²)
• Link springs — Connected nodes pull toward ideal distance of 120px
• Center gravity — Nodes drift toward the center
• Velocity damping — 0.6x per iteration for stability

Composing Messages

Click "New Message" to open the compose modal with fields:

• From Agent — Select the sending agent
• To Agent — Select the receiving agent
• Subject — Message subject line
• Content — Message body (textarea)
• Priority — Low, Normal, High, Urgent

The message is sent via POST /messages and both the message list and topology are refreshed.

Configuration & Setup

Agent Messages works automatically once agents are created. Messages are generated by:

• Agent-to-agent task delegation
• Manual message composition via this page
• External inbound messages (email, API, etc.)
• Agent-initiated outbound communication

The org switcher filters messages to the selected organization.

API Reference

POST /messages Body

{
  "orgId": "org_123",
  "fromAgentId": "agent_abc",
  "toAgentId": "agent_xyz",
  "subject": "Monthly report ready",
  "content": "The report has been generated...",
  "priority": "normal"
}

Best Practices

• Monitor external outbound: High external outbound counts may indicate agents over-communicating with customers. Review and adjust agent instructions.
• Use the topology regularly: It reveals communication bottlenecks — if one agent is a hub for all messages, consider distributing responsibilities.
• Set meaningful subjects: Message subjects appear in the table and make filtering and auditing much easier.
• Use priority levels: Mark urgent messages as such so receiving agents can prioritize accordingly.
• Watch for isolated nodes: Agents with no topology connections may not be properly integrated into your workflows.

Troubleshooting

Related Pages