Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://docs.respan.ai/mcp"
    }
  }
}

​
What is Anthropic Agents SDK?

The Anthropic Agents SDK (claude-agent-sdk) is a framework for building agent workflows powered by Claude. It supports tool use, sub-agent delegation, and structured conversations. The Respan exporter hooks into the SDK’s lifecycle events to capture full trace data.

​
Setup

The Anthropic Agents SDK uses an exporter pattern rather than the standard Respan() instrumentor pattern. The exporter wraps query() calls to capture traces.
1

Install packages

pip install claude-agent-sdk respan-exporter-anthropic-agents python-dotenv
2

Set environment variables

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
RESPAN_API_KEY is used for trace export. ANTHROPIC_API_KEY is used by the Claude Agent SDK to call Anthropic directly.
You can skip ANTHROPIC_API_KEY by routing calls through the Respan gateway.
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
# No ANTHROPIC_API_KEY needed
Pass the gateway URL and key via ClaudeAgentOptions.env:
options = ClaudeAgentOptions(
    permission_mode="bypassPermissions",
    max_turns=1,
    env={
        "ANTHROPIC_BASE_URL": "https://api.respan.ai/api/anthropic",
        "ANTHROPIC_AUTH_TOKEN": RESPAN_API_KEY,
        "ANTHROPIC_API_KEY": RESPAN_API_KEY,
    },
)
3

Initialize and run

import os
from dotenv import load_dotenv

load_dotenv(override=True)

from claude_agent_sdk import ClaudeAgentOptions
from respan_exporter_anthropic_agents import RespanAnthropicAgentsExporter

exporter = RespanAnthropicAgentsExporter(
    api_key=os.getenv("RESPAN_API_KEY"),
    base_url=os.getenv("RESPAN_BASE_URL"),
)

async for message in exporter.query(
    prompt="What is 2 + 2? Reply in one word.",
    options=ClaudeAgentOptions(
        permission_mode="bypassPermissions",
        max_turns=1,
    ),
):
    print(type(message).__name__)
4

View your trace

Open the Traces page to see your agent trace.

​
Configuration

ParameterTypeDefaultDescription
api_keystrRESPAN_API_KEY env varRespan API key.
base_urlstrRESPAN_BASE_URL env varAPI base URL.
endpointstr | NoneNoneCustom ingest endpoint URL.
timeout_secondsint15HTTP timeout for trace export.
max_retriesint3Retry attempts for failed exports.

​
Attributes

The exporter automatically captures:
AttributeSourceDescription
session_idSystemMessageUnique session identifier.
input_tokensAssistantMessage.usagePrompt token count.
output_tokensAssistantMessage.usageCompletion token count.
cache_creation_input_tokensAssistantMessage.usageCache creation tokens.
cache_read_input_tokensAssistantMessage.usageCache read tokens.
modelAssistantMessageModel name used.

​
Decorators

The Anthropic Agents SDK uses the exporter pattern rather than @workflow/@task decorators. All lifecycle events are captured automatically by the exporter.

​
Examples

​
Wrapped query

The simplest integration pattern — exporter.query() handles tracing hooks automatically. 
from claude_agent_sdk import ClaudeAgentOptions
from respan_exporter_anthropic_agents import RespanAnthropicAgentsExporter

exporter = RespanAnthropicAgentsExporter()

message_types = []
async for message in exporter.query(
    prompt="Name three primary colors.",
    options=ClaudeAgentOptions(
        permission_mode="bypassPermissions",
        max_turns=1,
    ),
):
    message_types.append(type(message).__name__)

print(" -> ".join(message_types))
# SystemMessage -> UserMessage -> AssistantMessage -> ResultMessage

​
Tool use

Tool calls are automatically captured as child spans with inputs and outputs. 
from claude_agent_sdk import ClaudeAgentOptions
from respan_exporter_anthropic_agents import RespanAnthropicAgentsExporter

exporter = RespanAnthropicAgentsExporter()

async for message in exporter.query(
    prompt="List the Python files in the current directory.",
    options=ClaudeAgentOptions(
        permission_mode="bypassPermissions",
        max_turns=3,
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    print(type(message).__name__)

​
Streaming

The exporter.query() method streams messages as they arrive. 
from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
from respan_exporter_anthropic_agents import RespanAnthropicAgentsExporter

exporter = RespanAnthropicAgentsExporter()

async for message in exporter.query(
    prompt="Write a haiku about programming.",
    options=ClaudeAgentOptions(
        permission_mode="bypassPermissions",
        max_turns=1,
    ),
):
    msg_type = type(message).__name__

    if msg_type == "AssistantMessage":
        for block in getattr(message, "content", []):
            if hasattr(block, "text"):
                print(block.text)
    elif isinstance(message, ResultMessage):
        print(f"Done: {message.subtype}, turns={message.num_turns}")

​
Traced events

The exporter hooks into five SDK lifecycle events:
EventSpan TypeDescription
UserPromptSubmittaskUser submits a prompt.
PreToolUse—Tool invocation starts (paired with PostToolUse).
PostToolUsetoolTool completes with input/output.
SubagentStoptaskSub-agent finishes execution.
Stop—Root agent terminates.

​
Gateway

You can route all Anthropic calls through the Respan gateway by setting environment variables: 
export ANTHROPIC_BASE_URL="https://api.respan.ai/api/anthropic"
export ANTHROPIC_API_KEY="YOUR_RESPAN_API_KEY"
Or configure via ClaudeAgentOptions.env: 
options = ClaudeAgentOptions(
    permission_mode="bypassPermissions",
    max_turns=1,
    env={
        "ANTHROPIC_BASE_URL": "https://api.respan.ai/api/anthropic",
        "ANTHROPIC_AUTH_TOKEN": os.getenv("RESPAN_API_KEY"),
        "ANTHROPIC_API_KEY": os.getenv("RESPAN_API_KEY"),
    },
)