Agent Lens runs on the same backend as Weights & Biases, so some configuration names keep the
wandb prefix: the WANDB_API_KEY environment variable, the wandb-api-key header, and the wandb.entity and wandb.project resource attributes. Use these names as shown.Authentication
You can send spans to the following endpoint:- Path:
/agents/otel/v1/traces - Method:
POST - Content-Type:
application/x-protobuf - Base URL:
https://trace.wandb.aifor Forge.
opentelemetry-exporter-otlp-proto-http (Python) or @opentelemetry/exporter-trace-otlp-proto (TypeScript). The endpoint also accepts gzip and deflate content encoding.
To authenticate with the endpoint, set your API key in your OTLPSpanExporter configuration using one of the following values:
wandb-api-key: Your Forge API key as the value.Authorization: HTTP Basic authentication withapias the user and your Forge API key as the password. This form is useful when your exporter or collector only supports standard authorization headers.
Project routing
Agent Lens routes spans to a project using either OTel resource attributes or a request header:- Resource attributes (recommended): Set
wandb.entityto your Forge team or user name andwandb.projectto the project name on yourTracerProviderresource. project_idheader: Set the value to[YOUR-TEAM]/[YOUR-PROJECT].
Shape spans for the Conversations tab
Agent Lens accepts any OTel span and stores all of its attributes, but spans must follow the OpenTelemetry semantic conventions for Agent Lens to correctly render in the Conversations tab. Setgen_ai.operation.name on each span to tell Agent Lens what the span represents:
To show token counts and estimate cost, also set the token usage attribute on each LLM span.
To check what Agent Lens received for a span, open the span’s Raw tab in the conversation view. For the agent data model that these spans map to, see Trace your agents.
Configure with environment variables only
If your application or collector reads the standard OTel exporter environment variables, you can set the following variables and route spans to Agent Lens without changing any code:OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: The Agent Lens endpoint your exporter sends spans to.OTEL_EXPORTER_OTLP_TRACES_HEADERS: Authenticates each request with your Forge API key, sent in thewandb-api-keyheader.OTEL_RESOURCE_ATTRIBUTES: Sends spans to your project. Setwandb.entityto your Forge team or user name andwandb.projectto the project name.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: Sets the exporter to send OTLP protobuf over HTTP. It must behttp/protobuf, because the endpoint accepts only protobuf payloads.
Example: emit agent spans without the Agent Lens SDK
The following example instruments one agent turn using only OTel packages. A user asks about the weather, the model calls aget_weather tool, and then the model answers with the result. The example emits an invoke_agent span for the turn, a chat span for each LLM call, and an execute_tool span for the tool call, then exports them to the Agent Lens agents endpoint.
The turn and each LLM call carry the user’s prompt and the model’s replies in gen_ai.input.messages and gen_ai.output.messages. Each LLM call also carries the provider, the requested and returned model IDs, and its token counts. The tool call carries its input and output in gen_ai.tool.call.arguments and gen_ai.tool.call.result. As we recommend, every span carries the conversation ID, the agent name, and the user’s ID and email. The example hardcodes all of these values for demonstration purposes.
First, install the required dependencies:
WANDB_API_KEY environment variable to your API key:
[YOUR-TEAM] and [YOUR-PROJECT] in the following code with your Forge team and project names, and run it:
invoke_agent spans with the same gen_ai.conversation.id. Each turn must be the root span of its own trace, so turns can’t share a parent span. Give all of a turn’s spans timestamps from one clock, and end the turn’s span after its children. See Keep span times consistent.
After your application exports spans, open the Conversations view of your Agent Lens project.