Strands Agents SDK

Setup

Install Braintrust, the Amazon Strands Agents SDK, and the model provider package your agent uses. The examples below use OpenAI.

Install packages

pnpm add braintrust @strands-agents/sdk openai

npm install braintrust @strands-agents/sdk openai

Set environment variables

.env

BRAINTRUST_API_KEY=<your-braintrust-api-key>
OPENAI_API_KEY=<your-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.

Initialize Braintrust and invoke your agent

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());

Run with the import hook

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, then run the compiled file with the import hook.

If you’re using a bundler, see Trace LLM calls for plugin and loader setup.

Manual instrumentation

To trace Strands manually, wrap the SDK module with wrapStrandsAgentSDK to opt into tracing explicitly.

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: <node-id>), 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.

AI providers

SDKs

Developer tools

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources

​Setup

​Auto-instrumentation

​Manual instrumentation

​What Braintrust traces

​Resources

Setup

Auto-instrumentation

Manual instrumentation

What Braintrust traces

Resources