SDK quick start

The SDK is a preview. Use the installation source provided by Bench; a public npm release is not available yet.

Set up with your coding agent

Open SDK in Bench

Open SDK in the sidebar, or Production → Set up SDK inside a system. Enter your repository and branch, then select Create setup key. SDK access is included on every plan.

Copy the agent prompt

Review the prompt shown in Bench, then select Copy agent prompt. Paste it into Claude Code, Cursor, Codex, or another trusted coding agent in your application repository. The prompt includes a one-time key, the installation source and your API endpoint. Use a trusted agent: that prompt contains a secret. Do not commit or share it. The key is shown only for this setup session. Copy it before leaving the page.

Verify an interaction

The agent adds server-side instrumentation and sends a synthetic metadata-only trace. Open AI systems, select the declared runtime system, then Production.

The setup key is scoped to one repository, has no team-wide read access and has a zero evaluation cap. Creating it does not start a paid evaluation. Manage or revoke it from SDK → Manage keys.

Install manually

Build the local bench-sdk checkout with npm ci && npm test && npm pack, then:

npm install /absolute/path/to/trybench-sdk-0.1.0.tgz

import { Bench } from '@trybench/sdk'

const bench = new Bench({
  apiKey: process.env.BENCH_API_KEY!,
  repository: process.env.BENCH_REPOSITORY!,
  branch: process.env.BENCH_BRANCH!,
  endpoint: process.env.BENCH_API_BASE_URL,
  systemName: 'Support agent',
  captureContent: false,
})

const result = await bench.trace(
  { name: 'Answer customer', kind: 'LLM' },
  () => yourExistingModelCall(),
)

Use Node.js 20+ on the server. Never use public environment-variable prefixes such as NEXT_PUBLIC_ or VITE_ for the key. The default endpoint is the API’s existing origin; always set BENCH_API_BASE_URL explicitly for this preview. Use https://api.staging.usebench.ai for staging or http://127.0.0.1:8080 locally. Do not send staging keys to production. The staging installer is a commit-pinned Git source from a private repository and requires GitHub repository access. There is no public npm package yet.

What Bench recognizes

systemName declares a runtime boundary. If omitted, the repository name is used. The first trace creates a runtime system for that name, repository and branch. This is observed runtime structure, not a verified business-purpose inference. GitHub scans or uploaded prompts still provide the prompt definitions needed for prompt benchmarking. SDK-only runtime systems can receive and display traces before those definitions are connected. Use nested bench.trace calls for agents and tools. The SDK preserves parent IDs. Pass a real componentId from Bench to connect a span to a discovered prompt, or link it from Production. Do not invent component IDs.

Frameworks

Wrap your existing Node/server call for AI SDK, Mastra, OpenAI Agents or a custom workflow. This release does not automatically patch those libraries. It is not an OTLP collector, Python SDK, browser SDK or a guarantee of complete agent tracing. For a reusable coding-agent guide, see skills/bench-sdk/SKILL.md inside the local package. Follow production checks when ready to evaluate.

Find your activity

Open an AI system’s Production tab. Recent interactions appear after the SDK sends them. The Quickstart button opens this guide in a new tab; Set up SDK opens the in-app setup. Capturing metadata does not start an evaluation.

Start here

Evaluate and improve

MCP

SDK

Development

SDK quick start

Set up with your coding agent

Install manually

What Bench recognizes

Frameworks

Find your activity

​Set up with your coding agent

​Install manually

​What Bench recognizes

​Frameworks

​Find your activity

Set up with your coding agent

Install manually

What Bench recognizes

Frameworks

Find your activity