Prototype showing gen_ai.conversation_root span attribute to mark the root GenAI span of a conversation by wrisa · Pull Request #187 · open-telemetry/opentelemetry-python-genai

wrisa · 2026-06-30T19:05:21Z

Description

Fixes # (issue356)
``
Adds gen_ai.conversation_root as a boolean span attribute automatically set on `WorkflowInvocation` and `AgentInvocation` spans that are the outermost GenAI span in a trace — i.e., the entry point of a conversation.

Detection uses a context-scoped attribute key (following the API shape of open-telemetry/opentelemetry-specification#4931) stored under a private OTel context key rather than raw OTel span parentage. This correctly handles the common production case where a GenAI root span lives under a non-GenAI parent (HTTP, gRPC, queue consumer, etc.) — a plain OTel parent span never writes the key, so it never suppresses conversation_root.

Design

Context-scoped attribute key

A private OTel context key is used to propagate a gen_ai.conversation_root marker through the OTel context:

  context_attributes.py
  _GENAI_CONTEXT_ATTRS_KEY = otel_context.create_key(
      "opentelemetry.util.genai.context_scoped_attrs"
  )

set_context_scoped_attributes uses existing-key-wins semantics (outermost writer wins), matching the CSA spec. This means once the root sets the key, any nested WorkflowInvocation or AgentInvocation sees it already present and does not mark itself as root.

Auto-detection in `WorkflowInvocation` and `AgentInvocation`

Before _start():

  csa = get_context_scoped_attributes()
  if "gen_ai.conversation_root" not in csa:
      # No enclosing GenAI root — this is the root
      self.conversation_root = True

Propagate the key so nested invocations do not mark themselves root

extra_ctx = set_context_scoped_attributes({"gen_ai.conversation_root": True})
self._start(..., extra_context=extra_ctx)

The key is attached alongside the span in a single attach() call and automatically detached when the invocation ends (same lifecycle as the span context token), so the next independent conversation starts fresh.

Emission

In GenAIInvocation._finish():

  if self.conversation_root is not None:
      self.span.set_attribute("gen_ai.conversation_root", self.conversation_root)

Only emitted when explicitly set — None means "not applicable" and produces no attribute.

Scope

Only WorkflowInvocation and AgentInvocation participate in root detection. InferenceInvocation (chat), ToolInvocation (execute_tool), EmbeddingInvocation, and RetrievalInvocation never set conversation_root — even when called at the top level with no GenAI parent — because they represent model/tool operations, not conversation-level entry points.

Example traces

Agent under HTTP span (common production case):

  HTTP GET /plan-trip                              ← plain OTel span, ignored by detection
    invoke_agent Travel Planner   conversation_root=True   ← root: no CSA key in context
      invoke_agent Flight Search                           ← not root: key already in context
        chat                                              ← never eligible
        execute_tool search_flights                       ← never eligible
      invoke_agent Hotel Booking                          ← not root: key already in context
        chat                                              ← never eligible

Workflow wrapping agents:

  invoke_workflow Travel Planner  conversation_root=True   ← root
    invoke_agent Flight Search                            ← not root
      chat                                               ← never eligible
    invoke_agent Hotel Booking                           ← not root
      chat                                               ← never eligible

What this does NOT do

Does not mark chat, execute_tool, retrieval, or embedding spans as root even when called at the top level — those are model/tool operations, not conversation entry points
Does not add gen_ai.conversation_root to the semconv (a separate semconv PR/issue should track that)
Does not use ContextVar — uses the OTel context system directly so propagation is consistent with async frameworks and distributed context

Relation to prior art

Builds on the context-scoped attributes pattern prototyped in POC: Conversation id and association properties using context scoped attributes opentelemetry-python-contrib#4468 (context_attributes.py module reused as-is)
Follows the API shape of OTEP: Context-scoped Attributes opentelemetry-specification#4931 so migration to a future upstream CSA implementation is straightforward

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How has this been tested?

Please describe the tests that you ran to verify your changes. Provide
instructions so we can reproduce. List any relevant details for your test
configuration.

Test A

Checklist

See CONTRIBUTING.md
for the style guide, changelog guidance, and more.

Followed the style guidelines of this project
Changelog updated if the change requires an entry
Unit tests added
Documentation updated

This reverts commit 4114ac3.

github-actions · 2026-07-16T04:18:17Z

This PR has been automatically marked as stale because it has not had any activity for 14 days. It will be closed if no further activity occurs within 14 days of this comment.
If you're still working on this, please add a comment or push new commits.

opentelemetry-pr-dashboard · 2026-07-18T13:52:22Z

Pull request dashboard status

Waiting on the author · refreshed 2026-08-04 14:20 UTC

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

Inline threads: 1, 2, 3, 4, 5

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

Adds a prototype mechanism in opentelemetry-util-genai to mark the outermost conversation-level GenAI span via a new boolean span attribute (gen_ai.conversation_root) on workflow and agent invocations, using an OTel context-scoped attribute marker to detect/propgate “root-ness” without relying on span parentage.

Changes:

Introduces a context_attributes helper module to store “context-scoped attributes” in the OTel context with outermost-writer-wins semantics.
Extends GenAIInvocation._start() to optionally attach a pre-enriched context alongside the span; emits gen_ai.conversation_root when set on the invocation.
Adds workflow/agent root auto-detection + propagation and corresponding unit tests.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
util/opentelemetry-util-genai/src/opentelemetry/util/genai/context_attributes.py	New CSA helper for storing/reading GenAI context-scoped attributes.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_invocation.py	Adds `conversation_root` field, supports `extra_context` during span attach, emits the span attribute.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_workflow_invocation.py	Detects/propagates conversation root marker for workflow spans.
util/opentelemetry-util-genai/src/opentelemetry/util/genai/_agent_invocation.py	Detects/propagates conversation root marker for agent spans.
util/opentelemetry-util-genai/tests/test_context_attributes.py	Unit tests for CSA helper semantics (merge + defaults).
util/opentelemetry-util-genai/tests/test_handler_workflow.py	Adds workflow-level tests for conversation root detection/emission.
util/opentelemetry-util-genai/tests/test_handler_agent.py	Adds agent-level tests for conversation root detection/emission.

+from opentelemetry.util.genai.context_attributes import (
+    get_context_scoped_attributes,
+    set_context_scoped_attributes,
+)


+            if self.conversation_root is not None:
+                self.span.set_attribute(
+                    "gen_ai.conversation_root", self.conversation_root
+                )


+        from unittest.mock import patch
+        from opentelemetry.util.genai.types import ContentCapturingMode


opentelemetry-pr-dashboard · 2026-07-29T19:39:58Z

Hi @wrisa — just a friendly reminder that this pull request is waiting on you.

There are still items that need your attention. See the dashboard status comment for the full list. You don't need to push a code change to hand it back — replying to move each discussion forward is enough, whether that's answering a question, explaining why no change is needed, or asking a follow-up. The dashboard then automatically routes it back to reviewers.

If you believe this pull request is incorrectly routed as waiting on the author, comment /dashboard route:reviewers to route it from waiting on the author to waiting on reviewers.

lzchen · 2026-08-03T20:21:42Z

+        # non-GenAI parents (HTTP, gRPC, etc.) — unlike checking OTel span
+        # parentage directly.
+        csa = get_context_scoped_attributes()
+        if "gen_ai.conversation_root" not in csa:


I might have missed the discussion for this but is this in genai semconv? If this is a prototype to drive semantic conventions, should this be gated/opt-in?

lzchen · 2026-08-03T20:22:17Z

@@ -0,0 +1,69 @@
+# Copyright The OpenTelemetry Authors


This file should probably be internal?

Add conversation root

4114ac3

wrisa changed the title ~~Add conversation root~~ Add conversation root(WIP) Jun 30, 2026

opentelemetry-pr-dashboard Bot mentioned this pull request Jun 30, 2026

Pull Request Dashboard #171

Open

wrisa added 2 commits July 1, 2026 05:38

Revert "Add conversation root"

7d611ba

This reverts commit 4114ac3.

removed recording span logic and added context scoped attributes

e22d3d4

wrisa changed the title ~~Add conversation root(WIP)~~ Prototype showing gen_ai.conversation_root span attribute to mark the root GenAI span of a conversation (WIP) Jul 1, 2026

wrisa mentioned this pull request Jul 2, 2026

Add gen_ai.conversation_root attribute to invoke_agent and invoke_workflow spans to enable session/conversation views in observability UIs open-telemetry/semantic-conventions-genai#356

Open

github-actions Bot added the Stale Issue or PR has been inactive label Jul 16, 2026

wrisa mentioned this pull request Jul 21, 2026

Add gen_ai.root_operation.name open-telemetry/semantic-conventions-genai#355

Draft

3 tasks

wrisa changed the title ~~Prototype showing gen_ai.conversation_root span attribute to mark the root GenAI span of a conversation (WIP)~~ Prototype showing gen_ai.conversation_root span attribute to mark the root GenAI span of a conversation Jul 21, 2026

wrisa marked this pull request as ready for review July 21, 2026 16:11

wrisa requested a review from a team as a code owner July 21, 2026 16:11

Copilot AI review requested due to automatic review settings July 21, 2026 16:11

Copilot started reviewing on behalf of wrisa July 21, 2026 16:15 View session

Copilot AI reviewed Jul 21, 2026

View reviewed changes

github-actions Bot removed the Stale Issue or PR has been inactive label Jul 22, 2026

RKest mentioned this pull request Jul 30, 2026

feat(util-genai): add per-signal context-scoped attributes #337

Closed

4 tasks

lzchen reviewed Aug 3, 2026

View reviewed changes

Navigation Menu

Uh oh!

Prototype showing gen_ai.conversation_root span attribute to mark the root GenAI span of a conversation - #187

Prototype showing gen_ai.conversation_root span attribute to mark the root GenAI span of a conversation#187
wrisa wants to merge 3 commits into
open-telemetry:mainfrom
wrisa:conversation-root

wrisa commented Jun 30, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 16, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 18, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

lzchen Aug 3, 2026 •

edited

Loading

Uh oh!

lzchen Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		from unittest.mock import patch
		from opentelemetry.util.genai.types import ContentCapturingMode

Uh oh!

Conversation

wrisa commented Jun 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Design

Context-scoped attribute key

Auto-detection in WorkflowInvocation and AgentInvocation

Emission

Scope

Example traces

How has this been tested?

Checklist

Uh oh!

github-actions Bot commented Jul 16, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

opentelemetry-pr-dashboard Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lzchen Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lzchen Aug 3, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wrisa commented Jun 30, 2026 •

edited

Loading

Auto-detection in `WorkflowInvocation` and `AgentInvocation`

opentelemetry-pr-dashboard Bot commented Jul 18, 2026 •

edited

Loading

opentelemetry-pr-dashboard Bot commented Jul 29, 2026 •

edited

Loading

lzchen Aug 3, 2026 •

edited

Loading