Reference - ZeroEval Documentation

Installation

npm install zeroeval

Core Functions

`init()`

Initializes the ZeroEval SDK. Must be called before using any other SDK features.

function init(opts?: InitOptions): void;

Parameters

Option	Type	Default	Description
`apiKey`	`string`	`ZEROEVAL_API_KEY` env	Your ZeroEval API key
`apiUrl`	`string`	`https://api.zeroeval.com`	Custom API URL
`workspaceName`	`string`	`"Personal Workspace"`	Workspace/organization name
`flushInterval`	`number`	`10`	Interval in seconds to flush spans
`maxSpans`	`number`	`100`	Maximum spans to buffer before flushing
`collectCodeDetails`	`boolean`	`true`	Capture source code context
`integrations`	`Record<string, boolean>`	—	Enable/disable specific integrations
`debug`	`boolean`	`false`	Enable debug logging
`redaction`	`Partial<RedactionConfig>`	—	Source-side PII redaction settings

Example

import * as ze from "zeroeval";

ze.init({
  apiKey: "your-api-key",
  redaction: { enabled: true },
  debug: true,
});

redaction uses camelCase keys in TypeScript. Redaction applies only to ingested payload fields (input_data and output_data). Attributes, tags, session metadata, and error messages are not redacted.

Key	Type	Default	Description
`enabled`	`boolean`	`false`	Turn source-side redaction on
`redactInputs`	`boolean`	`true`	Redact `input_data`
`redactOutputs`	`boolean`	`true`	Redact `output_data`
`sensitiveKeys`	`string[]`	built-in list	Force-redact matching keys such as `email`, `apiKey`, `authorization`, and `cookie` inside IO payloads
`customPatterns`	`Array<RegExp \| string>`	`[]`	Additional patterns to redact inside IO payloads

See PII redaction for scope, placeholder behavior, normalization rules, and examples.

Wrapper Functions

`wrap()`

Wraps a supported AI client to automatically trace all API calls.

function wrap<T extends object>(client: T): WrappedClient<T>;

Supported Clients

OpenAI SDK (openai package)
Vercel AI SDK (ai package)
Claude Agent SDK (@anthropic-ai/claude-agent-sdk package)

Examples

// OpenAI
import { OpenAI } from "openai";
import * as ze from "zeroeval";

const openai = ze.wrap(new OpenAI());

// Vercel AI SDK
import * as ai from "ai";
import * as ze from "zeroeval";

const wrappedAI = ze.wrap(ai);

// Claude Agent SDK
import * as ze from "zeroeval";

const claudeAgentSdk = await import("@anthropic-ai/claude-agent-sdk");
const sdk = ze.wrap(claudeAgentSdk);

`wrapClaudeAgentSdk()`

Wraps the entire @anthropic-ai/claude-agent-sdk module so that query() and session helpers are automatically traced.

function wrapClaudeAgentSdk<T extends object>(module: T): T;

Example

import * as ze from "zeroeval";

const claudeAgentSdk = await import("@anthropic-ai/claude-agent-sdk");
const sdk = ze.wrapClaudeAgentSdk(claudeAgentSdk);

for await (const message of sdk.query({ prompt: "Hello!" })) {
  // each query() call is traced as a claude_agent.query span
}

`wrapClaudeAgentQuery()`

Wraps only the query function from the Claude Agent SDK.

function wrapClaudeAgentQuery(queryFn: QueryFn): QueryFn;

Example

import { query } from "@anthropic-ai/claude-agent-sdk";
import * as ze from "zeroeval";

const tracedQuery = ze.wrapClaudeAgentQuery(query);

for await (const message of tracedQuery({ prompt: "Hello!" })) {
  // traced as a claude_agent.query span
}

Spans API

`withSpan()`

Wraps a function execution in a span, automatically capturing timing and errors.

function withSpan<T>(
  opts: SpanOptions,
  fn: () => Promise<T> | T,
): Promise<T> | T;

SpanOptions

Option	Type	Required	Description
`name`	`string`	Yes	Name of the span
`sessionId`	`string`	No	Session ID to associate with the span
`sessionName`	`string`	No	Human-readable session name
`tags`	`Record<string, string>`	No	Tags to attach to the span
`attributes`	`Record<string, unknown>`	No	Additional attributes
`inputData`	`any`	No	Manual input data override
`outputData`	`any`	No	Manual output data override

Example

import * as ze from "zeroeval";

const result = await ze.withSpan({ name: "fetch-user-data" }, async () => {
  const user = await fetchUser(userId);
  return user;
});

