@cloudsignal/agent

Reference implementation of A2A over MQTT. The package gives a conforming MQTT 5 client agent presence (cards and will), a task inbox, request/response correlation, and the A2A task lifecycle.

Status

v0.1.x, tracking spec v0.1. Published on npm. MIT licensed.

Install

npm install @cloudsignal/agent

The underlying MQTT 5 client is a transitive dependency. Install @cloudsignal/mqtt-client directly only if you need low-level access.

Quickstart

The Agent class handles A2A peer-to-peer concerns: presence, agent-card discovery, and task delegation between agents. For calling MCP tools, use @cloudsignal/mcp-over-mqtt - the two packages compose.

import { Agent, InMemoryPersistence } from '@cloudsignal/agent';
 
const agent = new Agent({
  name: 'agent-a',
  broker: 'mqtts://broker.cloudsignal.app:8883',
  credentials: {
    orgId: process.env.ORG_ID!,
    tokenServiceUrl: 'https://tokens.cloudsignal.app',
    externalToken: process.env.AGENT_JWT,
  },
  persistence: new InMemoryPersistence(),
});
 
await agent.start();
 
// Discover peers
const peers = await agent.peers();
console.log('online peers:', peers.map((p) => p.name));

For the full A2A delegation flow (request/response, task lifecycle, cards), see A2A over MQTT.

Common operations

The most-asked patterns are shown here. The full operation list ships alongside each SDK release in the package README and the typedoc.

Discover peer agents

Subscribe to retained agent cards across the namespace and collect what's currently online. The SDK exposes both wildcard collection and named lookup; the wildcard form is shown here.

// Wildcard enumeration: collect all online peers within a short window.
const peers = await agent.peers();
console.log(`Found ${peers.length} online peers`);
for (const card of peers) {
  console.log(`  - ${card.name} (capabilities: ${card.capabilities.join(', ')})`);
}
 
// Optionally filter by capability:
const taskRunners = await agent.peers({ capability: 'task-type-1' });
 
// Exact lookup for a known peer (works on brokers that block wildcard subscriptions):
const peer = await agent.peer('agent-b');
if (peer) {
  console.log(`agent-b is online; last seen ${peer.last_seen}`);
}

See A2A Section 2.4 Agent cards (discovery) for the wire-level details.

Handle reconnection

⚠️ Future direction. The published @cloudsignal/agent v0.1.x exposes connection state via the agent.isOnline getter but does not currently surface onConnect / onDisconnect / onReconnect callbacks or an EventEmitter interface to the application layer. Reconnection lifecycle is handled internally by the underlying MQTT client. A future SDK release will expose application-level reconnection hooks; this section will document them when the surface lands.

For the wire-level reconnection model (persistent sessions + Will Delay tolerating brief blips), see Substrate Section 1.5 Session and presence.

API surface

@cloudsignal/agent covers A2A semantics, agent cards, presence, request/response, and streaming tasks. The full API is documented alongside each release in the package README; typedoc is generated alongside each release.

Pairs with

@cloudsignal/mcp-over-mqtt for the tool-server side of the wire.
@cloudsignal/mqtt-client, the underlying MQTT 5 client.

Where to go next

A2A over MQTT spec - the wire protocol this package implements.
Substrate - common-ground definitions (claims, topic conventions, QoS, sessions, cards) that A2A depends on.
Run MQTT.Agent on a local Mosquitto broker - end-to-end testbed including a working agent (note: guide is currently aspirational pending vanilla-MQTT auth).

SDK

@cloudsignal/mcp-over-mqtt