> ## Documentation Index
> Fetch the complete documentation index at: https://scorecard-d65b5e8a-mintlify-update-user-annotations-convers.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Agent SDK Tracing

> Trace your Claude Agent SDK applications with Scorecard.

export const DarkLightImage = ({lightSrc, caption, alt, darkSrc = null, width = "1000"}) => {
  const getAbsoluteUrl = src => {
    if (src.startsWith('http://') || src.startsWith('https://')) {
      return src;
    }
    const currentUrl = typeof window !== 'undefined' ? window.location.origin : '';
    if (currentUrl.includes('.mintlify.app')) {
      const subdomain = currentUrl.split('.')[0].replace('https://', '');
      return `https://mintlify.s3.us-west-1.amazonaws.com/${subdomain}${src.startsWith('/') ? '' : '/'}${src}`;
    } else if (currentUrl === 'https://docs.scorecard.io') {
      return `https://mintlify.s3.us-west-1.amazonaws.com/scorecard-d65b5e8a${src.startsWith('/') ? '' : '/'}${src}`;
    } else {
      return `${currentUrl}${src.startsWith('/') ? '' : '/'}${src}`;
    }
  };
  const content = <>
      <img className="block dark:hidden" width={width} src={getAbsoluteUrl(lightSrc)} alt={alt} />
      <img className="hidden dark:block" width={width} src={getAbsoluteUrl(darkSrc || lightSrc.replace('light', 'dark'))} alt={alt} />
    </>;
  if (caption) {
    return <Frame caption={caption}>{content}</Frame>;
  } else {
    return content;
  }
};

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.

<Info>
  **Using the standard Anthropic SDK?** Check out the general [Tracing Quickstart](/intro/tracing-quickstart) for the proxy method that works with any Anthropic client.
</Info>

## Steps

<Steps>
  <Step title="Set up environment variables">
    Configure the OpenTelemetry exporter to send traces to Scorecard. You'll need your Scorecard API key from [Settings](https://app.scorecard.io/settings).

    ```bash theme={null}
    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"
    ```

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

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

    ```bash theme={null}
    export OTEL_RESOURCE_ATTRIBUTES="scorecard.project_id=<your-project-id>"
    ```

    If not set, traces will default to your oldest project in the organization.
  </Step>

  <Step title="Run your agent">
    With the environment variables configured, run your Claude Agent SDK application. All agent activity is automatically traced.

    ```python title="example.py" [expandable] theme={null}
    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)
    ```
  </Step>

  <Step title="View traces in Scorecard">
    Navigate to the **Records** page in [Scorecard](https://app.scorecard.io) to see your agent traces.

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

    <DarkLightImage lightSrc="/images/records-table-claude-sdk-light.png" darkSrc="/images/records-table-claude-sdk-dark.png" alt="Records table showing Claude Agent SDK traces" caption="Records page showing agent traces" />

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

    <DarkLightImage lightSrc="/images/records-details-claude-sdk-light.png" darkSrc="/images/records-details-claude-sdk-dark.png" alt="Trace details view" caption="Trace details with request/response data and model usage" />
  </Step>
</Steps>

## 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

<CardGroup cols={2}>
  <Card title="Tracing Features" icon="chart-line" href="/features/tracing">
    Learn about advanced tracing patterns and trace grouping
  </Card>

  <Card title="Metrics" icon="gauge" href="/features/metrics">
    Create custom metrics to evaluate agent performance
  </Card>

  <Card title="Trace to Testcase" icon="flask" href="/features/trace-to-testcase">
    Convert production traces into evaluation test cases
  </Card>
</CardGroup>