> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verlon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> The Verlon SDK for TypeScript/JavaScript: agent tracing, task attribution, and the live model registry

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](/integrations/openai-sdk) and the [Anthropic SDK integration guide](/integrations/anthropic-sdk). The Verlon SDK's job is to make those calls observable and attributable, not to make them.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @verlon-ai/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @verlon-ai/sdk
  ```

  ```bash yarn theme={null}
  yarn add @verlon-ai/sdk
  ```
</CodeGroup>

## Get Your API Key

1. Sign up at [verlon.ai/signup](https://verlon.ai/signup)
2. Get your API key from the [Dashboard](https://verlon.ai/dashboard)
3. Store it in an environment variable

```bash .env theme={null}
VERLON_API_KEY=your-api-key-here
```

<Warning>
  Never commit API keys to version control. Use environment variables.
</Warning>

## 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.

```typescript theme={null}
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](/platform/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:

```typescript theme={null}
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.

```typescript theme={null}
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.

```typescript theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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

<Warning>
  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](/getting-started/migrate#migrating-off-the-verlon-sdks-inference-methods).
</Warning>

Setup and migration guides:

<CardGroup cols={2}>
  <Card title="OpenAI SDK Integration" icon="plug" href="/integrations/openai-sdk">
    Point the openai package at Verlon
  </Card>

  <Card title="Anthropic SDK Integration" icon="plug" href="/integrations/anthropic-sdk">
    Point the Anthropic SDK at Verlon
  </Card>

  <Card title="OpenAI Compatibility" icon="circle-check" href="/provider-compatibility/openai">
    Supported routes and parameters
  </Card>

  <Card title="Anthropic Compatibility" icon="circle-check" href="/provider-compatibility/anthropic">
    Supported routes and parameters
  </Card>
</CardGroup>

<Note>
  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](/getting-started/migrate#migrating-off-the-verlon-sdks-inference-methods) has the full method-by-method table.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="Agent Gates" icon="route" href="/platform/agent-gates">
    Traces, tasks, and sessions on the platform
  </Card>

  <Card title="Creating Gates" icon="door-open" href="/dashboard/creating-gates">
    Configure gates in the dashboard
  </Card>

  <Card title="Migration Guide" icon="route" href="/getting-started/migrate">
    Method-by-method replacements for the deprecated inference surface
  </Card>
</CardGroup>