Claude Agent SDK

The Claude Agent SDK (claude-agent-sdk) lets you run Claude-powered agent sessions with tool use, multi-turn reasoning, and streamed events. Respan gives you full observability over every SDK run, streamed response, and tool call — and gateway routing for Claude models through the Anthropic-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key. For gateway, also add credits or a provider key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Tracing

Gateway

Setup

Install packages

$ pip install claude-agent-sdk respan-ai respan-instrumentation-claude-agent-sdk

Set environment variables

$ export ANTHROPIC_API_KEY="YOUR_ANTHROPIC_API_KEY"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

ANTHROPIC_API_KEY is used for Claude requests. RESPAN_API_KEY is used to export traces to Respan.

Initialize and run

1 import asyncio
2 
3 import claude_agent_sdk
4 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
5 from respan import Respan
6 from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor
7 
8 respan = Respan(
9     instrumentations=[ClaudeAgentSDKInstrumentor(capture_content=True)],
10 )
11 
12 async def main():
13     async for message in claude_agent_sdk.query(
14         prompt="Explain tracing in one sentence.",
15         options=ClaudeAgentOptions(model="sonnet", max_turns=1),
16     ):
17         if isinstance(message, ResultMessage):
18             print(message.result)
19 
20 asyncio.run(main())
21 respan.flush()

View your trace

Open the Traces page to see your workflow with Claude Agent SDK spans, streamed responses, and tool activity.

Configuration

Parameter	Type	Default	Description
`api_key`	`str \| None`	`None`	Falls back to `RESPAN_API_KEY` env var.
`base_url`	`str \| None`	`None`	Falls back to `RESPAN_BASE_URL` env var.
`instrumentations`	`list`	`[]`	Plugin instrumentations to activate (e.g. `ClaudeAgentSDKInstrumentor(capture_content=True)`).
`customer_identifier`	`str \| None`	`None`	Default customer identifier for all spans.
`metadata`	`dict \| None`	`None`	Default metadata attached to all spans.
`environment`	`str \| None`	`None`	Environment tag (e.g. `"production"`).

Attributes

In Respan()

Set defaults at initialization — these apply to all spans.

1 from respan import Respan
2 from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor
3 
4 respan = Respan(
5     instrumentations=[ClaudeAgentSDKInstrumentor(capture_content=True)],
6     customer_identifier="user_123",
7     metadata={"service": "claude-agent-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request using a context scope.

1 import claude_agent_sdk
2 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
3 from respan import Respan, propagate_attributes
4 from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor
5 
6 respan = Respan(
7     instrumentations=[ClaudeAgentSDKInstrumentor(capture_content=True)],
8 )
9 
10 async def handle_request(user_id: str, prompt: str):
11     with propagate_attributes(
12         customer_identifier=user_id,
13         thread_identifier="conv_abc_123",
14         metadata={"plan": "pro"},
15     ):
16         async for message in claude_agent_sdk.query(
17             prompt=prompt,
18             options=ClaudeAgentOptions(model="sonnet", max_turns=1),
19         ):
20             if isinstance(message, ResultMessage):
21                 print(message.result)

Attribute	Type	Description
`customer_identifier`	`str`	Identifies the end user in Respan analytics.
`thread_identifier`	`str`	Groups related messages into a conversation.
`metadata`	`dict`	Custom key-value pairs. Merged with default metadata.

Decorators (optional)

Decorators are not required. All Claude Agent SDK runs and streamed responses are auto-traced by the instrumentor. Use @workflow and @task (Python) or withWorkflow and withTask (TypeScript) to add structure when you want to group related agent runs into a named workflow with nested tasks.

1 import asyncio
2 
3 import claude_agent_sdk
4 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
5 from respan import Respan, task, workflow
6 from respan_instrumentation_claude_agent_sdk import ClaudeAgentSDKInstrumentor
7 
8 respan = Respan(
9     instrumentations=[ClaudeAgentSDKInstrumentor(capture_content=True)],
10 )
11 
12 @task(name="draft_answer")
13 async def draft_answer(prompt: str) -> str:
14     async for message in claude_agent_sdk.query(
15         prompt=prompt,
16         options=ClaudeAgentOptions(model="sonnet", max_turns=1),
17     ):
18         if isinstance(message, ResultMessage):
19             return message.result
20     return ""
21 
22 @workflow(name="customer_support_flow")
23 async def handle_ticket():
24     summary = await draft_answer("Summarize a billing issue in one sentence.")
25     print(summary)
26 
27 asyncio.run(handle_ticket())
28 respan.flush()

Examples

Basic query

Run a single Claude Agent SDK query and print the final result.

1 import asyncio
2 
3 import claude_agent_sdk
4 from claude_agent_sdk import ClaudeAgentOptions, ResultMessage
5 
6 async def main():
7     async for message in claude_agent_sdk.query(
8         prompt="Say hello in three languages.",
9         options=ClaudeAgentOptions(model="sonnet", max_turns=1),
10     ):
11         if isinstance(message, ResultMessage):
12             print(message.result)
13 
14 asyncio.run(main())

Streaming message flow

The SDK emits multiple message objects during a run. You can inspect the flow while Respan traces the full session.

1 import asyncio
2 
3 import claude_agent_sdk
4 from claude_agent_sdk import ClaudeAgentOptions
5 
6 async def main():
7     message_types = []
8     async for message in claude_agent_sdk.query(
9         prompt="Explain recursion in one short paragraph.",
10         options=ClaudeAgentOptions(model="sonnet", max_turns=1),
11     ):
12         message_types.append(type(message).__name__)
13 
14     print(" -> ".join(message_types))
15 
16 asyncio.run(main())