> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samvad.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> @samvad-protocol/sdk — the reference implementation of the SAMVAD protocol.

## Installation

```bash theme={null}
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:

| Concern                | What the SDK does                                                             |
| ---------------------- | ----------------------------------------------------------------------------- |
| Ed25519 keys           | Generates, persists, and loads keypairs from `.samvad/keys/`                  |
| Message signing        | RFC 9421 HTTP Message Signatures (Ed25519 + Content-Digest) on every envelope |
| Signature verification | Verifies every inbound signature against the sender's card                    |
| Replay prevention      | Tracks nonces in a 5-minute window                                            |
| Rate limiting          | Per-sender sliding-window request limits + daily token budgets                |
| Input validation       | Validates payloads against your Zod schema before the handler runs            |
| Agent card             | Generates and serves `/.well-known/agent.json` from your config               |
| Standard endpoints     | Serves `/agent/intro`, `/agent/health`, task polling, SSE                     |
| Delegation             | Issues and verifies EdDSA JWT delegation tokens (RFC 8693)                    |
| Tracing                | Generates and propagates OpenTelemetry-compatible trace/span IDs              |

## Core API surface

```typescript theme={null}
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:

```typescript theme={null}
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](https://github.com/w3rc/samvad-agents/tree/main/agents/scout), [Claw](https://github.com/w3rc/samvad-agents/tree/main/agents/claw), and [Research](https://github.com/w3rc/samvad-agents/tree/main/agents/research) agents use internally.

## Next steps

<CardGroup cols={2}>
  <Card title="Building Agents" icon="server" href="/sdk/building-agents">
    Skills, trust tiers, rate limits, async mode.
  </Card>

  <Card title="Calling Agents" icon="arrow-right" href="/sdk/calling-agents">
    Sync calls, async tasks, SSE streaming.
  </Card>

  <Card title="Delegation" icon="link" href="/sdk/delegation">
    JWT delegation tokens for multi-agent chains.
  </Card>

  <Card title="npm" icon="box" href="https://www.npmjs.com/package/@samvad-protocol/sdk">
    View on npm.
  </Card>
</CardGroup>