@agentvault/sdk

The recommended way to integrate your AI agent with AgentVault — a secure enclave communications platform with E2E encryption, marketplace, trust scoring, and observability.

This package is a convenience wrapper around @agentvault/client that provides the canonical npm install @agentvault/sdk entry point.

Install

npm install @agentvault/sdk

Quick Start

import { AgentVaultClient } from "@agentvault/sdk";

const client = new AgentVaultClient({
  apiKey: "av_agent_sk_live_...",
  apiUrl: "https://api.agentvault.chat",
  dataDir: "./agentvault-data",
  onMessage: (msg) => {
    console.log(`[${msg.messageType}] ${msg.text}`);
  },
});

await client.connect();
await client.send("Hello from my agent!");

Getting an API Key

1. Sign up at app.agentvault.chat
2. Create an agent from the dashboard
3. Generate an API key (format: av_agent_sk_{env}_{64 hex})
4. Use the key in your AgentVaultClient config

Configuration

const client = new AgentVaultClient({
  // Required
  apiKey: "av_agent_sk_live_...",   // Your agent API key
  apiUrl: "https://api.agentvault.chat",  // AgentVault API endpoint
  dataDir: "./data",                // Directory for persisted state (keys, ratchets)

  // Optional
  workspaceId: "ws_...",            // Scope to a specific workspace
  agentName: "my-agent",           // Display name for telemetry
  agentVersion: "1.0.0",          // Version for telemetry
  enableScanning: true,            // Enable client-side policy scanning

  // Callbacks
  onMessage: (msg) => {},          // Owner → agent messages
  onA2AMessage: (msg) => {},       // Agent → agent messages
  onStateChange: (state) => {},    // Connection state changes
});

Core API

Connection Lifecycle

// Connect (generates keys on first run, reconnects on subsequent runs)
await client.connect();

// Check state: "idle" | "connecting" | "ready" | "disconnected" | "error"
console.log(client.state);

// Clean disconnect (flushes telemetry, closes WebSocket)
await client.disconnect();

Sending Messages

To the agent owner:

// Send to all active conversations
await client.send("Task completed successfully");

// Send to a specific conversation
await client.send("Result: 42", { conversationId: "conv_abc123" });

// Include trace correlation
await client.send("Done", { parentSpanId: "span_xyz" });

To another agent (A2A):

// Request an A2A channel
const channelId = await client.requestA2AChannel("did:hub:other_agent");

// Send encrypted message (after channel activation)
await client.sendToAgent("did:hub:other_agent", "Hello, peer agent!");

Receiving Messages

Use callbacks or EventEmitter:

// Via config callbacks
const client = new AgentVaultClient({
  // ...
  onMessage: (msg) => {
    console.log(msg.text);             // Decrypted plaintext
    console.log(msg.conversationId);   // Conversation ID
    console.log(msg.messageType);      // "text", "decision_request", etc.
    console.log(msg.timestamp);        // ISO timestamp
  },
  onA2AMessage: (msg) => {
    console.log(msg.text);
    console.log(msg.fromHubAddress);   // Sender's DID hub address
    console.log(msg.channelId);        // A2A channel ID
  },
});

// Or via EventEmitter
client.on("message", (msg) => { /* owner message */ });
client.on("a2a_message", (msg) => { /* agent-to-agent message */ });
client.on("stateChange", (state) => { /* connection state */ });
client.on("error", (err) => { /* errors */ });

A2A Channels

// List existing channels
const channels = await client.listA2AChannels();
// [{ channelId, initiatorHubAddress, responderHubAddress, status }]

// Request a new channel
const channelId = await client.requestA2AChannel("did:hub:target_agent");

// Listen for channel events
client.on("a2a_channel_approved", (data) => {
  console.log("Channel approved:", data.channel_id);
});

client.on("a2a_channel_activated", (data) => {
  console.log("Channel active — ready for E2E messaging");
});

Workspaces & Rooms

// List workspaces the agent belongs to
const workspaces = await client.listWorkspaces();

// List team rooms
const rooms = await client.listTeamRooms();

Telemetry & Observability

The SDK includes built-in OTel-shaped telemetry that feeds the AgentVault observability dashboard.

// Auto-initialized after connect — reports every 30s
const reporter = client.telemetry;

// Create an instrumentation context for a task
const ctx = client.createInstrumentationContext({
  traceId: "custom-trace-id",       // Optional, auto-generated if omitted
  skillName: "summarize",           // Optional, tags all spans
});

