Quick Start

const { AI2AI } = require('ai2ai');

const agent = new AI2AI({ name: 'my-agent', port: 18800 });
await agent.start();
await agent.send('other-agent', 'Hello from my AI!');

Features

• 🔐 Ed25519 signatures — Every message is cryptographically signed
• 🔒 X25519 encryption — Optional payload encryption (AES-256-GCM)
• 📡 Agent discovery — Registry, DNS TXT, mDNS/Bonjour, .well-known
• 🔄 Reliability — Retry with backoff, circuit breaker, persistent queue
• 📨 Delivery receipts — sent/delivered/read confirmations
• 🛡️ Security hardening — Rate limiting, nonce tracking, message expiry, blocklist
• 🔑 Key rotation — Rotate keys with automatic announcement
• 💀 Dead letter queue — Failed messages preserved for retry
• 👤 Human-in-the-loop — Approval workflow for sensitive actions
• 🧵 Conversation threading — State machine: proposed → negotiating → confirmed
• 🛒 Commerce — Request quotes, make offers, accept/reject (always requires human approval)
• 📦 Zero dependencies — Node.js built-ins only

Installation

npm install ai2ai

Or clone directly:

git clone https://github.com/DarrenEdwards111/ai2ai-protocol.git

Basic Usage

Create an Agent

const { AI2AI } = require('ai2ai');

const agent = new AI2AI({
  name: 'alice-agent',
  humanName: 'Alice',
  port: 18800,
});

// Listen for messages
agent.on('message', (payload, from) => {
  console.log(`Message from ${from.human}: ${payload.message}`);
});

// Listen for requests
agent.on('request', (intent, payload, from) => {
  console.log(`Request: ${intent} from ${from.human}`);
});

await agent.start();

Send Messages

// Add a contact
agent.addContact('bob-agent', { endpoint: 'http://localhost:18801/ai2ai' });

// Send a message
await agent.send('bob-agent', 'Hey Bob, are you free for lunch?');

// Send a structured request
await agent.request('bob-agent', 'schedule.meeting', {
  subject: 'Team Lunch',
  proposed_times: ['2026-02-20T12:00:00Z'],
});

Discovery

Registry

const { RegistryServer, RegistryClient } = require('ai2ai/src/registry');

// Start a registry server
const registry = new RegistryServer();
await registry.start(18820);

// Register your agent
const agent = new AI2AI({
  name: 'my-agent',
  port: 18800,
  registry: 'http://localhost:18820',
});
await agent.start();
await agent.register();

// Discover other agents
const agents = await agent.discover({ capability: 'schedule.meeting' });

DNS TXT Record

Add a DNS TXT record:

_ai2ai.yourdomain.com  TXT  "endpoint=https://your-server.com/ai2ai"

Local Network (mDNS)

const { startLocalDiscovery } = require('ai2ai/src/registry');

const discovery = startLocalDiscovery((agent) => {
  console.log(`Found: ${agent.agentId} at ${agent.endpoint}`);
});

discovery.announce('my-agent', 18800, 'Alice');
discovery.query();

Security Model

| Feature | Description | |---------|-------------| | Ed25519 signatures | Every message signed with sender's private key | | X25519 encryption | Optional ECDH + AES-256-GCM payload encryption | | Nonce tracking | Prevent replay attacks | | Message expiry | Reject messages older than configurable TTL (default 24h) | | Rate limiting | Per-agent request throttling | | Agent blocklist | Block specific agents | | Key rotation | Rotate keys with announcement to contacts | | Verification cache | Cache signature verification results | | Trust levels | none → known → trusted (commerce always requires approval) |

Integrations

OpenClaw

const { createOpenClawAdapter } = require('ai2ai/src/integrations/openclaw');

const adapter = createOpenClawAdapter({
  agentName: 'my-agent',
  onMessage: (payload, from) => console.log(from, payload),
  notify: (text) => console.log(text),
});
await adapter.start();

Webhooks

const { createWebhookForwarder } = require('ai2ai/src/integrations/webhook');

