Copy this into your coding agent
Paste into Cursor, Codex, Claude Code, or another coding agent in your project.Beta. Choose a language below for installation, tracing and real app tests.
Set up with your coding agent
1
Open SDK in Bench
Open SDK in the sidebar, or Production → Set up SDK inside a system.
Choose your language. Bench prepares your account setup key automatically.
SDK access is included on every plan.
2
Copy the agent prompt
Under Set up using a coding agent, select Copy prompt.
Paste it into Claude Code, Cursor, Codex, or another trusted coding agent in your application repository.
The prompt includes your setup key, installation command and API endpoint. Your coding agent reads the repository, branch and deployment configuration from the open project.
Use a trusted agent: that prompt contains a secret. Do not commit or share it.
You can return to setup to copy the same account key. Revoke it from API keys if needed.
3
Verify an interaction
The agent adds server-side instrumentation and sends a synthetic metadata-only
trace. SDK setup shows Waiting for first event, then SDK events received
once ingestion succeeds. Open AI systems, select the system,
then Production.
environment, such as staging or production, in the SDK options
to distinguish received deployments. Connection status shows the last accepted
event for a system/environment, not a live heartbeat or proof that every route has
instrumentation. A silent application cannot be distinguished from an absent SDK
using telemetry alone.
Choose your language
Each guide includes a coding-agent prompt, a connection example and lifecycle
instructions. The TypeScript and Python clients ship the OpenTelemetry bridge;
all four expose
record_external_span (Go RecordExternalSpan).
What Bench recognizes
systemName names the agent or workflow. If omitted, the repository name is used.
The first trace creates a system for that name, repository and branch, and Bench
draws the system from the spans it receives: AGENT spans become agents, LLM
spans become the model components inside them, TOOL spans become tools, and a
parent agent to a child agent becomes a hand-off. Spans without a Bench kind are
classified from the OpenTelemetry GenAI attributes (gen_ai.operation.name,
gen_ai.agent.name, gen_ai.tool.name, gen_ai.request.model). Bench makes no
model call for this, and every request can add nodes. Open the system’s System
overview to see it. You can add its intended business outcome on the
Understanding page.
Traces do not carry editable prompt templates. Prompt components come from a
GitHub scan, an upload, or your coding agent registering the model calls it finds in
the repository with register_calls (see Bench from coding agent).
Until then a system connected only through the SDK shows its structure and traces
but reports that no executable prompt was found.
Wrap agents and tools using your language guide. Follow its context instructions
to retain parent IDs. Use a real prompt component ID from Bench to connect a span
to discovered criteria, or link it from Production. Do not invent component IDs.
Frameworks
Frameworks that already emit OpenTelemetry GenAI spans need no wrapping: register Bench’s span exporter on the framework’s tracer provider and the same agent, model and tool tree arrives metadata-only. In Python,bench_sdk.otel.attach(bench)
covers OpenAI Agents, Strands, Pydantic AI (Agent.instrument_all()), LangChain
and LangGraph instrumentation, CrewAI, LlamaIndex, Google ADK and AutoGen. In
TypeScript, add new BenchSpanExporter(bench) to the provider used by Vercel AI SDK
experimental_telemetry, OpenAI Agents or LangChain. Frameworks with their own
tracing events forward each finished span with recordExternalSpan (Python
record_external_span, Go RecordExternalSpan, Rust record_external_span),
keeping the framework’s identifiers. Custom code nests trace calls: an AGENT
span per agent or workflow, an LLM span per model call, a TOOL span per tool.
Components discovered this way use stable call sites: sdk:runtime,
sdk:agent:<slug>, sdk:model:<agent>:<provider>/<model> and
sdk:tool:<agent>:<name>. Failed spans keep error.message and
exception.type / exception.message, never the stack trace.
Bench does not patch libraries automatically, is not an OTLP collector or browser
SDK, and cannot see paths no request exercised. Use the separate
Python, Go and Rust clients for those languages.
For a reusable coding-agent guide, see skills/bench-sdk/SKILL.md inside the
installed 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.Use development, staging and production
SetBENCH_ENVIRONMENT in each deployment. Open Event environment in a system’s Production tab to select the events you want to inspect.
A staging event confirms staging receipt; it does not mark production as connected.
Older events without an environment appear under Not specified.
Environments share your Bench account, permissions and evaluation allowance. A
label does not switch your application’s payment, email or database credentials.
Use separate test credentials and fixture data when testing side effects. Learn
more in environments.
If no event arrives
Check the endpoint and API key, confirm the instrumented code ran, and flush before a short-lived process exits. Look for SDK delivery errors in your server logs without printing credentials. A deployment with no recent requests may have no recent events even when the SDK is installed. After confirming receipt, replace the synthetic callback with an existing app operation. For long-running servers, reuse the Bench instance and callshutdown()
on shutdown. For serverless handlers, await flush() before the request lifecycle ends.