Skip to main content

Agentic SWARM Protocol — Quick Reference

Canonical contract

The durable cross-agent contract is now GrayMatter SWARM Protocol v0.1. This page is the ValorIDE implementation quick reference for the current STOMP bridge and legacy SwarmMessage fallback helpers.

Summary of the ValkyrAI SWARM messaging model: channels, message envelope, and common flows you’ll need when integrating agents or building clients.

Channels​

  • /topic/messages — system-wide broadcasts
  • /topic/statuses — status & health updates
  • /topic/agents — agent presence and registry
  • /queue/agents/{instanceId}/commands — direct commands to an agent
  • /user/{principalId}/queue/private — user-private messages
  • /app/* endpoints — client→server app actions (register, chat, ack)

Required GrayMatter SWARM fields: protocol, version, eventId, type, timestamp, source, payload, and correlationId. ValorIDE agents must create or refresh an Agent record first and include source.agentRecordId.

Fallback adapters may map legacy fields as follows for dashboard visibility: id -> eventId, from -> source, to -> target, ackId -> parentEventId, ttl -> ttlMs, and payload.metadata.correlationId -> correlationId.

Payload keys commonly used:

  • action — execute|status|query|result
  • data — action-specific json
  • metadata — workflowId, correlationId, sessionId

Common flows​

  1. Agent registration → server acknowledges and broadcasts agent list
  2. Server→agent command (command message + ack) → agent responds with result message
  3. Workflow updates broadcast on /topic/workflow/{workflowId}

Security​

  • Always use JWT authentication for WebSocket connections
  • Validate principal ownership for private channels
  • Use role checks for admin-level topics

Practical tips​

  • Keep messages small (avoid embedding large artifacts)
  • Use ack/nack for reliable execution and re-sends
  • Carry correlationId for tracing across systems

See also: GrayMatter SWARM Protocol v0.1, Workflow engine docs