const webhook = createWebhookForwarder({
  url: 'https://your-server.com/webhook',
  secret: 'shared-secret',
});

agent.on('message', webhook.handler);

Express Middleware

const { ai2aiMiddleware } = require('ai2ai/src/integrations/express');

app.use('/ai2ai', ai2aiMiddleware({
  agentName: 'my-agent',
  onMessage: (payload, from, envelope) => { ... },
}));

Protocol Specification

See SPEC.md for the full protocol specification including:

• Message envelope format
• All message types and intent types
• Security model
• Discovery mechanisms
• Error codes
• Versioning rules

API Reference

AI2AI (Production Client)

const agent = new AI2AI({
  name: string,           // Agent ID
  humanName: string,      // Human operator name
  port: number,           // Server port (default: 18800)
  registry: string,       // Registry URL
  timeout: number,        // Request timeout ms (default: 30000)
  messageTTL: number,     // Message TTL ms (default: 86400000)
  dataDir: string,        // Data directory
});

await agent.start(port?)          // Start HTTP server
await agent.stop()                // Stop agent
await agent.register(url?)        // Register with registry
await agent.send(id, msg, opts?)  // Send message
await agent.request(id, intent, payload, opts?)  // Send request
await agent.discover(query?)      // Search registry
agent.addContact(id, info)        // Add/update contact
agent.getContact(id)              // Get contact
agent.on('message', handler)      // Listen for messages
agent.on('request', handler)      // Listen for requests
agent.on('receipt', handler)      // Listen for receipts

RegistryServer

const server = new RegistryServer({ staleTimeout: 120000 });
await server.start(port)  // Start registry HTTP server
server.stop()             // Stop server

RegistryClient

const client = new RegistryClient({ registryUrl, agentId });
await client.register(agentInfo)  // Register
await client.search(query?)       // Search agents
await client.resolve(agentId)     // Resolve by ID
await client.deregister()         // Remove registration
await client.heartbeat()          // Send keepalive

Reliability

const { retryWithBackoff, CircuitBreaker, Deduplicator, DeliveryTracker, DeadLetterQueue, PersistentQueue } = require('ai2ai-protocol/src/reliability');

Security

const { KeyRotation, RateLimiter, NonceTracker, Blocklist, VerificationCache, isMessageExpired } = require('ai2ai-protocol/src/security');

Examples

See the examples/ directory:

• basic-agent.js — Minimal working agent
• two-agents.js — Two agents chatting
• with-registry.js — Agent discovery via registry
• webhook-receiver.js — Forward to webhooks
• openclaw-skill.js — OpenClaw integration

Tests

cd src
node test.js      # Original 146 tests
node test-v1.js   # New v1.0 tests (110 tests)

Contributing

1. Fork the repo
2. Create a feature branch
3. Run tests: cd src && node test.js && node test-v1.js
4. Submit a PR

License

Apache 2.0 — See LICENSE

| Intent | Description | |--------|-------------| | schedule.meeting | Propose times, negotiate, confirm | | schedule.call | Schedule a call | | schedule.group | Find time for multiple people | | message.relay | Pass a message to another human | | info.request | Ask for specific information | | info.share | Share information (one-way) | | social.introduction | Introduce two humans via agents | | commerce.request | Request a quote | | commerce.offer | Make an offer | | commerce.accept | Accept a deal | | commerce.reject | Decline a deal |

Intents are extensible. Add your own.

🔒 Security

• Ed25519 message signing — every message is cryptographically signed
• X25519 + AES-256-GCM end-to-end payload encryption
• Trust levels — none → known → trusted (escalate over time)
• Human approval — required for all actions by default
• Rate limiting — per-agent, prevents spam
• Prompt injection protection — structured JSON, not raw text execution

📨 Message Format

Every AI2AI message is a JSON envelope:

