Overview

What is Verra?

Verra is a drop-in security proxy that sits between your AI agents and your LLM providers. Every request is scanned, governed by policy, and logged, without any changes to your agent code.

You point your agent at https://api.helloverra.com/api/proxy instead of https://api.openai.com and add one header. Verra forwards the request to the real provider after running its security pipeline.

Your Agent
    │
    │  POST /api/proxy  ·  x-verra-key: va-...
    ▼
┌──────────────────────────────────────────┐
│              Verra Proxy                 │
│                                          │
│  Auth → DLP → Policy → Route → Forward  │
│                         │                │
│                    Scan Response         │
└──────────────────────────────────────────┘
        │                       │
        ▼                       ▼
  LLM Provider             Audit Log

Works with OpenAI, Anthropic, Azure OpenAI, Amazon Bedrock, and Google Vertex AI out of the box. No infrastructure changes required.

Quickstart

Up in three steps

No SDK install required. Verra is a pure HTTP proxy: change one URL, add one header. Your existing OpenAI-compatible client works without modification.

1. Get your Verra key

After signing up, navigate to Agents → Register Agent in the Verra admin dashboard and register your agent. The key is shown once after registration. Keys have the prefix va-.

Store it as an environment variable, never commit it to source control.

2. Point your agent at Verra

Change the base URL in your LLM client and add the x-verra-key header. Everything else stays the same.

3. Verify in the dashboard

Make any LLM call. Verra auto-registers your agent on first call. Open the admin dashboard → Receipts to see the audit log entry with risk level, DLP findings, and trace ID.

OpenClaw

OpenClaw supports a baseUrl override per model provider. Point it at Verra and use your Verra agent key as the API key with no other changes needed.

Replace anthropic with openai if your agents use GPT models. All OpenClaw sessions flow through Verra automatically.

LangChain callback (optional)

If you use LangChain, install the npm SDK and attach the callback handler. See the npm SDK section for full configuration options.

npm SDK

@helloverra/sdk

The Verra npm package ships the detection pipeline, LangChain and CrewAI integrations, and all types as a standalone library. Use it to run Verra's security checks directly in your Node.js application, no proxy hop required.

LangChain integration

Import from @helloverra/sdk/langchain. The callback handler auto-registers your agent on first call and reports a receipt to your Verra dashboard for every LLM invocation.

CrewAI integration

Import from @helloverra/sdk/crewai. Attach step and task callbacks to any CrewAI agent to inspect tool inputs and outputs.

Direct pipeline usage

Run the detection pipeline directly without an integration wrapper. Useful for custom frameworks or serverless handlers.

Configuration

Observability

Observability integrations

LangSmith

Verra and LangSmith complement each other: LangSmith gives you execution traces and prompt debugging; Verra gives you security enforcement and compliance receipts. Two things work out of the box.

1. Run IDs in receipts. When you use VerraCallbackHandler, every receipt written to the Verra dashboard includes the LangSmith run_idin its findings.langsmith_run_id field. You can look up the corresponding LangSmith trace directly from any blocked or flagged receipt.

2. Automatic tool gating. VerraCallbackHandler now hooks handleToolStart and calls /api/gate/tool-inputautomatically on every tool invocation, with no manual gate call needed. Blocked tools raise a VerraSecurityError (or return your fallback message) before the tool runs.

Exporting Verra traces to LangSmith

LangSmith accepts OpenTelemetry traces over OTLP. Since Verra is OTel-native, you can send Verra spans (proxy requests, risk analysis, upstream LLM calls) directly into your LangSmith project by setting two environment variables:

Verra spans will appear in LangSmith as a parallel trace alongside your LangChain execution trace, tagged with gen_ai.* and verra.* attributes. No code changes required, just the environment variables.

Other OTLP backends

The same OTEL_EXPORTER_OTLP_ENDPOINT variable works with any OpenTelemetry-compatible backend. Point it at Grafana Tempo, Jaeger, Honeycomb, Datadog, or your own collector.

Each proxy request creates a root span (verra.proxy) with child spans for risk analysis and the upstream LLM call. Token usage is recorded asgen_ai.usage.input_tokens and gen_ai.usage.output_tokens. Request counts and latency are exported as OTLP metrics every 60 seconds.

Configuration

Configuration

Environment variables

Policies

Policies are managed in the admin dashboard under Settings → Policies. Each policy is a named rule set that specifies which agents it applies to, which checks to run, and what action to take (pass / warn / block / escalate).

