feat(llmobs): propagate agent_version to the agent's subtree

[mz1119]

Description

Reports the agent version as an agent_version tag on the agent span and every span it runs, matching dd-trace-js (DataDog/dd-trace-js#10536) and dd-trace-java (DataDog/dd-trace-java#12291). The agent panel attributes tokens and cost to a version through the agent's child spans.

with LLMObs.agent(name="travel_desk", version="2.1.0"):
    with LLMObs.tool(name="get_weather"):  # agent_version:2.1.0
        ...

• The nearest agent's version is resolved at span activation, alongside the existing agent attribution. Non-agent spans emit it at finish, overriding a user tag of the same name.
• Scoped up to a nested agent: a nested agent's version (or lack of one) applies to its own subtree.
• A version set with annotate() reaches spans started after the call.
• Carried across asyncio tasks and thread pools via the in-process context, but not propagated across services.

Testing

Unit tests for subtree propagation, sibling and nested agents, annotation timing, annotation_context, asyncio tasks, thread pools, and no leakage into distributed headers. Flipped the existing tests that asserted the version stays off children.

when clicking into the agent, we see tool usage being attributed to version, and I verified that the token sums included subtree llm sums (3.0.0 should have 25.9k and 4.0.0 should have 10.4k)

Risks

Descendant spans that previously had no agent_version now carry one.

Additional Notes

Assumes non-distributed, non-nested agents, as in the JS and Java PRs.

🤖 Generated with Claude Code

[cit-pr-commenter-54b7da]

Codeowners resolved as

Resolved from the full PR diff against main using the target branch CODEOWNERS file.
CODEOWNERS team requests not listed below are not required by the current file set.

ddtrace/llmobs/_constants.py                                            @DataDog/ml-observability
ddtrace/llmobs/_llmobs.py                                               @DataDog/ml-observability
ddtrace/llmobs/_utils.py                                                @DataDog/ml-observability
ddtrace/llmobs/types.py                                                 @DataDog/ml-observability
releasenotes/notes/llmobs-agent-version-subtree-f2321e0e547b39e8.yaml   @DataDog/apm-python
tests/llmobs/test_llmobs_decorators.py                                  @DataDog/ml-observability
tests/llmobs/test_llmobs_service.py                                     @DataDog/ml-observability
tests/llmobs/test_propagation.py                                        @DataDog/ml-observability

[cit-pr-commenter-54b7da]

Circular import analysis

⚠️ Existing circular imports

There are 1 circular imports that already exist on the base branch and have not been changed by this PR.

ddtrace.errortracking._handled_exceptions.bytecode_injector -> ddtrace.errortracking._handled_exceptions.callbacks -> ddtrace.errortracking._handled_exceptions.collector -> ddtrace.errortracking._handled_exceptions.bytecode_reporting -> ddtrace.errortracking._handled_exceptions.bytecode_injector

[cit-pr-commenter-54b7da]

Dependency direction analysis

⚠️ Existing dependency direction violations

There are 201 dependency direction violations that already exist on the base branch and have not been changed by this PR.

Show existing violations (showing 5 of 201 highest severity)

ddtrace.internal.tracemethods -×-> ddtrace.trace  (internal-core -> product:tracing, score=132)
ddtrace.internal.openfeature._span_enrichment -×-> ddtrace.trace  (product:openfeature -> product:tracing, score=130)
ddtrace.internal.ci_visibility.recorder -×-> ddtrace.trace  (product:ci_visibility -> product:tracing, score=130)
ddtrace.profiling.scheduler -×-> ddtrace.trace  (product:profiling -> product:tracing, score=130)
ddtrace.debugging._exception.replay -×-> ddtrace.trace  (product:debugging -> product:tracing, score=130)

To see all violations, download the layers-base.json and layers-pr.json artifacts from this CI job and run:

uv run --script scripts/import-analysis/layers.py compare layers-base.json layers-pr.json

[datadog-official]

✅ All CI checks and tests passed.

🎉 All green!

🧪 All tests passed
❄️ No new flaky tests detected

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: d2df4c3 | Docs | View more details | Give us feedback!}

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-06T19:44:40.138887Z	d2df4c3	New commits
🔒 Security Review	✅ Completed 2026-10-06T19:42:54.969471Z	d2df4c3	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64abb06f12

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d2df4c35d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Clear stale agent versions when snapshotting contexts

When work is already running from an asyncio/thread context containing an outer agent version, active.context retains PARENT_AGENT_VERSION in its trace-level _meta. If that work enters an unversioned nested agent and schedules another task or thread, _resolve_parent_agent(active) correctly returns no version for the nested agent, but this truthy-only assignment leaves the outer value in the copied metadata; the grandchild consequently emits the outer agent_version, violating the documented nested-agent boundary. Remove the key when the resolved version is absent, analogous to _stamp_agent_attribution clearing stale attribution.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

💡 Codex Review

dd-trace-py/ddtrace/llmobs/_llmobs.py

Lines 2518 to 2519 in d2df4c3

	if parent_agent_version:
	context._meta[PARENT_AGENT_VERSION] = parent_agent_version

Clear stale agent versions when snapshotting contexts

When work is already running from an asyncio/thread context containing an outer agent version, active.context retains PARENT_AGENT_VERSION in its trace-level _meta. If that work enters an unversioned nested agent and schedules another task or thread, _resolve_parent_agent(active) correctly returns no version for the nested agent, but this truthy-only assignment leaves the outer value in the copied metadata; the grandchild consequently emits the outer agent_version, violating the documented nested-agent boundary. Remove the key when the resolved version is absent, analogous to _stamp_agent_attribution clearing stale attribution.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".