fix(openai-agents): optional import of optional deps

[duanyutong]

Changes

• optional deps (not declared in deps) should be imported lazily and not crash the programme

• 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.
• PR name follows conventional commits format: feat(instrumentation): ... or fix(instrumentation): ....
• (If applicable) I have updated the documentation accordingly.

---

Important

Lazy import set_agent_name in on_span_start() to prevent crashes if traceloop.sdk.tracing is not installed.

• Behavior:
  • Lazy import set_agent_name from traceloop.sdk.tracing in on_span_start() in _hooks.py to prevent crashes if the module is not installed.
  • Handles ModuleNotFoundError by passing silently, ensuring the program continues running without the optional dependency.

^{This description was created by for 548ca67. You can customize this summary. It will automatically update as commits are pushed.}

Summary by CodeRabbit

• Bug Fixes
  • Made handling of an optional tracing dependency more robust: missing dependency no longer raises errors and downstream processing continues normally; tracing-related calls are skipped when the optional component isn't present.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Walkthrough

The module-level import of set_agent_name is now guarded with a try/except ModuleNotFoundError, assigning None when unavailable. Calls to set_agent_name inside on_span_start are made conditional, so execution continues without error if the traceloop SDK is absent.

Changes

Cohort / File(s)	Summary
Guarded import & conditional call packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py	Added a top-level try/except ModuleNotFoundError around set_agent_name import (falls back to None), and made the set_agent_name(agent_name) invocation in on_span_start conditional on the symbol being present.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~5–10 minutes

• Single-file change with straightforward control-flow guard
• Check that the fallback (None) path doesn't mask other import errors
• Ensure linting/type checks handle optional callable usage

Possibly related PRs

• fix(openai-agents): propagate gen_ai.agent.name through an agent flow + set workflow name to fast mcp #3388: Introduces and implements set_agent_name guard in _hooks.py to eliminate hard dependency failures on the traceloop SDK.

Suggested reviewers

• nirga

Poem

🐰 I peeked at imports, soft and small,

Wrapped them gently, so none should fall.
If traceloop naps, I hop along,
No crash, no clatter, just a quiet song.
Tiny paws tidy the code — all strong.

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'fix(openai-agents): optional import of optional deps' is directly related to the main change in the PR, which is making optional dependencies be imported lazily to avoid crashes when they're not available.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 548ca67 and 20cfa6e.

📒 Files selected for processing (1)

• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py

---

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 and usage tips.}

[ellipsis-dev]

Important

Looks good to me! 👍

Reviewed everything up to 548ca67 in 2 minutes and 19 seconds. Click for details.

• Reviewed 29 lines of code in 1 files
• Skipped 0 files when reviewing.
• Skipped posting 2 draft comments. View those below.
• Modify your settings and rules to customize what types of comments Ellipsis leaves. And don't forget to react with 👍 or 👎 to teach Ellipsis.

1. packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py:79

• Draft comment:
  Consider caching the imported 'set_agent_name' function (e.g., in a module-level variable) to avoid repeated dynamic imports on each call, which could improve performance when many spans are started.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 20% vs. threshold = 50% The comment is suggesting a performance optimization - caching the import to avoid repeated dynamic imports. However, this falls into a gray area. The change was intentional - moving from top-level import to dynamic import with error handling, likely to make the traceloop.sdk dependency optional. The comment is technically correct that repeated imports could have performance implications, but: 1) Python caches imports in sys.modules, so the performance impact is likely minimal, 2) The comment is somewhat speculative about whether this is actually a problem, 3) The change was clearly intentional to handle the optional dependency gracefully. The comment doesn't acknowledge the trade-off being made here (optional dependency vs. slight performance consideration). Python's import system already caches modules in sys.modules, so repeated import statements don't actually re-execute the module - they just look up the cached module. The performance impact is likely negligible. Additionally, the change to dynamic import was clearly intentional to handle an optional dependency, and the comment doesn't acknowledge this design decision. While Python does cache imports, there is still overhead in the import statement itself (lookup, exception handling). However, given that this was an intentional change to make the dependency optional, and the performance impact is likely minimal in practice, the comment may be premature optimization without evidence of actual performance problems. The comment suggests a performance optimization but doesn't provide evidence that there's an actual performance problem. The change to dynamic import was clearly intentional to handle an optional dependency gracefully. Without strong evidence of performance issues, this is speculative optimization advice.

2. packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py:81

• Draft comment:
  Catching only ModuleNotFoundError might be too narrow. Consider catching ImportError to cover broader import failures, especially for compatibility with older Python versions.
• Reason this comment was not posted:
  Decided after close inspection that this draft comment was likely wrong and/or not actionable: usefulness confidence = 15% vs. threshold = 50% ModuleNotFoundError is a subclass of ImportError that was introduced in Python 3.6. The comment claims catching ImportError would be better for "older Python versions" compatibility. However, I need to consider: 1) Is this codebase targeting Python versions older than 3.6? 2) Are there other import failures besides missing modules that should be caught? 3) Is this actually a problem? Looking at the code, it seems like a modern Python codebase (uses type hints, modern syntax). Python 3.6 was released in 2016 and is long past EOL. ModuleNotFoundError is more specific and appropriate for this use case - they're specifically checking if the module exists. ImportError could catch other issues like circular imports or syntax errors in the module, which might mask real problems. The comment seems to be making an assumption about Python version compatibility without evidence. I might be wrong about the Python version requirements - perhaps this package does need to support older Python versions. Also, there could be legitimate cases where ImportError (but not ModuleNotFoundError) is raised when the module exists but has import issues, and silently passing might be the desired behavior in those cases too. Even if older Python versions were a concern, Python 3.6+ has been standard for many years and is the minimum for most modern packages. The comment provides no evidence that this codebase targets pre-3.6 Python. More importantly, catching the more specific ModuleNotFoundError is better practice - it only catches the intended case (module not found) rather than masking other import problems. The comment is speculative ("might be too narrow") without demonstrating an actual issue. This comment should be deleted. It's speculative about Python version compatibility without evidence, and catching the more specific ModuleNotFoundError is actually better practice than catching the broader ImportError. The comment doesn't identify a real problem with the code.

Workflow ID: wflow_mtytPxbvoSMrrQl5

^{You can customize by changing your verbosity settings, reacting with 👍 or 👎, replying to comments, or adding code review rules.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py (1)

79-84: LGTM! Lazy import correctly implements graceful degradation.

The try-except pattern properly handles the optional traceloop SDK dependency, allowing the instrumentation to work whether or not the SDK is installed.

Optional: Consider adding a debug log when the module is not found to aid troubleshooting:

 try: # Set agent name in OpenTelemetry context for propagation to child spans from traceloop.sdk.tracing import set_agent_name set_agent_name(agent_name) except ModuleNotFoundError: + # traceloop SDK not installed; agent name propagation will be skipped pass

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between c8c1553 and 548ca67.

📒 Files selected for processing (1)

• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

**/*.py

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.py: Store API keys only in environment variables/secure vaults; never hardcode secrets in code
Use Flake8 for code linting and adhere to its rules

Files:

• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py

🧠 Learnings (1)

📚 Learning: 2025-12-02T21:09:48.674Z

Learnt from: duanyutong Repo: traceloop/openllmetry PR: 3487 File: packages/opentelemetry-instrumentation-openai/opentelemetry/instrumentation/openai/utils.py:177-178 Timestamp: 2025-12-02T21:09:48.674Z Learning: The opentelemetry-instrumentation-openai and opentelemetry-instrumentation-openai-agents packages must remain independent and not share code, so code duplication between them is acceptable. 

Applied to files:

• packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py

🧬 Code graph analysis (1)

packages/opentelemetry-instrumentation-openai-agents/opentelemetry/instrumentation/openai_agents/_hooks.py (1)

packages/traceloop-sdk/traceloop/sdk/tracing/tracing.py (1)

• set_agent_name (249-250)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: GitGuardian Security Checks