> ## Documentation Index > Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt > Use this file to discover all available pages before exploring further. # Strands Agents SDK > Trace Strands agent runs in Braintrust to debug agent reasoning, model calls, and tool execution [Strands Agents SDK](https://strandsagents.com/) helps you build AI agents. Braintrust traces Strands agents end-to-end, covering the agent's reasoning loop, model calls, and tool executions. The integration works with any model provider Strands supports. **TypeScript** ## Setup Install Braintrust, the Amazon Strands Agents SDK, and the model provider package your agent uses. The examples below use OpenAI. **1. Install packages** ```bash pnpm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pnpm add braintrust @strands-agents/sdk openai ``` ```bash npm theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} npm install braintrust @strands-agents/sdk openai ``` **2. Set environment variables** ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} BRAINTRUST_API_KEY= OPENAI_API_KEY= ``` ## Auto-instrumentation To trace `Agent`, `Graph`, and `Swarm` invocations from `@strands-agents/sdk` without changing your agent construction code, run your app with Braintrust's import hook. **1. Initialize Braintrust and invoke your agent** ```typescript title="trace-strands-auto.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import { Agent, tool } from "@strands-agents/sdk"; import { OpenAIModel } from "@strands-agents/sdk/models/openai"; import { initLogger } from "braintrust"; initLogger({ projectName: "strands-example", // Replace with your project name apiKey: process.env.BRAINTRUST_API_KEY, }); const lookupWeather = tool({ name: "lookup_weather", description: "Return the current weather for one city.", inputSchema: { type: "object", properties: { city: { type: "string" } }, required: ["city"], }, callback: ({ city }) => ({ city, forecast: "sunny" }), }); const agent = new Agent({ id: "weather-agent", name: "weather-agent", model: new OpenAIModel({ modelId: "gpt-5-mini", clientConfig: { apiKey: process.env.OPENAI_API_KEY }, }), printer: false, systemPrompt: "Answer weather questions concisely.", tools: [lookupWeather], }); const result = await agent.invoke("What is the weather in San Francisco?"); console.log(result.toString()); ``` **2. Run with the import hook** ```bash theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} node --import braintrust/hook.mjs trace-strands-auto.ts ``` The auto-instrumentation example uses plain JavaScript so `node --import` can run the file directly. The Braintrust APIs work the same in TypeScript projects. Compile your TypeScript to JavaScript and run the compiled file with the import hook, or [run TypeScript directly](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) with a TypeScript loader. > [!NOTE] > > If you're using a bundler, see [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md#auto-instrumentation) for plugin and loader setup. ## Manual instrumentation To trace Strands manually, wrap the SDK module with `wrapStrandsAgentSDK` to opt into tracing explicitly. ```typescript title="trace-strands-manual.ts" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import * as Strands from "@strands-agents/sdk"; import { OpenAIModel } from "@strands-agents/sdk/models/openai"; import { initLogger, wrapStrandsAgentSDK } from "braintrust"; initLogger({ projectName: "strands-example", // Replace with your project name apiKey: process.env.BRAINTRUST_API_KEY, }); const { Agent, tool } = wrapStrandsAgentSDK(Strands); const lookupWeather = tool({ name: "lookup_weather", description: "Return the current weather for one city.", inputSchema: { type: "object", properties: { city: { type: "string" } }, required: ["city"], }, callback: ({ city }) => ({ city, forecast: "sunny" }), }); const agent = new Agent({ id: "weather-agent", name: "weather-agent", model: new OpenAIModel({ modelId: "gpt-5-mini", clientConfig: { apiKey: process.env.OPENAI_API_KEY }, }), printer: false, systemPrompt: "Answer weather questions concisely.", tools: [lookupWeather], }); const result = await agent.invoke("What is the weather in San Francisco?"); console.log(result.toString()); ``` ## What Braintrust traces Braintrust captures the Strands span tree for agent and multi-agent runs: * Agent spans such as `Agent: weather-agent`, with invocation input, final output, agent ID, agent name, model ID, stop reason, token metrics, and duration. * Model spans such as `Strands model: gpt-5-mini`, nested under the agent span, with model metadata, stop reason, token metrics, and latency metrics. * Tool spans such as `tool: lookup_weather`, with tool input, output, tool call ID, tool name, status, errors, and duration. * Multi-agent orchestration spans (`Strands Graph` and `Strands Swarm`), including per-node spans (`node: `), handoffs, status, output, token metrics, and duration. * Inline document, image, and video content in span inputs stored as Braintrust attachments rather than embedded bytes. * Parent-child nesting under any enclosing Braintrust span. ## Resources * [Amazon Strands Agents SDK on npm](https://www.npmjs.com/package/@strands-agents/sdk) * [Strands Agent SDK documentation](https://strandsagents.com/) * [Trace LLM calls](https://docs.braintrust.dev/instrument/trace-llm-calls.md) **Python** ## Setup Install the Braintrust SDK and Strands, then set your API keys. The examples below use OpenAI. **1. Install packages** ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} uv add braintrust "strands-agents[openai]" strands-agents-tools ``` ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} pip install braintrust "strands-agents[openai]" strands-agents-tools ``` **2. Set environment variables** ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} BRAINTRUST_API_KEY= OPENAI_API_KEY= ``` ## Auto-instrumentation To trace Strands alongside Braintrust's other supported libraries, call `braintrust.auto_instrument()` before creating your agent. ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} import os import braintrust from strands import Agent, tool from strands.models.openai import OpenAIModel braintrust.auto_instrument() braintrust.init_logger( api_key=os.environ["BRAINTRUST_API_KEY"], project="strands-example", # Replace with your project name ) @tool def current_weather(city: str) -> str: """Return the current weather for a city.""" return f"It is sunny in {city}." model = OpenAIModel( model_id="gpt-4o-mini", client_args={"api_key": os.environ["OPENAI_API_KEY"]}, ) agent = Agent( system_prompt="You answer weather questions concisely.", tools=[current_weather], model=model, ) result = agent("What is the weather in San Francisco?") print(result) ``` > [accordion] Trace only Strands > > To trace Strands without auto-instrumenting other libraries, use `setup_strands()` instead of `braintrust.auto_instrument()`. > > ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}} > import os > > from braintrust.integrations.strands import setup_strands > from strands import Agent, tool > from strands.models.openai import OpenAIModel > > setup_strands(project_name="strands-example") > > @tool > def current_weather(city: str) -> str: > """Return the current weather for a city.""" > return f"It is sunny in {city}." > > model = OpenAIModel( > model_id="gpt-4o-mini", > client_args={"api_key": os.environ["OPENAI_API_KEY"]}, > ) > agent = Agent( > system_prompt="You answer weather questions concisely.", > tools=[current_weather], > model=model, > ) > > print(agent("What is the weather in San Francisco?")) > ``` > [!TIP] > > Already running Strands with `StrandsTelemetry` or an OTLP exporter? Keep that setup and route spans to Braintrust using the [Braintrust OpenTelemetry guide](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md#python-sdk-configuration). ## What Braintrust traces Braintrust mirrors Strands' native span tree, so the trace shape matches the agent's actual execution. Captured spans: * Agent invocation spans (`.invoke`), with input messages, agent name, model ID, and tool definitions; output stop reason, final message, and structured output. * Event loop cycle spans (`event_loop.cycle`), with input messages and cycle ID; output message and tool result message. * Model call spans (`.chat`), with input messages, system prompt, and model ID; output message, stop reason, and per-call token usage. * Tool call spans (`.execute`), with tool definition as input; output, execution status, and errors. * Parent-child nesting that mirrors Strands' span hierarchy and nests under any enclosing Braintrust span. ## Resources * [Strands Agents SDK documentation](https://strandsagents.com/) * [Braintrust Python SDK reference](https://docs.braintrust.dev/sdks/python/versions/latest.md) * [Braintrust OpenTelemetry guide](https://docs.braintrust.dev/integrations/sdk-integrations/opentelemetry/send-traces-and-logs.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.