`@span` Decorator

Decorator for class methods to automatically create spans.

span(opts: SpanOptions): MethodDecorator

Example

import * as ze from "zeroeval";

class UserService {
  @ze.span({ name: "get-user" })
  async getUser(id: string): Promise<User> {
    return await db.users.findById(id);
  }
}

Requires experimentalDecorators: true in your tsconfig.json.

Context Functions

`getCurrentSpan()`

Returns the currently active span, if any.

function getCurrentSpan(): Span | undefined;

`getCurrentTrace()`

Returns the current trace ID.

function getCurrentTrace(): string | undefined;

`getCurrentSession()`

Returns the current session ID.

function getCurrentSession(): string | undefined;

`setTag()`

Sets tags on a span, trace, or session.

function setTag(
  target: Span | string | undefined,
  tags: Record<string, string>,
): void;

Parameters

Parameter	Description
`Span`	Sets tags on the specific span
`string`	Sets tags on the trace or session by ID
`undefined`	Sets tags on the current span

Prompts API

`prompt()`

Creates or fetches versioned prompts from the Prompt Library. Returns decorated content for downstream LLM calls.

async function prompt(options: PromptOptions): Promise<string>;

PromptOptions

Option	Type	Required	Description
`name`	`string`	Yes	Task name associated with the prompt
`content`	`string`	No	Raw prompt content (used as fallback or for explicit mode)
`variables`	`Record<string, string>`	No	Template variables to interpolate `{{variable}}` tokens
`from`	`string`	No	Version control: `"latest"`, `"explicit"`, or a 64-char SHA-256 hash

Behavior

Auto-optimization (default): If content is provided without from, tries to fetch the latest optimized version first, falls back to provided content
Explicit mode (from: "explicit"): Always uses provided content, bypasses auto-optimization
Latest mode (from: "latest"): Requires an optimized version to exist, fails if none found
Hash mode (from: "<hash>"): Fetches a specific version by its 64-character SHA-256 content hash

Examples

import * as ze from "zeroeval";

// Auto-optimization mode (recommended)
const prompt = await ze.prompt({
  name: "customer-support",
  content: "You are a helpful {{role}} assistant.",
  variables: { role: "customer service" },
});

// Explicit mode - bypass auto-optimization
const prompt = await ze.prompt({
  name: "customer-support",
  content: "You are a helpful assistant.",
  from: "explicit",
});

// Latest mode - require optimized version
const prompt = await ze.prompt({
  name: "customer-support",
  from: "latest",
});

// Hash mode - specific version
const prompt = await ze.prompt({
  name: "customer-support",
  from: "a1b2c3d4e5f6...", // 64-char SHA-256 hash
});

Return Value

Returns a decorated prompt string with metadata header used by integrations:

<zeroeval>{"task":"...", "prompt_version": 1, ...}</zeroeval>Your prompt content here

Errors

Error	When
`Error`	Both `content` and `from` provided (except `from: "explicit"`), or neither
`PromptRequestError`	`from: "latest"` but no versions exist
`PromptNotFoundError`	`from` is a hash that does not exist

`sendFeedback()`

Sends feedback for a completion to enable prompt optimization.

async function sendFeedback(
  options: SendFeedbackOptions,
): Promise<PromptFeedbackResponse>;

SendFeedbackOptions

Option	Type	Required	Description
`promptSlug`	`string`	Yes	The slug of the prompt (task name)
`completionId`	`string`	Yes	UUID of the span/completion
`thumbsUp`	`boolean`	Yes	`true` for positive, `false` for negative
`reason`	`string`	No	Explanation of the feedback
`expectedOutput`	`string`	No	What the expected output should be
`metadata`	`Record<string, unknown>`	No	Additional metadata
`judgeId`	`string`	No	Judge automation ID for judge feedback
`expectedScore`	`number`	No	Expected score for scored judges
`scoreDirection`	`'too_high' \| 'too_low'`	No	Score direction for scored judges

Example

import * as ze from "zeroeval";

await ze.sendFeedback({
  promptSlug: "support-bot",
  completionId: "550e8400-e29b-41d4-a716-446655440000",
  thumbsUp: false,
  reason: "Response was too verbose",
  expectedOutput: "A concise 2-3 sentence response",
});

Utility Functions

`renderTemplate()`

Render a template string with variable substitution.

function renderTemplate(
  template: string,
  variables: Record<string, string | number | boolean>,
  options?: { ignoreMissing?: boolean },
): string;

