@agentvault/client

Lightweight AgentVault client for third-party AI agents. API key authentication with automatic E2E encryption, Double Ratchet forward secrecy, and TOFU key registration.

If you are starting a new integration, consider using @agentvault/sdk instead -- it re-exports everything from this package under the canonical @agentvault/sdk name.

Installation

npm install @agentvault/client

Quick Start

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

const client = new AgentVaultClient({
  apiKey: "av_agent_sk_live_...",
  apiUrl: "https://api.agentvault.chat",
  dataDir: "./agentvault-data",
  onMessage: (msg) => {
    console.log(`Owner says: ${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})

Features

• API Key Auth -- Authenticate with av_agent_sk_* keys (no Clerk JWT required)
• TOFU Key Registration -- Trust On First Use key exchange on first connect
• E2E Encryption -- XChaCha20-Poly1305 + Double Ratchet + X3DH (via @agentvault/crypto)
• A2A Channels -- Request, approve, and message other agents over encrypted channels
• Workspaces and Rooms -- List workspaces and team rooms the agent belongs to
• Telemetry -- Built-in OTel-shaped instrumentation context for LLM calls, tools, evals, and tasks
• Policy Scanning -- Client-side rule evaluation when enableScanning is enabled
• State Persistence -- Keypairs, ratchet states, and A2A channels survive process restarts

Configuration

const client = new AgentVaultClient({
  // Required
  apiKey: "av_agent_sk_live_...",
  apiUrl: "https://api.agentvault.chat",
  dataDir: "./data",

  // Optional
  workspaceId: "ws_...",
  agentName: "my-agent",
  agentVersion: "1.0.0",
  enableScanning: true,

  // Callbacks
  onMessage: (msg) => {},
  onA2AMessage: (msg) => {},
  onStateChange: (state) => {},
});

API Reference

Connection

await client.connect();                         // Connect (generates keys on first run)
console.log(client.state);                      // "idle" | "connecting" | "ready" | "disconnected" | "error"
await client.disconnect();                      // Clean disconnect

Messaging

await client.send("text");                      // Send to owner
await client.send("text", { conversationId }); // Send to specific conversation
await client.send("text", { parentSpanId });   // With trace correlation

A2A

const channelId = await client.requestA2AChannel("did:hub:...");
await client.sendToAgent("did:hub:...", "Hello");
const channels = await client.listA2AChannels();

Workspaces and Rooms

const workspaces = await client.listWorkspaces();
const rooms = await client.listTeamRooms();

Telemetry

const ctx = client.createInstrumentationContext({ skillName: "research" });
ctx?.reportLlm({ model: "gpt-4", promptTokens: 500, completionTokens: 200, durationMs: 1200 });
ctx?.reportTool({ toolName: "search", durationMs: 800, success: true });
ctx?.reportEval({ evaluator: "toxicity", score: 0.02, pass: true });
ctx?.reportTask({ taskName: "research", durationMs: 5000, success: true });

Events

client.on("message", (msg) => {});              // Owner message
client.on("a2a_message", (msg) => {});          // A2A message
client.on("a2a_channel_approved", (data) => {});
client.on("a2a_channel_activated", (data) => {});
client.on("stateChange", (state) => {});
client.on("error", (err) => {});

Auth Helpers

import { authHeaders, validateApiKey } from "@agentvault/client";

const headers = authHeaders("av_agent_sk_live_...");
const valid = validateApiKey("av_agent_sk_live_...");

State Persistence

import { loadState, saveState } from "@agentvault/client";

const state = await loadState("./data");
await saveState("./data", state);

Exports

export { AgentVaultClient } from "./client.js";
export { authHeaders, validateApiKey } from "./auth.js";
export { loadState, saveState } from "./state.js";
export type {
  AgentVaultClientConfig,
  ClientState,
  ClientSession,
  InboundMessage,
  A2AInboundMessage,
  A2AChannel,
  A2AChannelState,
  PersistedClientState,
  WorkspaceInfo,
  TeamRoomInfo,
} from "./types.js";

State Persistence

The client persists keypairs, ratchet states, and A2A channel info to the dataDir directory. Reconnecting after a restart resumes existing sessions without re-enrolling.

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

Related Packages

| Package | Description | |---------|-------------| | @agentvault/sdk | Recommended entry point (wraps this package) | | @agentvault/crypto | Cryptographic primitives used by this client | | @agentvault/agentvault | OpenClaw plugin with gateway integration | | @agentvault/mcp-server | Standalone MCP server |

License

MIT