Claude Agent SDK Traces

Use this integration for applications that call the Claude Agent SDK, formerly the Claude Code SDK. Python can patch query() during setup() before import. TypeScript uses an explicit wrapper because ESM namespace bindings cannot be safely patched in place. The Claude Agent SDK integration emits an AGENT span for each query loop. To group those executions under a stable custom ID in the Agents dashboard, wrap the product-level query with agentSpan() / agent_span() and use the SDK wrapper inside it. If your app shells out to the claude binary instead of importing @anthropic-ai/claude-agent-sdk or claude_agent_sdk, use Claude Code SDK traces.

Install

bun add @inference/tracing @anthropic-ai/claude-agent-sdk

pip install 'inference-catalyst-tracing[claude-agent-sdk]'

TypeScript Wrapped Query

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";
import { setup, wrapClaudeAgentSdkQuery } from "@inference/tracing";

const tracing = await setup({ serviceName: "claude-agent" });
const tracedQuery = wrapClaudeAgentSdkQuery(query);

const stream = tracedQuery({
  prompt:
    "Count the number of files matching *.md under the current directory tree. " +
    "Use the Bash tool. Reply with just the integer.",
  options: {
    maxTurns: 4,
    allowedTools: ["Bash"],
    permissionMode: "bypassPermissions",
  },
});

for await (const message of stream) {
  console.log(message);
}

await tracing.shutdown();

Stable Agent Identity

Use a stable agent.id for the logical agent or workflow you operate. The Claude Agent SDK span remains visible inside the trace, and the outer AGENT span provides the dashboard grouping key.

import { agentSpan } from "@inference/tracing";

const prompt = "Review the current diff and list risky changes.";

await agentSpan(
  {
    agentId: "claude-review-agent",
    agentName: "Claude Review Agent",
    spanName: "claude-review.run",
    sessionId: "conversation-pr-review-101",
    role: "code-review",
    system: "anthropic",
  },
  async (span) => {
    span.setInput(prompt);
    const stream = tracedQuery({ prompt, options: { maxTurns: 4 } });
    let output = "";

    for await (const message of stream) {
      output += JSON.stringify(message) + "\n";
    }

    span.setOutput(output.trim());
  },
);

from inference_catalyst_tracing import agent_span

prompt = "Review the current diff and list risky changes."

async def traced_review() -> None:
    options = ClaudeAgentOptions(max_turns=4)

    with agent_span(
        tracing.tracer,
        agent_id="claude-review-agent",
        agent_name="Claude Review Agent",
        span_name="claude-review.run",
        session_id="conversation-pr-review-101",
        agent_role="code-review",
        system="anthropic",
    ) as span:
        span.set_input(prompt)
        output = []
        async for message in query(prompt=prompt, options=options):
            output.append(str(message))
        span.set_output("\n".join(output))

Python Query Loop

Python

import asyncio

from inference_catalyst_tracing import setup

tracing = setup(service_name="claude-agent")

from claude_agent_sdk import ClaudeAgentOptions, query

async def main() -> None:
    options = ClaudeAgentOptions(
        max_turns=4,
        allowed_tools=["Bash"],
        permission_mode="bypassPermissions",
    )
    async for message in query(
        prompt=(
            "Count files matching *.md under the current directory tree. "
            "Use the Bash tool. Reply with just the integer."
        ),
        options=options,
    ):
        print(message)

asyncio.run(main())
tracing.shutdown()

What To Look For

An AGENT span for the query run
An outer AGENT span with agent.id when you add the stable identity wrapper
Nested LLM turns from the Claude Agent SDK
Tool-use and tool-result data when built-in tools are used
Final assistant output captured on the span

Integrations

Traces

Gateway

Install

TypeScript Wrapped Query

Stable Agent Identity

Python Query Loop

What To Look For

​Install

​TypeScript Wrapped Query

​Stable Agent Identity

​Python Query Loop

​What To Look For

Install

TypeScript Wrapped Query

Stable Agent Identity

Python Query Loop

What To Look For