Add gen_ai.agent.turn.count to invoke_agent spans

[Zhuoxi2000]

Description

Part of #332 — this PR takes the gen_ai.agent.turn.count piece agreed there. The per-turn index on child spans remains tracked separately in the issue.

• Add gen_ai.agent.turn.count (int, development) to the attribute registry: the number of agent turns completed during an invocation, where one turn is one agent-loop cycle consisting of a model inference and any tool executions it requests.
• Add it to the shared invoke_agent attribute group for client and internal spans, Recommended when the agent loop is observable to instrumentation.
• Regenerate docs with make generate-all and add the Towncrier fragment.

Motivation

The main use cases are incident triage and cost/latency analysis. Having the turn count directly on the invoke_agent span lets a backend answer questions like “did this invocation loop more than expected?” or “what does a turn cost on average?” without reconstructing the loop from child spans, whose topology can vary across frameworks.

I ran into this while building TraceLake, an OTLP GenAI ingestion pipeline into Iceberg, where turn count is a useful aggregation key for per-turn latency/cost rollups and detecting runaway loops.

There is also precedent across agent runtimes: OpenAI Agents SDK exposes individual inference responses and max_turns, Claude Agent SDK reports num_turns, and LangGraph bounds loops with recursion_limit. Observability tools such as LangSmith and Langfuse similarly expose per-run step counts.

Prototype

The openai-agents reference scenario now records the attribute on the invoke_agent span using RunResult.raw_responses, which contains one entry per model inference performed by the runner.

I re-ran the scenario against the mock server; the Weaver live check reports no violations, and data.json plus the coverage reports are regenerated in this PR.

Checklist

• Motivation section filled in above
• Reference scenarios updated for affected libraries
• Towncrier fragment added under changelog.d/ for any change to the conventions that a consumer would care about. Editorial changes (typos, pure rewording, repo tooling) don't need an entry.

See [CONTRIBUTING.md]

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: Zhuoxi2000 / name: Edson (820e5c9, 90a15b0)

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on the author · refreshed 2026-09-21 17:47 UTC

Resolve merge conflicts.

Respond to 2 review items (e.g. link a commit, explain why not, ask a follow-up):

• Inline threads: 1, 2

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
• Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

Pull request overview

This PR extends the GenAI semantic conventions by introducing a new agent-level attribute, gen_ai.agent.turn.count, intended to summarize how many agent-loop turns (model inference + any requested tool executions) occurred during an invoke_agent span, and updates the OpenAI Agents reference scenario plus generated artifacts accordingly.

Changes:

• Add gen_ai.agent.turn.count to the attribute registry and to the shared invoke_agent attribute group with a conditional recommendation.
• Emit the new attribute in the openai-agents reference scenario and update its scenario data.json.
• Regenerate derived docs and reference reports, and add a Towncrier fragment.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
reference/scenarios/openai-agents/scenario.py	Emits gen_ai.agent.turn.count on the invoke_agent span based on run-loop inference count.
reference/scenarios/openai-agents/data.json	Declares the new attribute as expected for the gen_ai.invoke_agent.internal signal in this scenario.
reference/reports/invoke-agent-internal-span.md	Generated report now lists openai-agents as supporting gen_ai.agent.turn.count.
reference/reports/invoke-agent-client-span.md	Generated report shows no client-span library support yet for gen_ai.agent.turn.count.
model/gen-ai/spans.yaml	Adds gen_ai.agent.turn.count to the invoke_agent common attribute group as conditionally recommended.
model/gen-ai/registry.yaml	Registers the new gen_ai.agent.turn.count attribute definition and guidance.
docs/registry/attributes/gen-ai.md	Generated registry page update reflecting the new attribute.
docs/gen-ai/gen-ai-agent-spans.md	Generated agent-span documentation updated to include the new attribute.
changelog.d/+.enhancement.md	Adds a Towncrier fragment entry for the consumer-visible convention change.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.