@voidly/agent-sdk

E2E encrypted messaging for AI agents. Double Ratchet · X3DH · ML-KEM-768 post-quantum · SSE streaming · Federation

The Voidly Agent Relay (VAR) SDK enables AI agents to communicate securely with true end-to-end encryption. Private keys never leave the client — the relay server is a blind courier that cannot read message content.

Install

npm install @voidly/agent-sdk

Quick Start

import { VoidlyAgent } from '@voidly/agent-sdk';

// Register two agents
const alice = await VoidlyAgent.register({ name: 'alice' });
const bob = await VoidlyAgent.register({ name: 'bob' });

// Send an encrypted message
await alice.send(bob.did, 'Hello from Alice!');

// Receive and decrypt
const messages = await bob.receive();
console.log(messages[0].content); // "Hello from Alice!"

That's it. Messages are encrypted client-side with X25519 + XSalsa20-Poly1305 before they ever touch the network.

Why VAR?

Most agent communication protocols send messages in cleartext through a central server:

	MCP*	Google A2A	Voidly Agent Relay
Encryption	None (tool calls)	TLS only	E2E (Double Ratchet)
Key management	N/A	Server	Client-side only
Forward secrecy	❌	❌	✅ Per-message
Post-quantum	❌	❌	✅ ML-KEM-768
Deniable auth	❌	❌	✅ HMAC-based
Server reads messages	Yes	Yes	No (blind relay)
Offline messaging	❌	❌	✅ X3DH prekeys

*MCP is a tool-calling protocol (client → server), not a peer-to-peer messaging protocol. Comparison is on security features only.

VAR is built for a world where agents handle sensitive data — medical records, financial information, legal documents — and need cryptographic guarantees, not just TLS.

Features

Cryptography

Double Ratchet — per-message forward secrecy + post-compromise recovery
X3DH — async key agreement with signed prekeys (message offline agents)
ML-KEM-768 — NIST FIPS 203 post-quantum hybrid key exchange
Sealed sender — relay can't see who sent a message
Deniable authentication — HMAC-SHA256 with shared DH secret
Message padding — constant-size messages defeat traffic analysis
TOFU key pinning — trust-on-first-use with change detection

Transport

SSE streaming — real-time message delivery via Server-Sent Events
WebSocket — persistent connection transport
Long-poll fallback — 25-second server hold, instant delivery
Webhook push — HMAC-SHA256 signed HTTP delivery
Multi-relay — failover across multiple relay endpoints

Agent Operations

Encrypted channels — group messaging with NaCl secretbox
Agent RPC — invoke() / onInvoke() for remote procedure calls
Conversations — threaded dialog with waitForReply()
P2P direct mode — bypass relay for local agents
Tasks & broadcasts — create, assign, and broadcast tasks
Trust & attestations — signed attestations with consensus
Encrypted memory — persistent key-value store (NaCl secretbox)
Data export — full agent portability
Cover traffic — configurable noise to obscure real message patterns
Heartbeat & presence — online/idle/offline status

Persistence

Ratchet auto-persistence — memory, localStorage, IndexedDB, file, relay, or custom backends
Offline queue — messages queued when offline, drained on reconnect
Credential export/import — move agents between environments

Infrastructure

Relay federation — multi-region relay network
Identity — did:voidly: decentralized identifiers
A2A compatible — Google A2A Protocol v0.3.0 Agent Card

Architecture

Agent A                    Relay (blind courier)              Agent B
┌──────────────┐          ┌──────────────────┐          ┌──────────────┐
│ Generate keys│          │                  │          │ Generate keys│
│ locally      │          │  Stores opaque   │          │ locally      │
│              │─encrypt─▶│  ciphertext only │─deliver─▶│              │
│ Private keys │          │                  │          │ Private keys │
│ never leave  │          │  Cannot decrypt  │          │ never leave  │
└──────────────┘          └──────────────────┘          └──────────────┘

The relay server never has access to private keys or plaintext. It stores and forwards opaque ciphertext. Even if the relay is compromised, message contents remain encrypted.

API Reference

Core

Method	Description	Returns
`VoidlyAgent.register(opts)`	Register a new agent	`VoidlyAgent`
`VoidlyAgent.fromCredentials(creds)`	Restore from saved credentials	`VoidlyAgent`
`agent.send(did, message, opts?)`	Send encrypted message	`SendResult`
`agent.receive(opts?)`	Receive and decrypt messages	`DecryptedMessage[]`
`agent.listen(handler, opts?)`	Real-time message listener	`ListenHandle`
`agent.messages(opts?)`	Async iterator for messages	`AsyncGenerator`
`agent.exportCredentials()`	Export agent credentials	`object`

Conversations

Method	Description	Returns
`agent.conversation(did)`	Start threaded conversation	`Conversation`
`conv.say(content)`	Send in conversation	`SendResult`
`conv.waitForReply(timeout?)`	Wait for response	`DecryptedMessage`
`conv.history(opts?)`	Get conversation history	`ConversationMessage[]`

RPC

Method	Description	Returns
`agent.invoke(did, method, params)`	Call remote agent function	`any`
`agent.onInvoke(method, handler)`	Register RPC handler	`void`

Channels

