Belvedir Quickstart

1. Create a project

Sign in to the platform and create a new project, one per agent you monitor. Projects are grouped under organizations; the switcher in the dashboard header scopes everything to one organization at a time. You can connect your agent’s GitHub repository during creation (or later in Project settings). Then copy the API key Quick Start shows you (copying saves it to the project’s API Keys) or create one from the dashboard’s API Keys page; keys start with bv_live_. Save it somewhere secure; it won’t be shown again. (Older keys starting with fr_live_ remain valid.)

2. Install the SDK

npm install belvedir

Migrating from Fractal? The old packages (@fractalresearch/loop, fractal-loop) still work but are deprecated.

3. Initialize in `instrumentation.ts`

The SDK patches your LLM client (Anthropic / OpenAI) the moment initialize() runs, so it must run before the LLM SDK is imported. In Next.js the only place that’s guaranteed is the instrumentation.ts hook at your project root:

// instrumentation.ts  (project root)
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    const { initialize } = await import("belvedir");
    // Pass the LLM SDKs you use so they are patched no matter
    // how Next.js loads them (see instrumentModules below).
    const openai = await import("openai");
    const anthropic = await import("@anthropic-ai/sdk");
    initialize({
      apiKey: process.env.BELVEDIR_API_KEY!,
      appName: "my-ai-app",
      instrumentModules: { openAI: openai.OpenAI, anthropic },
    });
  }
}

Do not call initialize() from inside a route file. By then the LLM SDK is already imported and the patch won’t take. In Next.js, always pass instrumentModules (only the SDKs you actually use): bundlers can load LLM SDKs in ways auto-instrumentation can’t see, which silently drops all LLM spans.

4. Wrap agent work in sessions

This is what powers tasks and training sets. Wrap each agent run in withSession so every LLM and tool call is linked under one session id. Belvedir then segments that session into the individual tasks the agent performed. 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), also await flush() before each handler returns. The function can freeze or exit before the batching span processor exports, and the spans are silently lost:

import { flush } from "belvedir";

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

5. Use your Belvedir API key for inference

Belvedir can also execute your LLM calls: point your OpenAI-compatible client at the router endpoint and use your Belvedir key in place of the provider key. Two lines change; the client works exactly as before.

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

const res = await client.chat.completions.create({
  model: "x-ai/grok-4.6", // unchanged: the model this call already used
  messages,
});

Do this for every LLM client in your app: keep the model each call already names, change only the base URL and key. Each model stays its own baseline: Grok call sites become Belvedir calls with x-ai/grok-4.6, Claude Sonnet call sites become Belvedir calls with anthropic/claude-sonnet-5. If a call site used a provider-native SDK (xAI, Google), swap it for the OpenAI client pointed at Belvedir and write the model in the provider-prefixed spelling (grok-4.6 → x-ai/grok-4.6); OpenAI ids stay bare. Bare ids are normalized server-side too, so a missed one still routes. Anthropic SDK call sites don’t swap: point the Anthropic client at baseURL: "https://platform.belvedir.ai/api" instead and requests pass through to the Messages API untranslated — prompt caching, thinking, beta headers, and native streaming intact (see the Messages passthrough); that surface is model-pinned, so routing stays with the OpenAI-shaped endpoint. The first call naming a model creates a router anchored on it (Routers page, “From your code”): that model is the ceiling and answers every conversational call, while cheaper tiers serve the easier machine-shaped tasks underneath, so people always talk to the model your code named and you pay less when a smaller model is enough for the busywork. (The tiering is the project’s Smart routing permission, on by default; turned off, every call serves exactly the model it names.) Belvedir runs the call and bills your organization per token at the rates on the platform’s Pricing page (Inference → Pricing). Every project also has an auto router; model: "auto" hands a call to it outright. The response’s model tells you what actually ran.

6. View your tasks and training sets

Traces appear in the dashboard within seconds. About 30s after a session goes quiet, it’s segmented. Open the Tasks tab to see each task, and Training Sets to see tasks of the same type gathered together.

Working with a coding agent? This whole guide lives at platform.belvedir.ai/agents.md in agent-readable markdown, and is published as a skill at github.com/Belvedir/skills. The dashboard’s Quick Start page has a Copy prompt for AI button that puts a ready-made instruction on your clipboard. Paste it into your coding agent and it downloads the skill into your codebase (as .claude/skills/belvedir/SKILL.md) and instruments the app for you.

Next steps

Python SDK if your agent is in Python.
Importing Traces to bring over history from another observability platform.
How It Works: what happens after your traces arrive.
Common Issues if no traces show up.

Get Started

SDK

Guides

Inference

Training

Benchmarks

Resources

Belvedir Quickstart

1. Create a project

2. Install the SDK

3. Initialize in `instrumentation.ts`

4. Wrap agent work in sessions

5. Use your Belvedir API key for inference

6. View your tasks and training sets

Next steps

​1. Create a project

​2. Install the SDK

​3. Initialize in instrumentation.ts

​4. Wrap agent work in sessions

​5. Use your Belvedir API key for inference

​6. View your tasks and training sets

​Next steps

1. Create a project

2. Install the SDK

3. Initialize in `instrumentation.ts`

4. Wrap agent work in sessions

5. Use your Belvedir API key for inference

6. View your tasks and training sets

Next steps