Add Execution Tracking to Your Agent (JavaScript / TypeScript SDK)

SDK3 min read

The Kynver JavaScript SDK lets you add execution tracking to any Node.js, Next.js, or server-side TypeScript agent. Once set up, every interaction your agent handles is recorded as a receipt on Kynver.

The SDK must only run on the server. Never use it with an API key in the browser or in client-side code — your key would be exposed to anyone who views the page source. Use KynverTracker only in Server Components, Route Handlers, API routes, or server-only utilities.

Installation

npm install @kynver-app/sdk

Environment Variables

Add these to your .env file. Never commit this file to source control.

# Required — find this in Dashboard → your agent → Profile
KYNVER_AGENT_DID=did:kynver:...

# Required — find this in Dashboard → your agent → Settings → API Keys
KYNVER_API_KEY=kyn_...

# Optional — only needed for Tier 2 self-sovereign signing
# after completing the ownership challenge
KYNVER_SIGNING_KEY=your_hex_key_here

Option 1 — Auto-Instrumentation (Recommended)

The easiest way to add tracking. Add this as the very first line of your agent's entry file:

import '@kynver-app/sdk/auto';

That is the entire setup. The SDK reads your environment variables and automatically intercepts calls to LangChain, OpenAI, and Anthropic clients — every LLM call your agent makes becomes a receipt. No other code changes needed.

If KYNVER_AGENT_DID is not set, auto-instrumentation is a no-op — it will not throw an error, which makes it safe to include in shared entry files.

See Auto-Instrumentation: One Import to Track Everything sdk auto instrumentation for what gets intercepted and how.

Option 2 — Manual Tracking (Full Control)

If you want explicit control over what gets tracked:

import { KynverTracker } from '@kynver-app/sdk';

const tracker = new KynverTracker({
  agentDid: process.env.KYNVER_AGENT_DID,
  apiKey: process.env.KYNVER_API_KEY,
  // signingKey: process.env.KYNVER_SIGNING_KEY  // optional, for Tier 2
});

After each agent execution, call reportExecution():

const result = await tracker.reportExecution({
  instruction: userInput,       // what the user asked
  output: agentOutput,          // what the agent replied
  taskCategory: 'chat',         // describe the type of task
  status: 'success',            // 'success', 'failure', or 'partial'
});

// result.receiptId is the receipt ID
// result.queued is true as a temporary stub fallback

Tracking High-Stakes Actions

For actions with real-world impact — payments, sent emails, data deletions — capture authorization before the action happens:

try {
  const token = await tracker.captureAuthorization({
    actionType: 'send_email',
    scope: 'user:123',
    consentMethod: 'in_app',
  });

  await doHighStakesAction();

  await tracker.reportExecution({
    instruction,
    output,
    authorizationTokenIds: [token.id],
  });
} catch (e) {
  if (e.code === 'KYNVER_AUDIT_UNAVAILABLE') return; // block the action
  throw e;
}

Showing Receipts to Your Users

After calling reportExecution(), you can display the receipt using React components:

import { KynverChatReceipt } from '@kynver-app/sdk/react';
// Optional default styles:
// import '@kynver-app/sdk/react/styles.css';

<KynverChatReceipt
  receiptId={result.receiptId}
  agentDid={agentDid}
/>

See Displaying Kynver Receipts to Your Users receipt components for all receipt component options.

User Connect

Let users link their Kynver identity to your app to see their interaction history:

const { endUserToken, connectUrl } = await tracker.getUserConnectInfo({
  returnUrl: 'https://yourapp.com/after-connect',
});
// Pass connectUrl to your frontend as a "Monitor on Kynver →" link

All Entry Points

@kynver-app/sdk — the main tracker and REST client, no React
@kynver-app/sdk/auto — one-import auto-instrumentation
@kynver-app/sdk/react — React receipt display components
@kynver-app/sdk/react/styles.css — optional default styles for receipt components