Skip to main content

Agentic SWARM Protocol — Quick Reference

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 fields: id (uuid), type (command|response|event|ack|nack), from, to, timestamp, payload

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: Workflow engine docs