hivetrace 1.3.3__py3-none-any.whl → 1.3.4__py3-none-any.whl

hivetrace/adapters/__init__.py

@@ -30,3 +30,14 @@ try:
     __all__.extend(["LangChainAdapter", "langchain_trace"])
 except ImportError:
     pass
+
+try:
+    from hivetrace.adapters.openai_agents import (
+        HivetraceOpenAIAgentProcessor as _HivetraceOpenAIAgentProcessor,
+    )
+
+    HivetraceOpenAIAgentProcessor = _HivetraceOpenAIAgentProcessor
+
+    __all__.extend(["HivetraceOpenAIAgentProcessor"])
+except ImportError:
+    pass

hivetrace/adapters/openai_agents/__init__.py

@@ -0,0 +1,3 @@
+from hivetrace.adapters.openai_agents.tracing import HivetraceOpenAIAgentProcessor
+
+__all__ = ["HivetraceOpenAIAgentProcessor"]

hivetrace/adapters/openai_agents/adapter.py

@@ -0,0 +1,129 @@
+import uuid
+
+from hivetrace.adapters.base_adapter import BaseAdapter
+from hivetrace.adapters.openai_agents.models import AgentCall, Call
+
+
+class OpenaiAgentsAdapter(BaseAdapter):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+    def log_traces(self, trace_calls: dict[str, Call | None], conversation_uuid: str):
+        _trace_calls = self._join_handoff_spans(trace_calls)
+        _trace_calls = self._join_agent_calling_tool_spans(_trace_calls)
+        source_agent = _trace_calls[list(_trace_calls.keys())[0]]
+        self._log_start_message(source_agent, conversation_uuid)
+
+        for trace_call in _trace_calls.values():
+            if trace_call is None or trace_call.span_parent_id is None:
+                continue
+
+            parent_agent: AgentCall = _trace_calls[trace_call.span_parent_id]
+            if trace_call.type == "agent":
+                additional_params = {
+                    "agent_conversation_id": conversation_uuid,
+                    "is_final_answer": False,
+                    "agents": {
+                        trace_call.agent_uuid: {
+                            "agent_parent_id": parent_agent.agent_uuid,
+                            "name": trace_call.name,
+                            "description": trace_call.instructions,
+                        },
+                    },
+                }
+                self.output(
+                    message=trace_call.output,
+                    additional_params=additional_params,
+                )
+
+            elif trace_call.type == "tool":
+                self._prepare_and_log(
+                    log_method_name_stem="function_call",
+                    is_async=False,
+                    tool_call_details={
+                        "application_id": self.application_id,
+                        "tool_call_id": str(uuid.uuid4()),
+                        "func_name": trace_call.name,
+                        "func_args": f"{trace_call.input}",
+                        "func_result": f"{trace_call.output}",
+                        "additional_parameters": {
+                            "agent_conversation_id": conversation_uuid,
+                            "agents": {
+                                parent_agent.agent_uuid: {
+                                    "name": parent_agent.name,
+                                    "description": parent_agent.instructions,
+                                },
+                            },
+                        },
+                    },
+                )
+        self._log_final_message(source_agent, conversation_uuid)
+
+    def _join_agent_calling_tool_spans(
+        self, trace_calls: dict[str, Call | None]
+    ) -> dict[str, Call | None]:
+        for span_id, span in trace_calls.items():
+            if span.type == "agent" and span.span_parent_id is not None:
+                parent = trace_calls[span.span_parent_id]
+                if parent.type == "tool":
+                    trace_calls[span.span_parent_id] = None
+                    trace_calls[span_id].span_parent_id = parent.span_parent_id
+                    trace_calls[span_id].input = (
+                        parent.input if span.input is None else span.input
+                    )
+                    trace_calls[span_id].output = (
+                        parent.output if span.output is None else span.output
+                    )
+        return trace_calls
+
+    def _join_handoff_spans(
+        self, trace_calls: dict[str, Call | None]
+    ) -> dict[str, Call | None]:
+        for span in reversed(trace_calls.values()):
+            if span.type == "handoff" and span.span_parent_id is not None:
+                parent = trace_calls[span.span_parent_id]
+                child = next(
+                    (
+                        call
+                        for call in trace_calls.values()
+                        if call.name == span.to_agent
+                    ),
+                    None,
+                )
+                if parent is None:
+                    continue
+                child.span_parent_id = span.span_parent_id
+                if parent.output is None:
+                    parent.output = child.output
+                if parent.input is None:
+                    parent.input = child.input
+        return trace_calls
+
+    def _log_start_message(self, trace_call: AgentCall, conversation_uuid: str):
+        self.input(
+            message=trace_call.input,
+            additional_params={
+                "agent_conversation_id": conversation_uuid,
+                "agents": {
+                    trace_call.agent_uuid: {
+                        "name": trace_call.name,
+                        "description": trace_call.instructions,
+                    },
+                },
+            },
+        )
+
+    def _log_final_message(self, trace_call: AgentCall, conversation_uuid: str):
+        self.output(
+            message=trace_call.output,
+            additional_params={
+                "agent_conversation_id": conversation_uuid,
+                "is_final_answer": True,
+                "agents": {
+                    trace_call.agent_uuid: {
+                        "name": trace_call.name,
+                        "description": trace_call.instructions,
+                    },
+                },
+            },
+        )

