feat: add support for openai agents

README-zh.md

@@ -42,6 +42,7 @@ LoongSuite Python Agent 同时也是上游 [OTel Python Agent](https://github.co
 | [LiteLLM](https://github.com/BerriAI/litellm) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-litellm/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-litellm/) |
 | [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-mcp/README.md) | in dev |
 | [Mem0](https://github.com/mem0ai/mem0) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-mem0/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-mem0/) |
+| [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-openai-agents/README.rst) | in dev |
 
 **发行版与辅助组件：**
 

README.md

@@ -42,6 +42,7 @@ Source tree: [`instrumentation-loongsuite/`](instrumentation-loongsuite).
 | [LiteLLM](https://github.com/BerriAI/litellm) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-litellm/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-litellm/) |
 | [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-mcp/README.md) | in dev |
 | [Mem0](https://github.com/mem0ai/mem0) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-mem0/README.md) | [PyPI](https://pypi.org/project/loongsuite-instrumentation-mem0/) |
+| [OpenAI Agents SDK](https://github.com/openai/openai-agents-python) | [GUIDE](instrumentation-loongsuite/loongsuite-instrumentation-openai-agents/README.rst) | in dev |
 
 **Distro and helpers:**
 

instrumentation-loongsuite/loongsuite-instrumentation-openai-agents/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased
+
+### Added
+
+- Initialize the instrumentation for OpenAI Agents SDK
+  ([#161](https://github.com/alibaba/loongsuite-python-agent/pull/161))

instrumentation-loongsuite/loongsuite-instrumentation-openai-agents/README.rst

@@ -0,0 +1,49 @@
+OpenTelemetry OpenAI Agents SDK Instrumentation
+================================================
+
+|pypi|
+
+.. |pypi| image:: https://badge.fury.io/py/loongsuite-instrumentation-openai-agents.svg
+   :target: https://pypi.org/project/loongsuite-instrumentation-openai-agents/
+
+This library provides automatic instrumentation for the
+`OpenAI Agents SDK <https://github.com/openai/openai-agents-python>`_,
+capturing telemetry data for agent runs, tool executions, LLM generations,
+handoffs, and guardrails.
+
+Installation
+------------
+
+::
+
+    pip install loongsuite-instrumentation-openai-agents
+
+Usage
+-----
+
+.. code-block:: python
+
+    from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
+
+    OpenAIAgentsInstrumentor().instrument()
+
+    # Your OpenAI Agents SDK code works as normal
+    from agents import Agent, Runner
+
+    agent = Agent(name="assistant", instructions="You are helpful.")
+    result = Runner.run_sync(agent, "Hello!")
+
+The instrumentation automatically captures:
+
+- Agent invocation spans (``invoke_agent``)
+- Tool execution spans (``execute_tool``)
+- LLM generation spans (``chat``)
+- Agent handoff spans
+- Guardrail execution spans
+
+References
+----------
+
+* `OpenTelemetry Project <https://opentelemetry.io/>`_
+* `OpenAI Agents SDK documentation <https://openai.github.io/openai-agents-python/>`_
+* `OpenTelemetry GenAI Semantic Conventions <https://opentelemetry.io/docs/specs/semconv/gen-ai/>`_

instrumentation-loongsuite/loongsuite-instrumentation-openai-agents/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "loongsuite-instrumentation-openai-agents"
+dynamic = ["version"]
+description = "LoongSuite OpenAI Agents SDK instrumentation"
+readme = "README.rst"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [
+  { name = "OpenTelemetry Authors", email = "cncf-opentelemetry-contributors@lists.cncf.io" },
+  { name = "minimAluminiumalism", email = "caixuesen@outlook.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+  "opentelemetry-api ~= 1.37",
+  "opentelemetry-instrumentation ~= 0.58b0",
+  "opentelemetry-semantic-conventions ~= 0.58b0",
+  "opentelemetry-util-genai",
+]
+
+[project.optional-dependencies]
+instruments = [
+  "openai-agents >= 0.0.7",
+]
+
+[project.entry-points.opentelemetry_instrumentor]
+openai_agents = "opentelemetry.instrumentation.openai_agents:OpenAIAgentsInstrumentor"
+
+[project.urls]
+Homepage = "https://github.com/alibaba/loongsuite-python-agent/tree/main/instrumentation-loongsuite/loongsuite-instrumentation-openai-agents"
+Repository = "https://github.com/alibaba/loongsuite-python-agent"
+
+[tool.hatch.version]
+path = "src/opentelemetry/instrumentation/openai_agents/version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/src",
+  "/tests",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opentelemetry"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

instrumentation-loongsuite/loongsuite-instrumentation-openai-agents/src/opentelemetry/instrumentation/openai_agents/__init__.py

@@ -0,0 +1,140 @@
+# Copyright The OpenTelemetry Authors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+OpenTelemetry OpenAI Agents SDK Instrumentation
+================================================
+
+This package provides automatic instrumentation for the OpenAI Agents SDK,
+capturing telemetry data for agent runs, tool executions, LLM generations,
+handoffs, and guardrails.
+
+Usage
+-----
+
+Basic instrumentation::
+
+    from opentelemetry.instrumentation.openai_agents import (
+        OpenAIAgentsInstrumentor,
+    )
+
+    OpenAIAgentsInstrumentor().instrument()
+
+    from agents import Agent, Runner
+
+    agent = Agent(name="assistant", instructions="You are helpful.")
+    result = Runner.run_sync(agent, "Hello!")
+
+The instrumentation leverages the SDK's built-in ``TracingProcessor``
+interface to register an OpenTelemetry bridge, so all native SDK tracing
+points are automatically captured without monkey-patching.
+"""
+
+import logging
+import os
+from typing import Any, Collection, Optional
+
+from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
+from opentelemetry.instrumentation.openai_agents.package import (
+    _instruments,
+)
+from opentelemetry.instrumentation.openai_agents.version import (
+    __version__,
+)
+from opentelemetry.util.genai.extended_handler import (
+    ExtendedTelemetryHandler,
+)
+
+logger = logging.getLogger(__name__)
+
+_ENV_CAPTURE_CONTENT = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"
+
+
+def _should_capture_content() -> bool:
+    val = os.environ.get(_ENV_CAPTURE_CONTENT, "").strip().lower()
+    return val not in ("false", "0", "no", "off", "")
+
+
+class OpenAIAgentsInstrumentor(BaseInstrumentor):
+    """Instrumentor for the OpenAI Agents SDK.
+
+    Registers an OpenTelemetry-aware ``TracingProcessor`` with the
+    SDK's global trace provider so that every agent run, tool call,
+    LLM generation, handoff, and guardrail execution is automatically
+    exported as an OTel span.
+    """
+
+    _handler: Optional[ExtendedTelemetryHandler] = None
+    _processor: Optional[Any] = None
+
+    def instrumentation_dependencies(self) -> Collection[str]:
+        return _instruments
+
+    def _instrument(self, **kwargs: Any) -> None:
+        tracer_provider = kwargs.get("tracer_provider")
+        meter_provider = kwargs.get("meter_provider")
+        logger_provider = kwargs.get("logger_provider")
+
+        OpenAIAgentsInstrumentor._handler = ExtendedTelemetryHandler(
+            tracer_provider=tracer_provider,
+            meter_provider=meter_provider,
+            logger_provider=logger_provider,
+        )
+
+        capture_content = _should_capture_content()
+
+        from agents.tracing import (  # noqa: PLC0415
+            add_trace_processor,
+        )
+
+        from opentelemetry.instrumentation.openai_agents._processor import (  # noqa: PLC0415
+            OTelTracingProcessor,
+        )
+
+        processor = OTelTracingProcessor(
+            handler=OpenAIAgentsInstrumentor._handler,
+            capture_content=capture_content,
+        )
+        OpenAIAgentsInstrumentor._processor = processor
+        add_trace_processor(processor)
+
+    def _uninstrument(self, **kwargs: Any) -> None:
+        processor = OpenAIAgentsInstrumentor._processor
+        if processor is None:
+            return
+
+        try:
+            from agents.tracing.setup import (  # noqa: PLC0415
+                get_trace_provider,
+            )
+
+            provider = get_trace_provider()
+            if hasattr(provider, "_multi_processor"):
+                mp = provider._multi_processor
+                if hasattr(mp, "_processors"):
+                    procs = mp._processors
+                    if processor in procs:
+                        procs.remove(processor)
+        except Exception as e:
+            logger.debug("Failed to remove processor: %s", e)
+
+        processor.shutdown()
+        OpenAIAgentsInstrumentor._processor = None
+        OpenAIAgentsInstrumentor._handler = None
+
+
+__all__ = [
+    "__version__",
+    "OpenAIAgentsInstrumentor",
+]