feat(telemetry): Add tool definitions to traces via semconv opt-in

Author: Ratish1

src/strands/agent/agent.py

@@ -938,6 +938,7 @@ def _start_agent_trace_span(self, messages: Messages) -> trace_api.Span:
             tools=self.tool_names,
             system_prompt=self.system_prompt,
             custom_trace_attributes=self.trace_attributes,
+            tools_config=self.tool_registry.get_all_tools_config(),
         )
 
     def _end_agent_trace_span(

src/strands/telemetry/tracer.py

@@ -81,9 +81,7 @@ class Tracer:
     are sent to the OTLP endpoint.
     """
 
-    def __init__(
-        self,
-    ) -> None:
+    def __init__(self) -> None:
         """Initialize the tracer."""
         self.service_name = __name__
         self.tracer_provider: Optional[trace_api.TracerProvider] = None
@@ -92,17 +90,18 @@ def __init__(
         ThreadingInstrumentor().instrument()
 
         # Read OTEL_SEMCONV_STABILITY_OPT_IN environment variable
-        self.use_latest_genai_conventions = self._parse_semconv_opt_in()
+        opt_in_values = self._parse_semconv_opt_in()
+        self.use_latest_genai_conventions = "gen_ai_latest_experimental" in opt_in_values
+        self.include_tool_definitions = "gen_ai_tool_definitions" in opt_in_values
 
-    def _parse_semconv_opt_in(self) -> bool:
+    def _parse_semconv_opt_in(self) -> set[str]:
         """Parse the OTEL_SEMCONV_STABILITY_OPT_IN environment variable.
 
         Returns:
-            Set of opt-in values from the environment variable
+            A set of opt-in values from the environment variable.
         """
         opt_in_env = os.getenv("OTEL_SEMCONV_STABILITY_OPT_IN", "")
-
-        return "gen_ai_latest_experimental" in opt_in_env
+        return {value.strip() for value in opt_in_env.split(",")}
 
     def _start_span(
         self,
@@ -551,6 +550,7 @@ def start_agent_span(
         model_id: Optional[str] = None,
         tools: Optional[list] = None,
         custom_trace_attributes: Optional[Mapping[str, AttributeValue]] = None,
+        tools_config: Optional[dict] = None,
         **kwargs: Any,
     ) -> Span:
         """Start a new span for an agent invocation.
@@ -561,6 +561,7 @@ def start_agent_span(
             model_id: Optional model identifier.
             tools: Optional list of tools being used.
             custom_trace_attributes: Optional mapping of custom trace attributes to include in the span.
+            tools_config: Optional dictionary of tool configurations.
             **kwargs: Additional attributes to add to the span.
 
         Returns:
@@ -577,8 +578,15 @@ def start_agent_span(
             attributes["gen_ai.request.model"] = model_id
 
         if tools:
-            tools_json = serialize(tools)
-            attributes["gen_ai.agent.tools"] = tools_json
+            attributes["gen_ai.agent.tools"] = serialize(tools)
+
+        if self.include_tool_definitions and tools_config:
+            try:
+                tool_definitions = self._construct_tool_definitions(tools_config)
+                attributes["gen_ai.tool.definitions"] = serialize(tool_definitions)
+            except Exception:
+                # A failure in telemetry should not crash the agent
+                logger.warning("failed to attach tool metadata to agent span", exc_info=True)
 
         # Add custom trace attributes if provided
         if custom_trace_attributes:
@@ -649,6 +657,18 @@ def end_agent_span(
 
         self._end_span(span, attributes, error)
 
+    def _construct_tool_definitions(self, tools_config: dict) -> list[dict[str, Any]]:
+        """Constructs a list of tool definitions from the provided tools_config."""
+        return [
+            {
+                "name": name,
+                "description": spec.get("description"),
+                "inputSchema": spec.get("inputSchema"),
+                "outputSchema": spec.get("outputSchema"),
+            }
+            for name, spec in tools_config.items()
+        ]
+
     def start_multiagent_span(
         self,
         task: str | list[ContentBlock],

tests/strands/agent/test_agent.py

@@ -1360,6 +1360,7 @@ def test_agent_call_creates_and_ends_span_on_success(mock_get_tracer, mock_model
         tools=agent.tool_names,
         system_prompt=agent.system_prompt,
         custom_trace_attributes=agent.trace_attributes,
+        tools_config=unittest.mock.ANY,
     )
 
     # Verify span was ended with the result
@@ -1394,6 +1395,7 @@ async def test_event_loop(*args, **kwargs):
         tools=agent.tool_names,
         system_prompt=agent.system_prompt,
         custom_trace_attributes=agent.trace_attributes,
+        tools_config=unittest.mock.ANY,
     )
 
     expected_response = AgentResult(
@@ -1432,6 +1434,7 @@ def test_agent_call_creates_and_ends_span_on_exception(mock_get_tracer, mock_mod
         tools=agent.tool_names,
         system_prompt=agent.system_prompt,
         custom_trace_attributes=agent.trace_attributes,
+        tools_config=unittest.mock.ANY,
     )
 
     # Verify span was ended with the exception
@@ -1468,6 +1471,7 @@ async def test_agent_stream_async_creates_and_ends_span_on_exception(mock_get_tr
         tools=agent.tool_names,
         system_prompt=agent.system_prompt,
         custom_trace_attributes=agent.trace_attributes,
+        tools_config=unittest.mock.ANY,
     )
 
     # Verify span was ended with the exception
@@ -2240,8 +2244,8 @@ def test_agent_backwards_compatibility_single_text_block():
 
     # Should extract text for backwards compatibility
     assert agent.system_prompt == text
-    
-    
+
+
 @pytest.mark.parametrize(
     "content, expected",
     [

tests/strands/telemetry/test_tracer.py

@@ -1,5 +1,6 @@
 import json
 import os
+import unittest.mock
 from datetime import date, datetime, timezone
 from unittest import mock
 
@@ -9,9 +10,12 @@
     StatusCode,  # type: ignore
 )
 
+import strands
+from strands import Agent
 from strands.telemetry.tracer import JSONEncoder, Tracer, get_tracer, serialize
 from strands.types.content import ContentBlock
 from strands.types.streaming import Metrics, StopReason, Usage
+from tests.fixtures.mocked_model_provider import MockedModelProvider
 
 
 @pytest.fixture(autouse=True)
@@ -49,6 +53,15 @@ def clean_env():
         yield
 
 
+@pytest.fixture
+def tool_decorated():
+    @strands.tools.tool(name="tool_decorated")
+    def function(random_string: str) -> str:
+        return random_string
+
+    return function
+
+
 def test_init_default():
     """Test initializing the Tracer with default parameters."""
     tracer = Tracer()
@@ -1324,3 +1337,64 @@ def test_start_event_loop_cycle_span_with_tool_result_message(mock_tracer):
             "gen_ai.tool.message", attributes={"content": json.dumps(messages[0]["content"])}
         )
         assert span is not None
+
+
+def test_agent_does_not_include_tools_in_trace_by_default(tool_decorated):
+    """Verify that by default, the agent does not add tool specs to the trace."""
+    with unittest.mock.patch("strands.agent.agent.get_tracer") as mock_get_tracer:
+        mock_tracer_instance = unittest.mock.MagicMock()
+        mock_span = unittest.mock.MagicMock()
+        mock_tracer_instance.start_agent_span.return_value = mock_span
+        mock_tracer_instance.include_tool_definitions = False
+        mock_get_tracer.return_value = mock_tracer_instance
+
+        mock_model = MockedModelProvider([{"role": "assistant", "content": [{"text": "hello!"}]}])
+
+        agent = Agent(tools=[tool_decorated], model=mock_model)
+        agent("test prompt")
+
+        # Check that set_attribute was not called for our specific key
+        called_attributes = [call.args[0] for call in mock_span.set_attribute.call_args_list]
+        assert "gen_ai.tool.definitions" not in called_attributes
+
+
+def test_agent_includes_tools_in_trace_when_enabled(tool_decorated):
+    """Verify that the agent adds tool specs to the trace when the flag is enabled."""
+    with unittest.mock.patch("strands.agent.agent.get_tracer") as mock_get_tracer:
+        # Create a REAL tracer instance so its logic runs
+        mock_tracer_instance = Tracer()
+        # but turn off the flag
+        mock_tracer_instance.include_tool_definitions = True
+        mock_span = unittest.mock.MagicMock()
+
+        # Mock the lower-level _start_span method, NOT start_agent_span
+        mock_tracer_instance._start_span = unittest.mock.MagicMock(return_value=mock_span)
+        mock_get_tracer.return_value = mock_tracer_instance
+
+        mock_model = MockedModelProvider([{"role": "assistant", "content": [{"text": "hello!"}]}])
+
+        agent = Agent(tools=[tool_decorated], model=mock_model)
+        agent("test prompt")
+
+        # Now, we assert that _start_span was called, and we inspect the
+        # attributes that were passed to it.
+        mock_tracer_instance._start_span.assert_called_once()
+        call_args, call_kwargs = mock_tracer_instance._start_span.call_args
+        passed_attributes = call_kwargs.get("attributes", {})
+
+        # Construct the data we expect to find in the attributes
+        tool_spec = tool_decorated.tool_spec
+        expected_tool_details = [
+            {
+                "name": tool_spec.get("name"),
+                "description": tool_spec.get("description"),
+                "inputSchema": tool_spec.get("inputSchema"),
+                "outputSchema": tool_spec.get("outputSchema"),
+            }
+        ]
+
+        expected_json = serialize(expected_tool_details)
+
+        # Verify that our tool definitions are present in the attributes passed to the span
+        assert "gen_ai.tool.definitions" in passed_attributes
+        assert passed_attributes["gen_ai.tool.definitions"] == expected_json