feat(strands): add agents integration (#346)

Trace Strands agent, event loop, model, and tool lifecycle spans by
mirroring the framework's native tracer hooks without requiring users to
enable OTEL.

Add Strands version matrix coverage, auto-instrumentation wiring, and
VCR-backed tests for latest and 1.20.0. Store Strands token usage under
metadata.strands_usage to avoid double-counting provider token metrics.

resolves
#337

Author: AbhiPrasad

py/noxfile.py

@@ -247,6 +247,18 @@ def test_agno(session, version):
     _run_tests(session, f"{INTEGRATION_DIR}/agno/test_workflow.py", version=version)
 
 
+STRANDS_VERSIONS = _get_matrix_versions("strands-agents")
+
+
+@nox.session()
+@nox.parametrize("version", STRANDS_VERSIONS, ids=STRANDS_VERSIONS)
+def test_strands(session, version):
+    _install_test_deps(session)
+    _install_matrix_dep(session, "strands-agents", version)
+    _install_group_locked(session, "test-strands")
+    _run_tests(session, f"{INTEGRATION_DIR}/strands/test_strands.py", version=version)
+
+
 AGENTSCOPE_VERSIONS = _get_matrix_versions("agentscope")
 
 

py/pyproject.toml

@@ -133,6 +133,11 @@ test-agentscope = [
     "openai==2.31.0",
 ]
 
+test-strands = [
+    {include-group = "test"},
+    "openai==2.32.0",
+]
+
 test-pydantic-ai-logfire = [
     {include-group = "test"},
     "logfire==4.32.1",
@@ -237,6 +242,7 @@ conflicts = [
         {group = "test-crewai"},
         {group = "test-agno"},
         {group = "test-agentscope"},
+        {group = "test-strands"},
         {group = "test-langchain"},
         {group = "lint"},
     ],
@@ -305,6 +311,10 @@ latest = "autogen-agentchat==0.7.5"
 latest = "autogen-ext[openai]==0.7.5"
 "0.7.0" = "autogen-ext[openai]==0.7.0"
 
+[tool.braintrust.matrix.strands-agents]
+latest = "strands-agents==1.37.0"
+"1.20.0" = "strands-agents==1.20.0"
+
 [tool.braintrust.matrix.pydantic-ai-integration]
 latest = "pydantic-ai==1.86.1"
 "1.10.0" = "pydantic-ai==1.10.0"
@@ -396,6 +406,7 @@ openai = ["openai"]
 openai_agents = ["openai-agents"]
 openrouter = ["openrouter"]
 pydantic_ai = ["pydantic-ai-integration", "pydantic-ai-wrap-openai"]
+strands = ["strands-agents"]
 
 [tool.braintrust.vendor-packages]
 agno = "agno"
@@ -415,4 +426,5 @@ mistralai = "mistralai"
 openai = "openai"
 openai-agents = "agents"
 openrouter = "openrouter"
+strands-agents = "strands"
 temporalio = "temporalio"

py/src/braintrust/auto.py

@@ -25,6 +25,7 @@
     OpenAIIntegration,
     OpenRouterIntegration,
     PydanticAIIntegration,
+    StrandsIntegration,
 )
 from braintrust.integrations.base import BaseIntegration
 
@@ -64,6 +65,7 @@ def auto_instrument(
     cohere: bool = True,
     autogen: bool = True,
     crewai: bool = True,
+    strands: bool = True,
 ) -> dict[str, bool]:
     """
     Auto-instrument supported AI/ML libraries for Braintrust tracing.
@@ -92,6 +94,7 @@ def auto_instrument(
         cohere: Enable Cohere instrumentation (default: True)
         autogen: Enable AutoGen instrumentation (default: True)
         crewai: Enable CrewAI instrumentation (default: True)
+        strands: Enable Strands Agents instrumentation (default: True)
 
     Returns:
         Dict mapping integration name to whether it was successfully instrumented.
@@ -173,6 +176,8 @@ def auto_instrument(
         results["autogen"] = _instrument_integration(AutoGenIntegration)
     if crewai:
         results["crewai"] = _instrument_integration(CrewAIIntegration)
+    if strands:
+        results["strands"] = _instrument_integration(StrandsIntegration)
 
     return results
 

py/src/braintrust/integrations/__init__.py

@@ -15,6 +15,7 @@
 from .openai_agents import OpenAIAgentsIntegration
 from .openrouter import OpenRouterIntegration
 from .pydantic_ai import PydanticAIIntegration
+from .strands import StrandsIntegration
 
 
 __all__ = [
@@ -35,4 +36,5 @@
     "OpenAIAgentsIntegration",
     "OpenRouterIntegration",
     "PydanticAIIntegration",
+    "StrandsIntegration",
 ]

py/src/braintrust/integrations/strands/__init__.py

@@ -0,0 +1,22 @@
+"""Braintrust integration for Strands Agents."""
+
+from braintrust.logger import NOOP_SPAN, current_span, init_logger
+
+from .integration import StrandsIntegration
+from .patchers import wrap_strands_tracer
+
+
+__all__ = ["StrandsIntegration", "setup_strands", "wrap_strands_tracer"]
+
+
+def setup_strands(
+    api_key: str | None = None,
+    project_id: str | None = None,
+    project_name: str | None = None,
+) -> bool:
+    """Set up Braintrust tracing for Strands Agents."""
+    span = current_span()
+    if span == NOOP_SPAN:
+        init_logger(project=project_name, api_key=api_key, project_id=project_id)
+
+    return StrandsIntegration.setup()

py/src/braintrust/integrations/strands/cassettes/1.20.0/test_strands_openai_agent_traces_native_otel_lifecycle.yaml

@@ -0,0 +1,137 @@
+interactions:
+- request:
+    body: '{"messages":[{"role":"system","content":"Answer with one short sentence."},{"role":"user","content":[{"text":"What
+      is 2 + 2?","type":"text"}]}],"model":"gpt-4o-mini","max_tokens":16,"stream":true,"stream_options":{"include_usage":true},"temperature":0,"tools":[]}'
+    headers:
+      Accept:
+      - application/json
+      Accept-Encoding:
+      - gzip, deflate
+      Connection:
+      - keep-alive
+      Content-Length:
+      - '263'
+      Content-Type:
+      - application/json
+      Host:
+      - api.openai.com
+      User-Agent:
+      - AsyncOpenAI/Python 2.32.0
+      X-Stainless-Arch:
+      - arm64
+      X-Stainless-Async:
+      - async:asyncio
+      X-Stainless-Lang:
+      - python
+      X-Stainless-OS:
+      - MacOS
+      X-Stainless-Package-Version:
+      - 2.32.0
+      X-Stainless-Runtime:
+      - CPython
+      X-Stainless-Runtime-Version:
+      - 3.12.12
+      x-stainless-read-timeout:
+      - '600'
+      x-stainless-retry-count:
+      - '0'
+    method: POST
+    uri: https://api.openai.com/v1/chat/completions
+  response:
+    body:
+      string: 'data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"role":"assistant","content":"","refusal":null},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"pk97oOD3G"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"2"},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"FWoXAmqq5w"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"
+        +"},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"lhqvL5rG8"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"
+        "},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"XR35oXmsEL"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"2"},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"jgY9365oSi"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"
+        equals"},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"xGU2"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"
+        "},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"r0m78JOjNz"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"4"},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"J2Zqjb6BCe"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{"content":"."},"logprobs":null,"finish_reason":null}],"usage":null,"obfuscation":"IPWvGvSjYe"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}],"usage":null,"obfuscation":"oRbJv"}
+
+
+        data: {"id":"chatcmpl-DYGoLJoFHNxxTp5Dlc6rejRQywFLq","object":"chat.completion.chunk","created":1777060145,"model":"gpt-4o-mini-2024-07-18","service_tier":"default","system_fingerprint":"fp_918210d279","choices":[],"usage":{"prompt_tokens":37,"completion_tokens":9,"total_tokens":46,"prompt_tokens_details":{"cached_tokens":0,"audio_tokens":0},"completion_tokens_details":{"reasoning_tokens":0,"audio_tokens":0,"accepted_prediction_tokens":0,"rejected_prediction_tokens":0}},"obfuscation":"avqwL2vQhJB"}
+
+
+        data: [DONE]
+
+
+        '
+    headers:
+      CF-Cache-Status:
+      - DYNAMIC
+      CF-Ray:
+      - 9f17a112c997175c-YYZ
+      Connection:
+      - keep-alive
+      Content-Type:
+      - text/event-stream; charset=utf-8
+      Date:
+      - Fri, 24 Apr 2026 19:49:06 GMT
+      Server:
+      - cloudflare
+      Strict-Transport-Security:
+      - max-age=31536000; includeSubDomains; preload
+      Transfer-Encoding:
+      - chunked
+      X-Content-Type-Options:
+      - nosniff
+      access-control-expose-headers:
+      - X-Request-ID
+      alt-svc:
+      - h3=":443"; ma=86400
+      openai-organization:
+      - braintrust-data
+      openai-processing-ms:
+      - '1121'
+      openai-project:
+      - proj_vsCSXafhhByzWOThMrJcZiw9
+      openai-version:
+      - '2020-10-01'
+      set-cookie:
+      - __cf_bm=CRLtmVWDCbvpssTphfkvEbY8e9EYpEgUvoYSE1e3sX8-1777060145.090192-1.0.1.1-9bJCZxU874KR6eEDb6WL48mIvH3drpQUnSaYDjVfPVmXXr43ttzr3vlIV_26.Ad.fnRRJQ21PoVv47xzxY0UczM56WXgcDc1TvsIRWAA_3axHYFsDOUVM087u8AxC.VJ;
+        HttpOnly; Secure; Path=/; Domain=api.openai.com; Expires=Fri, 24 Apr 2026
+        20:19:06 GMT
+      x-openai-proxy-wasm:
+      - v0.1
+      x-ratelimit-limit-requests:
+      - '30000'
+      x-ratelimit-limit-tokens:
+      - '150000000'
+      x-ratelimit-remaining-requests:
+      - '29999'
+      x-ratelimit-remaining-tokens:
+      - '149999985'
+      x-ratelimit-reset-requests:
+      - 2ms
+      x-ratelimit-reset-tokens:
+      - 0s
+      x-request-id:
+      - req_91fceca254ef423881441fdc4636c6aa
+    status:
+      code: 200
+      message: OK
+version: 1