traccia 0.1.5__py3-none-any.whl → 0.1.6__py3-none-any.whl

traccia/auto.py

@@ -123,10 +123,22 @@ def init(
     # Add rate limiting config back into merged_config for start_tracing
     merged_config.update(rate_limit_config)
     
+    # Extract openai_agents config (not passed to start_tracing)
+    openai_agents_enabled = merged_config.pop('openai_agents', True)
+    
     # Initialize via start_tracing with full config
     provider = start_tracing(**merged_config)
     _init_method = "init"
     
+    # Auto-install OpenAI Agents SDK integration if available
+    if openai_agents_enabled:
+        try:
+            from traccia.integrations.openai_agents import install as install_openai_agents
+            install_openai_agents(enabled=True)
+        except Exception:
+            # Agents SDK not installed or error during install, skip silently
+            pass
+    
     # Auto-start trace if requested
     if final_auto_start:
         _auto_trace_context = _start_auto_trace(provider, _auto_trace_name)

traccia/config.py

@@ -34,6 +34,7 @@ ENV_VAR_MAPPING = {
     "auto_instrument_tools": ["TRACCIA_AUTO_INSTRUMENT_TOOLS"],
     "max_tool_spans": ["TRACCIA_MAX_TOOL_SPANS"],
     "max_span_depth": ["TRACCIA_MAX_SPAN_DEPTH"],
+    "openai_agents": ["TRACCIA_OPENAI_AGENTS"],
     
     # Rate limiting & Batching
     "max_spans_per_second": ["TRACCIA_MAX_SPANS_PER_SECOND"],
@@ -161,6 +162,10 @@ class InstrumentationConfig(BaseModel):
         gt=0,
         description="Maximum depth of nested spans"
     )
+    openai_agents: bool = Field(
+        default=True,
+        description="Auto-install OpenAI Agents SDK integration when available"
+    )
 
 
 class RateLimitConfig(BaseModel):
@@ -299,6 +304,7 @@ class TracciaConfig(BaseModel):
             "auto_instrument_tools": self.instrumentation.auto_instrument_tools,
             "max_tool_spans": self.instrumentation.max_tool_spans,
             "max_span_depth": self.instrumentation.max_span_depth,
+            "openai_agents": self.instrumentation.openai_agents,
             # Rate limiting & Batching
             "max_spans_per_second": self.rate_limiting.max_spans_per_second,
             "max_queue_size": self.rate_limiting.max_queue_size,
@@ -460,7 +466,7 @@ def load_config_from_env(flat: bool = False) -> Dict[str, Any]:
                 env_config["exporters"][key] = value
     
     # Instrumentation section
-    for key in ["enable_patching", "enable_token_counting", "enable_costs", "auto_instrument_tools"]:
+    for key in ["enable_patching", "enable_token_counting", "enable_costs", "auto_instrument_tools", "openai_agents"]:
         value = get_env_value(key)
         if value is not None:
             env_config["instrumentation"][key] = value.lower() in ("true", "1", "yes")

traccia/instrumentation/__init__.py

@@ -1,7 +1,12 @@
-"""Instrumentation helpers and monkey patching."""
+"""Infrastructure and vendor instrumentation.
+
+This module exposes helpers for HTTP client/server tracing (including FastAPI),
+vendor SDK patching (OpenAI, Anthropic, requests), and decorators used for
+auto-instrumentation.
+"""
 
 from traccia.instrumentation.decorator import observe
-from traccia.instrumentation.openai import patch_openai
+from traccia.instrumentation.openai import patch_openai, patch_openai_responses
 from traccia.instrumentation.anthropic import patch_anthropic
 from traccia.instrumentation.requests import patch_requests
 from traccia.instrumentation.http_client import inject_headers as inject_http_headers
@@ -11,6 +16,7 @@ from traccia.instrumentation.fastapi import install_http_middleware
 __all__ = [
     "observe",
     "patch_openai",
+    "patch_openai_responses",
     "patch_anthropic",
     "patch_requests",
     "inject_http_headers",

traccia/instrumentation/openai.py

@@ -1,4 +1,4 @@
-"""OpenAI monkey patching for chat completions."""
+"""OpenAI monkey patching for chat completions and responses API."""
 
 from __future__ import annotations
 
@@ -6,6 +6,7 @@ from typing import Any, Dict, Optional, Callable
 from traccia.tracer.span import SpanStatus
 
 _patched = False
+_responses_patched = False
 
 
 def _safe_get(obj, path: str, default=None):
@@ -168,6 +169,185 @@ def patch_openai() -> bool:
 
     if patched_any:
         _patched = True
+    
+    # Also patch Responses API (used by OpenAI Agents SDK)
+    patch_openai_responses()
+    
+    return patched_any
+
+
+def patch_openai_responses() -> bool:
+    """Patch OpenAI Responses API for tracing."""
+    global _responses_patched
+    if _responses_patched:
+        return True
+    try:
+        import openai
+    except Exception:
+        return False
+
+    def _extract_responses_input(kwargs, args):
+        """Extract input from responses.create call."""
+        input_data = kwargs.get("input")
+        if input_data is None and len(args) >= 2:
+            input_data = args[1]
+        if not input_data:
+            return None, None
+        
+        # input can be a string or list of ResponseInputItem
+        if isinstance(input_data, str):
+            return [{"role": "user", "content": input_data}], input_data
+        elif isinstance(input_data, list):
+            # Convert to slim representation
+            slim = []
+            parts = []
+            for item in list(input_data)[:50]:
+                if isinstance(item, dict):
+                    role = item.get("role", "user")
+                    content_items = item.get("content", [])
+                    
+                    # Extract text from content items
+                    text_parts = []
+                    if isinstance(content_items, str):
+                        text_parts.append(content_items)
+                    elif isinstance(content_items, list):
+                        for c in content_items:
+                            if isinstance(c, dict) and c.get("type") == "text":
+                                text_parts.append(c.get("text", ""))
+                    
+                    content_str = " ".join(text_parts) if text_parts else ""
+                    slim.append({"role": role, "content": content_str})
+                    if content_str:
+                        parts.append(f"{role}: {content_str}")
+            
+            prompt_text = "\n".join(parts) if parts else None
+            return slim or None, prompt_text
+        
+        return None, None
+
+    def _extract_responses_output(resp) -> Optional[str]:
+        """Extract output text from Response object."""
+        output = getattr(resp, "output", None) or _safe_get(resp, "output")
+        if not output:
+            return None
+        
+        parts = []
+        for item in output:
+            if isinstance(item, dict):
+                content = item.get("content", [])
+            else:
+                content = getattr(item, "content", [])
+            
+            # Extract text from content items
+            if isinstance(content, list):
+                for c in content:
+                    if isinstance(c, dict) and c.get("type") == "text":
+                        text = c.get("text", "")
+                        if text:
+                            parts.append(text)
+                    elif hasattr(c, "type") and c.type == "text":
+                        text = getattr(c, "text", "")
+                        if text:
+                            parts.append(text)
+        
+        return "\n".join(parts) if parts else None
+
+    def _wrap_responses(create_fn: Callable):
+        if getattr(create_fn, "_agent_trace_patched", False):
+            return create_fn
+
+        async def wrapped_create(*args, **kwargs):
+            tracer = _get_tracer("openai.responses")
+            model = kwargs.get("model") or _safe_get(args, "0.model", None)
+            input_slim, prompt_text = _extract_responses_input(kwargs, args)
+            
+            attributes: Dict[str, Any] = {
+                "llm.vendor": "openai",
+                "llm.api": "responses"
+            }
+            if model:
+                attributes["llm.model"] = model
+            if input_slim:
+                import json
+                try:
+                    attributes["llm.openai.input"] = json.dumps(input_slim)[:1000]
+                except Exception:
+                    attributes["llm.openai.input"] = str(input_slim)[:1000]
+            if prompt_text:
+                attributes["llm.prompt"] = prompt_text[:2000]
+            
+            with tracer.start_as_current_span("llm.openai.responses", attributes=attributes) as span:
+                try:
+                    resp = await create_fn(*args, **kwargs)
+                    
+                    # Extract response details
+                    resp_model = getattr(resp, "model", None) or _safe_get(resp, "model")
+                    if resp_model and "llm.model" not in span.attributes:
+                        span.set_attribute("llm.model", str(resp_model))
+                    
+                    # Extract usage
+                    usage = getattr(resp, "usage", None) or _safe_get(resp, "usage")
+                    if usage:
+                        span.set_attribute("llm.usage.source", "provider_usage")
+                        input_tokens = getattr(usage, "input_tokens", None) or (usage.get("input_tokens") if isinstance(usage, dict) else None)
+                        output_tokens = getattr(usage, "output_tokens", None) or (usage.get("output_tokens") if isinstance(usage, dict) else None)
+                        total_tokens = getattr(usage, "total_tokens", None) or (usage.get("total_tokens") if isinstance(usage, dict) else None)
+                        
+                        if input_tokens is not None:
+                            span.set_attribute("llm.usage.prompt_tokens", input_tokens)
+                            span.set_attribute("llm.usage.input_tokens", input_tokens)
+                            span.set_attribute("llm.usage.prompt_source", "provider_usage")
+                        if output_tokens is not None:
+                            span.set_attribute("llm.usage.completion_tokens", output_tokens)
+                            span.set_attribute("llm.usage.output_tokens", output_tokens)
+                            span.set_attribute("llm.usage.completion_source", "provider_usage")
+                        if total_tokens is not None:
+                            span.set_attribute("llm.usage.total_tokens", total_tokens)
+                    
+                    # Extract completion text
+                    completion = _extract_responses_output(resp)
+                    if completion:
+                        span.set_attribute("llm.completion", completion[:2000])
+                    
+                    # Extract status
+                    status = getattr(resp, "status", None) or _safe_get(resp, "status")
+                    if status:
+                        span.set_attribute("llm.response.status", str(status))
+                    
+                    return resp
+                except Exception as exc:
+                    span.record_exception(exc)
+                    span.set_status(SpanStatus.ERROR, str(exc))
+                    raise
+
+        wrapped_create._agent_trace_patched = True
+        return wrapped_create
+
+    patched_any = False
+
+    # Patch AsyncOpenAI.responses.create
+    try:
+        from openai import AsyncOpenAI
+        if hasattr(AsyncOpenAI, "responses"):
+            responses = getattr(AsyncOpenAI, "responses")
+            if hasattr(responses, "create"):
+                # This is a property/descriptor, need to patch the underlying class
+                pass
+    except Exception:
+        pass
+
+    # Patch the Responses resource class directly
+    try:
+        from openai.resources.responses import AsyncResponses
+        if hasattr(AsyncResponses, "create"):
+            original_create = AsyncResponses.create
+            AsyncResponses.create = _wrap_responses(original_create)
+            patched_any = True
+    except Exception:
+        pass
+
+    if patched_any:
+        _responses_patched = True
     return patched_any
 
 

traccia/integrations/__init__.py

@@ -1,4 +1,4 @@
-"""Traccia integrations for frameworks like LangChain, CrewAI, LlamaIndex."""
+"""Traccia integrations for frameworks like LangChain, OpenAI Agents SDK."""
 
 __all__ = []
 
@@ -14,9 +14,26 @@ def _import_langchain():
         ) from e
 
 
+def _import_openai_agents():
+    try:
+        from traccia.integrations.openai_agents import install
+        return install
+    except ImportError as e:
+        raise ModuleNotFoundError(
+            "OpenAI Agents integration requires openai-agents. "
+            "Install with: pip install openai-agents"
+        ) from e
+
+
 # Make available if imported
 try:
     from traccia.integrations.langchain import TracciaCallbackHandler
     __all__.append("TracciaCallbackHandler")
 except ImportError:
     pass
+
+try:
+    from traccia.integrations.openai_agents import install as install_openai_agents
+    __all__.append("install_openai_agents")
+except ImportError:
+    pass

traccia/integrations/openai_agents/__init__.py

@@ -0,0 +1,73 @@
+"""Traccia integration for OpenAI Agents SDK."""
+
+from typing import Optional
+
+_installed = False
+
+
+def install(enabled: Optional[bool] = None) -> bool:
+    """
+    Install Traccia tracing for OpenAI Agents SDK.
+    
+    This registers a TracingProcessor with the Agents SDK that captures
+    agent runs, tool calls, handoffs, and LLM generations as Traccia spans.
+    
+    Args:
+        enabled: If False, skip installation. If None, check config.
+        
+    Returns:
+        True if installed successfully, False otherwise.
+        
+    Example:
+        ```python
+        from traccia import init
+        from traccia.integrations.openai_agents import install
+        
+        init()
+        install()  # Register Agents SDK tracing
+        ```
+    
+    Note:
+        This is automatically called by `traccia.init()` when the `openai-agents`
+        package is installed, unless disabled via config.
+    """
+    global _installed
+    
+    if _installed:
+        return True
+    
+    # Check if explicitly disabled
+    if enabled is False:
+        return False
+    
+    # Check config if not explicitly enabled
+    if enabled is None:
+        from traccia import runtime_config
+        # Check if disabled in config
+        if runtime_config.get_config_value("openai_agents") is False:
+            return False
+    
+    try:
+        # Import Agents SDK components
+        from agents import add_trace_processor
+        from agents.tracing import TracingProcessor
+        
+        # Import our processor
+        from traccia.integrations.openai_agents.processor import TracciaAgentsTracingProcessor
+        
+        # Register the processor
+        processor = TracciaAgentsTracingProcessor()
+        add_trace_processor(processor)
+        
+        _installed = True
+        return True
+        
+    except ImportError:
+        # Agents SDK not installed, skip silently
+        return False
+    except Exception:
+        # Other errors, fail silently to avoid breaking app startup
+        return False
+
+
+__all__ = ["install"]

traccia/integrations/openai_agents/processor.py

@@ -0,0 +1,262 @@
+"""Traccia processor for OpenAI Agents SDK tracing."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    try:
+        from agents.tracing import Span, Trace
+        from agents.tracing.span_data import (
+            AgentSpanData,
+            FunctionSpanData,
+            GenerationSpanData,
+            HandoffSpanData,
+            GuardrailSpanData,
+            ResponseSpanData,
+            CustomSpanData,
+        )
+    except ImportError:
+        pass
+
+
+class TracciaAgentsTracingProcessor:
+    """
+    Traccia processor for OpenAI Agents SDK.
+    
+    Implements the Agents SDK TracingProcessor interface to capture agent
+    runs, tool calls, handoffs, and generations into Traccia spans.
+    """
+
+    def __init__(self):
+        """Initialize the processor."""
+        self._trace_map = {}  # Map Agents trace_id -> Traccia trace context
+        self._span_map = {}   # Map Agents span_id -> Traccia span
+        self._tracer = None
+
+    def _get_tracer(self):
+        """Get or create the Traccia tracer."""
+        if self._tracer is None:
+            import traccia
+            self._tracer = traccia.get_tracer("openai.agents")
+        return self._tracer
+
+    def on_trace_start(self, trace: Trace) -> None:
+        """Called when an Agents trace starts."""
+        try:
+            # Store trace context for span correlation
+            self._trace_map[trace.trace_id] = {
+                "trace_id": trace.trace_id,
+                "started_at": getattr(trace, "started_at", None),
+            }
+        except Exception:
+            # Don't break agent execution on tracing errors
+            pass
+
+    def on_trace_end(self, trace: Trace) -> None:
+        """Called when an Agents trace ends."""
+        try:
+            # Clean up trace mapping
+            self._trace_map.pop(trace.trace_id, None)
+        except Exception:
+            pass
+
+    def on_span_start(self, span: Span[Any]) -> None:
+        """Called when an Agents span starts."""
+        try:
+            tracer = self._get_tracer()
+            span_data = span.span_data
+            
+            # Determine span name based on span type
+            span_name = self._get_span_name(span_data)
+            
+            # Start Traccia span
+            attributes = self._extract_attributes(span_data)
+            traccia_span = tracer.start_span(span_name, attributes=attributes)
+            
+            # Store mapping
+            self._span_map[span.span_id] = traccia_span
+        except Exception:
+            # Don't break agent execution
+            pass
+
+    def on_span_end(self, span: Span[Any]) -> None:
+        """Called when an Agents span ends."""
+        try:
+            traccia_span = self._span_map.pop(span.span_id, None)
+            if not traccia_span:
+                return
+            
+            # Update attributes with final data
+            span_data = span.span_data
+            self._update_span_attributes(traccia_span, span_data)
+            
+            # Record error if present
+            error = getattr(span, "error", None)
+            if error:
+                from traccia.tracer.span import SpanStatus
+                error_msg = str(error.get("message", "Unknown error") if isinstance(error, dict) else error)
+                traccia_span.set_status(SpanStatus.ERROR, error_msg)
+            
+            # End the span
+            traccia_span.end()
+        except Exception:
+            # Ensure span ends even if there's an error
+            try:
+                if traccia_span:
+                    traccia_span.end()
+            except:
+                pass
+
+    def _get_span_name(self, span_data: Any) -> str:
+        """Determine Traccia span name from Agents span data."""
+        span_type = getattr(span_data, "type", "unknown")
+        
+        if span_type == "agent":
+            agent_name = getattr(span_data, "name", "unknown")
+            return f"agent.{agent_name}"
+        elif span_type == "generation":
+            return "llm.agents.generation"
+        elif span_type == "function":
+            func_name = getattr(span_data, "name", "unknown")
+            return f"agent.tool.{func_name}"
+        elif span_type == "handoff":
+            return "agent.handoff"
+        elif span_type == "guardrail":
+            guardrail_name = getattr(span_data, "name", "unknown")
+            return f"agent.guardrail.{guardrail_name}"
+        elif span_type == "response":
+            return "agent.response"
+        elif span_type == "custom":
+            custom_name = getattr(span_data, "name", "unknown")
+            return f"agent.custom.{custom_name}"
+        else:
+            return f"agent.{span_type}"
+
+    def _extract_attributes(self, span_data: Any) -> dict[str, Any]:
+        """Extract initial attributes from Agents span data."""
+        attrs = {
+            "agent.span.type": getattr(span_data, "type", "unknown"),
+        }
+        
+        span_type = getattr(span_data, "type", None)
+        
+        if span_type == "agent":
+            attrs["agent.name"] = getattr(span_data, "name", None)
+            tools = getattr(span_data, "tools", None)
+            if tools:
+                attrs["agent.tools"] = json.dumps(tools)[:500]
+            handoffs = getattr(span_data, "handoffs", None)
+            if handoffs:
+                attrs["agent.handoffs"] = json.dumps(handoffs)[:500]
+            output_type = getattr(span_data, "output_type", None)
+            if output_type:
+                attrs["agent.output_type"] = str(output_type)
+                
+        elif span_type == "generation":
+            model = getattr(span_data, "model", None)
+            if model:
+                attrs["llm.model"] = str(model)
+            model_config = getattr(span_data, "model_config", None)
+            if model_config:
+                attrs["llm.model_config"] = json.dumps(model_config)[:500]
+                
+        elif span_type == "function":
+            func_name = getattr(span_data, "name", None)
+            if func_name:
+                attrs["agent.tool.name"] = func_name
+                
+        elif span_type == "handoff":
+            from_agent = getattr(span_data, "from_agent", None)
+            to_agent = getattr(span_data, "to_agent", None)
+            if from_agent:
+                attrs["agent.handoff.from"] = from_agent
+            if to_agent:
+                attrs["agent.handoff.to"] = to_agent
+                
+        elif span_type == "guardrail":
+            guardrail_name = getattr(span_data, "name", None)
+            if guardrail_name:
+                attrs["agent.guardrail.name"] = guardrail_name
+        
+        return attrs
+
+    def _update_span_attributes(self, traccia_span: Any, span_data: Any) -> None:
+        """Update Traccia span with final attributes from completed Agents span."""
+        try:
+            span_type = getattr(span_data, "type", None)
+            
+            if span_type == "generation":
+                # Add usage info
+                usage = getattr(span_data, "usage", None)
+                if usage and isinstance(usage, dict):
+                    input_tokens = usage.get("input_tokens")
+                    output_tokens = usage.get("output_tokens")
+                    if input_tokens is not None:
+                        traccia_span.set_attribute("llm.usage.input_tokens", input_tokens)
+                        traccia_span.set_attribute("llm.usage.prompt_tokens", input_tokens)
+                    if output_tokens is not None:
+                        traccia_span.set_attribute("llm.usage.output_tokens", output_tokens)
+                        traccia_span.set_attribute("llm.usage.completion_tokens", output_tokens)
+                    if input_tokens is not None and output_tokens is not None:
+                        traccia_span.set_attribute("llm.usage.total_tokens", input_tokens + output_tokens)
+                
+                # Add truncated input/output for observability
+                input_data = getattr(span_data, "input", None)
+                if input_data:
+                    try:
+                        input_str = json.dumps(input_data)[:1000]
+                        traccia_span.set_attribute("llm.input", input_str)
+                    except:
+                        traccia_span.set_attribute("llm.input", str(input_data)[:1000])
+                
+                output_data = getattr(span_data, "output", None)
+                if output_data:
+                    try:
+                        output_str = json.dumps(output_data)[:1000]
+                        traccia_span.set_attribute("llm.output", output_str)
+                    except:
+                        traccia_span.set_attribute("llm.output", str(output_data)[:1000])
+            
+            elif span_type == "function":
+                # Add function input/output
+                func_input = getattr(span_data, "input", None)
+                if func_input:
+                    traccia_span.set_attribute("agent.tool.input", str(func_input)[:500])
+                
+                func_output = getattr(span_data, "output", None)
+                if func_output:
+                    traccia_span.set_attribute("agent.tool.output", str(func_output)[:500])
+                
+                mcp_data = getattr(span_data, "mcp_data", None)
+                if mcp_data:
+                    traccia_span.set_attribute("agent.tool.mcp", json.dumps(mcp_data)[:500])
+            
+            elif span_type == "guardrail":
+                triggered = getattr(span_data, "triggered", False)
+                traccia_span.set_attribute("agent.guardrail.triggered", triggered)
+            
+            elif span_type == "response":
+                response = getattr(span_data, "response", None)
+                if response:
+                    response_id = getattr(response, "id", None)
+                    if response_id:
+                        traccia_span.set_attribute("agent.response.id", response_id)
+        
+        except Exception:
+            # Don't break tracing on attribute errors
+            pass
+
+    def shutdown(self) -> None:
+        """Shutdown the processor."""
+        try:
+            self._trace_map.clear()
+            self._span_map.clear()
+        except Exception:
+            pass
+
+    def force_flush(self) -> None:
+        """Force flush any queued spans."""
+        # Traccia handles flushing at the provider level
+        pass

traccia/runtime_config.py

@@ -1,6 +1,6 @@
 """Runtime configuration state management."""
 
-from typing import Optional, List
+from typing import Optional, List, Any
 
 # Global runtime configuration state
 _config = {
@@ -15,6 +15,7 @@ _config = {
     "agent_id": None,
     "debug": False,
     "attr_truncation_limit": 1000,
+    "openai_agents": True,
 }
 
 
@@ -104,3 +105,23 @@ def set_attr_truncation_limit(value: int) -> None:
 
 def get_attr_truncation_limit() -> int:
     return _config["attr_truncation_limit"]
+
+
+def get_openai_agents() -> bool:
+    """Get whether OpenAI Agents SDK integration is enabled."""
+    return _config.get("openai_agents", True)
+
+
+def set_openai_agents(value: bool) -> None:
+    """Set whether OpenAI Agents SDK integration is enabled."""
+    _config["openai_agents"] = value
+
+
+def set_config_value(key: str, value: Any) -> None:
+    """Set a runtime config value."""
+    _config[key] = value
+
+
+def get_config_value(key: str, default: Any = None) -> Any:
+    """Get a runtime config value."""
+    return _config.get(key, default)

{traccia-0.1.5.dist-info → traccia-0.1.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traccia
-Version: 0.1.5
+Version: 0.1.6
 Summary: Production-ready distributed tracing SDK for AI agents and LLM applications
 License: Apache-2.0
 Project-URL: Homepage, https://github.com/traccia-ai/traccia
@@ -45,6 +45,7 @@ Traccia is a lightweight, high-performance Python SDK for observability and trac
 ## ✨ Features
 
 - **🔍 Automatic Instrumentation**: Auto-patch OpenAI, Anthropic, requests, and HTTP libraries
+- **🤖 Framework Integrations**: Support for LangChain and OpenAI Agents SDK
 - **📊 LLM-Aware Tracing**: Track tokens, costs, prompts, and completions automatically
 - **⚡ Zero-Config Start**: Simple `init()` call with automatic config discovery
 - **🎯 Decorator-Based**: Trace any function with `@observe` decorator
@@ -129,6 +130,33 @@ Spans for LLM/chat model runs are created automatically with the same attributes
 
 **Note:** `pip install traccia[langchain]` installs traccia plus `langchain-core`; you need this extra to use the callback handler. If you already have `langchain-core` (e.g. from `langchain` or `langchain-openai`), base `pip install traccia` may be enough at runtime, but `traccia[langchain]` is the supported way to get a compatible dependency.
 
+### OpenAI Agents SDK
+
+Traccia **automatically** detects and instruments the OpenAI Agents SDK when installed. No extra code needed:
+
+```python
+from traccia import init
+from agents import Agent, Runner
+
+init()  # Automatically enables Agents SDK tracing
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant"
+)
+result = Runner.run_sync(agent, "Write a haiku about recursion")
+```
+
+**Configuration**: Auto-enabled by default when `openai-agents` is installed. To disable:
+
+```python
+init(openai_agents=False)  # Explicit parameter
+# OR set environment variable: TRACCIA_OPENAI_AGENTS=false
+# OR in traccia.toml under [instrumentation]: openai_agents = false
+```
+
+**Compatibility**: If you have `openai-agents` installed but don't use it (e.g., using LangChain or pure OpenAI instead), the integration is registered but never invoked—no overhead or extra spans.
+
 ---
 
 ## 📖 Configuration
@@ -169,6 +197,7 @@ reset_trace_file = false      # Reset file on initialization
 enable_patching = true          # Auto-patch libraries (OpenAI, Anthropic, requests)
 enable_token_counting = true    # Count tokens for LLM calls
 enable_costs = true             # Calculate costs
+openai_agents = true            # Auto-enable OpenAI Agents SDK integration
 auto_instrument_tools = false   # Auto-instrument tool calls (experimental)
 max_tool_spans = 100            # Max tool spans to create
 max_span_depth = 10             # Max nested span depth
@@ -607,6 +636,17 @@ Application Code (@observe)
    Backend (Grafana Tempo / Jaeger / Zipkin / etc.)
 ```
 
+### Instrumentation vs Integrations
+
+- **`traccia.instrumentation.*`**: Infrastructure and vendor instrumentation.
+  - HTTP client/server helpers (including FastAPI middleware).
+  - Vendor SDK hooks and monkey patching (e.g., OpenAI, Anthropic, `requests`).
+  - Decorators and utilities used for auto-instrumenting arbitrary functions.
+
+- **`traccia.integrations.*`**: AI/agent framework integrations.
+  - Adapters that plug into higher-level frameworks via their official extension points (e.g., LangChain callbacks).
+  - Work at the level of chains, tools, agents, and workflows rather than raw HTTP or SDK calls.
+
 ---
 
 ## 🤝 Contributing

{traccia-0.1.5.dist-info → traccia-0.1.6.dist-info}/RECORD

@@ -1,11 +1,11 @@
 traccia/__init__.py,sha256=O2Hs3GFVcFsmeBlJwJhqPvFH9kB-pAJarEfB9G4xLZU,1998
-traccia/auto.py,sha256=S-T6edev59c3HEgAU9ENQjOtL2duUJdjJzlBk6hGek0,25792
+traccia/auto.py,sha256=zr4zTMIPEn7epm1KO8APzpdzuaYroeW_ZKB8L41AFXk,26302
 traccia/auto_instrumentation.py,sha256=e2Gzt2AtGSXbv6BSZpAApAtMcTlEwc08dgZgQMfrREU,2107
 traccia/cli.py,sha256=lQJU-dAxxcWyOew7OCBi2u7RbMXcwOxtLyfzFwlZ4f0,12362
-traccia/config.py,sha256=BCj_N_zkuRlfPMsuTO-LpcZDQdKQjJ6QHxAIWfCg0HI,24527
+traccia/config.py,sha256=BByH9VOjjXKHLeJlWXXEA2Vlq3k9AqriNggdrlUrff0,24798
 traccia/errors.py,sha256=CMIS01M3pnr3oRhtzQkyKYkDgYkJNlGd6D9Zg2AohA0,1158
 traccia/pricing_config.py,sha256=ZTccshJbAySWJw9Rdvpj2SMaHkEio325t8NkfJfNzfY,1732
-traccia/runtime_config.py,sha256=LjeKCPYKkbZiI38ih4OX4XMkW72hA29Or0hso4W63-M,2157
+traccia/runtime_config.py,sha256=c6Cto1pQjKy4Jb6pSClQrgzQRv8flZrePNpK1wxbx3s,2735
 traccia/context/__init__.py,sha256=_tNDOoVZ3GgbYtw9I3F8YSKuPovQBa0orjtd7CtfI1w,738
 traccia/context/context.py,sha256=hBvsrYV_-2cHCC7jTH5iGKHzxZRGpMH2vc0oTW2cqAY,1967
 traccia/context/propagators.py,sha256=Tq3O-JYEBqkshrrhGYn-j_2V718gfLiFDaVzsDdVmms,8747
@@ -14,18 +14,20 @@ traccia/exporter/console_exporter.py,sha256=IKR9S_DJbOqB7aRaDHGtl7GlDiV3GLHTh7I9
 traccia/exporter/file_exporter.py,sha256=4TcHvhCs6yGCfU-HKVtA8oKjnlzlSfGiI0TMTdVvdsc,6922
 traccia/exporter/http_exporter.py,sha256=kLcDn0WoFbSc6pAawj_-MNqOASGMEiFKki-Y3FeieKU,8039
 traccia/exporter/otlp_exporter.py,sha256=sy74xOgKyLofG_S9QHTuQo4HB4LaKnVVWKYv1cHRZx0,7692
-traccia/instrumentation/__init__.py,sha256=Eiq9SCD7jucIQZsaWisHLG1-SFhebscMHRDyAN6Qjqk,736
+traccia/instrumentation/__init__.py,sha256=kOs72xJCraJknhDAtbxgiVNUgwI-efAGGFB3tXJsRhI,967
 traccia/instrumentation/anthropic.py,sha256=R4vL1plLHgt0TXkDwt1Priic9HppIp2Oyt11IJZZ9Ug,3444
 traccia/instrumentation/decorator.py,sha256=BTZvtFpNA2MVuNkoMbbZtgVK_c_su1M3V1OIuBoTEl0,10049
 traccia/instrumentation/fastapi.py,sha256=LpenJ5aIrcTTWZb6_6GsQ_6cXrVMDjdfeyfQeGvDUTs,1271
 traccia/instrumentation/http_client.py,sha256=fBZx2RNcMxH73cmTrDjlQVYxerBUKQnw8OANyfak5HE,586
 traccia/instrumentation/http_server.py,sha256=RTMklczBEam8PE-pPVMUWBo8YtU7_ISa6-G0Zqjbptk,913
-traccia/instrumentation/openai.py,sha256=GmupQ96g7Jb_gJZZoQrF3UygNzqiEjAxGhpeaAp-3pY,7087
+traccia/instrumentation/openai.py,sha256=nItQnjpq3GXNfM1VE3DIt2YIHRlg5e495KtvpQjFjFs,14862
 traccia/instrumentation/requests.py,sha256=I7Oc_px9RDtliQ2ktQVymPUc2Zkaz1NdepxWQygMb24,2267
-traccia/integrations/__init__.py,sha256=bbAVvZaqg0FcM9OVchpb_fHRrTQN8lylMiFTsXHa9sM,662
+traccia/integrations/__init__.py,sha256=bkLPf2DyX7c6-_p12aKgdgsM9EOyF2EZ7y2-jNjxDzw,1150
 traccia/integrations/langchain/__init__.py,sha256=98umBkI8DePI4eUJBZtBUgjMsmaUNF2EfMPK2bWH3iM,524
 traccia/integrations/langchain/callback.py,sha256=xwHVMKRa6TduLm2bU4NNuDvK2AySQsmnQWWqA8whYOQ,14771
 traccia/integrations/langchain/utils.py,sha256=TjkEUKprTL2CfkSjVG4jSO0fLk_n3wvTgxv5NN_wHeI,4258
+traccia/integrations/openai_agents/__init__.py,sha256=bFxSf5rvnKzl87Ux8MkFylUYY0vagil3cTTrb0HeNeg,2028
+traccia/integrations/openai_agents/processor.py,sha256=DpwSISq9R3dUiS0so95T7bSCLwcRnG8IcsiXCsRg_fY,10450
 traccia/processors/__init__.py,sha256=-hwG9SXM6JbGJaIol2KnS3aWwr9P_TVbJ4AZtGTe2zY,1192
 traccia/processors/agent_enricher.py,sha256=Ur1QvqXSCWT9RgZQw6s53P6URfGmH0KsC7WRJlCYRew,6434
 traccia/processors/batch_processor.py,sha256=JTZzWQs5jXlIiqI7PqukfrHil3V81ZC4tRsqeGYv_v8,4832
@@ -45,9 +47,9 @@ traccia/tracer/span_context.py,sha256=Y6J5Rr6bu-WG2-K2tyncLyyjdAK74b3fbSpIkLOQor
 traccia/tracer/tracer.py,sha256=oxXJnkR95-UnQeVhdtOOW7q0iAqWf_M9YmvCEcvRhkg,9496
 traccia/utils/__init__.py,sha256=JelSlN-M6Sv8y_MLpYAz_kBUguBnxFSuzvhg4eFIdpg,357
 traccia/utils/helpers.py,sha256=yhihp2Jw2TLTPxffGee5nE8nRcZ5C2aWgyLHKZek3Cc,2107
-traccia-0.1.5.dist-info/licenses/LICENSE,sha256=HNl57LOj88EfKh-IWmeqWxsDRh_FF6lj0l-E2A4Hr8w,10757
-traccia-0.1.5.dist-info/METADATA,sha256=ginDaCSUr7lpnmd2FVuGuTFYSURcVuMrCGee2CNpOhc,19011
-traccia-0.1.5.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
-traccia-0.1.5.dist-info/entry_points.txt,sha256=SG7gacPRmFzLw2HYTblUZsmC_TO3n14-dNi28SL-C2k,45
-traccia-0.1.5.dist-info/top_level.txt,sha256=Kc56JudupqSkzJPOnuQ6mPHJmhtike7pssNX0u_p59w,8
-traccia-0.1.5.dist-info/RECORD,,
+traccia-0.1.6.dist-info/licenses/LICENSE,sha256=HNl57LOj88EfKh-IWmeqWxsDRh_FF6lj0l-E2A4Hr8w,10757
+traccia-0.1.6.dist-info/METADATA,sha256=IJnHGuC2bOBkvx0YdRIpwNWndQOg7x8AgJS2afj1Aj0,20676
+traccia-0.1.6.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+traccia-0.1.6.dist-info/entry_points.txt,sha256=SG7gacPRmFzLw2HYTblUZsmC_TO3n14-dNi28SL-C2k,45
+traccia-0.1.6.dist-info/top_level.txt,sha256=Kc56JudupqSkzJPOnuQ6mPHJmhtike7pssNX0u_p59w,8
+traccia-0.1.6.dist-info/RECORD,,