agentmetrics-openai-agents 0.2.0__tar.gz

agentmetrics_openai_agents-0.2.0/.gitignore

@@ -0,0 +1,62 @@
+# Generated — dashboard SPA copied here during server build
+api/app/static/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.venv/
+.env
+*.egg-info/
+dist/
+build/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Node / JS
+node_modules/
+.next/
+.turbo/
+dist/
+build/
+*.tsbuildinfo
+.pnpm-store/
+
+# Env files
+.env
+.env.local
+.env.production
+.env.*.local
+api/.env.local
+dashboard/.env.local
+
+# Build artifacts inside packages
+packages/python/dist/
+packages/python/*.egg-info/
+packages/js/dist/
+packages/js/node_modules/
+
+# Internal docs — never public
+.internal/
+PLAN.md
+CODE.md
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# Docker
+*.log
+.internal
+
+# Local data (SQLite DB when running without Docker)
+data/

agentmetrics_openai_agents-0.2.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: agentmetrics-openai-agents
+Version: 0.2.0
+Summary: AgentMetrics observability integration for OpenAI Agents SDK
+Project-URL: Homepage, https://github.com/andalabx/agentmetrics
+Project-URL: Repository, https://github.com/andalabx/agentmetrics
+License: MIT
+Keywords: agentmetrics,ai-agents,observability,openai,openai-agents
+Requires-Python: >=3.10
+Requires-Dist: agentmetrics-shared>=0.2.0
+Requires-Dist: agentmetrics>=0.2.0
+Requires-Dist: openai-agents>=0.0.5
+Description-Content-Type: text/markdown
+
+# agentmetrics-openai-agents
+
+[![PyPI](https://img.shields.io/pypi/v/agentmetrics-openai-agents?color=6366f1&label=pypi&logo=python&logoColor=white)](https://pypi.org/project/agentmetrics-openai-agents)
+[![License: MIT](https://img.shields.io/badge/license-MIT-6366f1)](../../LICENSE)
+
+AgentMetrics integration for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/). Register one trace processor at startup and every agent run reports back to your dashboard showing latency, cost, token counts, tool calls, and errors, with zero changes to your agent code.
+
+---
+
+## Install
+
+```bash
+pip install agentmetrics-openai-agents
+```
+
+---
+
+## Quickstart
+
+```python
+from agents.tracing import add_trace_processor
+from agentmetrics_openai_agents import AgentMetricsProcessor
+
+# register once at startup, covers all agents in the process
+add_trace_processor(AgentMetricsProcessor(
+    agent_id="my-openai-agent",
+    base_url="http://localhost:8099",
+))
+
+# Run your agents as normal
+result = await Runner.run(my_agent, "Summarize this document")
+```
+
+---
+
+## API
+
+### `AgentMetricsProcessor(agent_id, base_url)`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `agent_id` | `"openai-agent"` | Fallback label if the trace has no `name` attribute |
+| `base_url` | `"http://localhost:8099"` | AgentMetrics server address |
+
+Implements `TracingProcessor` from `agents.tracing`. Pass to `add_trace_processor()` before running any agents.
+
+### `.force_flush()`
+
+Blocks until all in-flight HTTP requests complete.
+
+### `.shutdown()`
+
+Calls `force_flush()`. Called automatically when the process exits cleanly.
+
+---
+
+## What gets tracked
+
+Each agent trace emits one event to `/v1/events` when `on_trace_end` fires:
+
+| Field | Description |
+|---|---|
+| `status` | `success` or `failed` |
+| `duration_ms` | Wall-clock trace duration |
+| `input_tokens` / `output_tokens` | Aggregated from all `LLMSpanData` spans |
+| `cache_read_tokens` / `cache_write_tokens` | Cache token counts |
+| `llm_calls` | Number of LLM spans in the trace |
+| `tool_calls` / `tool_errors` | Counts from `FunctionSpanData` spans |
+| `tool_names` | Set of function/tool names |
+| `model` | Model name from the first LLM span output |
+| `estimated_cost_usd` | Computed from token counts and model pricing |
+| `error` | First 500 chars of the trace error on failure |
+
+---
+
+## License
+
+[MIT](../../LICENSE)

agentmetrics_openai_agents-0.2.0/README.md

@@ -0,0 +1,78 @@
+# agentmetrics-openai-agents
+
+[![PyPI](https://img.shields.io/pypi/v/agentmetrics-openai-agents?color=6366f1&label=pypi&logo=python&logoColor=white)](https://pypi.org/project/agentmetrics-openai-agents)
+[![License: MIT](https://img.shields.io/badge/license-MIT-6366f1)](../../LICENSE)
+
+AgentMetrics integration for the [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/). Register one trace processor at startup and every agent run reports back to your dashboard showing latency, cost, token counts, tool calls, and errors, with zero changes to your agent code.
+
+---
+
+## Install
+
+```bash
+pip install agentmetrics-openai-agents
+```
+
+---
+
+## Quickstart
+
+```python
+from agents.tracing import add_trace_processor
+from agentmetrics_openai_agents import AgentMetricsProcessor
+
+# register once at startup, covers all agents in the process
+add_trace_processor(AgentMetricsProcessor(
+    agent_id="my-openai-agent",
+    base_url="http://localhost:8099",
+))
+
+# Run your agents as normal
+result = await Runner.run(my_agent, "Summarize this document")
+```
+
+---
+
+## API
+
+### `AgentMetricsProcessor(agent_id, base_url)`
+
+| Parameter | Default | Description |
+|---|---|---|
+| `agent_id` | `"openai-agent"` | Fallback label if the trace has no `name` attribute |
+| `base_url` | `"http://localhost:8099"` | AgentMetrics server address |
+
+Implements `TracingProcessor` from `agents.tracing`. Pass to `add_trace_processor()` before running any agents.
+
+### `.force_flush()`
+
+Blocks until all in-flight HTTP requests complete.
+
+### `.shutdown()`
+
+Calls `force_flush()`. Called automatically when the process exits cleanly.
+
+---
+
+## What gets tracked
+
+Each agent trace emits one event to `/v1/events` when `on_trace_end` fires:
+
+| Field | Description |
+|---|---|
+| `status` | `success` or `failed` |
+| `duration_ms` | Wall-clock trace duration |
+| `input_tokens` / `output_tokens` | Aggregated from all `LLMSpanData` spans |
+| `cache_read_tokens` / `cache_write_tokens` | Cache token counts |
+| `llm_calls` | Number of LLM spans in the trace |
+| `tool_calls` / `tool_errors` | Counts from `FunctionSpanData` spans |
+| `tool_names` | Set of function/tool names |
+| `model` | Model name from the first LLM span output |
+| `estimated_cost_usd` | Computed from token counts and model pricing |
+| `error` | First 500 chars of the trace error on failure |
+
+---
+
+## License
+
+[MIT](../../LICENSE)

agentmetrics_openai_agents-0.2.0/agentmetrics_openai_agents/__init__.py

@@ -0,0 +1,27 @@
+from agentmetrics_openai_agents.processor import AgentMetricsProcessor
+
+
+def instrument(
+    api_key: str,
+    agent_id: str = "openai-agent",
+    base_url: str = "http://localhost:8099",
+) -> AgentMetricsProcessor:
+    """
+    Register AgentMetrics as a tracing processor for all OpenAI Agents SDK runs.
+
+    Usage::
+
+        from agentmetrics_openai_agents import instrument
+
+        instrument(api_key="am_...")
+        # All agent runs are now tracked automatically.
+    """
+    from agents.tracing import add_trace_processor
+
+    processor = AgentMetricsProcessor(api_key=api_key, agent_id=agent_id, base_url=base_url)
+    add_trace_processor(processor)
+    return processor
+
+
+__version__ = "0.1.0"
+__all__ = ["AgentMetricsProcessor", "instrument"]

agentmetrics_openai_agents-0.2.0/agentmetrics_openai_agents/processor.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from agentmetrics.http_client import HttpClient
+from agentmetrics_shared import AgentEndEvent, estimate_cost
+from agents.tracing import Span, Trace, TracingProcessor
+from agents.tracing.spans import (
+    AgentSpanData,
+    FunctionSpanData,
+    HandoffSpanData,
+    LLMSpanData,
+)
+
+logger = logging.getLogger(__name__)
+
+# INT-22: singleton guard — register the processor only once per process
+_PROCESSOR_REGISTERED = False
+_PROCESSOR_LOCK = __import__("threading").Lock()
+
+
+# INT-20: helper to try both known cache token attribute names
+def _get_cached_tokens(details: Any) -> int:
+    """Return cached token count, trying both known attribute/key names."""
+    if details is None:
+        return 0
+    if isinstance(details, dict):
+        return (
+            details.get("cached_tokens")
+            or details.get("cached_input_tokens")
+            or 0
+        )
+    return (
+        getattr(details, "cached_tokens", None)
+        or getattr(details, "cached_input_tokens", None)
+        or 0
+    )
+
+
+class _TraceState:
+    __slots__ = (
+        "agent_id",
+        "cache_read_tokens",
+        "cache_write_tokens",
+        "error",
+        "input_tokens",
+        "llm_calls",
+        "model",
+        "output_tokens",
+        "start_ms",
+        "status",
+        "tool_calls",
+        "tool_errors",
+        "tool_names",
+    )
+
+    def __init__(self, agent_id: str) -> None:
+        self.agent_id  = agent_id
+        self.start_ms  = time.monotonic()
+        self.input_tokens     = 0
+        self.output_tokens    = 0
+        self.cache_read_tokens  = 0
+        self.cache_write_tokens = 0
+        self.llm_calls   = 0
+        self.tool_calls  = 0
+        self.tool_errors = 0
+        self.tool_names: set[str] = set()
+        self.model: str | None = None
+        self.status = "success"
+        self.error: str | None = None
+
+
+class AgentMetricsProcessor(TracingProcessor):
+    """
+    OpenAI Agents SDK tracing processor that sends run summaries to AgentMetrics.
+
+    Add once globally - covers all agents in the process.
+
+    Usage::
+
+        from agents.tracing import add_trace_processor
+        from agentmetrics_openai_agents import AgentMetricsProcessor
+
+        add_trace_processor(AgentMetricsProcessor(api_key="am_..."))
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        agent_id: str = "openai-agent",
+        base_url: str = "http://localhost:8099",
+    ) -> None:
+        self._client   = HttpClient(api_key=api_key, base_url=base_url)
+        self._agent_id = agent_id
+        # trace_id (str) → _TraceState
+        self._traces: dict[str, _TraceState] = {}
+
+
+    def on_trace_start(self, trace: Trace) -> None:
+        agent_name = getattr(trace, "name", None) or self._agent_id
+        self._traces[trace.trace_id] = _TraceState(agent_name)
+
+    def on_trace_end(self, trace: Trace) -> None:
+        state = self._traces.pop(trace.trace_id, None)
+        if state is None:
+            return
+        if getattr(trace, "error", None):
+            state.status = "failed"
+            state.error  = str(trace.error)[:500]
+        self._emit(state, trace.trace_id)
+
+
+    def on_span_start(self, span: Span[Any]) -> None:
+        pass
+
+    def on_span_end(self, span: Span[Any]) -> None:
+        state = self._traces.get(span.trace_id)
+        if state is None:
+            return
+
+        data = span.span_data
+
+        if isinstance(data, LLMSpanData):
+            state.llm_calls += 1
+            usage = getattr(data, "usage", None) or {}
+            if hasattr(usage, "input_tokens"):
+                state.input_tokens  += getattr(usage, "input_tokens", 0) or 0
+                state.output_tokens += getattr(usage, "output_tokens", 0) or 0
+                # INT-20: use helper to try both cached_tokens and cached_input_tokens
+                details = getattr(usage, "input_tokens_details", None) or {}
+                state.cache_read_tokens += _get_cached_tokens(details)
+            elif isinstance(usage, dict):
+                state.input_tokens  += usage.get("input_tokens", 0) or usage.get("prompt_tokens", 0) or 0
+                state.output_tokens += usage.get("output_tokens", 0) or usage.get("completion_tokens", 0) or 0
+                # INT-20: also check dict path for cached tokens
+                details = usage.get("input_tokens_details") or {}
+                state.cache_read_tokens += _get_cached_tokens(details)
+            if not state.model:
+                resp = getattr(data, "output", None)
+                if resp:
+                    state.model = getattr(resp, "model", None)
+
+        elif isinstance(data, FunctionSpanData):
+            state.tool_calls += 1
+            name = getattr(data, "name", None)
+            if name:
+                state.tool_names.add(name)
+            if getattr(span, "error", None):
+                state.tool_errors += 1
+
+        elif isinstance(data, HandoffSpanData):
+            state.tool_calls += 1
+
+        elif isinstance(data, AgentSpanData):
+            # agent-level errors bubble up to trace; nothing extra here
+            pass
+
+
+    def force_flush(self) -> None:
+        self._client.flush(timeout=10.0)
+
+    def shutdown(self) -> None:
+        self.force_flush()
+
+
+    def _emit(self, state: _TraceState, trace_id: str) -> None:
+        duration_ms = (time.monotonic() - state.start_ms) * 1000
+        ev = AgentEndEvent(agent_id=state.agent_id, platform="openai-agents")
+        ev.trace_id           = trace_id
+        ev.input_tokens       = state.input_tokens
+        ev.output_tokens      = state.output_tokens
+        ev.cache_read_tokens  = state.cache_read_tokens
+        ev.cache_write_tokens = state.cache_write_tokens
+        ev.llm_calls          = state.llm_calls
+        ev.tool_calls         = state.tool_calls
+        ev.tool_errors        = state.tool_errors
+        ev.tool_names         = list(state.tool_names)
+        ev.status             = state.status
+        ev.duration_ms        = round(duration_ms, 2)
+        ev.error              = state.error
+        ev.model              = state.model
+        ev.estimated_cost_usd = estimate_cost(
+            state.model or "", state.input_tokens, state.output_tokens,
+            state.cache_read_tokens, state.cache_write_tokens,
+        ) or None
+        self._client.fire_and_forget(ev.to_payload())
+
+
+def register(
+    api_key: str,
+    agent_id: str = "openai-agent",
+    base_url: str = "http://localhost:8099",
+) -> None:
+    """
+    INT-22: Register the AgentMetrics processor with a singleton guard so it is
+    added at most once per process, even if called multiple times.
+    """
+    global _PROCESSOR_REGISTERED
+    with _PROCESSOR_LOCK:
+        if _PROCESSOR_REGISTERED:
+            logger.debug(
+                "agentmetrics: OpenAI Agents processor already registered, skipping"
+            )
+            return
+        try:
+            from agents import add_trace_processor
+            add_trace_processor(AgentMetricsProcessor(
+                api_key=api_key, agent_id=agent_id, base_url=base_url
+            ))
+            _PROCESSOR_REGISTERED = True
+        except (ImportError, AttributeError) as exc:
+            logger.debug(
+                "agentmetrics: could not register OpenAI Agents processor: %s", exc
+            )

agentmetrics_openai_agents-0.2.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agentmetrics-openai-agents"
+version = "0.2.0"
+description = "AgentMetrics observability integration for OpenAI Agents SDK"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+keywords = ["openai", "openai-agents", "agentmetrics", "observability", "ai-agents"]
+dependencies = [
+    "agentmetrics>=0.2.0",
+    "agentmetrics-shared>=0.2.0",
+    "openai-agents>=0.0.5",
+]
+
+[project.urls]
+Homepage = "https://github.com/andalabx/agentmetrics"
+Repository = "https://github.com/andalabx/agentmetrics"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentmetrics_openai_agents"]
+
+[tool.uv.sources]
+agentmetrics = { workspace = true }
+agentmetrics-shared = { workspace = true }