Overview

The Verlon SDK is the observability and control-plane companion to the Verlon gateway. It gives your agents traces, tasks, and tool spans on the dashboard timeline, bridges the official provider SDKs into that tracing, and exposes the live model registry. Inference itself no longer goes through this SDK. Chat, images, embeddings, and speech run through the official provider SDKs (openai, @anthropic-ai/sdk) pointed at Verlon’s drop-in gateway routes — see the OpenAI SDK integration guide and the Anthropic SDK integration guide. The Verlon SDK’s job is to make those calls observable and attributable, not to make them.

Installation

npm install @verlon-ai/sdk

pnpm add @verlon-ai/sdk

yarn add @verlon-ai/sdk

Get Your API Key

Sign up at verlon.ai/signup
Get your API key from the Dashboard
Store it in an environment variable

.env

VERLON_API_KEY=your-api-key-here

Never commit API keys to version control. Use environment variables.

Quickstart: Trace an Agent

Create a client, get a handle for your agent gate, declare the tasks it performs, and open a trace scope. Any LLM call made inside the scope with task.clientOptions() carries gate and task attribution and lands on the trace timeline automatically.

import { Verlon } from '@verlon-ai/sdk';
import OpenAI from 'openai';

const verlon = new Verlon({
  apiKey: process.env.VERLON_API_KEY
});

const support = verlon.agent(process.env.SUPPORT_GATE_ID);
const classify = support.task('classify');

await support.trace({ conversationId: chatId }, async () => {
  const openai = new OpenAI({
    apiKey: process.env.VERLON_API_KEY,
    ...classify.clientOptions('openai')
  });

  const completion = await openai.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: ticketText }]
  });

  console.log(completion.choices[0].message.content);
});

clientOptions('openai' | 'anthropic') returns { baseURL, fetch, defaultHeaders } to spread into the official SDK’s constructor:

baseURL routes the call through the Verlon gateway (the provider hint sets the right base path for each SDK).
defaultHeaders carries the gate and task identity.
fetch is an instrumented wrapper that injects the active trace context per call, so a client constructed once never pins a stale trace.

Use agent.clientOptions(...) instead of a task’s when a call belongs to the agent but no specific task. Everything the trace records — spans, timing, cost, model choice — appears on the gate’s timeline in the dashboard. See Agent Gates for the platform side.

Other HTTP clients

For an HTTP client that accepts a custom fetch, verlon.instrumentFetch() returns the same instrumented wrapper on its own. For clients that don’t, ambientHeaders() (exported from the package root) returns the active trace context as plain headers — call it per request, inside the trace scope:

import { ambientHeaders } from '@verlon-ai/sdk';

const response = await got.post(url, {
  headers: { ...ambientHeaders(), 'x-verlon-gate-id': gateId }
});

Tool Spans

Wrap a function with verlon.tool() and each execution becomes a tool span on the active trace, with arguments, timing, and errors recorded. Outside a trace scope the wrapper is a pure pass-through; errors are rethrown unchanged.

const searchDocs = verlon.tool('search_docs', async (query: string) => {
  return index.search(query);
});

await support.trace({ conversationId: chatId }, async () => {
  const results = await searchDocs('refund policy');
  // shows up as a tool span on the trace timeline
});

Model Registry

verlon.models() fetches the platform’s current model registry — models, capabilities, and pricing. It’s unauthenticated (the registry is public), so it’s safe to call before a key is configured.

const { models, version } = await verlon.models();

const grok = models['grok-4.5'];
console.log(grok.pricing?.input);

Prefer this over the exported MODEL_REGISTRY constant when the answer matters at runtime: the constant is a snapshot frozen at publish time (it exists to generate the ModelId union at compile time), while models() asks the platform.

Configuration

import { Verlon } from '@verlon-ai/sdk';

const verlon = new Verlon({
  apiKey: process.env.VERLON_API_KEY,  // Required
  baseUrl: 'https://custom.api'        // Optional, defaults to https://api.verlon.ai
});

TypeScript Support

The SDK is fully typed. The tracing surface (AgentHandle, TaskHandle, trace options), the registry snapshot, and the ModelId union are all exported from the package root:

import { Verlon, type ModelRegistrySnapshot } from '@verlon-ai/sdk';

const verlon = new Verlon({ apiKey: process.env.VERLON_API_KEY! });

const snapshot: ModelRegistrySnapshot = await verlon.models();

Deprecated: Inference Methods

All of the SDK’s inference methods — complete(), chat(), chatStream(), image(), embeddings(), tts(), video(), and ocr() — are deprecated and will be removed in 3.0.0, scheduled December 1, 2026. Inference belongs to the official provider SDKs against Verlon’s drop-in routes; see the migration guide.

Setup and migration guides:

OpenAI SDK Integration

Point the openai package at Verlon

Anthropic SDK Integration

Point the Anthropic SDK at Verlon

OpenAI Compatibility

Supported routes and parameters

Anthropic Compatibility

Supported routes and parameters

Video and OCR have drop-in mirrors too: the openai package’s async Videos surface (videos.create / retrieve / downloadContent) against /v1/videos, and mistral.ocr.process() against /mistral/v1/ocr. The migration guide has the full method-by-method table.

Next Steps

Agent Gates

Traces, tasks, and sessions on the platform

Creating Gates

Configure gates in the dashboard

Migration Guide

Method-by-method replacements for the deprecated inference surface

Getting Started

SDK Reference

Platform

Integrations

Provider Compatibility

Installation

Get Your API Key

Quickstart: Trace an Agent

Other HTTP clients

Tool Spans

Model Registry

Configuration

TypeScript Support

Deprecated: Inference Methods

OpenAI SDK Integration

Anthropic SDK Integration

OpenAI Compatibility

Anthropic Compatibility

Next Steps

Agent Gates

Creating Gates

Migration Guide

​Installation

​Get Your API Key

​Quickstart: Trace an Agent

​Other HTTP clients

​Tool Spans

​Model Registry

​Configuration

​TypeScript Support

​Deprecated: Inference Methods

OpenAI SDK Integration

Anthropic SDK Integration

OpenAI Compatibility

Anthropic Compatibility

​Next Steps

Agent Gates

Creating Gates

Migration Guide

Installation

Get Your API Key

Quickstart: Trace an Agent

Other HTTP clients

Tool Spans

Model Registry

Configuration

TypeScript Support

Deprecated: Inference Methods

Next Steps