Skip to main content

​
Installation

npm install @samvad-protocol/sdk zod
  • Package: @samvad-protocol/sdk
  • Node: 20+
  • Module format: ESM-only ("type": "module")
  • Dependencies: fastify, zod, @noble/ed25519, jose

​
What the SDK handles automatically

You write a handler. The SDK handles everything else:
ConcernWhat the SDK does
Ed25519 keysGenerates, persists, and loads keypairs from .samvad/keys/
Message signingRFC 9421 HTTP Message Signatures (Ed25519 + Content-Digest) on every envelope
Signature verificationVerifies every inbound signature against the sender’s card
Replay preventionTracks nonces in a 5-minute window
Rate limitingPer-sender sliding-window request limits + daily token budgets
Input validationValidates payloads against your Zod schema before the handler runs
Agent cardGenerates and serves /.well-known/agent.json from your config
Standard endpointsServes /agent/intro, /agent/health, task polling, SSE
DelegationIssues and verifies EdDSA JWT delegation tokens (RFC 8693)
TracingGenerates and propagates OpenTelemetry-compatible trace/span IDs

​
Core API surface

import {
  Agent,          // Build and serve an agent
  AgentClient,    // Call remote agents
  SamvadError,    // Protocol error class
  ErrorCode,      // Error code constants

  // Signing (RFC 9421)
  signRequest, verifyRequest, computeContentDigest, parseKeyId,

  // Keys
  generateKeypair, saveKeypair, loadKeypair, encodePublicKey, decodePublicKey,

  // Nonce replay protection
  NonceStore,

  // Injection scanning
  scanObjectForInjection, wrapWithContentBoundary,

  // Verify middleware (for Next.js / serverless agents)
  createVerifyMiddleware,

  // Types
  AgentCard, SkillDef, MessageEnvelope, ResponseEnvelope,
  TaskRecord, TaskStatus, TrustTier, CommunicationMode,
  SkillContext, PublicKey, RateLimit, Keypair,
  RequestSignatureHeaders, NonceCheckResult,
  VerifyMiddlewareConfig, VerifiedRequest, VerifyError, VerifyResult,
} from '@samvad-protocol/sdk'
The signing, key management, nonce store, and injection scanner modules are exported for use in custom agent implementations that don’t use the Agent class (e.g. Next.js API routes, serverless functions).

​
Building agents without Fastify

The Agent class uses Fastify under the hood. If you’re building on Next.js, Express, or serverless functions, use createVerifyMiddleware instead — it gives you the full protocol verification pipeline (nonce, rate limit, signature, trust tier) as a framework-agnostic function: 
import { createVerifyMiddleware } from '@samvad-protocol/sdk'

const verify = createVerifyMiddleware({
  agentId: 'agent://my-agent.com',
  skills: myCard.skills,
  rateLimiter: (ip) => ({ allowed: true }), // plug in your own
})

// In any route handler (Next.js, Express, etc.):
const result = await verify('POST', '/agent/message', bodyBytes, req.headers, clientIp)
if (!result.ok) {
  // result.error has { status, code, message }
  return Response.json(result.error, { status: result.error.status })
}
const { envelope, spanId } = result.data
// envelope is a verified MessageEnvelope — handle the skill call
This is what the Scout, Claw, and Research agents use internally.

​
Next steps

Building Agents

Skills, trust tiers, rate limits, async mode.

Calling Agents

Sync calls, async tasks, SSE streaming.

Delegation

JWT delegation tokens for multi-agent chains.

npm

View on npm.