@cloudsignal/agent

A2A over MQTT — a reference implementation of agent-to-agent communication using MQTT 5, with a draft protocol spec.

• Production-proven: every pattern validated in a live multi-agent system (CloudSignal GTM — 5 AI agents coordinating via MQTT).
• Protocol-first: ships with SPEC.md documenting the wire protocol, not just the code.
• Broker-agnostic API: designed for any MQTT 5 broker. Initial release tested on CloudSignal; v1.0 will verify EMQX, HiveMQ, Mosquitto.
• Generic persistence: bring your own storage. No Supabase lock-in, no hidden database requirements.

Install

npm install @cloudsignal/agent @cloudsignal/mqtt-client

Quickstart

import { Agent, InMemoryPersistence } from '@cloudsignal/agent';

const scout = new Agent({
  name: 'scout',
  namespace: 'myapp',
  capabilities: ['research', 'monitor'],

  broker: 'mqtts://broker.example.com:8883',
  credentials: {
    orgId: 'org_...',
    secretKey: 'sk_...',
    userEmail: '[email protected]',
    tokenServiceUrl: 'https://auth.example.com',
  },

  persistence: new InMemoryPersistence(),

  onTask: async (task) => {
    console.log(`Got task from ${task.from}: ${task.title}`);
    const answer = `Hello! I saw your request: "${task.messages[0].content}"`;
    await task.complete(answer);
  },
});

await scout.start();

Delegating to another agent

// Fire-and-forget — result arrives on scout's onResult handler
await scout.delegate('analyst', {
  type: 'research',
  title: 'Research ACME Corp',
  prompt: 'Look up ACME Corp and summarize their tech stack',
});

// Synchronous — awaits the response
const result = await scout.request('analyst', {
  type: 'query',
  title: 'Quick fact',
  prompt: 'What city is ACME Corp headquartered in?',
}, { timeout: 30_000 });

console.log(result.result);

Discovering peers

// By name (works with any broker, exact-topic subscribe)
const analyst = await scout.peer('analyst');
console.log(analyst?.capabilities);  // ['research', 'trends']

// By capability (requires wildcard subscribe support)
const researchers = await scout.peers({ capability: 'research' });
console.log(researchers.map((p) => p.name));

Bring your own persistence

import type { Persistence, NewTask, TaskRecord, NewMessage, MessageRecord } from '@cloudsignal/agent';

class MyPersistence implements Persistence {
  async createTask(input: NewTask): Promise<TaskRecord> { /* ... */ }
  async getTask(task_id: string): Promise<TaskRecord | null> { /* ... */ }
  async updateTask(task_id: string, updates: Partial<TaskRecord>): Promise<TaskRecord | null> { /* ... */ }
  async appendMessage(input: NewMessage): Promise<MessageRecord> { /* ... */ }
  async getMessages(task_id: string): Promise<MessageRecord[]> { /* ... */ }
}

const agent = new Agent({
  name: 'scout',
  // ...
  persistence: new MyPersistence(),
});

Protocol

See SPEC.md for the full wire protocol — topic structure, Agent Card schema, task lifecycle, message envelopes, security model.

This is a DRAFT specification (v0.1). The v1.0 release will stabilize the protocol, verify broker interop across EMQX/HiveMQ/Mosquitto, and ship a matching Python implementation.

License

MIT