feat(obs): install the openai-agents bridge so Runner turns produce spans

The traces signal wired but produced nothing for the fleet's dominant agent shape.
sgp_obs.init() installs most of the traces wiring itself; the openai-agents bridge
is the one piece it does not. Measured on 0.16.0 after a plain init() with traces
on:

    GenAI attempt span processor   installed
    litellm logical adapter        installed  (_SgpObsLiteLLMLogger)
    httpx / aiohttp egress         instrumented
    openai-agents bridge           NOT installed

That last one carries roughly 83% of model-calling agents, so without it a Runner
turn contributes no logical model-operation spans and "traces on" looks like it
does nothing at all.

This is what the obs-test-* agents in agentex-agents#2183 each hand-roll: every one
of the five ships an identical 114-line obs_bootstrap.py. Comparing that file
against what init() already does, four of its five steps are redundant — the httpx
and aiohttp instrumentors (init's _instrument_egress does them, and 0.16.0
deliberately reuses an already-instrumented one rather than warning), the attempt
processor, and the litellm adapter. Only the bridge was load-bearing. With this
change an adopting agent's bootstrap collapses to nothing, except the parts that
are genuinely agent-specific: capture_turn's redaction allowlist, and its business
span call sites.

Installed unconditionally when traces are wired, because openai-agents is a hard
dependency of this SDK, so `agents` is importable in every agent. The call is
idempotent. A False return means `agents` was somehow not importable, which should
be impossible here, so that warns rather than passing silently.

Verified through the SDK's own entry point, not the library's:

    SDK init status: wired:metrics,traces
      attempt span processor : True
      openai-agents bridge   : True
      litellm adapter        : ['_SgpObsLiteLLMLogger']

88 tests, ruff clean, pyright 0 errors, all with sgp-obs absent.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: stephen-wang24

src/agentex/lib/core/observability/sgp_obs_setup.py

@@ -141,13 +141,54 @@ def init_sgp_obs(app: Any = None) -> str:
         return _status
 
     if "traces" in handles:
+        _install_openai_agents_bridge()
         _warn_if_correlation_backend_mismatched()
 
     _status = "wired:" + ",".join(sorted(handles))
     logger.info("sgp-obs wired (%s)", _status)
     return _status
 
 
