> ## 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](/docs/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, and for capabilities the CLI doesn't cover, such as monitor views, alerts, and authoring evaluators, preprocessors, and facets.

[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="setup-typescript">
    Setup
  </h2>

  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>

  <h2 id="auto-instrumentation-typescript">
    Auto-instrumentation
  </h2>

  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.

  <Steps>
    <Step title="Initialize Braintrust and invoke your agent">
      <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>
    </Step>

    <Step title="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](/docs/instrument/trace-llm-calls#auto-instrumentation) for plugin and loader setup.
      </Note>
    </Step>
  </Steps>

  <h2 id="manual-instrumentation-typescript">
    Manual instrumentation
  </h2>

  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>

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

  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.

  <h2 id="resources-typescript">
    Resources
  </h2>

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

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

  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>

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

  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](/docs/integrations/sdk-integrations/opentelemetry#python-sdk-configuration).
  </Tip>

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

  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.

  <h2 id="resources-python">
    Resources
  </h2>

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