{
  "ai2ai": "0.1",
  "id": "uuid",
  "timestamp": "2026-02-07T19:00:00Z",
  "from": {
    "agent": "darren-assistant",
    "human": "Darren"
  },
  "to": {
    "agent": "alex-assistant",
    "human": "Alex"
  },
  "conversation": "conv-uuid",
  "type": "request",
  "intent": "schedule.meeting",
  "payload": { ... },
  "requires_human_approval": true,
  "signature": "ed25519-signature"
}

Message types: ping | request | response | confirm | reject | inform

🏗️ Architecture

┌──────────────────────┐         ┌──────────────────────┐
│   Darren's Setup     │         │    Alex's Setup       │
│                      │         │                       │
│  Human ←→ OpenClaw   │         │  Human ←→ OpenClaw    │
│           ↕          │  HTTP   │           ↕           │
│     AI2AI Server ────┼────────→┤     AI2AI Server      │
│     (port 18810)     │←────────┼     (port 18811)      │
│           ↕          │         │           ↕           │
│  Keys | Trust | Log  │         │  Keys | Trust | Log   │
└──────────────────────┘         └──────────────────────┘

• ai2ai-server.js — HTTP endpoint, receives incoming messages
• ai2ai-client.js — Sends outgoing messages
• ai2ai-handlers.js — Intent processing (schedule, message, commerce, etc.)
• ai2ai-crypto.js — Ed25519 signing & verification
• ai2ai-encryption.js — X25519 + AES-256-GCM payload encryption
• ai2ai-trust.js — Contact management & trust levels
• ai2ai-queue.js — Disk-backed retry queue with exponential backoff
• ai2ai-discovery.js — DNS, mDNS, .well-known agent discovery
• ai2ai-conversations.js — Conversation state machine & expiry
• ai2ai-logger.js — Structured audit logging
• ai2ai-bridge.js — CLI tool for agents to use the protocol
• openclaw-integration.js — Natural language command parsing

🎯 Real-World Scenarios

Six runnable demos that prove AI2AI works for real multi-agent tasks. Each spins up local agents, completes a task end-to-end, and verifies the result.

# Run all demos
node examples/demo-schedule.js      # Schedule Meeting
node examples/demo-price-quote.js   # Price Comparison
node examples/demo-research.js      # Collaborative Research
node examples/demo-delegation.js    # Delegation Chain
node examples/demo-info-exchange.js # Information Exchange
node examples/demo-approval.js      # Human Approval Flow

1. 🗓️ Schedule Meeting

Two agents negotiate a meeting time. Agent B checks its calendar and proposes slots, Agent A picks one, both confirm.

  [Alice] Requesting meeting with Bob: "Project Sync"
  [Bob] Checking calendar... proposing 3 available slots
  [Alice] Picking: 2026-03-10T14:00
  ✅ Both agents agreed: "Project Sync" at 2026-03-10T14:00

2. 💰 Price Comparison

A buyer agent sends quote requests to two merchant agents, collects responses, and picks the cheapest.

  [Merchant B] responding £28
  [Merchant C] responding £32
  ✅ Buyer selected merchant-b at £28

3. 🔬 Collaborative Research

A researcher agent asks a specialist for technical analysis. The specialist returns structured data with sources, which gets incorporated into a report.

  [Specialist] Responding with structured answer (confidence: 0.95)
  [Researcher] Report compiled: "LoRa Modulation Technical Brief" with 3 sections
  ✅ Report includes specialist contribution

4. 🔗 Delegation Chain

Manager → Coordinator → Worker. The coordinator can't fully complete the task, so it delegates a subtask to the worker, combines results, and returns to the manager.

  [Coordinator] delegating to worker
  [Worker] Subtask complete
  [Coordinator] Combining results and sending to manager
  ✅ Delegation chain complete: manager ← coordinator ← worker

5. 📊 Information Exchange

An agent requests sensor data twice, 2 seconds apart. Verifies both readings have different timestamps and values.

  [Sensor] Reading #1: 21.3°C at 2026-02-15T04:16:48Z
  [Sensor] Reading #2: 21.6°C at 2026-02-15T04:16:50Z
  ✅ Two readings received with different timestamps

6. 🔐 Human Approval Flow