hivetrace/adapters/openai_agents/models.py

@@ -0,0 +1,68 @@
+"""
+Models for OpenAI Agents hivetrace adapter.
+"""
+
+from dataclasses import dataclass
+from typing import Literal, Optional
+
+from hivetrace.utils.uuid_generator import generate_agent_uuid
+
+
+@dataclass
+class Call:
+    """
+    Base class for all calls.
+    """
+
+    span_parent_id: Optional[str] = None
+    type: Literal["agent", "tool", "handoff"] = "agent"
+    name: str = ""
+    input: Optional[str] = None
+    output: Optional[str] = None
+    instructions: Optional[str] = None
+    from_agent: Optional[str] = None
+    to_agent: Optional[str] = None
+
+    def to_dict(self):
+        return {
+            "span_parent_id": self.span_parent_id,
+            "type": self.type,
+            "name": self.name,
+            "input": self.input,
+            "output": self.output,
+            "instructions": self.instructions,
+            "from_agent": self.from_agent,
+            "to_agent": self.to_agent,
+        }
+
+
+@dataclass
+class AgentCall(Call):
+    """
+    Call for an agent.
+    """
+
+    type: Literal["agent"] = "agent"
+
+    @property
+    def agent_uuid(self) -> str:
+        return generate_agent_uuid(self.name)
+
+
+@dataclass
+class ToolCall(Call):
+    """
+    Call for a tool.
+    """
+
+    type: Literal["tool"] = "tool"
+
+
+@dataclass
+class HandoffCall(Call):
+    """
+    Call for a handoff.
+    """
+
+    type: Literal["handoff"] = "handoff"
+    name: str = "handoff_call"

hivetrace/adapters/openai_agents/tracing.py