`extractVariables()`

Extract variable names from a template string.

function extractVariables(template: string): Set<string>;

`sha256Hex()`

Compute SHA-256 hash of text.

async function sha256Hex(text: string): Promise<string>;

`normalizePromptText()`

Normalize prompt text for consistent hashing.

function normalizePromptText(text: string): string;

Error Classes

`PromptNotFoundError`

Thrown when a specific prompt version (by hash) is not found.

class PromptNotFoundError extends Error {
  constructor(message: string);
}

`PromptRequestError`

Thrown when a prompt request fails (e.g., no versions exist for from: "latest").

class PromptRequestError extends Error {
  constructor(message: string, statusCode?: number);
}

Types

`Prompt`

interface Prompt {
  id: string;
  prompt_id: string;
  content: string;
  content_hash: string;
  version: number;
  model_id?: string;
}

`PromptMetadata`

interface PromptMetadata {
  task: string;
  prompt_slug?: string;
  prompt_version?: number;
  prompt_version_id?: string;
  content_hash?: string;
  variables?: Record<string, string>;
}

Environment Variables

Set before importing ZeroEval to configure default behavior.

Variable	Type	Default	Description
`ZEROEVAL_API_KEY`	string	`""`	API key for authentication
`ZEROEVAL_API_URL`	string	`"https://api.zeroeval.com"`	API endpoint URL
`ZEROEVAL_WORKSPACE_NAME`	string	`"Personal Workspace"`	Workspace name
`ZEROEVAL_SESSION_ID`	string	auto-generated	Session ID for grouping traces
`ZEROEVAL_SESSION_NAME`	string	`""`	Human-readable session name
`ZEROEVAL_SAMPLING_RATE`	float	`"1.0"`	Sampling rate (0.0-1.0)
`ZEROEVAL_DISABLED_INTEGRATIONS`	string	`""`	Comma-separated integrations to disable
`ZEROEVAL_DEBUG`	boolean	`"false"`	Enable debug logging
`ZEROEVAL_REDACT_PII`	boolean	`"false"`	Enable SDK-side PII redaction

export ZEROEVAL_API_KEY="ze_1234567890abcdef"
export ZEROEVAL_SAMPLING_RATE="0.1"
export ZEROEVAL_DEBUG="true"

Configuration Examples

Production

ze.init({
  apiKey: "your_key",
  flushInterval: 1,
  maxSpans: 200,
  debug: false,
  integrations: {
    openai: true,
    vercelAI: true,
    claudeAgent: true,
  },
});

Development

ze.init({
  apiKey: "your_key",
  debug: true,
  collectCodeDetails: true,
});

Need help? Check out our GitHub examples or reach out on Discord.

​Installation

​Core Functions

​init()

​Parameters

​Example

​Wrapper Functions

​wrap()

​Supported Clients

​Examples

​wrapClaudeAgentSdk()

​Example

​wrapClaudeAgentQuery()

​Example

​Spans API

​withSpan()

​SpanOptions

​Example

​@span Decorator

​Example

​Context Functions

​getCurrentSpan()

​getCurrentTrace()

​getCurrentSession()

​setTag()

​Parameters

​Prompts API

​prompt()

​PromptOptions

​Behavior

​Examples

​Return Value

​Errors

​sendFeedback()

​SendFeedbackOptions

​Example

​Utility Functions

​renderTemplate()

​extractVariables()

​sha256Hex()

​normalizePromptText()

​Error Classes

​PromptNotFoundError

​PromptRequestError

​Types

​Prompt

​PromptMetadata

​Environment Variables

​Configuration Examples

​Production

​Development

Installation

Core Functions

`init()`

Parameters

Example

Wrapper Functions

`wrap()`

Supported Clients

Examples

`wrapClaudeAgentSdk()`

Example

`wrapClaudeAgentQuery()`

Example

Spans API

`withSpan()`

SpanOptions

Example

`@span` Decorator

Example

Context Functions

`getCurrentSpan()`

`getCurrentTrace()`

`getCurrentSession()`

`setTag()`

Parameters

Prompts API

`prompt()`

PromptOptions

Behavior

Examples

Return Value

Errors

`sendFeedback()`

SendFeedbackOptions

Example

Utility Functions

`renderTemplate()`

`extractVariables()`

`sha256Hex()`

`normalizePromptText()`

Error Classes

`PromptNotFoundError`

`PromptRequestError`

Types

`Prompt`

`PromptMetadata`

Environment Variables

Configuration Examples

Production

Development