Model routing

Configure a private model target in Settings → Model Routing. When a request is flagged as high-risk, Verra routes it to the private endpoint instead of the public provider, no raw data leaves your network.

API Reference

API Reference

POST /api/proxy

The proxy endpoint accepts any OpenAI-compatible request body. Verra inspects it, applies policies, then forwards to the configured upstream provider.

Request headers

Response headers

Blocked requests

When a request is blocked by policy, Verra returns 403 Forbidden with a structured error body instead of forwarding to the LLM.

Escalated requests

Escalated requests return 202 Accepted immediately. The upstream call is held pending human approval. Your agent should surface the approval URL to the user; the call proceeds once approved, or expires after one hour.

GET /api/receipts

Query the audit log. Requires an admin API key (va-admin_...).

Returns a JSON array of receipt objects. Each receipt contains id, agent_id, trace_id, risk_level, action, findings, input_hash, output_hash, and created_at. Raw text is never returned.

Concepts

How the pipeline works

Every request through Verra passes five sequential stages. Each stage can independently pass, warn, block, or escalate the request.

1. Auth

The x-verra-key header is verified against your organization. Invalid or revoked keys receive a 401 immediately, before any content is read.

2. Data Loss Prevention (DLP)

The request body is scanned for sensitive patterns before it reaches the model. Four detectors run in parallel so latency is the max of the slowest detector, not a sum.

3. Policy evaluation

Policies are evaluated in order. The first matching rule determines the action. If no rule matches, the default action (configurable, defaults to pass) applies.

4. Tool access control

For agentic requests that include tool definitions, Verra validates against a four-layer gate: RBAC, agent-type permission matrix, behavioral baseline, and content scan. An HR agent cannot invoke code execution tools; a finance agent cannot query external databases, regardless of what the prompt says.

5. Model routing

Low-risk requests are forwarded to your configured LLM provider. High-risk requests are routed to your private model endpoint, keeping sensitive data inside your network boundary. You configure both targets in the dashboard.

Multi-turn session analysis

Pass x-verra-session-id on each request to enable session-aware detection. Verra loads the last 10 messages from that session and prepends them as context before running the pipeline. This catches slow-burn attacks that unfold across multiple turns, for example an adversary who gradually shifts the model's behavior over several exchanges rather than in a single message.

Agent-to-agent authorization

When Agent A calls Agent B, Verra validates the trust chain. The delegating agent's trace ID must be present and its permissions must be a superset of the callee's requirements. Sensitive data categories (health, finance, HR) never cross agent-type boundaries regardless of policy configuration.

Human-in-the-loop approvals

Requests escalated by policy return 202 Accepted before forwarding. The admin queue surfaces the justification and context to a human reviewer. Approvals expire after one hour. Rejected requests write a block receipt and notify the calling agent.

Agent Trust Score (ATS)

Every registered agent carries an Agent Trust Score — a 0–100 composite index that measures how well-governed an agent is, modeled after credit-scoring methodology. Scores are visible per-agent in the dashboard and update in real time as configuration and behavior change.

No pillar is binary — each uses partial credit and sliding thresholds so the score reflects real security posture rather than a checkbox audit. A revoked agent does not have its score capped; it simply loses the Identity Integrity points, letting the other four pillars reflect whatever configuration is still in place.

Compliance

Compliance exports

Verra generates evidence packs for your auditors directly from the receipt log. Exports are available from the admin dashboard under Evidence Packs.

EU AI Act

The EU AI Act evidence pack maps your Verra receipt and approval data to the four high-risk system articles:

Export formats: JSON, CSV, Excel (.xlsx), PDF. The PDF includes a structured auditor report with cover page, per-article sections, and attestation block.

SOC 2 Type II

The SOC 2 AI Addendum pack maps Verra data to five Trust Services Criteria:

Export formats: ZIP (6 CSVs + integrity manifest), Excel (.xlsx), PDF. The integrity manifest contains SHA-256 hashes of each CSV file, allowing auditors to verify the export has not been modified.

HIPAA

The HIPAA evidence pack maps Verra data to the Security Rule and Breach Notification Rule requirements most relevant to AI systems handling protected health information (PHI):

Export formats: ZIP (CSVs + integrity manifest), Excel (.xlsx), PDF.

Shadow AI detection

Any AI call that bypasses the proxy is surfaced in the Shadow AI dashboard with agent, timestamp, and request metadata. Findings feed into the compliance gap report.