TypeScript SDK Configuration

This guide covers configuration, policy enforcement, and governance metadata for the Pavri TypeScript SDK beta.

Installation and Setup

npm install @pavri/sdk

Requires Node.js >= 24.0.0 and a running Pavri backend.

Basic Setup

import { secure, type PavriConfig } from "@pavri/sdk";

const config: PavriConfig = {
  agent_name: "my-agent",
  backend_url: process.env.PAVRI_BACKEND_URL ?? "http://localhost:8080",
  api_key: process.env.PAVRI_API_KEY,
  environment: "production",
  team: "platform",
};

const myAgent = { /* your agent object */ };
const securedAgent = await secure(myAgent, config);

Configuration Options

The SDK accepts a PavriConfig object or reads from environment variables.

Config Field	Env Variable	Required	Default	Description
agent_name	PAVRI_AGENT_NAME	Yes	—	Unique name for this agent within the tenant
backend_url	PAVRI_BACKEND_URL	No	http://localhost:8080	Pavri backend endpoint
api_key	PAVRI_API_KEY	Yes (prod)	—	Tenant API key
org_id	PAVRI_ORG_ID	No	—	Organisation identifier for multi-org tenants
team	PAVRI_TEAM	No	—	Team name for inventory grouping
environment	PAVRI_ENVIRONMENT	No	development	Deployment environment label
enforcement_mode	—	No	active	active, shadow, or audit
fail_open	—	No	true	If true, allow requests when the backend is unreachable

Configuration Priority

The SDK resolves configuration in this order (highest priority first):

1. Explicit PavriConfig object passed to secure()
2. Environment variables with the PAVRI_ prefix
3. Built-in defaults

Policy Enforcement

When an agent secured with secure() executes, the SDK evaluates the active policy snapshot for every tool call and model invocation.

How Policy Evaluation Works

1. The SDK fetches the current policy snapshot from the backend on startup and caches it locally.
2. Before each tool call or model invocation, the SDK evaluates the relevant policies.
3. If a policy matches and the enforcement mode is active, the SDK either allows or denies the operation.
4. In shadow mode, the SDK evaluates policies but never denies — it only records what would have been blocked.

Handling PolicyDeniedError

When a policy blocks an operation in active mode, the SDK throws a PolicyDeniedError.

import { secure, PolicyDeniedError } from "@pavri/sdk";

const securedAgent = await secure(agent, config);

try {
  const result = await securedAgent.run(input);
} catch (err) {
  if (err instanceof PolicyDeniedError) {
    console.error("Operation blocked by policy:", err.policyId, err.reason);
    // Handle gracefully — return a safe fallback or surface to the user
  } else {
    throw err;
  }
}

The PolicyDeniedError includes:

Property	Type	Description
policyId	string	The ID of the policy that triggered the denial
policyName	string	Human-readable policy name
reason	string	Short explanation of why the operation was denied
operation	string	The operation that was blocked (e.g., tool_call:send_email)
sessionId	string	The active session ID for cross-referencing in the dashboard

Governance Metadata

You can attach governance metadata to an agent to improve correlation, discovery, and policy targeting.

const securedAgent = await secure(agent, {
  ...config,
  metadata: {
    owner: "platform-team",
    cost_centre: "eng-infra",
    compliance_scope: "pci",
    data_classification: "confidential",
  },
});

Governance metadata is:

• Stored in the agent's inventory record
• Visible in the dashboard under the agent's Environment facts panel
• Available to policy rules for attribute-based access control
• Included in audit trail exports

Shadow Mode vs Active Enforcement

Pavri supports three enforcement modes to support a gradual rollout:

Active Mode (default)

Policies are fully enforced. Blocked operations throw PolicyDeniedError and are never executed.

const securedAgent = await secure(agent, {
  ...config,
  enforcement_mode: "active",
});

Use active mode in production once you have validated your policies in shadow mode.

Shadow Mode

Policies are evaluated but never enforced. The SDK records what would have been blocked without actually blocking anything.

const securedAgent = await secure(agent, {
  ...config,
  enforcement_mode: "shadow",
});

Use shadow mode:

• When introducing the SDK to an existing production agent
• When testing new policies before rolling them out
• During the initial governance onboarding period

Shadow mode decisions are visible in the Sessions timeline in the dashboard — look for events with a "Shadow" governance badge.

Audit Mode

Like shadow mode, but also emits structured compliance events to the audit stream. No operations are blocked.

const securedAgent = await secure(agent, {
  ...config,
  enforcement_mode: "audit",
});

Use audit mode for compliance reporting without enforcement.

Parity Notes with Python SDK

The TypeScript SDK beta targets feature parity with the Python SDK. See the SDK Parity Reference for a full comparison table.

Key known gaps in the TypeScript SDK beta:

• Framework adapters — LangGraph, AutoGen, and CrewAI adapters are not yet available. The TypeScript SDK currently supports generic object wrapping via secure(). Framework-native adapters are planned for Phase 2 Sprint 4.
• Streaming telemetry — token-level streaming telemetry is not yet implemented. Token counts are reported at session end rather than incrementally.
• MCP connector — MCP server scanning is not yet supported in the TypeScript SDK.

Next Steps

• TypeScript SDK Parity Reference — detailed feature comparison with the Python SDK
• Discovery concepts — understand how the SDK interacts with the discovery pipeline
• TypeScript Quickstart — step-by-step setup guide