Claude Agent SDK

The Anthropic Claude Agent SDK (formerly Claude Code SDK) is the same runtime that powers Claude Code. It executes Claude agentically — reading files, editing them, running subprocesses, and fetching the web. Trefur ships a dedicated patch_claude_agent_sdk adapter in Python + TypeScript that captures every tool use + tool result alongside the underlying Anthropic API call.

Install (Python)

pip install trefur-observe claude-agent-sdk

Setup (Python)

import os
import anyio
from claude_agent_sdk import query, ClaudeAgentOptions
from trefur_observe import TrefurObserve, patch_claude_agent_sdk

# Initialise observe once at startup.
TrefurObserve.init(
    api_key=os.environ["TREFUR_API_KEY"],
    agent={"name": "code-review-agent", "framework": "claude-agent-sdk"},
)
patch_claude_agent_sdk(TrefurObserve.get_instance())

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-4-20250514",
        allowed_tools=["Read", "Edit", "Bash"],
    )
    async for message in query(
        prompt="Review the diff in branch feature-x and suggest fixes",
        options=options,
    ):
        # Each message (assistant turn, tool use, tool result) flows
        # through here. Trefur has already captured it.
        pass

anyio.run(main)

Install (TypeScript)

npm install @trefur/observe @anthropic-ai/claude-agent-sdk

Setup (TypeScript)

import * as cas from '@anthropic-ai/claude-agent-sdk';
import { TrefurObserve, patchClaudeAgentSDK } from '@trefur/observe';

TrefurObserve.init({
  apiKey: process.env.TREFUR_API_KEY!,
  agent: { name: 'code-review-agent', framework: 'claude-agent-sdk' },
});
// patchClaudeAgentSDK takes the imported module namespace and the
// observe instance. Invoke the SDK through the same 'cas' import.
patchClaudeAgentSDK(cas, TrefurObserve.getInstance());

for await (const msg of cas.query({
  prompt: 'Review the diff in branch feature-x and suggest fixes',
  options: {
    model: 'claude-sonnet-4-20250514',
    allowedTools: ['Read', 'Edit', 'Bash'],
  },
})) {
  // Each message (assistant turn, tool use, tool result) is captured.
}

What gets traced

  • Each query() iteration renders as a run.
  • Every tool use — Read, Edit, Bash, WebFetch, Grep, Glob — captured with input + output.
  • File I/O from the Read + Edit + Write tools — content captured (subject to your redaction level).
  • Subprocess calls from the Bash tool — command + stdout + stderr + exit code.
  • Token usage per assistant turn + cumulative for the run.
  • MCP-server tool calls if the SDK is configured with MCP servers — tagged with the server name.

Common use case — autonomous code review + edit loops

The canonical pattern is a long-running agent doing code review + applying fixes in a sandbox. Trefur renders the full session: the files it read, the diffs it applied, every subprocess it spawned, and the cumulative token cost. Wire to the Anthropic connector for org-wide Admin-API usage visibility on top.

Common pitfalls

  • Long-running sessions. The Claude Agent SDK can run for hours. Trefur batches and flushes every 5 seconds by default, so an OOM or crash mid-session still leaves a partial trace. Pass flush_interval=1.0 (seconds) to TrefurObserve.init for faster checkpointing if you need it.
  • MCP servers running inside the agent. If your MCP server is process-local (stdio transport), telemetry from inside the server isn't captured by patch_claude_agent_sdk. Install the SDK inside the MCP server process too if you want full coverage.
  • Sensitive file content. The Read tool captures file content by default. Call TrefurObserve.get_instance().set_prompt_capture_mode("redacted") to redact bodies while keeping the envelope, or "hash_only" / "off" to capture even less.

See the Python SDK or JavaScript SDK reference for the full adapter surface.