version: "1.0.0" name: agent-messaging description: Coordinate agents via messaging: send, receive, and manage inter-agent communication. Use when agents need to collaborate, hand off work, or notify each other. category: ai-maestro

Agent Messaging

Overview

Multi-agent work needs communication: task assignments, handoffs, status updates, and questions — passed as messages between agents.

The Agent Messaging Protocol pattern: signed, addressed messages with types (task, result, question, notification), routed through the orchestrator.

Good messaging: explicit recipients, structured payloads, acknowledged receipt, and a searchable history.

When to use

• Agents handing off work to each other
• Coordinator assigning tasks to worker agents
• Agents requesting info or review from peers
• Broadcasting status or alerts across a fleet
• Auditing what agents told each other

Core concepts

• Addressed messages.

Every message has sender, recipient(s), and type. Broadcast sparingly; addressed messages create accountability.

• Message types.

Task (do this), result (done, here's output), question (need input), notification (FYI), escalation (needs human). Types drive handling.

• Structured payloads.

Machine-readable bodies: task specs, file paths, data — not prose paragraphs. Structure enables automation on receipt.

• Signed messages.

Cryptographic signatures prove sender identity. In multi-agent systems, spoofed instructions are a real attack vector.

• Acknowledgment.

Recipients ack receipt; senders retry or escalate on no-ack. Unacknowledged critical messages are how work silently dies.

• Threading.

Replies reference the original message ID. Threads keep multi-turn coordination coherent across many agents.

• Inbox discipline.

Agents process inboxes in priority order, archive handled messages, escalate what they can't handle. Inbox zero applies to agents too.

• History and audit.

Message log is the collaboration audit trail: who asked what, who promised what, when. Invaluable for debugging and accountability.

Practical workflow

1. Define the protocol.

Message types, required fields, addressing rules, ack expectations. Write it down — agents follow specs, not vibes.

1. Set up identities.

Each agent has a verifiable identity (keys for signing). The orchestrator routes and logs.

1. Send structured messages.

Task assignments with full specs; handoffs with artifact locations; questions with context and deadline.

1. Process inboxes.

Agents triage on wake: urgent first, tasks next, FYIs last. Ack everything actionable; archive handled.

1. Thread conversations.

Multi-turn coordination stays in threads. New topic = new thread, not a reply to an old one.

1. Escalate properly.

Blocked or confused: escalate to coordinator/human with context, not silence. Escalation is a message type, use it.

1. Audit regularly.

Review message logs for patterns: bottlenecks, dropped handoffs, unclear specs. The log reveals system problems.

1. Secure the channel.

Signatures verified, sensitive payloads encrypted, access scoped. Inter-agent messaging is infrastructure — harden it.

Common pitfalls

• Unaddressed broadcasts.

Everything to everyone = nothing to anyone. Address messages; broadcast only true announcements.

• Prose payloads.

'Hey can you look at the thing?' as a task. Structured specs or the recipient guesses — and guesses wrong.

• No acknowledgment.

Fire-and-forget task assignment. No-ack means no accountability; require acks on anything important.

• Unsigned messages.

Any agent can claim to be the coordinator. Sign messages; verify signatures — prompt injection via messaging is real.

• Thread chaos.

Ten topics in one thread. One thread per topic; discipline here prevents coordination collapse.

• Inbox neglect.

Agents that never check messages. Inbox processing must be scheduled, not optional.

• No escalation path.

Stuck agents staying silent. Escalation must be easy, expected, and blameless.

• Unlogged coordination.

Decisions made in messages nobody can find later. The log is the memory of the collaboration — keep it.