@@ -0,0 +1,149 @@
+"""
+Tracing processor for OpenAI Agents.
+"""
+
+import os
+
+from agents.tracing import TracingProcessor
+from agents.tracing.span_data import (
+    AgentSpanData,
+    FunctionSpanData,
+    HandoffSpanData,
+    ResponseSpanData,
+)
+from agents.tracing.spans import Span
+from agents.tracing.traces import Trace
+from openai.types.responses import ResponseFunctionToolCall, ResponseOutputMessage
+
+from hivetrace import HivetraceSDK
+from hivetrace.adapters.openai_agents.adapter import OpenaiAgentsAdapter
+from hivetrace.adapters.openai_agents.models import (
+    AgentCall,
+    Call,
+    HandoffCall,
+    ToolCall,
+)
+from hivetrace.utils.uuid_generator import generate_uuid
+
+
+class HivetraceOpenAIAgentProcessor(TracingProcessor):
+    """
+    Tracing processor for OpenAI Agents.
+
+    This class is responsible for tracing the execution of OpenAI Agents.
+    It is used to log the traces of the agents and tools.
+
+    Attributes:
+        conversation_uuid: str
+            The UUID of the conversation.
+
+        adapter: OpenaiAgentsAdapter
+            The adapter for the OpenAI Agents.
+
+        _trace_calls: dict[str, Call | None]
+            The trace calls.
+    """
+
+    conversation_uuid: str = ""
+
+    def __init__(
+        self,
+        hivetrace_instance: HivetraceSDK | None = None,
+        application_id: str | None = os.getenv("HIVETRACE_APPLICATION_ID"),
+    ):
+        if not application_id:
+            raise ValueError("HIVETRACE_APPLICATION_ID is not set")
+
+        if not hivetrace_instance:
+            hivetrace_instance = HivetraceSDK(
+                config={
+                    "HIVETRACE_URL": os.getenv("HIVETRACE_URL"),
+                    "HIVETRACE_ACCESS_TOKEN": os.getenv("HIVETRACE_ACCESS_TOKEN"),
+                },
+                async_mode=False,
+            )
+        self.adapter = OpenaiAgentsAdapter(
+            hivetrace=hivetrace_instance,
+            application_id=application_id,
+        )
+        self._trace_calls: dict[str, Call | None] = {}
+
+    def on_trace_start(self, trace: Trace):
+        metadata = trace.metadata or {}
+        self.adapter.user_id = metadata.get("user_id", generate_uuid())
+        self.adapter.session_id = metadata.get("session_id", generate_uuid())
+        self.conversation_uuid = generate_uuid()
+
+    def on_trace_end(self, _: Trace):
+        self.adapter.log_traces(self._trace_calls, self.conversation_uuid)
+
+    def on_span_start(self, span: Span):
+        if span.span_id not in self._trace_calls:
+            # Save start of agent call
+            if (
+                isinstance(span.span_data, AgentSpanData)
+                and span.span_data.type == "agent"
+            ):
+                self._trace_calls[span.span_id] = AgentCall(
+                    span_parent_id=span.parent_id,
+                    name=getattr(span.span_data, "name", "Unknown"),
+                )
+
+            # Save start of tool call
+            elif (
+                isinstance(span.span_data, FunctionSpanData)
+                and span.span_data.type == "function"
+            ):
+                self._trace_calls[span.span_id] = ToolCall(
+                    span_parent_id=span.parent_id,
+                    name=getattr(span.span_data, "name", "Unknown"),
+                )
+
+    def on_span_end(self, span: Span):
+        # Save end of handoff call
+        if (
+            isinstance(span.span_data, HandoffSpanData)
+            and span.span_data.type == "handoff"
+        ):
+            if (
+                span.span_data.from_agent is not None
+                and span.span_data.to_agent is not None
+            ):
+                self._trace_calls[span.span_id] = HandoffCall(
+                    span_parent_id=span.parent_id,
+                    from_agent=span.span_data.from_agent,
+                    to_agent=span.span_data.to_agent,
+                )
+
+        # Save input and output for tool
+        if (
+            isinstance(span.span_data, FunctionSpanData)
+            and span.span_data.type == "function"
+        ):
+            self._trace_calls[span.span_id].input = span.span_data.input
+            self._trace_calls[span.span_id].output = span.span_data.output
+
+        # Save input and output for agent
+        elif (
+            isinstance(span.span_data, ResponseSpanData)
+            and span.span_data.type == "response"
+        ):
+            response = span.span_data.response
+            if not response or not response.output:
+                return
+            if isinstance(response.output[0], ResponseOutputMessage):
+                self._trace_calls[span.parent_id].input = span.span_data.input[0][
+                    "content"
+                ]
+                self._trace_calls[span.parent_id].output = (
+                    response.output[0].content[0].text
+                )
+                self._trace_calls[span.parent_id].instructions = response.instructions
+            elif isinstance(response.output[0], ResponseFunctionToolCall):
+                self._trace_calls[span.parent_id].instructions = response.instructions
+
+    def shutdown(self):
+        self._trace_calls = {}
+
+    def force_flush(self):
+        self._trace_calls = {}

hivetrace/utils/uuid_generator.py

