@verra/sdk

The Verra AI governance SDK. Wraps your LLM clients and agent frameworks so every prompt and response goes through Verra's detection pipeline (PII, jailbreak, prompt injection, policy violation) before reaching the model, and every call produces a receipt in your Verra dashboard.

Pairs with the Verra proxy (https://api.helloverra.com/api/proxy) for HTTP-shaped clients, or runs entirely in-process for SDK-shaped clients (LangChain, CrewAI, LlamaIndex, AutoGen, Semantic Kernel).

Install

npm install @verra/sdk

Quick start

LangChain

import { ChatOpenAI } from '@langchain/openai';
import { withVerraSecurity } from '@verra/sdk/langchain';

const llm = new ChatOpenAI({ model: 'gpt-4o' });

const safeLLM = withVerraSecurity(llm, {
  orgId: process.env.VERRA_ORG_ID,
  verraProxyUrl: 'https://api.helloverra.com',
  agentName: 'customer-support-agent',
  onBlock: { strategy: 'fallback', message: "I can't help with that." },
});

const result = await safeLLM.invoke('Hello!');

CrewAI

import { applyVerraSecurity } from '@verra/sdk/crewai';

applyVerraSecurity(agent, {
  orgId: process.env.VERRA_ORG_ID,
  verraProxyUrl: 'https://api.helloverra.com',
  agentName: 'researcher',
  onBlock: { strategy: 'throw' },
});

LlamaIndex

import { OpenAI } from 'llamaindex';
import { withVerraSecurity } from '@verra/sdk/llamaindex';

const llm = withVerraSecurity(new OpenAI({ model: 'gpt-4o' }), {
  verraProxyUrl: 'https://api.helloverra.com',
  agentName: 'my-agent',
  onBlock: { strategy: 'throw' },
});

AutoGen

import { createVerraMiddleware } from '@verra/sdk/autogen';

const middleware = createVerraMiddleware({
  verraProxyUrl: 'https://api.helloverra.com',
  agentName: 'research-agent',
  onBlock: { strategy: 'throw' },
});

const securedClient = middleware.wrapClient(modelClient);

Semantic Kernel

import { Kernel } from '@microsoft/semantic-kernel';
import { createVerraFilter } from '@verra/sdk/semantickernel';

const kernel = new Kernel();
const { promptRenderFilter, functionInvocationFilter } = createVerraFilter({
  verraProxyUrl: 'https://api.helloverra.com',
  agentName: 'sk-agent',
});

kernel.use(promptRenderFilter);
kernel.use(functionInvocationFilter);

Configuration

All integrations accept the same VerraIntegrationConfig:

| Option | Type | Notes | |---|---|---| | orgId | string | Your Verra org ID (from the admin dashboard). | | verraProxyUrl | string | Base URL of your Verra deployment. Defaults to https://api.helloverra.com. | | agentName | string | Stable identifier for this agent. Surfaces in receipts and the admin dashboard. | | onBlock | { strategy: 'throw' \| 'fallback', message?: string } | What to do when Verra blocks a call. throw raises VerraSecurityError; fallback returns the supplied message. | | onFlag | 'log' \| 'pass' \| 'throw' | What to do when a call is flagged (medium-risk findings, not blocked). Defaults to log. | | onError | 'fail_open' \| 'fail_closed' | What to do when the Verra pipeline itself errors. Defaults to fail_open. |

Direct detection pipeline

For custom integrations, the detection pipeline is exported directly:

import { runInputPipeline, runOutputPipeline } from '@verra/sdk';

const inputVerdict = await runInputPipeline({
  text: userMessage,
  policy: yourCustomerPolicy,
});

if (inputVerdict.action === 'block') {
  // handle block
}

See the docs for the full API reference.

ML detection

The SDK's PII, jailbreak, and prompt-injection detectors call an ML inference service. Three deployment modes; pick the one that fits your privacy and cost posture.

| Mode | Set | Auth | Where text goes | |---|---|---|---| | A. Verra-hosted | ML_INFERENCE_URL=https://api.helloverra.com/api + VERRA_API_KEY=… | SDK adds x-verra-key automatically | Verra's in-VPC detector service; metered through receipts | | B. Self-hosted | ML_INFERENCE_URL=http://your-host:8080 | none | Stays on your infrastructure; run the open-source services/ml-inference Docker image | | C. No ML | leave ML_INFERENCE_URL unset | n/a | Nowhere; SDK falls back to regex-only detection |

If both env vars are set, the SDK sends x-verra-key on every detection call. If only ML_INFERENCE_URL is set, no auth header is sent (Mode B). If neither is set, the ML-backed detectors short-circuit and the SDK relies on regex + LLM-judge layers.

What Verra stores from detection calls

Verra never stores the raw scanned text. Receipts capture only the text length, a hash for deduplication, the requested detectors, and the resulting scores. This matches how the proxy handles prompts and completions, and applies regardless of which mode you choose.

License

MIT