Claude Agent SDK Tracing

Trace your Claude Agent SDK applications with Scorecard.

The Claude Agent SDK is Anthropic’s framework for building AI agents that can reason, use tools, and complete multi-step tasks. It includes built-in support for OpenTelemetry tracing, making it easy to capture detailed telemetry from your agent workflows.

This quickstart shows how to send traces from your Claude Agent SDK (Python v0.1.18+, TypeScript v0.1.71+) applications to Scorecard for observability, debugging, and evaluation.

Using the standard Anthropic SDK? Check out the general Tracing Quickstart for the proxy method that works with any Anthropic client.

Steps

1. Set up environment variables

   Configure the OpenTelemetry exporter to send traces to Scorecard. You’ll need your Scorecard API key from Settings.

   export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <your_scorecard_api_key>"
   export ENABLE_BETA_TRACING_DETAILED=1
   export BETA_TRACING_ENDPOINT="https://tracing.scorecard.io/otel"
   

   Replace <your_scorecard_api_key> with your actual Scorecard API key (starts with ak_).

   Optional: To send traces to a specific project, set the project ID:

   export OTEL_RESOURCE_ATTRIBUTES="scorecard.project_id=<your-project-id>"
   

   If not set, traces will default to your oldest project in the organization.

2. Run your agent

   With the environment variables configured, run your Claude Agent SDK application. All agent activity is automatically traced.

   example.py

   import anyio
   from claude_agent_sdk import (
       AssistantMessage,
       TextBlock,
       query,
   )
   
   async def main():
       async for message in query(prompt="What is 2 + 2?"):
           if isinstance(message, AssistantMessage):
               for block in message.content:
                   if isinstance(block, TextBlock):
                       print(f"Claude: {block.text}")
   
   anyio.run(main)
   
3. View traces in Scorecard

   Navigate to the Records page in Scorecard to see your agent traces.

   It may take 1-2 minutes for traces to appear on the Records page.

   

   Click on any record to view the full trace details, including the complete request/response data and model usage.

   

What Gets Traced

The Claude Agent SDK automatically captures:

Trace Data	Description
LLM Calls	Every messages.create call with full prompt and completion
Tool Use	Tool invocations, inputs, and outputs as nested spans
Model Usage	Input, output, and total token counts per call
Model Info	Model name, parameters, and configuration
Errors	Any failures with full error context

Environment Variables Reference

Variable	Required	Description
OTEL_EXPORTER_OTLP_HEADERS	Yes	Authentication header: Authorization=Bearer <scorecard_api_key>
ENABLE_BETA_TRACING_DETAILED	Yes	Set to 1 to enable detailed tracing
BETA_TRACING_ENDPOINT	Yes	OTLP endpoint URL (use https://tracing.scorecard.io/otel for Scorecard)
OTEL_RESOURCE_ATTRIBUTES	No	Set scorecard.project_id=<id> to target a specific project (defaults to oldest project)

Next Steps

Tracing Features

Learn about advanced tracing patterns and trace grouping

Metrics

Create custom metrics to evaluate agent performance

Trace to Testcase

Convert production traces into evaluation test cases