Strands Agents (tracing)

Strands Agents is an SDK for building model-driven agents with tools, sessions, and orchestration. Respan captures agent runs, reasoning loops, model calls, tool invocations, graph spans, and swarm spans.

This tracing setup uses your model provider credentials directly. To route model calls through Respan instead, use the Strands Agents gateway setup.

Set up Respan

Create an account at platform.respan.ai and grab an API key.

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

Use Respan Gateway

See Strands Agents gateway setup to route model calls through the Respan gateway.

Example projects

Example projects root

Setup

Install packages

$ pip install respan-ai respan-instrumentation-strands-agents "strands-agents[openai]"

Set environment variables

$ export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"

OPENAI_API_KEY is used for direct provider calls. RESPAN_API_KEY exports traces to Respan.

Initialize and run

1 import os
2 
3 from strands import Agent
4 from strands.models.openai import OpenAIModel
5 from strands.tools import tool
6 from respan import Respan
7 from respan_instrumentation_strands_agents import StrandsAgentsInstrumentor
8 
9 respan = Respan(instrumentations=[StrandsAgentsInstrumentor()])
10 
11 @tool
12 def get_weather(location: str) -> str:
13     """Get the current weather for a location."""
14     return f"The weather in {location} is sunny, 72F."
15 
16 model = OpenAIModel(
17     model_id="gpt-4o-mini",
18     client_args={"api_key": os.environ["OPENAI_API_KEY"]},
19 )
20 
21 agent = Agent(model=model, tools=[get_weather])
22 response = agent("What is the weather in Seattle?")
23 print(response)
24 respan.flush()

View your trace

Open the Traces page to see Strands agent, model, tool, loop, graph, swarm, and node spans.

Configuration

Parameter	Type	Default	Description
`api_key` / `apiKey`	`str \| None` / `string \| undefined`	`RESPAN_API_KEY`	Respan API key used to export traces.
`base_url` / `baseURL`	`str \| None` / `string \| undefined`	`RESPAN_BASE_URL`	Optional Respan trace export API URL.
`instrumentations`	`list` / `RespanInstrumentation[]`	`[]`	Include `StrandsAgentsInstrumentor()` or `new StrandsAgentsInstrumentor()` to activate Strands tracing.
`includeToolDefinitions`	`boolean`	`true`	TypeScript option that opts in to Strands tool-definition semantic conventions before export.

Attributes

In Respan()

Set defaults at initialization. These apply to all spans.

1 from respan import Respan
2 from respan_instrumentation_strands_agents import StrandsAgentsInstrumentor
3 
4 respan = Respan(
5     instrumentations=[StrandsAgentsInstrumentor()],
6     customer_identifier="user_123",
7     metadata={"service": "strands-api", "version": "1.0.0"},
8 )

With propagate_attributes

Override per-request attributes using a context scope.

1 from respan import Respan, propagate_attributes
2 from respan_instrumentation_strands_agents import StrandsAgentsInstrumentor
3 
4 respan = Respan(instrumentations=[StrandsAgentsInstrumentor()])
5 
6 async def handle_request(user_id: str, message: str):
7     with propagate_attributes(
8         customer_identifier=user_id,
9         thread_identifier="conv_abc_123",
10         metadata={"plan": "pro"},
11     ):
12         print(agent(message))

Attribute	Type	Description
`customer_identifier`	`str` / `string`	Identifies the end user in Respan analytics.
`thread_identifier`	`str` / `string`	Groups related messages into a conversation.
`metadata`	`dict` / `Record<string, unknown>`	Custom key-value pairs.