A purchase request for £500 triggers a human approval requirement (threshold: £100). Simulates the human approving before confirming.

  [Approver] ⚠️ Amount £500 exceeds £100 — human approval required
  [Approver] 👤 Human reviewed and APPROVED
  ✅ Human approval flow completed

🧪 Tests

cd src/
node test.js

✅ Passed: 146
❌ Failed: 0
⏭️  Skipped: 1 (mDNS requires multicast network)

🗺️ Roadmap

• [x] Protocol spec v0.1
• [x] Core implementation (server, client, handlers)
• [x] Ed25519 signing
• [x] X25519 encryption
• [x] Trust management
• [x] Message queuing with retry
• [x] 11 intent handlers
• [x] Network discovery (DNS, mDNS, well-known)
• [x] Conversation state machine
• [x] OpenClaw skill integration
• [x] Two-agent live demo
• [x] 146 tests passing
• [ ] Agent directory / registry
• [ ] ActivityPub bridge
• [ ] Multi-runtime SDKs (Python, Go)
• [ ] Mobile agent support
• [ ] Payment rails for commerce intent
• [ ] Hosted hub (managed endpoints)

⚔️ Why AI2AI?

Most agent-to-agent protocols assume you're inside a trusted corporate network. AI2AI assumes the internet is hostile — because when your AI talks to agents it's never met, on servers it doesn't control, security isn't optional.

| Feature | AI2AI | Google A2A | Agent Zero FastA2A | |---------|-------|------------|-------------------| | Cryptographic signatures | Ed25519 on every message ✅ | None (relies on OAuth) ❌ | None ❌ | | End-to-end encryption | X25519 + AES-256-GCM ✅ | None ❌ | None ❌ | | Discovery methods | Registry + DNS + mDNS ✅ | Agent Cards only | Agent Cards only | | Reliable delivery | Retry, circuit breaker, receipts ✅ | Not specified ❌ | Not specified ❌ | | Replay protection | Nonce tracking + message TTL ✅ | Not specified ❌ | Not specified ❌ | | Key rotation | Automatic key lifecycle ✅ | N/A ❌ | N/A ❌ | | Dead letter queue | Failed messages preserved ✅ | Not specified ❌ | Not specified ❌ | | Trust model | Zero-trust, hostile internet ✅ | Corporate OAuth | None | | Dependencies | Zero ✅ | Google Cloud ecosystem | Python ecosystem | | Battle-tested | Live demo, 256 tests ✅ | Spec only | Basic wrapper |

Google's A2A is built for enterprise — managed identities, corporate infrastructure, centralised orchestration. Great if you're connecting Salesforce agents inside a data centre.

AI2AI is built for the open internet — where personal AI companions talk to strangers, negotiate on behalf of their humans, and form trust networks from scratch. Every message signed. Every payload encrypted. Zero dependencies.

"The internet is hostile. Your protocol should know that."

🤔 FAQ

Q: Does this need powerful models? A: No. qwen2:7b (free, local) handles structured JSON negotiation perfectly. But it works just as well with cloud APIs like Claude, GPT, or Gemini if you prefer. The protocol is model-agnostic — it's just JSON.

Q: How is this different from MCP or ACP? A: MCP connects agents to tools. ACP connects agents to services. AI2AI connects agents to each other, acting as human representatives. It's the social layer.

Q: What about bad actors? A: Human-in-the-loop by default. Your agent never commits without your approval. Same model as email — you can receive spam, but you don't have to open it.

Q: Can non-OpenClaw agents use this? A: Yes. The protocol is a JSON HTTP API. Any agent framework can implement it.

📄 License

Apache 2.0 — Build on it. Fork it. Make it better. Patent protected.

🌍 The Vision

Email gave humans a decentralised way to communicate. The web gave humans a decentralised way to publish. AI2AI gives AI agents a decentralised way to act on behalf of humans.

No company should own the protocol by which our digital representatives talk to each other.

The protocol is the product. The simpler it is, the more people build on it.

Built in one night. Open forever. 🦞