The Anatomy of an Agent Message

When I route a task from HUNTER to CLOSER, I do not send a free-form text message. I send a structured message with six fields: sender, recipient, message type, priority, payload, and trace ID. The structure is not bureaucracy. It is what makes communication at scale traceable, debuggable, and reliable.

Sender and recipient identify who is talking to whom. Message type classifies the communication: task-dispatch, result-return, status-update, escalation, or information-share. Priority determines processing order: critical, high, normal, or low. Payload carries the actual content — the task description, the research results, the status report. Trace ID links every message in a workflow chain so that when something goes wrong at step 7, you can trace it back through steps 6, 5, 4, 3, 2, and 1 to find where the problem originated.

Most agent team failures trace to unstructured communication. An agent receives a blob of text, interprets it however the model sees fit, and produces output that the next agent may or may not understand. Structured messages eliminate interpretation ambiguity. The receiving agent does not need to figure out what kind of message this is — the type field tells it. The receiving agent does not need to guess the priority — the field tells it. The receiving agent does not need to parse free-form text to find the task — the payload contains it in a known format.

interface AgentMessage {
  sender: string;        // "HUNTER"
  recipient: string;     // "CLOSER"
  type: 'task' | 'result' | 'status' | 'escalation' | 'info';
  priority: 'critical' | 'high' | 'normal' | 'low';
  traceId: string;       // Links all messages in one workflow chain
  timestamp: string;     // ISO 8601
  payload: Record<string, unknown>;  // Typed per message type
}

// Example: HUNTER dispatching a qualified lead to CLOSER
const handoff: AgentMessage = {
  sender: 'HUNTER',
  recipient: 'CLOSER',
  type: 'task',
  priority: 'high',
  traceId: 'lead-2026-0222-047',
  timestamp: '2026-02-22T14:30:00Z',
  payload: {
    leadName: 'Acme Corp',
    qualificationScore: 8.4,
    context: 'Responded to AI strategy webinar. Decision maker confirmed.',
    requiredAction: 'Schedule discovery call within 48 hours',
  },
};