+def _install_openai_agents_bridge() -> bool:
+    """Register sgp-obs' openai-agents trace processor, so a ``Runner`` turn produces
+    logical model-operation spans.
+
+    This is the one piece of traces wiring ``sgp_obs.init()`` does NOT do for itself.
+    Measured on 0.16.0 after a plain ``init()`` with the traces signal on:
+
+        GenAI attempt span processor  installed
+        litellm logical adapter       installed
+        httpx / aiohttp egress        instrumented
+        openai-agents bridge          NOT installed
+
+    which is why the obs-test agents each carry a hand-written bootstrap that calls it.
+    It matters more than the others here: roughly 83% of model-calling agents reach the
+    model through the openai-agents ``Runner``, so without this the dominant path
+    contributes no logical spans and "traces on" looks like it does nothing.
+
+    Unconditional because ``openai-agents`` is a hard dependency of this SDK, so the
+    ``agents`` package is importable in every agent. The call is idempotent and returns
+    False rather than raising when the SDK is somehow absent.
+    """
+    try:
+        from sgp_obs.traces import install_openai_agents_bridge  # type: ignore[import-not-found]
+
+        installed = bool(install_openai_agents_bridge())
+        if installed:
+            logger.debug("sgp-obs openai-agents bridge installed")
+        else:
+            # Only reachable if `agents` is not importable, which should not happen
+            # while openai-agents is a hard dependency — so say so rather than shrug.
+            logger.warning(
+                "sgp-obs openai-agents bridge did not install; Runner turns will "
+                "produce no logical model-operation spans."
+            )
+        return installed
+    except Exception:  # pragma: no cover - telemetry must never break startup
+        logger.debug("sgp-obs openai-agents bridge unavailable", exc_info=True)
+        return False
+
+
 def _warn_if_correlation_backend_mismatched() -> None:
     """Warn when sgp-obs is exporting OTel traces but the SDK's business-span
     correlation is still reading ddtrace.

src/agentex/lib/core/observability/tests/test_sgp_obs_setup.py

@@ -52,13 +52,21 @@ def caplog_at(monkeypatch):
     yield records
 
 
-def _fake_sgp_obs(monkeypatch, init=None, shutdown=None):
-    """Install a stand-in ``sgp_obs`` module whose entry points we control."""
+def _fake_sgp_obs(monkeypatch, init=None, shutdown=None, bridge=None):
+    """Install a stand-in ``sgp_obs`` module whose entry points we control.
+
+    ``bridge`` stands in for ``sgp_obs.traces.install_openai_agents_bridge``; it lives
+    on a fake ``sgp_obs.traces`` submodule because that is how the SDK imports it.
+    """
     module = type(sys)("sgp_obs")
     module.init = init if init is not None else (lambda **_kwargs: {"metrics": object()})
     if shutdown is not None:
         module.shutdown = shutdown
     monkeypatch.setitem(sys.modules, "sgp_obs", module)
+
+    traces = type(sys)("sgp_obs.traces")
+    traces.install_openai_agents_bridge = bridge if bridge is not None else (lambda: True)
+    monkeypatch.setitem(sys.modules, "sgp_obs.traces", traces)
     return module
 
 
@@ -339,3 +347,56 @@ def test_the_json_rpc_route_is_still_mounted(self, monkeypatch):
         _block_sgp_obs_import(monkeypatch)
         routes = {getattr(r, "path", None) for r in BaseACPServer().routes}
         assert {"/healthz", "/api"} <= routes
+
+
+class TestOpenAIAgentsBridge:
+    """sgp_obs.init() installs the GenAI attempt processor, the litellm adapter and the
+    egress instrumentors by itself, but NOT the openai-agents bridge (measured on
+    0.16.0). That is the path ~83% of model-calling agents take, so the SDK installs it
+    — otherwise "traces on" produces no logical model-operation spans for most agents.
+    """
+
+    def test_installed_when_traces_are_wired(self, monkeypatch):
+        calls = []
+        _fake_sgp_obs(
+            monkeypatch,
+            init=lambda **_kwargs: {"traces": object()},
+            bridge=lambda: calls.append(True) or True,
+        )
+        monkeypatch.setenv("SGP_OBS_MODE", "lgtm")
+        assert init_sgp_obs() == "wired:traces"
+        assert calls == [True]
+
+    def test_not_installed_without_the_traces_signal(self, monkeypatch):
+        """A metrics-only agent has no span pipeline to feed, so installing an
+        openai-agents trace processor would be pointless work at startup."""
+        calls = []
+        _fake_sgp_obs(
+            monkeypatch,
+            init=lambda **_kwargs: {"metrics": object()},
+            bridge=lambda: calls.append(True) or True,
+        )
+        assert init_sgp_obs() == "wired:metrics"
+        assert calls == []
+
+    def test_a_bridge_that_declines_is_reported(self, monkeypatch, caplog):
+        """False means the `agents` SDK was not importable. openai-agents is a hard
+        dependency of this package, so that should be impossible — say so rather than
+        swallow it."""
+        monkeypatch.setenv("SGP_OBS_MODE", "lgtm")
+        _fake_sgp_obs(
+            monkeypatch, init=lambda **_kwargs: {"traces": object()}, bridge=lambda: False
+        )
+        with caplog.at_level("WARNING"):
+            assert init_sgp_obs() == "wired:traces"
+        assert "openai-agents bridge" in caplog.text
+
+    def test_a_raising_bridge_does_not_stop_startup(self, monkeypatch):
+        def boom():
+            raise RuntimeError("sgp-obs internals moved")
+
+        monkeypatch.setenv("SGP_OBS_MODE", "lgtm")
+        _fake_sgp_obs(
+            monkeypatch, init=lambda **_kwargs: {"traces": object()}, bridge=boom
+        )
+        assert init_sgp_obs() == "wired:traces"