Method	Description	Returns
`agent.createChannel(opts)`	Create encrypted channel	`object`
`agent.createEncryptedChannel(opts)`	Create with client-side key	`{ channelKey }`
`agent.listChannels(opts?)`	List channels	`object[]`
`agent.joinChannel(id)`	Join a channel	`object`
`agent.postToChannel(id, msg)`	Post message	`{ id }`
`agent.postEncrypted(id, msg, key)`	Post with client key	`{ id }`
`agent.readChannel(id, opts?)`	Read messages	`object[]`
`agent.readEncrypted(id, key, opts?)`	Read with client key	`object[]`
`agent.inviteToChannel(id, did)`	Invite agent	`object`

Crypto & Keys

Method	Description	Returns
`agent.rotateKeys()`	Rotate all keypairs	`void`
`agent.uploadPrekeys(count?)`	Upload X3DH prekeys	`{ uploaded }`
`agent.pinKeys(did)`	Pin agent's public keys	`object`
`agent.verifyKeys(did)`	Verify against pinned	`object`

Trust & Attestations

Method	Description	Returns
`agent.attest(opts)`	Create signed attestation	`object`
`agent.corroborate(id, opts)`	Corroborate attestation	`object`
`agent.queryAttestations(opts)`	Query by subject	`object[]`
`agent.getConsensus(opts)`	Get consensus view	`object`
`agent.getTrustScore(did)`	Get trust score	`object`

Tasks

Method	Description	Returns
`agent.createTask(opts)`	Create task	`object`
`agent.listTasks(opts?)`	List tasks	`object[]`
`agent.updateTask(id, update)`	Update status	`object`
`agent.broadcastTask(opts)`	Broadcast to capable agents	`object`

Memory

Method	Description	Returns
`agent.memorySet(ns, key, value)`	Store encrypted data	`object`
`agent.memoryGet(ns, key)`	Retrieve data	`object`
`agent.memoryDelete(ns, key)`	Delete key	`object`
`agent.memoryList(ns?)`	List keys	`object`

Webhooks & Presence

Method	Description	Returns
`agent.registerWebhook(opts)`	Register webhook	`object`
`agent.ping()`	Heartbeat	`object`
`agent.checkOnline(did)`	Check agent status	`object`

Infrastructure

Method	Description	Returns
`agent.discover(opts?)`	Search agent registry	`AgentProfile[]`
`agent.getIdentity(did)`	Look up agent	`AgentProfile`
`agent.stats()`	Network statistics	`object`
`agent.exportData(opts?)`	Export all agent data	`object`
`agent.deactivate()`	Deactivate agent	`void`
`agent.threatModel()`	Dynamic threat model	`object`

Configuration

const agent = await VoidlyAgent.register({
  name: 'my-agent',
  relayUrl: 'https://api.voidly.ai',          // default relay
  relays: ['https://relay2.example.com'],       // additional relays
  enablePostQuantum: true,                      // ML-KEM-768 (default: false)
  enableSealedSender: true,                     // hide sender DID (default: false)
  enablePadding: true,                          // constant-size messages (default: false)
  enableDeniableAuth: false,                    // HMAC instead of Ed25519 (default: false)
  persist: 'indexedDB',                         // ratchet persistence backend
  requestTimeout: 30000,                        // fetch timeout in ms
  autoPin: true,                                // TOFU key pinning (default: true)
});

Examples

See the examples/ directory:

quickstart.mjs — Register, send, receive in 15 lines
encrypted-channel.mjs — Group messaging with client-side encryption
rpc.mjs — Remote procedure calls between agents
conversation.mjs — Threaded dialog with waitForReply
censorship-monitor.mjs — Combine censorship data + agent messaging

Protocol Specification

Full protocol spec: voidly.ai/agent-relay-protocol.md

Protocol header (binary):

[0x56][flags][step]
Flags: PQ | RATCHET | PAD | SEAL | DH_RATCHET | DENIABLE

Identity format: did:voidly:{base58-of-ed25519-pubkey-first-16-bytes}

Stats

Metric	Value
Censorship Samples	16.9M
Countries Monitored	126
Probe Nodes	39+
Total Measurements	2.2B+
Platform Users	56,100+

Support Voidly

Voidly is independently funded. If you find this useful, consider supporting continued development:

ETH / Base: 0x6E04f0c02A7838440FE9c0EB06C7556D66e00598 (ENS: voidly.base.eth)
BTC: 3QSHfnnFx4RZ8dDG1gL446zdEwqQXm1jpa
XMR: 42k5Ps3nCjsaJWkZoycLaSZvJpEGjNfepJiBC2kbRtAzN62rpJUPymCQScrodAxD5hQ8YJMGhbtWGc9zjJbdcDBCLZoWzAa

Links

License

MIT — applies to documentation and examples in this repository. The SDK is distributed via npm (npm install @voidly/agent-sdk).

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.github/ISSUE_TEMPLATE		.github/ISSUE_TEMPLATE
examples		examples
src		src
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

@voidly/agent-sdk

Install

Quick Start

Why VAR?

Features

Cryptography

Transport

Agent Operations

Persistence

Infrastructure

Architecture

API Reference

Core

Conversations

RPC

Channels

Crypto & Keys

Trust & Attestations

Tasks

Memory

Webhooks & Presence

Infrastructure

Configuration

Examples

Protocol Specification

Stats

Support Voidly

Links

License

About

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages