OpenAI Agents voice support (#900)

* Update attribute extraction to support dict as well as object.

* Adjust tests to match serialization format of `list[str]`. Patch JSON encode in tests to handle MagicMock objects.

* Instrumentor and wrappers for OpenAI responses.

* Collect base usage attributes, too.

* Move Response attribute parsing to openai module. Move common attribute parsing to common module.

* Include tags in parent span. Helpers for accessing global config and tags. Tests for helpers and common insrumentation attributes.

* Add tags to an example.

* Remove duplicate library attributes.

* Pass OpenAI responses objects through our new instrumentor.

* Incorporate common attributes, too.

* Add indexed PROMPT semconv to MessageAttributes. Provide reusable wrapping functionality from instrumentation.common. Include prompts in OpenAI Responses attributes.

* Type checking.

* Test coverage for instrumentation.common

* Type in method def should be string in case of missing import.

* Wrap third party module imports from openai in try except block

* OpenAI instrumentation tests. (Relocated to openai_core to avoid import hijack)

* OpenAI Agents voice support

* Additional voice-specific fields.

* update pyproject.toml and uv.lock to use correct dependency

* Remove `upload_object` helper.

* Remove tag helpers.

* Move agents example scripts.

---------

Co-authored-by: Pratyush Shukla <[email protected]>

Author: tcdent

agentops/client/api/__init__.py

@@ -9,6 +9,7 @@
 from agentops.client.api.base import BaseApiClient
 from agentops.client.api.types import AuthTokenResponse
 from agentops.client.api.versions.v3 import V3Client
+from agentops.client.api.versions.v4 import V4Client
 
 # Define a type variable for client classes
 T = TypeVar("T", bound=BaseApiClient)
@@ -44,6 +45,16 @@ def v3(self) -> V3Client:
         """
         return self._get_client("v3", V3Client)
 
+    @property
+    def v4(self) -> V4Client:
+        """
+        Get the V4 API client.
+
+        Returns:
+            The V4 API client
+        """
+        return self._get_client("v4", V4Client)
+
     def _get_client(self, version: str, client_class: Type[T]) -> T:
         """
         Get or create a version-specific client.

agentops/client/api/types.py

@@ -5,10 +5,18 @@
 """
 
 from typing import TypedDict
+from pydantic import BaseModel
 
 
 class AuthTokenResponse(TypedDict):
     """Response from the auth/token endpoint"""
 
     token: str
     project_id: str
+
+
+class UploadedObjectResponse(BaseModel):
+    """Response from the v4/objects/upload endpoint"""
+    url: str
+    size: int
+

agentops/client/api/versions/__init__.py

@@ -5,5 +5,6 @@
 """
 
 from agentops.client.api.versions.v3 import V3Client
+from agentops.client.api.versions.v4 import V4Client
 
-__all__ = ["V3Client"]
+__all__ = ["V3Client", "V4Client"]

agentops/client/api/versions/v4.py

@@ -0,0 +1,71 @@
+"""
+V4 API client for the AgentOps API.
+
+This module provides the client for the V4 version of the AgentOps API.
+"""
+from typing import Optional, Union, Dict
+
+from agentops.client.api.base import BaseApiClient
+from agentops.exceptions import ApiServerException
+from agentops.client.api.types import UploadedObjectResponse
+
+
+class V4Client(BaseApiClient):
+    """Client for the AgentOps V4 API"""
+    auth_token: str
+    
+    def set_auth_token(self, token: str):
+        """
+        Set the authentication token for API requests.
+
+        Args:
+            token: The authentication token to set
+        """
+        self.auth_token = token
+    
+    def prepare_headers(self, custom_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
+        """
+        Prepare headers for API requests.
+
+        Args:
+            custom_headers: Additional headers to include
+        Returns:
+            Headers dictionary with standard headers and any custom headers
+        """
+        headers = {
+            "Authorization": f"Bearer {self.auth_token}",
+        }
+        if custom_headers:
+            headers.update(custom_headers)
+        return headers
+
+    def upload_object(self, body: Union[str, bytes]) -> UploadedObjectResponse:
+        """
+        Upload an object to the API and return the response.
+        
+        Args:
+            body: The object to upload, either as a string or bytes.
+        Returns:
+            UploadedObjectResponse: The response from the API after upload.
+        """
+        if isinstance(body, bytes):
+            body = body.decode("utf-8")
+        
+        response = self.post("/v4/objects/upload/", body, self.prepare_headers())
+        
+        if response.status_code != 200:
+            error_msg = f"Upload failed: {response.status_code}"
+            try:
+                error_data = response.json()
+                if "error" in error_data:
+                    error_msg = error_data["error"]
+            except Exception:
+                pass
+            raise ApiServerException(error_msg)
+    
+        try:
+            response_data = response.json()
+            return UploadedObjectResponse(**response_data)
+        except Exception as e:
+            raise ApiServerException(f"Failed to process upload response: {str(e)}")
+

agentops/client/client.py

@@ -45,6 +45,9 @@ def init(self, **kwargs):
         # Prefetch JWT token if enabled
         # TODO: Move this validation somewhere else (and integrate with self.config.prefetch_jwt_token once we have a solution to that)
         response = self.api.v3.fetch_auth_token(self.config.api_key)
+        
+        # Save the bearer for use with the v4 API
+        self.api.v4.set_auth_token(response["token"])
 
         # Initialize TracingCore with the current configuration and project_id
         tracing_config = self.config.dict()

agentops/helpers/__init__.py

@@ -45,4 +45,5 @@
     "get_env_bool",
     "get_env_int",
     "get_env_list",
+    "get_tags_from_config",
 ]

agentops/instrumentation/__init__.py

@@ -23,7 +23,7 @@ class InstrumentorLoader:
         We use the `provider_import_name` to determine if the library is installed i
     n the environment.
 
-        `modue_name` is the name of the module to import from.
+        `module_name` is the name of the module to import from.
         `class_name` is the name of the class to instantiate from the module.
         `provider_import_name` is the name of the package to check for availability.
     """
@@ -53,7 +53,7 @@ def get_instance(self) -> BaseInstrumentor:
 
 available_instrumentors: list[InstrumentorLoader] = [
     InstrumentorLoader(
-        module_name="opentelemetry.instrumentation.openai",
+        module_name="agentops.instrumentation.openai",
         class_name="OpenAIInstrumentor",
         provider_import_name="openai",
     ),

agentops/instrumentation/common/README.md

@@ -0,0 +1,65 @@
+# AgentOps Instrumentation Common Module
+
+The `agentops.instrumentation.common` module provides shared utilities for OpenTelemetry instrumentation across different LLM service providers.
+
+## Core Components
+
+### Attribute Handler Example
+
+Attribute handlers extract data from method inputs and outputs:
+
+```python
+from typing import Optional, Any, Tuple, Dict
+from agentops.instrumentation.common.attributes import AttributeMap
+from agentops.semconv import SpanAttributes
+
+def my_attribute_handler(args: Optional[Tuple] = None, kwargs: Optional[Dict] = None, return_value: Optional[Any] = None) -> AttributeMap:
+    attributes = {}
+    
+    # Extract attributes from kwargs (method inputs)
+    if kwargs:
+        if "model" in kwargs:
+            attributes[SpanAttributes.MODEL_NAME] = kwargs["model"]
+        # ...
+    
+    # Extract attributes from return value (method outputs)
+    if return_value:
+        if hasattr(return_value, "model"):
+            attributes[SpanAttributes.LLM_RESPONSE_MODEL] = return_value.model
+        # ...
+    
+    return attributes
+```
+
+### `WrapConfig` Class
+
+Config object defining how a method should be wrapped:
+
+```python
+from agentops.instrumentation.common.wrappers import WrapConfig
+from opentelemetry.trace import SpanKind
+
+config = WrapConfig(
+    trace_name="llm.completion",    # Name that will appear in trace spans
+    package="openai.resources",     # Path to the module containing the class
+    class_name="Completions",       # Name of the class containing the method
+    method_name="create",           # Name of the method to wrap
+    handler=my_attribute_handler,   # Function that extracts attributes
+    span_kind=SpanKind.CLIENT       # Type of span to create
+)
+```
+
+### Wrapping/Unwrapping Methods
+
+```python
+from opentelemetry.trace import get_tracer
+from agentops.instrumentation.common.wrappers import wrap, unwrap
+
+# Create a tracer and wrap a method
+tracer = get_tracer("openai", "0.0.0")
+wrap(config, tracer)
+
+# Later, unwrap the method
+unwrap(config)
+```
+

agentops/instrumentation/common/__init__.py

@@ -0,0 +1,6 @@
+from .attributes import AttributeMap, _extract_attributes_from_mapping
+
+__all__ = [
+    "AttributeMap",
+    "_extract_attributes_from_mapping",
+]

agentops/instrumentation/common/attributes.py

@@ -0,0 +1,137 @@
+"""Common attribute processing utilities shared across all instrumentors.
+
+This module provides core utilities for extracting and formatting
+OpenTelemetry-compatible attributes from span data. These functions
+are provider-agnostic and used by all instrumentors in the AgentOps
+package.
+
+The module includes:
+
+1. Helper functions for attribute extraction and mapping
+2. Common attribute getters used across all providers
+3. Base trace and span attribute functions
+
+All functions follow a consistent pattern:
+- Accept span/trace data as input
+- Process according to semantic conventions
+- Return a dictionary of formatted attributes
+
+These utilities ensure consistent attribute handling across different
+LLM service instrumentors while maintaining separation of concerns.
+"""
+from typing import Dict, Any, Optional, List
+from agentops.logging import logger
+from agentops.helpers import safe_serialize, get_agentops_version
+from agentops.semconv import (
+    CoreAttributes,
+    InstrumentationAttributes,
+    WorkflowAttributes,
+)
+
+# target_attribute_key: source_attribute
+AttributeMap = Dict[str, Any]
+
+
+def _extract_attributes_from_mapping(span_data: Any, attribute_mapping: AttributeMap) -> AttributeMap:
+    """Helper function to extract attributes based on a mapping.
+    
+    Args:
+        span_data: The span data object or dict to extract attributes from
+        attribute_mapping: Dictionary mapping target attributes to source attributes
+        
+    Returns:
+        Dictionary of extracted attributes
+    """
+    attributes = {}
+    for target_attr, source_attr in attribute_mapping.items():
+        if hasattr(span_data, source_attr):
+            # Use getattr to handle properties
+            value = getattr(span_data, source_attr)
+        elif isinstance(span_data, dict) and source_attr in span_data:
+            # Use direct key access for dicts
+            value = span_data[source_attr]
+        else:
+            continue
+
+        # Skip if value is None or empty
+        if value is None or (isinstance(value, (list, dict, str)) and not value):
+            continue
+        
+        # Serialize complex objects
+        elif isinstance(value, (dict, list, object)) and not isinstance(value, (str, int, float, bool)):
+            value = safe_serialize(value)
+        
+        attributes[target_attr] = value
+    
+    return attributes
+
+
+def get_common_attributes() -> AttributeMap:
+    """Get common instrumentation attributes used across traces and spans.
+    
+    Returns:
+        Dictionary of common instrumentation attributes
+    """
+    return {
+        InstrumentationAttributes.NAME: "agentops",
+        InstrumentationAttributes.VERSION: get_agentops_version(),
+    }
+
+
+def get_base_trace_attributes(trace: Any) -> AttributeMap:
+    """Create the base attributes dictionary for an OpenTelemetry trace.
+    
+    Args:
+        trace: The trace object to extract attributes from
+        
+    Returns:
+        Dictionary containing base trace attributes
+    """
+    if not hasattr(trace, 'trace_id'):
+        logger.warning("Cannot create trace attributes: missing trace_id")
+        return {}
+    
+    attributes = {
+        WorkflowAttributes.WORKFLOW_NAME: trace.name,
+        CoreAttributes.TRACE_ID: trace.trace_id,
+        WorkflowAttributes.WORKFLOW_STEP_TYPE: "trace",
+        **get_common_attributes(),
+    }
+    
+    # Add tags from the config to the trace attributes (these should only be added to the trace)
+    from agentops import get_client
+    
+    config = get_client().config
+    tags = []
+    if config.default_tags:
+        # `default_tags` can either be a `set` or a `list`
+        tags = list(config.default_tags)
+    
+    attributes[CoreAttributes.TAGS] = tags
+    
+    return attributes
+
+
+def get_base_span_attributes(span: Any) -> AttributeMap:
+    """Create the base attributes dictionary for an OpenTelemetry span.
+    
+    Args:
+        span: The span object to extract attributes from
+        
+    Returns:
+        Dictionary containing base span attributes
+    """
+    span_id = getattr(span, 'span_id', 'unknown')
+    trace_id = getattr(span, 'trace_id', 'unknown')
+    parent_id = getattr(span, 'parent_id', None)
+    
+    attributes = {
+        CoreAttributes.TRACE_ID: trace_id,
+        CoreAttributes.SPAN_ID: span_id,
+        **get_common_attributes(),
+    }
+    
+    if parent_id:
+        attributes[CoreAttributes.PARENT_ID] = parent_id
+        
+    return attributes