[ps48]

Description

Adds mark_agent_root(), which marks the active span as its trace's agent root by setting derived.gen_ai.is_root = true.

OpenSearch Agent Traces lists a trace by the span marked with derived.gen_ai.is_root. Data Prepper marks the outermost GenAI span of each trace (opensearch-project/data-prepper#7192, for opensearch-project/data-prepper#7191): the root when it is a GenAI span, or the agent span below it, for example when an HTTP handler runs the agent. This helper lets applications choose the span themselves, for example a service's agent entry point. A span marked at the source wins, and Data Prepper then marks nothing else in that part of the trace.

Also exports the attribute name as AGENT_ROOT_ATTRIBUTE and documents the helper and the raw attribute in the README.

Related: OpenSearch Dashboards Agent Traces lists marked spans, opensearch-project/OpenSearch-Dashboards#12977.

Type of Change

• New feature (non-breaking change which adds functionality)
• Documentation update

How Has This Been Tested?

• Unit tests pass

• Integration tests pass (end to end, see below)

• Manual testing performed

• New TestMarkAgentRoot: marks the current span only (not its children), and is a no-op without an active span. pytest tests/test_enrich.py: 15 passed. ruff format, ruff check and mypy are clean.

• 4 tests in tests/test_exporters.py (TestAWSSigV4OTLPExporterInit, 'AWSSigV4OTLPExporter' object has no attribute '_session') fail locally with the dependency versions I installed. They are unrelated to this change, which doesn't touch the exporters.

• End to end on observability-stack: a FastAPI app used this SDK branch, with a Data Prepper image built from Mark the outermost GenAI span of traces with a non-GenAI root data-prepper#7192.

  • With mark_agent_root() called in the HTTP handler, OpenSearch had derived.gen_ai.is_root: true on that span only, and Data Prepper marked no other span.
  • Agent Traces listed the trace by that span.

Checklist

• My code follows the project's style guidelines
• I have performed a self-review of my own code
• I have added tests that prove my feature works
• I have updated the documentation (README)
• Commits are signed off (DCO)

[ps48]

CI notes:

• Lint and Format: ruff format --check was failing on existing README code blocks, because current ruff formats Python code in Markdown. Fixed in 0500aca (whitespace only).
• Tests: the 4 failures are all in tests/test_exporters.py::TestAWSSigV4OTLPExporterInit ('AWSSigV4OTLPExporter' object has no attribute '_session'). This PR doesn't touch the exporters, so they look like a dependency version change, not this PR. All other tests pass, including the new TestMarkAgentRoot.
• Dependency Vulnerabilities: pip-audit flags dependencies this PR doesn't change.

I can fix the exporter tests in a separate PR if that's useful.

[kylehounslow]

@ps48 changes LGTM. There are some CI errors (python tests), please take a look

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@32297cf). Learn more about missing BASE report.

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #48   +/-   ##
=======================================
  Coverage        ?   93.34%           
=======================================
  Files           ?        9           
  Lines           ?      857           
  Branches        ?        0           
=======================================
  Hits            ?      800           
  Misses          ?       57           
  Partials        ?        0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.