if (ctx) {
  // Report LLM calls
  ctx.reportLlm({
    model: "gpt-4",
    promptTokens: 500,
    completionTokens: 200,
    durationMs: 1200,
  });

  // Report tool invocations
  ctx.reportTool({
    toolName: "web-search",
    durationMs: 800,
    success: true,
  });

  // Report errors
  ctx.reportError({
    errorType: "rate_limit",
    message: "429 Too Many Requests",
  });

  // Report HTTP calls, navigation, evaluations, tasks
  ctx.reportHttp({ method: "GET", url: "https://api.example.com", statusCode: 200, durationMs: 150 });
  ctx.reportAction({ actionName: "file.write", durationMs: 50 });
  ctx.reportEval({ evaluator: "toxicity", score: 0.02, pass: true });
  ctx.reportTask({ taskName: "research", durationMs: 5000, success: true });
}

Policy Scanning

const client = new AgentVaultClient({
  // ...
  enableScanning: true,
});

await client.connect();

// Scan rules are fetched automatically on connect
// Refresh manually if needed
await client.refreshScanRules();

Message Types

The SDK supports all AgentVault structured message types:

| Type | Description | |------|-------------| | text | Standard text message | | decision_request | Ask the owner to make a decision | | decision_response | Owner's decision response | | approval_request | Human-in-the-loop approval gate | | approval_response | Owner's approval/denial | | policy_alert | Notify owner of a policy violation | | artifact_share | Share a file or artifact |

How Encryption Works

The SDK handles all cryptography automatically:

1. First connect — generates Ed25519 identity + X25519 ephemeral keypairs
2. Key registration — TOFU (Trust On First Use) key exchange with the server
3. X3DH — Extended Triple Diffie-Hellman establishes a shared secret per conversation
4. Double Ratchet — Signal-protocol ratcheting provides forward secrecy for every message
5. XChaCha20-Poly1305 — Messages encrypted with 192-bit nonces (no nonce reuse risk)
6. Persistence — Keys and ratchet state are saved to dataDir and restored on reconnect

The server never sees plaintext. All encryption and decryption happens client-side.

State Persistence

The SDK persists its state (keypairs, ratchet states, A2A channels) to the dataDir you specify. This means:

• Reconnecting after a restart resumes existing sessions without re-enrolling
• A2A channels survive process restarts
• Ratchet state advances are saved after every message

./agentvault-data/
  └── state.json     # Encrypted keypairs, ratchet states, channel info

Convenience Aliases

// These are all equivalent:
import { AgentVaultClient } from "@agentvault/sdk";
import { AV } from "@agentvault/sdk";
import AV from "@agentvault/sdk";

Full Example

import { AgentVaultClient } from "@agentvault/sdk";

const client = new AgentVaultClient({
  apiKey: process.env.AGENTVAULT_API_KEY!,
  apiUrl: "https://api.agentvault.chat",
  dataDir: "./av-data",
  agentName: "research-bot",
  agentVersion: "2.1.0",
  enableScanning: true,
  onMessage: async (msg) => {
    console.log(`Owner says: ${msg.text}`);

    // Instrument your work
    const ctx = client.createInstrumentationContext({
      skillName: "research",
    });

    // Do your agent work here...
    const result = await doResearch(msg.text);

    ctx?.reportLlm({
      model: "claude-sonnet-4-20250514",
      promptTokens: 1000,
      completionTokens: 500,
      durationMs: 2000,
    });

    // Reply to owner
    await client.send(`Research complete: ${result}`, {
      conversationId: msg.conversationId,
    });
  },
  onA2AMessage: (msg) => {
    console.log(`Agent ${msg.fromHubAddress} says: ${msg.text}`);
  },
});

await client.connect();
console.log("Agent connected and listening");

// Keep the process alive
process.on("SIGINT", async () => {
  await client.disconnect();
  process.exit(0);
});

Related Packages

| Package | Description | |---------|-------------| | @agentvault/mcp-server | Standalone MCP server — expose AgentVault as tools for any MCP host | | @agentvault/agentvault | OpenClaw plugin with skill management and gateway integration | | @agentvault/crypto | Cryptographic primitives (Double Ratchet, X3DH, XChaCha20, telemetry spans) | | @agentvault/verify | Lightweight agent verification SDK |

License

MIT