Claude Agent SDK Tracing

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

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"
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1
export OTEL_RESOURCE_ATTRIBUTES="scorecard.project_id=<your-project-id>"

Replace <your_scorecard_api_key> with your actual Scorecard API key (starts with ak_), and <your-project-id> with the project you want traces to land in.

If the project ID is wrong or invalid, traces will be sent to the oldest project in your organization.

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)

View traces in Scorecard

Navigate to the Records page in Scorecard to see your agent traces. Click any record to open its trace detail panel, which breaks the trace into four tabs: Conversation, Timeline, Chat, and Debug.The Conversation tab shows a chat-like replay of user messages, assistant responses, and tool calls.The Timeline tab shows a Gantt chart-style breakdown of every span, so you can see how LLM calls and tool executions overlap and how long each takes.The Chat tab lets you ask questions about the trace in natural language—what happened, why a step failed, or how it performed—and compare records side by side.The Debug tab pairs the full span tree with a trace overview—duration, cost, tokens, and model—plus the raw span data for deeper inspection.

Anatomy of a trace

Explore how a Claude Agent SDK trace is structured—spans, tool calls, model usage, and metadata—in this interactive demo:

Next Steps

Tracing Features

Learn about advanced tracing patterns and trace grouping

Metrics

Create custom metrics to evaluate agent performance

LangChain TracingTrace your LangChain applications with Scorecard using OpenLLMetry.

⌘I

Introduction

Quickstarts

Core features

Advanced features

Governance, Risk, and Compliance

Steps

Anatomy of a trace

Next Steps

Tracing Features

Metrics

​Steps

​Anatomy of a trace

​Next Steps

Tracing Features

Metrics

Steps

Anatomy of a trace

Next Steps