Add gen_ai.agent.turn.count to invoke_agent spans

changelog.d/+.enhancement.md

@@ -0,0 +1 @@
+Add `gen_ai.agent.turn.count` to the `invoke_agent` spans, recording the number of agent turns completed during the invocation.

model/gen-ai/registry.yaml

@@ -383,6 +383,16 @@ attributes:
     brief: The version of the GenAI agent.
     examples: ["1.0.0", "2025-05-01"]
     stability: development
+  - key: gen_ai.agent.turn.count
+    type: int
+    brief: The number of agent turns completed during the agent invocation.
+    note: >
+      A turn is one cycle of the agent loop: a model inference together with the
+      tool executions it requested. Instrumentations SHOULD record the total on
+      the `invoke_agent` span when the invocation ends, so a single-turn
+      invocation reports `1`.
+    examples: [1, 3]
+    stability: development
   - key: gen_ai.tool.name
     type: string
     brief: Name of the tool utilized by the agent.

model/gen-ai/spans.yaml

@@ -119,6 +119,9 @@ attribute_groups:
         brief: The free-form description of the invoked GenAI agent.
         requirement_level:
           conditionally_required: When available.
+      - ref: gen_ai.agent.turn.count
+        requirement_level:
+          recommended: If the agent loop is observable to the instrumentation.
 
 
   - id: attributes.gen_ai.execute_tool.common

reference/reports/invoke-agent-client-span.md

@@ -28,6 +28,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.agent.turn.count | (none) |
 | gen_ai.request.frequency_penalty | (none) |
 | gen_ai.request.max_tokens | [azure-ai-foundry], [openai-assistants] |
 | gen_ai.request.model | [azure-ai-foundry], [google-genai], [openai-assistants] |

reference/reports/invoke-agent-internal-span.md

@@ -24,6 +24,7 @@
 
 | Attribute | Supporting Libraries |
 | --- | --- |
+| gen_ai.agent.turn.count | [openai-agents] |
 | gen_ai.request.frequency_penalty | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
 | gen_ai.request.max_tokens | [agent-framework], [autogen], [crewai], [google-adk], [pydantic-ai] |
 | gen_ai.request.model | [agent-framework], [autogen], [crewai], [google-adk], [langchain], [openai-agents], [pydantic-ai] |

reference/scenarios/openai-agents/data.json

@@ -12,6 +12,7 @@
     ],
     "gen_ai.invoke_agent.internal": [
       "gen_ai.agent.name",
+      "gen_ai.agent.turn.count",
       "gen_ai.input.messages",
       "gen_ai.operation.name",
       "gen_ai.output.messages",

reference/scenarios/openai-agents/scenario.py

@@ -100,6 +100,10 @@ async def _capture_create(*args, **kwargs):
         if usage.total_tokens:
             agent_span.set_attribute("gen_ai.usage.input_tokens", usage.input_tokens)
             agent_span.set_attribute("gen_ai.usage.output_tokens", usage.output_tokens)
+        # One turn per model inference in the run loop; raw_responses holds one
+        # entry per inference the Runner performed.
+        if result.raw_responses:
+            agent_span.set_attribute("gen_ai.agent.turn.count", len(result.raw_responses))
         if captured_responses:
             last_response = captured_responses[-1]
             finish_reasons = [