# @verlon-ai/sdk

The observability SDK for [Verlon AI](https://verlon.ai) — agent tracing, task attribution, and the live model registry for apps that run their inference through the Verlon gateway.

**Inference does not go through this SDK.** Verlon's API is OpenAI-format (plus Anthropic, Mistral, and Gemini drop-ins), so you call it with the official provider SDK you already use — in any language. This package makes those calls observable and attributable; it doesn't make them.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.VERLON_API_KEY,
  baseURL: 'https://api.verlon.ai/v1',
});

const response = await openai.chat.completions.create({
  model: 'your-gate-id', // your gate — Verlon routes it
  messages: [{ role: 'user', content: 'Hello!' }],
});
```

See the [OpenAI SDK integration guide](https://docs.verlon.ai/integrations/openai-sdk) for streaming, tool calling, and gate addressing, and the [migration guide](https://docs.verlon.ai/getting-started/migrate) if you're coming from LiteLLM, OpenRouter, or an earlier version of this SDK.

## Installation

```bash
npm install @verlon-ai/sdk
# or: pnpm add @verlon-ai/sdk / yarn add @verlon-ai/sdk
```

ESM-only, TypeScript-first.

## Agent tracing

Give an agent's runs a timeline on the Verlon dashboard: traces, named tasks, tool spans, and session grouping — with per-task model control from the dashboard, no redeploys.

```typescript
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 () => {
  // clientOptions() wires the official SDK into the trace:
  // baseURL, gate/task identity headers, and a trace-aware fetch.
  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 }],
  });
});
```

- `verlon.agent(gateId)` — handle for one agent gate; `agent.trace(options, fn)` opens a trace scope (reuse `conversationId` across turns to group a session).
- `agent.task(name)` — one task per LLM call site; the dashboard can pin or delegate each task's model.
- `verlon.tool(name, fn)` — wraps a function so each execution is a tool span on the active trace.
- `verlon.instrumentFetch()` — the trace-aware fetch on its own, for any fetch-accepting client.
- `ambientHeaders()` — the active trace context as plain headers, for HTTP clients without a custom fetch.
- `verlon.flushTelemetry()` — drain buffered spans before process exit.

Full reference: [docs.verlon.ai/sdk-reference/overview](https://docs.verlon.ai/sdk-reference/overview) · platform concepts: [Agent Gates](https://docs.verlon.ai/platform/agent-gates)

## Model registry

```typescript
const { models, version } = await verlon.models();
console.log(models['grok-4.5'].pricing?.input);
```

Live platform registry — models, capabilities, pricing. Unauthenticated. Prefer it at runtime over the compile-time `MODEL_REGISTRY` snapshot, which exists to generate the `ModelId` union and drifts after publish.

## Deprecated: inference methods

All eight inference methods — `complete()`, `chat()`, `chatStream()`, `image()`, `embeddings()`, `tts()` (2.5.0), plus `video()` and `ocr()` (2.6.0, now that their drop-in mirrors exist: `/v1/videos` async jobs via `openai.videos.*`, and `/mistral/v1/ocr` via `mistral.ocr.process()`) — are deprecated and **will be removed in 3.0.0, scheduled December 1, 2026**. After that, this SDK performs no inference at all. They keep working until then (and log a one-time runtime warning). Replacements are the official provider SDKs against the gateway routes — the [migration guide](https://docs.verlon.ai/getting-started/migrate) has a method-by-method table; most call sites are a two-line change.

## Related packages

- [`@verlon-ai/cli`](https://www.npmjs.com/package/@verlon-ai/cli) — the `layer` CLI: connect coding agents, inspect gates and logs.
- [`@verlon-ai/admin`](https://www.npmjs.com/package/@verlon-ai/admin) — programmatic management of gates, keys, and logs.

## Documentation

[docs.verlon.ai](https://docs.verlon.ai) · [Dashboard](https://verlon.ai/dashboard) · [API reference](https://docs.verlon.ai/api-reference/overview)

## License

MIT