fix(sdk): restore agent context after decorator exits

[yaodong-shen]

Summary

• scope gen_ai.agent.name to the @agent span context token
• restore the previous OpenTelemetry context when the agent exits
• add regressions for independent work after an agent and sibling tasks inside a workflow

Root cause

_setup_span() attached the agent name before attaching the span context, then discarded that first token. Cleanup detached only the span token, restoring a context that still contained the completed agent name. Subsequent spans therefore inherited stale gen_ai.agent.name metadata.

Validation

• npx nx run traceloop-sdk:lint
• npx nx run traceloop-sdk:type-check
• npx nx run traceloop-sdk:test — 417 passed
• focused regression file — 5 passed

Fixes #4378

Checklist

• I have added tests that cover my changes.
• If adding a new instrumentation or changing an existing one, I've added screenshots from some observability platform showing the change. (Not applicable: SDK context cleanup only.)
• PR name follows conventional commits format: feat(instrumentation): ... or fix(instrumentation): ....
• (If applicable) I have updated the documentation accordingly. (Not applicable: no public API or user-facing behavior contract changed.)

Summary by CodeRabbit

• Bug Fixes

  • Improved agent and workflow context handling so completed agents no longer affect subsequent independent tasks.
  • Ensured sibling tasks correctly inherit the enclosing workflow context without retaining completed agent metadata.

• Tests

  • Added regression coverage for agent and workflow context isolation.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 96003cbc-99b5-4ab2-be55-6710455de6d0

📥 Commits

Reviewing files that changed from the base of the PR and between 93429cf and 58b339f.

📒 Files selected for processing (2)

• packages/traceloop-sdk/tests/test_agent_workflow_context.py
• packages/traceloop-sdk/traceloop/sdk/decorators/base.py

---

📝 Walkthrough

Walkthrough

The SDK now scopes agent names through the span context during agent span creation and records them on agent spans. Regression tests verify that completed agents do not leak metadata or parentage into subsequent tasks while enclosing workflow context is restored.

Changes

Agent context isolation

Layer / File(s)	Summary
Scope agent metadata during span setup packages/traceloop-sdk/traceloop/sdk/decorators/base.py	Agent names are added to the span context before attachment and recorded with GEN_AI_AGENT_NAME on agent spans.
Verify context restoration after agents packages/traceloop-sdk/tests/test_agent_workflow_context.py	Regression tests verify isolation for standalone tasks and restoration of the enclosing workflow for sibling tasks.

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

Possibly related PRs

• traceloop/openllmetry#4288: Updates the same agent span/context handling and related workflow-context tests.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main fix: restoring agent context after the decorator exits.
Linked Issues check	✅ Passed	The code fixes the agent-name leak and adds regression tests for both scenarios described in #4378.
Out of Scope Changes check	✅ Passed	The changes stay within the bug fix and test coverage for agent context restoration.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}