> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Strands Agents (tracing)

> Trace Strands Agents workflows with Respan.

[Strands Agents](https://strandsagents.com/) 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](/docs/gateway/strands-agents).

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

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

#### Use Respan Gateway

See [Strands Agents gateway setup](/docs/gateway/strands-agents) to route model calls through the Respan gateway.

#### Example projects

* [Example projects root](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

**`Python`**

```bash Python
pip install respan-ai respan-instrumentation-strands-agents "strands-agents[openai]"
```

**`TypeScript`**

```bash TypeScript
npm install @respan/respan @respan/instrumentation-strands-agents @strands-agents/sdk openai zod
```

#### Set environment variables

```bash
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

**`Python`**

```python Python
import os

from strands import Agent
from strands.models.openai import OpenAIModel
from strands.tools import tool
from respan import Respan
from respan_instrumentation_strands_agents import StrandsAgentsInstrumentor

respan = Respan(instrumentations=[StrandsAgentsInstrumentor()])

@tool
def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"The weather in {location} is sunny, 72F."

model = OpenAIModel(
    model_id="gpt-4o-mini",
    client_args={"api_key": os.environ["OPENAI_API_KEY"]},
)

agent = Agent(model=model, tools=[get_weather])
response = agent("What is the weather in Seattle?")
print(response)
```

**`TypeScript`**

```typescript TypeScript
import { Agent, tool } from "@strands-agents/sdk";
import { OpenAIModel } from "@strands-agents/sdk/models/openai";
import { Respan } from "@respan/respan";
import { StrandsAgentsInstrumentor } from "@respan/instrumentation-strands-agents";
import { z } from "zod";

const respan = new Respan({
  apiKey: process.env.RESPAN_API_KEY,
  baseURL: process.env.RESPAN_BASE_URL,
  instrumentations: [new StrandsAgentsInstrumentor()],
});
await respan.initialize();

const model = new OpenAIModel({
  api: "chat",
  modelId: "gpt-4.1-nano",
  apiKey: process.env.OPENAI_API_KEY,
});

const getWeather = tool({
  name: "get_weather",
  description: "Get the current weather for a city.",
  inputSchema: z.object({ city: z.string() }),
  callback: ({ city }) => `The weather in ${city} is sunny and 72F.`,
});

const agent = new Agent({
  name: "WeatherAgent",
  model,
  tools: [getWeather],
  systemPrompt: "You are a concise weather assistant.",
  printer: false,
});

await agent.invoke("What is the weather in Seattle?");
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) 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.

**`Python`**

```python Python
from respan import Respan
from respan_instrumentation_strands_agents import StrandsAgentsInstrumentor

respan = Respan(
    instrumentations=[StrandsAgentsInstrumentor()],
    customer_identifier="user_123",
    metadata={"service": "strands-api", "version": "1.0.0"},
)
```

**`TypeScript`**

```typescript TypeScript
import { Respan } from "@respan/respan";
import { StrandsAgentsInstrumentor } from "@respan/instrumentation-strands-agents";

// Note: default attributes are set via propagateAttributes() in TypeScript.
const respan = new Respan({
  instrumentations: [new StrandsAgentsInstrumentor()],
});
```

### With propagate_attributes

Override per-request attributes using a context scope.

**`Python`**

```python Python
from respan import Respan, propagate_attributes
from respan_instrumentation_strands_agents import StrandsAgentsInstrumentor

respan = Respan(instrumentations=[StrandsAgentsInstrumentor()])

async def handle_request(user_id: str, message: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        print(agent(message))
```

**`TypeScript`**

```typescript TypeScript
import { Respan } from "@respan/respan";
import { StrandsAgentsInstrumentor } from "@respan/instrumentation-strands-agents";

const respan = new Respan({
  instrumentations: [new StrandsAgentsInstrumentor()],
});
await respan.initialize();

async function handleRequest(userId: string, message: string) {
  await respan.propagateAttributes(
    {
      customer_identifier: userId,
      thread_identifier: "conv_abc_123",
      metadata: { plan: "pro" },
    },
    async () => {
      await agent.invoke(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.                      |