> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/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

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[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.

<View title="TypeScript" icon="https://img.logo.dev/typescriptlang.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="tracing-typescript">
    Tracing
  </h2>

  To trace Strands agents with Braintrust's TypeScript SDK, use auto-instrumentation or manual instrumentation. Auto-instrumentation is the recommended path for most users.

  <Tabs>
    <Tab title="Auto-instrumentation">
      <h3 id="setup-typescript-auto">
        Setup
      </h3>

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

      <Steps>
        <Step title="Install packages">
          <CodeGroup>
            ```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
            ```
          </CodeGroup>
        </Step>

        <Step title="Set environment variables">
          ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          BRAINTRUST_API_KEY=<your-braintrust-api-key>
          OPENAI_API_KEY=<your-openai-api-key>
          ```
        </Step>
      </Steps>

      <h3 id="trace-typescript-auto">
        Trace your agent
      </h3>

      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.

      <CodeGroup>
        ```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());
        ```
      </CodeGroup>

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

      <Note>
        If you're using a bundler, see [Trace LLM calls](/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Tab>

    <Tab title="Manual instrumentation">
      <h3 id="setup-typescript-manual">
        Setup
      </h3>

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

      <Steps>
        <Step title="Install packages">
          <CodeGroup>
            ```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
            ```
          </CodeGroup>
        </Step>

        <Step title="Set environment variables">
          ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          BRAINTRUST_API_KEY=<your-braintrust-api-key>
          OPENAI_API_KEY=<your-openai-api-key>
          ```
        </Step>
      </Steps>

      <h3 id="trace-typescript-manual">
        Trace your agent
      </h3>

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

      <CodeGroup>
        ```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());
        ```
      </CodeGroup>
    </Tab>
  </Tabs>

  <h3 id="what-traced-typescript">
    What Braintrust traces
  </h3>

  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 `Graph` and `Swarm` spans, including node spans, handoffs, status, output, token metrics, and duration.
  * Parent-child nesting under any enclosing Braintrust span.

  <h3 id="tracing-resources-typescript">
    Tracing resources
  </h3>

  * [Amazon Strands Agents SDK on npm](https://www.npmjs.com/package/@strands-agents/sdk)
  * [Strands Agent SDK documentation](https://strandsagents.com/)
  * [Trace LLM calls](/instrument/trace-llm-calls)
</View>

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="tracing-python">
    Tracing
  </h2>

  To trace Strands agents with Braintrust's Python SDK, use auto-instrumentation.

  <Tabs>
    <Tab title="Auto-instrumentation">
      <h3 id="setup-python-auto">
        Setup
      </h3>

      Install the Braintrust SDK and Strands, then set your API keys. The examples below use OpenAI.

      <Steps>
        <Step title="Install packages">
          <CodeGroup>
            ```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
            ```
          </CodeGroup>
        </Step>

        <Step title="Set environment variables">
          ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
          BRAINTRUST_API_KEY=<your-braintrust-api-key>
          OPENAI_API_KEY=<your-openai-api-key>
          ```
        </Step>
      </Steps>

      <h3 id="trace-python-auto">
        Trace your agent
      </h3>

      To trace Strands alongside Braintrust's other supported libraries, call `braintrust.auto_instrument()` before creating your agent.

      <CodeGroup>
        ```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)
        ```
      </CodeGroup>

      <Accordion title="Trace only Strands">
        To trace Strands without auto-instrumenting other libraries, use `setup_strands()` instead of `braintrust.auto_instrument()`.

        <CodeGroup>
          ```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?"))
          ```
        </CodeGroup>
      </Accordion>

      <Tip>
        Already running Strands with `StrandsTelemetry` or an OTLP exporter? Keep that setup and route spans to Braintrust using the [Braintrust OpenTelemetry guide](/integrations/sdk-integrations/opentelemetry#python-sdk-configuration).
      </Tip>
    </Tab>
  </Tabs>

  <h3 id="what-traced-python">
    What Braintrust traces
  </h3>

  Braintrust mirrors Strands' native span tree, so the trace shape matches the agent's actual execution. Captured spans:

  * Agent invocation spans (`<agent>.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 (`<model>.chat`), with input messages, system prompt, and model ID; output message, stop reason, and per-call token usage.
  * Tool call spans (`<tool>.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.

  <h3 id="tracing-resources-python">
    Tracing resources
  </h3>

  * [Strands Agents SDK documentation](https://strandsagents.com/)
  * [Braintrust Python SDK reference](/sdks/python/versions/latest)
  * [Braintrust OpenTelemetry guide](/integrations/sdk-integrations/opentelemetry)
</View>