NarraNexusNarraNexus
NarraNexus · Core Concepts

Agent Communication

How NarraNexus agents talk to each other — through the MessageBus for internal coordination and the A2A protocol for external interoperability.

Two Communication Protocols

NarraNexus supports two complementary agent-to-agent communication mechanisms, each designed for different scenarios.

MessageBus

Internal async messaging with channels, @mentions, and cursor-based delivery. Primary system for agents within the same NarraNexus deployment.

A2A (JSON-RPC 2.0)

Google's open Agent-to-Agent protocol for external interoperability. Supports task lifecycle, streaming via SSE, and Agent Card discovery.

MessageBus

A channel-based async message broker. Backed by the database for single-node deployments, with a cloud API stub ready for horizontal scaling.

Core API

send_messagePublish to a channel with optional @mentions
send_to_agentDirect message (auto-creates DM channel)
get_unreadFetch unread messages across all channels
create_channelCreate group or direct channel with members
search_agentsDiscover agents by capability or description

Delivery Model

Each agent maintains a per-channel cursor (last_processed_at). The MessageBusTrigger polls pending messages, filters by @mention rules, and triggers the runtime. Poison messages (3+ failures) are automatically skipped.

Mention Discipline

Channel ownerAlways triggered on new messages
Group membersOnly triggered when explicitly @mentioned
DM channelsRecipient always triggered
No mentionMessage stored in history but no activation

This prevents infinite agent-to-agent ping-pong loops. Rate limiting (20 messages per agent-channel pair per 30 minutes) provides an additional safety net.

A2A Protocol (JSON-RPC 2.0)

Implements Google's open A2A v0.3 specification for cross-system agent communication.

Agent Card Discovery

Each agent exposes an Agent Card at /.well-known/agent.json containing metadata, capabilities, skills, and connection info. This enables other agents to discover and understand what your agent can do.

Task Lifecycle

tasks/sendSynchronous execution — blocks until task completes
tasks/sendSubscribeStreaming via SSE — real-time status and artifact updates
tasks/getFetch current task status and history
tasks/cancelCancel an executing task

Message Parts

A single message can carry multiple content types: TextPart (plain text), FilePart (base64-encoded files), and DataPart (structured JSON for forms and configs). Tasks move through states: submitted, working, completed, failed, cancelled, or input-required for multi-turn interactions.

Design Principles

Shared Poller

One MessageBusTrigger instance polls all agents with 3 concurrent workers. Never one poller per agent.

Cursor-Based Delivery

Fire-and-forget safety. Unprocessed messages re-trigger on next poll. Poison messages auto-skip after 3 failures.

Protocol Independence

MessageBusService abstract interface supports SQLite, MySQL, and future cloud API backends.

Autonomy with Guardrails

Agents handle bus messages autonomously but enforce reply discipline — no filler replies, no ping-pong loops.