fix(sdk): stop span-attribute overflow from evicting trace references

[mmabrouk]

Symptom

Playground agent runs stopped showing any references (application / variant / revision) on their traces, even though the frontend forwards them correctly since #5163/#5179.

Cause

The root agent span records the resolved configuration flattened one attribute per leaf (ag.meta.configuration.agent.tools.16.input_schema.properties.message.type, ...). A resolved agent config now carries ~17 tools with full JSON schemas, so the span blows past OTel's default 128 span-attribute limit. BoundedAttributes silently evicts the oldest attributes on overflow, and the oldest are exactly the ag.refs.* references stamped at span start. Small-config runs (triggers) kept their references; playground runs lost them.

Verified live on the dev stack: the broken root span holds exactly 128 attributes with zero ag.refs.*, while a small trigger run seconds earlier holds 43 and keeps them.

Fix

Two independent guards:

• SpanLimits(max_attributes=256) on the TracerProvider (double the OTel default).
• Cap the root-span configuration flattening at max_depth=3, so each config section lands as one @ag.type=json: attribute (configuration.agent.tools, .llm, .instructions) instead of hundreds of leaves. Same mechanism data.inputs already uses.

Before / after (live dev stack, same playground app)

Before: root span references column NULL, no ag.refs.* attributes, ag.flags also evicted.
After: root span carries all three reference families (application, application_variant, application_revision v1) plus flags; ingestion populates the references column again.

SDK unit suite: the only failures are the documented pre-existing base reds (secrets SSRF x6, sdk permission-defaults x2, one QA replay), reproduced identically with the change reverted.

https://claude.ai/code/session_01QSwVMKwo4FBZXkeTd4t3SP

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jul 10, 2026 5:23pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a757fa6c-5f86-440d-96a1-5a2ee47fe19e

📥 Commits

Reviewing files that changed from the base of the PR and between dd3da2a and f8d41e3.

📒 Files selected for processing (2)

• sdks/python/agenta/sdk/decorators/tracing.py
• sdks/python/agenta/sdk/engines/tracing/tracing.py

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes
  • Improved tracing stability by limiting the amount of configuration metadata attached to each trace.
  • Prevented excessively large trace records from affecting observability performance.
  • Added safeguards to keep trace attributes within supported limits, ensuring more predictable tracing behavior.

Walkthrough

Tracing instrumentation now limits nested configuration metadata to three levels and configures the OpenTelemetry tracer provider to retain at most 256 span attributes.

Changes

Tracing attribute limits

Layer / File(s)	Summary
Bound configuration attribute depth sdks/python/agenta/sdk/decorators/tracing.py	Configuration metadata recorded by instrument._pre_instrument now applies max_depth=3.
Configure provider attribute limits sdks/python/agenta/sdk/engines/tracing/tracing.py	Tracing.configure() imports SpanLimits and initializes the TracerProvider with a 256-attribute maximum.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: preventing span-attribute overflow from evicting trace references.
Description check	✅ Passed	The description matches the changeset and explains the overflow cause, the two fixes, and the observed effect.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/span-attr-limit-config-depth

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.