Quickstart

1. Create a project

Sign in to the platform and create a new project, one per agent you monitor. Copy the API key the Quick Start page shows you (the copy is recorded on the project’s API Keys page), or create one on the API Keys page; keys start with bv_live_. Save it somewhere secure; it won’t be shown again.

2. Install the SDK

npm install belvedir

3. Initialize before importing your LLM SDK

initialize() patches your LLM client, so it must run before the LLM SDK is imported. Call it once at the top of your entry file:

import { initialize } from "belvedir";

initialize({
  apiKey: process.env.BELVEDIR_API_KEY!,
  appName: "my-agent",
});

// import OpenAI/Anthropic *after* initialize()

In an ESM entry point or any bundled app, also pass the LLM SDKs you use via instrumentModules; see Installation. In Next.js, put the call in instrumentation.ts and always pass instrumentModules; see the Next.js guide.

4. Wrap agent work in sessions

Wrap each agent run in withSession so every LLM and tool call is linked under one session id. Optionally wrap distinct units of work in task() for sharper task boundaries:

import loop from "belvedir";

await loop.withSession(
  { sessionId: chatId, userId: user.id },
  async () => {
    await loop.task("send_email", async () => {
      await agent.run("email danny the report");
    });
    await loop.task("summarize_inbox", async () => {
      await agent.run("summarize my unread mail");
    });
  }
);

Without withSession you still get raw traces, but they can’t be linked into sessions or segmented into tasks. On serverless (Vercel, Lambda, Cloud Functions), await flush() before each handler returns, or the spans are silently lost; see Flush on serverless:

import { flush } from "belvedir";

// ... LLM calls ...
await flush();
return Response.json(result);

5. Route your LLM calls through Belvedir (optional)

Belvedir can also execute your LLM calls. Point any OpenAI-compatible client at the router and use your Belvedir key in place of the provider key; keep the model each call already names.

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://platform.belvedir.ai/api/v1/route",
  apiKey: process.env.BELVEDIR_API_KEY, // was OPENAI_API_KEY
});

You are billed per token at the rates on the Pricing page. Anthropic SDK call sites point at a different base URL; Route your calls has the setup for both.

6. View your tasks and task groups

Traces appear in the dashboard within seconds. Shortly after a session goes quiet, it is segmented into tasks: open Tasks to see each one and Task Groups to see tasks of the same type gathered together. How it works explains the stages.

Working with a coding agent? The dashboard’s Quick Start page has a Copy prompt for AI button. Paste the prompt into your coding agent and it installs the Belvedir skill into your codebase (as .claude/skills/belvedir/SKILL.md) and instruments the app for you. The same guide is at platform.belvedir.ai/agents.md.

Next steps

Python quickstart if your agent is in Python.
Importing traces to bring over history from another observability platform.
Next.js and Vercel, AI SDK, or custom agent loops for stack-specific setup.
Common issues if no traces show up.

Get started

Node SDK

Guides

Inference

Training

Benchmarks

Resources

1. Create a project

2. Install the SDK

3. Initialize before importing your LLM SDK

4. Wrap agent work in sessions

5. Route your LLM calls through Belvedir (optional)

6. View your tasks and task groups

Next steps

​1. Create a project

​2. Install the SDK

​3. Initialize before importing your LLM SDK

​4. Wrap agent work in sessions

​5. Route your LLM calls through Belvedir (optional)

​6. View your tasks and task groups

​Next steps

1. Create a project

2. Install the SDK

3. Initialize before importing your LLM SDK

4. Wrap agent work in sessions

5. Route your LLM calls through Belvedir (optional)

6. View your tasks and task groups

Next steps