@@ -13,3 +13,16 @@ def generate_uuid() -> str:
     - A newly generated UUID as a string
     """
     return str(uuid.uuid4())
+
+
+def generate_agent_uuid(agent_name: str) -> str:
+    """
+    Generate a UUID for an agent from its name.
+
+    Parameters:
+    - agent_name: The name of the agent
+
+    Returns:
+    - A UUID for the agent as a string
+    """
+    return str(uuid.uuid3(uuid.NAMESPACE_DNS, agent_name))

{hivetrace-1.3.3.dist-info → hivetrace-1.3.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: hivetrace
-Version: 1.3.3
+Version: 1.3.4
 Summary: Hivetrace SDK for monitoring LLM applications
 Home-page: http://hivetrace.ai
 Author: Raft
@@ -19,6 +19,7 @@ Requires-Dist: langchain-community ==0.3.18 ; extra == 'all'
 Requires-Dist: langchain-openai ==0.2.5 ; extra == 'all'
 Requires-Dist: langchain ==0.3.19 ; extra == 'all'
 Requires-Dist: langchain-experimental ==0.3.4 ; extra == 'all'
+Requires-Dist: openai-agents >=0.1.0 ; extra == 'all'
 Requires-Dist: python-dotenv >=1.0.1 ; extra == 'all'
 Provides-Extra: base
 Requires-Dist: httpx >=0.28.1 ; extra == 'base'
@@ -30,6 +31,8 @@ Requires-Dist: langchain-community ==0.3.18 ; extra == 'langchain'
 Requires-Dist: langchain-openai ==0.2.5 ; extra == 'langchain'
 Requires-Dist: langchain ==0.3.19 ; extra == 'langchain'
 Requires-Dist: langchain-experimental ==0.3.4 ; extra == 'langchain'
+Provides-Extra: openai_agents
+Requires-Dist: openai-agents >=0.1.0 ; extra == 'openai_agents'
 
 # Hivetrace SDK
 
@@ -735,3 +738,113 @@ HIVETRACE_APP_ID=your-application-id
 
 ## License
 This project is licensed under the Apache License 2.0.
+
+# OpenAI Agents Integration
+
+## Overview
+
+HiveTrace SDK provides seamless integration with the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/) for monitoring agent interactions, tool usage, handoffs, and task executions in your OpenAI Agents-based applications.
+
+## Quick Start
+
+### Prerequisites
+
+- HiveTrace SDK installed: `pip install hivetrace[openai_agents]`
+- OpenAI Agents SDK installed: `pip install openai-agents`
+- Valid HiveTrace application ID and access token
+
+### Basic Setup
+
+**Step 1: Initialize the SDK (optional)**
+
+```python
+from hivetrace import HivetraceSDK
+from hivetrace.adapters.openai_agents import HivetraceOpenAIAgentProcessor
+
+# Initialize SDK
+hivetrace = HivetraceSDK(
+    config={
+        "HIVETRACE_URL": "https://your-hivetrace-instance.com",
+        "HIVETRACE_ACCESS_TOKEN": "your-access-token",
+    },
+    async_mode=False,
+)
+```
+
+**Step 2: Set Up the Tracing Processor**
+
+The `HivetraceOpenAIAgentProcessor` hooks into the OpenAI Agents SDK tracing system and automatically logs all agent and tool activity to HiveTrace.
+
+```python
+from agents import Agent, Runner, function_tool, set_trace_processors
+from hivetrace.adapters.openai_agents import HivetraceOpenAIAgentProcessor
+
+
+set_trace_processors(
+    HivetraceOpenAIAgentProcessor(
+        hivetrace_instance=hivetrace,
+        application_id="your-hivetrace-app-id",
+    )
+)
+```
+
+or setup environment variables HIVETRACE_URL, HIVETRACE_ACCESS_TOKEN, HIVETRACE_APPLICATION_ID for easier configuration:
+
+```python
+from agents import Agent, Runner, function_tool, set_trace_processors
+from hivetrace.adapters.openai_agents import HivetraceOpenAIAgentProcessor
+
+
+set_trace_processors([HivetraceOpenAIAgentProcessor()])
+```
+
+**Step 3: Call your agents**
+
+
+```python
+from agents.tracing.create import trace
+
+# Define your agent and tools as usual
+@function_tool
+def get_weather(city: str):
+    return f"The weather in {city} is sunny."
+
+agent = Agent(
+    name="WeatherAgent",
+    instructions="You provide weather updates.",
+    tools=[get_weather],
+)
+
+# Run the agent
+import asyncio
+async def main():
+    with trace(
+        workflow_name="Agent workflow",
+        metadata={
+            "session_id": "your-session-id",
+            "user_id": "your-user-id",
+        },
+    ):
+        result = await Runner.run(agent, "What's the weather in Paris?")
+        print(result.final_output)
+
+asyncio.run(main())
+```
+
+## Environment Variables
+
+Set up your environment variables for easier configuration:
+
+```bash
+# .env file
+HIVETRACE_URL=https://your-hivetrace-instance.com
+HIVETRACE_ACCESS_TOKEN=your-access-token
+HIVETRACE_APP_ID=your-application-id
+```
+
+---
+
+## Advanced Usage
+
+
+You now have complete monitoring of your OpenAI Agents system integrated with HiveTrace!

{hivetrace-1.3.3.dist-info → hivetrace-1.3.4.dist-info}/RECORD

@@ -1,7 +1,7 @@
 hivetrace/__init__.py,sha256=lA2xegZE0gBleteGHVY6YfbByLQMhsKBJhKhEvxozzo,896
 hivetrace/crewai_adapter.py,sha256=NeMH37GaUUZFEfpRQnrpbM8HhS1FgfU4I6SSXtqU19s,215
 hivetrace/hivetrace.py,sha256=iJOkHJudejopmt0rnFsPBVivylXBcnHSEvkItrpqLMA,9126
-hivetrace/adapters/__init__.py,sha256=wDHiTLMmLeEn5ZTsQYT7106KszYH5iRU2qUC8UEXAz8,745
+hivetrace/adapters/__init__.py,sha256=lWWh3KWDghlAz8H9U8TOGaoRv76QQyKg46zvkuVWG7Y,1033
 hivetrace/adapters/base_adapter.py,sha256=zN2HV3Kb8d5DS_Jua76iwIEkK05ot4y7nScmoSwvaG0,5400
 hivetrace/adapters/crewai/__init__.py,sha256=cHxroLbjZAH5HX763SEc4cRZrfJGQ6XjETJRx6LFjWY,239
 hivetrace/adapters/crewai/adapter.py,sha256=K_29a71KRWysplA6J3r-Z5CPM-kOVdOhHbNleFuHpao,17879
@@ -15,12 +15,16 @@ hivetrace/adapters/langchain/behavior_tracker.py,sha256=ETNQjoIDtk3Cde5DiOfMln_C
 hivetrace/adapters/langchain/callback.py,sha256=LJXzJDwAECOQIlZqkVvSCn1KzBjUVSQpzA5iJ9lH1z0,19730
 hivetrace/adapters/langchain/decorators.py,sha256=yocDjsDup8omiMYFX2Dx8mws45bTKsMGhF6-nuDwmfk,3193
 hivetrace/adapters/langchain/models.py,sha256=Pk4cQRrdSu9q8Mp49dU6oeUIesw1f1gG5rt1R9HjLMo,1435
+hivetrace/adapters/openai_agents/__init__.py,sha256=T-SEEfPEYQpWljoK6D5g3UPFJXBPs8wSQYITrh-32jQ,128
+hivetrace/adapters/openai_agents/adapter.py,sha256=tpgNnXU0Gr7Iu022CpjJ5Tear94etImh9vN_AaViCXE,5317
+hivetrace/adapters/openai_agents/models.py,sha256=THbpcD-J6BnMVZ4vYzymzmr-iezAV2crCr-Sd8wdWzw,1379
+hivetrace/adapters/openai_agents/tracing.py,sha256=W35siEaZTmzH3R3dufs0hNTlNWe5EPynxRmu3TXZm5M,5146
 hivetrace/adapters/utils/__init__.py,sha256=AkdJzecQlhT3hHFOIO5zWbAIEXvbgH_5vmzlPViedt0,142
 hivetrace/adapters/utils/logging.py,sha256=UxCMFvlpP6vJfzRwMYhhJIi7RTWdgVK2sWtCeEB67_w,1126
 hivetrace/utils/__init__.py,sha256=DxWV8tC4i5w4bMrvVuUM53_i7qHkfcduOAZF6nH6s7w,127
-hivetrace/utils/uuid_generator.py,sha256=ti9z7ZXegBLywI1fW_NtVZckeDwgf9qFDM_3k71dGCg,225
-hivetrace-1.3.3.dist-info/LICENSE,sha256=8d3g3prbWPDLQ5AV0dtyWfYTj5QPl8MJ_wlr2l8pjEU,11333
-hivetrace-1.3.3.dist-info/METADATA,sha256=NgfrjXwNWTyH5n2Lt56LEqvjeoTyc4saZUxtzf23Lm4,18343
-hivetrace-1.3.3.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-hivetrace-1.3.3.dist-info/top_level.txt,sha256=F6mZCzZ5CSftMc-M0NeOYWbwyTzjybR72P4qSBMyZZM,10
-hivetrace-1.3.3.dist-info/RECORD,,
+hivetrace/utils/uuid_generator.py,sha256=69yokLJxDYqHt0BQsgtPoyhqARnItAYvw4UDqtgCFok,509
+hivetrace-1.3.4.dist-info/LICENSE,sha256=8d3g3prbWPDLQ5AV0dtyWfYTj5QPl8MJ_wlr2l8pjEU,11333
+hivetrace-1.3.4.dist-info/METADATA,sha256=8tm6hPahNxBXPi6xK6aPz1U6GicGL5h1_EtOm0J_60o,21265
+hivetrace-1.3.4.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
+hivetrace-1.3.4.dist-info/top_level.txt,sha256=F6mZCzZ5CSftMc-M0NeOYWbwyTzjybR72P4qSBMyZZM,10
+hivetrace-1.3.4.dist-info/RECORD,,