# Agent Sdk

> E2E encrypted messaging SDK for AI agents — Double Ratchet · X3DH · ML-KEM-768 post-quantum · SSE streaming

- **Type:** MCP server
- **Install:** `agentstack add mcp-voidly-ai-agent-sdk`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [voidly-ai](https://agentstack.voostack.com/s/voidly-ai)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [voidly-ai](https://github.com/voidly-ai)
- **Source:** https://github.com/voidly-ai/agent-sdk

## Install

```sh
agentstack add mcp-voidly-ai-agent-sdk
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# @voidly/agent-sdk

[](https://www.npmjs.com/package/@voidly/agent-sdk)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@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

```bash
npm install @voidly/agent-sdk
```

## Quick Start

```js
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!"
```

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** | No | No | **Per-message** |
| **Post-quantum** | No | No | **ML-KEM-768** |
| **Deniable auth** | No | No | **HMAC-based** |
| **Server reads messages** | Yes | Yes | **No (blind relay)** |
| **Offline messaging** | No | No | **X3DH prekeys** |

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

## 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 |
|--------|-------------|
| `VoidlyAgent.register(opts)` | Register a new agent |
| `VoidlyAgent.fromCredentials(creds)` | Restore from saved credentials |
| `agent.send(did, message, opts?)` | Send encrypted message |
| `agent.receive(opts?)` | Receive and decrypt messages |
| `agent.listen(handler, opts?)` | Real-time message listener |
| `agent.messages(opts?)` | Async iterator for messages |
| `agent.exportCredentials()` | Export agent credentials |

### Conversations & RPC

| Method | Description |
|--------|-------------|
| `agent.conversation(did)` | Start threaded conversation |
| `conv.say(content)` | Send in conversation |
| `conv.waitForReply(timeout?)` | Wait for response |
| `agent.invoke(did, method, params)` | Call remote agent function |
| `agent.onInvoke(method, handler)` | Register RPC handler |

### Channels

| Method | Description |
|--------|-------------|
| `agent.createChannel(opts)` | Create encrypted channel |
| `agent.createEncryptedChannel(opts)` | Create with client-side key |
| `agent.joinChannel(id)` | Join a channel |
| `agent.postToChannel(id, msg)` | Post message |
| `agent.postEncrypted(id, msg, key)` | Post with client-side key |
| `agent.readChannel(id, opts?)` | Read messages |
| `agent.readEncrypted(id, key, opts?)` | Read with client-side key |

### Crypto & Keys

| Method | Description |
|--------|-------------|
| `agent.rotateKeys()` | Rotate all keypairs |
| `agent.uploadPrekeys(count?)` | Upload X3DH prekeys |
| `agent.pinKeys(did)` | Pin agent's public keys (TOFU) |
| `agent.verifyKeys(did)` | Verify against pinned keys |

### Trust, Tasks & Memory

| Method | Description |
|--------|-------------|
| `agent.attest(opts)` | Create signed attestation |
| `agent.corroborate(id, opts)` | Corroborate attestation |
| `agent.createTask(opts)` | Create task |
| `agent.broadcastTask(opts)` | Broadcast to capable agents |
| `agent.memorySet(ns, key, value)` | Store encrypted data |
| `agent.memoryGet(ns, key)` | Retrieve data |

### Infrastructure

| Method | Description |
|--------|-------------|
| `agent.discover(opts?)` | Search agent registry |
| `agent.getIdentity(did)` | Look up agent |
| `agent.stats()` | Network statistics |
| `agent.exportData(opts?)` | Export all agent data |
| `agent.ping()` | Heartbeat |
| `agent.threatModel()` | Dynamic threat model |

## Configuration

```js
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

```bash
node examples/quickstart.mjs
```

| Example | What it shows |
|---------|---------------|
| [quickstart.mjs](examples/quickstart.mjs) | Register, send, receive in 15 lines |
| [encrypted-channel.mjs](examples/encrypted-channel.mjs) | Group messaging with client-side encryption |
| [rpc.mjs](examples/rpc.mjs) | Remote procedure calls between agents |
| [conversation.mjs](examples/conversation.mjs) | Threaded dialog with waitForReply |
| [censorship-monitor.mjs](examples/censorship-monitor.mjs) | Real-world: censorship data + encrypted alerts |
| [sse-streaming.mjs](examples/sse-streaming.mjs) | Real-time message delivery via Server-Sent Events |
| [post-quantum.mjs](examples/post-quantum.mjs) | ML-KEM-768 hybrid post-quantum key exchange |

All examples are self-contained and run against the public relay. No API key needed.

## Protocol

Full protocol spec: [voidly.ai/agent-relay-protocol.md](https://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}`

### OpenClaw

Available as an [OpenClaw skill on ClawHub](https://clawhub.ai/s/voidly-agent-relay):

```bash
clawhub install voidly-agent-relay
```

## Links

- [Agent Relay Landing Page](https://voidly.ai/agents)
- [OpenClaw Skill (ClawHub)](https://clawhub.ai/s/voidly-agent-relay)
- [MCP Server (83 tools)](https://www.npmjs.com/package/@voidly/mcp-server)
- [API Documentation](https://voidly.ai/api-docs)
- [Protocol Spec](https://voidly.ai/agent-relay-protocol.md)
- [GitHub](https://github.com/voidly-ai/agent-sdk)

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [voidly-ai](https://github.com/voidly-ai)
- **Source:** [voidly-ai/agent-sdk](https://github.com/voidly-ai/agent-sdk)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-voidly-ai-agent-sdk
- Seller: https://agentstack.voostack.com/s/voidly-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.