agentx-python 0.4.11__py3-none-any.whl → 0.4.12__py3-none-any.whl

agentx/__init__.py

@@ -2,6 +2,15 @@ import logging
 
 from agentx.agentx import AgentX
 from agentx.version import VERSION
+from agentx.exceptions import (
+    AgentXError,
+    AgentXAuthError,
+    AgentXAPIError,
+    DatasetNotFound,
+    CINotEnabled,
+    CIRunExpired,
+    CIGateFailure,
+)
 
 logging.basicConfig(
     level=logging.INFO,
@@ -9,5 +18,14 @@ logging.basicConfig(
     datefmt="%Y-%m-%d %H:%M:%S %Z",
 )
 
-__all__ = ["AgentX"]
+__all__ = [
+    "AgentX",
+    "AgentXError",
+    "AgentXAuthError",
+    "AgentXAPIError",
+    "DatasetNotFound",
+    "CINotEnabled",
+    "CIRunExpired",
+    "CIGateFailure",
+]
 __version__ = VERSION

agentx/agentx.py

@@ -22,6 +22,8 @@ class AgentX:
 
         from agentx.evaluations.client import EvaluationsClient
         from agentx.evaluations.runner import EvaluationsRunner
+        from agentx.tracing.ingest_client import IngestClient
+        from agentx.tracing.tracer import Tracer
         from agentx.version import VERSION
 
         _eval_client = EvaluationsClient(
@@ -31,6 +33,13 @@ class AgentX:
         )
         self.evaluations = EvaluationsRunner(_eval_client)
 
+        _ingest_client = IngestClient(
+            api_key=self.api_key,
+            sdk_version=VERSION,
+            base_url=self.base_url,
+        )
+        self.tracer = Tracer(_ingest_client)
+
     @classmethod
     def from_env(cls) -> "AgentX":
         """Create an AgentX client using AGENTX_API_KEY (and optionally AGENTX_API_BASE_URL) from the environment."""

agentx/exceptions.py

@@ -0,0 +1,46 @@
+"""AgentX SDK exceptions."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.tracing.ci_types import CIRunResult
+
+
+class AgentXError(Exception):
+    """Base class for all AgentX SDK errors."""
+
+
+class AgentXAuthError(AgentXError):
+    """Invalid or missing API key."""
+
+
+class AgentXAPIError(AgentXError):
+    """Unexpected API error."""
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class DatasetNotFound(AgentXError):
+    """Dataset ID does not exist or is not accessible from this API key."""
+
+
+class CINotEnabled(AgentXError):
+    """Dataset exists but ci.enabled is false. Enable CI in the dataset settings."""
+
+
+class CIRunExpired(AgentXError):
+    """CI run was not finalized within the 2-hour window."""
+
+
+class CIGateFailure(AgentXError):
+    """Gate result is 'fail'. Raised when fail_on_gate=True."""
+
+    def __init__(self, result: "CIRunResult") -> None:
+        super().__init__(
+            f"CI gate failed: {result.pass_rate:.0%} passed "
+            f"({result.passed_questions}/{result.total_questions} questions)"
+        )
+        self.result = result

agentx/integrations/__init__.py

@@ -0,0 +1,7 @@
+# Framework-specific integrations for production tracing.
+# Each sub-module is lazily importable so the core SDK has no extra dependencies.
+#
+#   from agentx.integrations.langchain import AgentXCallbackHandler
+#   from agentx.integrations.crewai import AgentXCrewObserver
+#   from agentx.integrations.openai_agents import AgentXTracingProcessor
+#   from agentx.integrations.anthropic import patch_anthropic_client

agentx/integrations/anthropic.py

@@ -0,0 +1,152 @@
+"""
+Anthropic SDK integration for AgentX production tracing.
+
+Usage::
+
+    from agentx.integrations.anthropic import patch_anthropic_client
+    import anthropic
+
+    client = anthropic.Anthropic()
+    patch_anthropic_client(client, agentx.tracer, name="claude-agent")
+
+    # All subsequent client.messages.create() calls are now traced automatically.
+
+Requires: ``pip install agentx[anthropic]``
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+from agentx.tracing.tracer import Tracer, _safe_serialize
+
+
+def patch_anthropic_client(
+    client: Any,
+    tracer: Tracer,
+    name: str = "anthropic-agent",
+    metadata: Optional[Dict[str, Any]] = None,
+    session_id: Optional[str] = None,
+) -> None:
+    """
+    Monkey-patch ``client.messages.create`` and ``client.messages.stream``
+    (if present) to automatically send a trace for every call.
+
+    The original method is still called and its return value is passed through
+    unchanged so nothing in the caller needs to change.
+    """
+    messages = getattr(client, "messages", None)
+    if messages is None:
+        raise ValueError("Provided client does not have a .messages attribute")
+
+    _patch_create(messages, tracer, name, metadata, session_id)
+
+    # stream is optional (not present in all versions)
+    if hasattr(messages, "stream"):
+        _patch_stream(messages, tracer, name, metadata, session_id)
+
+
+def _patch_create(
+    messages_resource: Any,
+    tracer: Tracer,
+    name: str,
+    metadata: Optional[Dict[str, Any]],
+    session_id: Optional[str],
+) -> None:
+    original = messages_resource.create
+    if getattr(original, "_agentx_patched", False):
+        return  # already patched
+
+    def patched_create(*args, **kwargs):
+        start = time.time()
+        error: Optional[str] = None
+        response = None
+        try:
+            response = original(*args, **kwargs)
+            return response
+        except Exception as exc:
+            error = str(exc)
+            raise
+        finally:
+            latency_ms = int((time.time() - start) * 1000)
+            input_messages = kwargs.get("messages") or (args[0] if args else None)
+            model = kwargs.get("model")
+            output = None
+            if response is not None:
+                try:
+                    output = response.content[0].text if response.content else None
+                except Exception:
+                    output = str(response)[:500]
+            tracer._send(
+                name=name,
+                input=_safe_serialize(input_messages),
+                output=output,
+                latency_ms=latency_ms,
+                error=error,
+                framework="anthropic",
+                model=model,
+                metadata=metadata,
+                session_id=session_id,
+            )
+
+    patched_create._agentx_patched = True
+    messages_resource.create = patched_create
+
+
+def _patch_stream(
+    messages_resource: Any,
+    tracer: Tracer,
+    name: str,
+    metadata: Optional[Dict[str, Any]],
+    session_id: Optional[str],
+) -> None:
+    original_stream = messages_resource.stream
+    if getattr(original_stream, "_agentx_patched", False):
+        return
+
+    def patched_stream(*args, **kwargs):
+        start = time.time()
+        ctx = original_stream(*args, **kwargs)
+
+        class _TracedStream:
+            """Thin wrapper that records timing when the stream context exits."""
+
+            def __enter__(self_inner):
+                return ctx.__enter__()
+
+            def __exit__(self_inner, exc_type, exc_val, tb):
+                result = ctx.__exit__(exc_type, exc_val, tb)
+                latency_ms = int((time.time() - start) * 1000)
+                error = str(exc_val) if exc_val else None
+                output = None
+                try:
+                    final = ctx.get_final_message()
+                    output = final.content[0].text if final.content else None
+                except Exception:
+                    pass
+                tracer._send(
+                    name=name,
+                    input=_safe_serialize(kwargs.get("messages")),
+                    output=output,
+                    latency_ms=latency_ms,
+                    error=error,
+                    framework="anthropic",
+                    model=kwargs.get("model"),
+                    metadata=metadata,
+                    session_id=session_id,
+                )
+                return result
+
+            def __iter__(self_inner):
+                return iter(ctx)
+
+            def __aiter__(self_inner):
+                return aiter(ctx)
+
+            def __getattr__(self_inner, item):
+                return getattr(ctx, item)
+
+        return _TracedStream()
+
+    patched_stream._agentx_patched = True
+    messages_resource.stream = patched_stream

agentx/integrations/crewai.py

@@ -0,0 +1,106 @@
+"""
+CrewAI integration for AgentX production tracing.
+
+Usage::
+
+    from agentx.integrations.crewai import AgentXCrewObserver
+
+    observer = AgentXCrewObserver(agentx.tracer, name="my-crew")
+    result = observer.kickoff(crew, inputs={"topic": "AI"})
+
+Or as a context manager around your own kickoff::
+
+    with observer.observe(name="my-crew", input={"topic": "AI"}) as span:
+        result = crew.kickoff(inputs={"topic": "AI"})
+        span.output = result.raw
+
+Requires: ``pip install agentx[crewai]``
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+from agentx.tracing.tracer import Tracer, _safe_serialize
+
+
+class AgentXCrewObserver:
+    """
+    Wraps a CrewAI ``Crew.kickoff()`` call and sends one trace per execution.
+    Does not require any CrewAI version-specific event system.
+    """
+
+    def __init__(
+        self,
+        tracer: Tracer,
+        name: str = "crewai-crew",
+        metadata: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+    ) -> None:
+        self._tracer = tracer
+        self._name = name
+        self._metadata = metadata
+        self._session_id = session_id
+
+    def kickoff(self, crew: Any, inputs: Optional[Dict[str, Any]] = None) -> Any:
+        """
+        Call ``crew.kickoff(inputs=inputs)``, capture result, and send a trace.
+        Returns the raw CrewAI ``CrewOutput`` object unchanged.
+        """
+        start = time.time()
+        error: Optional[str] = None
+        result = None
+        try:
+            result = crew.kickoff(inputs=inputs or {})
+            return result
+        except Exception as exc:
+            error = str(exc)
+            raise
+        finally:
+            latency_ms = int((time.time() - start) * 1000)
+            output = None
+            if result is not None:
+                output = getattr(result, "raw", None) or _safe_serialize(result)
+
+            # Collect task outputs as tool_calls for observability
+            tool_calls = []
+            if result is not None:
+                task_outputs = getattr(result, "tasks_output", []) or []
+                for task_out in task_outputs:
+                    tool_calls.append(
+                        {
+                            "name": getattr(task_out, "description", "task")[:100],
+                            "output": str(getattr(task_out, "raw", ""))[:500],
+                        }
+                    )
+
+            self._tracer._send(
+                name=self._name,
+                input=_safe_serialize(inputs) if inputs else None,
+                output=output,
+                latency_ms=latency_ms,
+                error=error,
+                framework="crewai",
+                tool_calls=tool_calls or None,
+                metadata=self._metadata,
+                session_id=self._session_id,
+            )
+
+    def observe(
+        self,
+        name: Optional[str] = None,
+        input: Optional[Any] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+    ):
+        """Return a context-manager span for manual kickoff wrapping."""
+        from agentx.tracing.tracer import _TraceSpan
+
+        return _TraceSpan(
+            tracer=self._tracer,
+            name=name or self._name,
+            input=_safe_serialize(input) if input is not None else None,
+            metadata=metadata or self._metadata,
+            framework="crewai",
+            session_id=session_id or self._session_id,
+        )

agentx/integrations/langchain.py

@@ -0,0 +1,249 @@
+"""
+LangChain integration for AgentX production tracing.
+
+Usage::
+
+    from agentx.integrations.langchain import AgentXCallbackHandler
+
+    handler = AgentXCallbackHandler(agentx.tracer, name="my-chain")
+
+    # LCEL chain
+    chain.invoke({"query": q}, config={"callbacks": [handler]})
+
+    # AgentExecutor
+    agent.invoke({"input": q}, config={"callbacks": [handler]})
+
+Requires: ``pip install agentx[langchain]``
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, List, Optional, Union
+from uuid import UUID
+
+from agentx.tracing.tracer import Tracer, _safe_serialize
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+    from langchain_core.outputs import LLMResult
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "langchain-core is required for AgentXCallbackHandler. "
+        "Install it with: pip install agentx[langchain]"
+    ) from exc
+
+
+class AgentXCallbackHandler(BaseCallbackHandler):
+    """
+    LangChain callback handler that captures the top-level chain run and all
+    nested tool calls, then sends one trace per top-level chain invocation.
+    """
+
+    def __init__(
+        self,
+        tracer: Tracer,
+        name: str = "langchain-agent",
+        metadata: Optional[Dict[str, Any]] = None,
+        session_id: Optional[str] = None,
+    ) -> None:
+        super().__init__()
+        self._tracer = tracer
+        self._name = name
+        self._metadata = metadata
+        self._session_id = session_id
+
+        # Keyed by run_id (UUID) → state dict
+        self._runs: Dict[UUID, Dict[str, Any]] = {}
+        # Track which run_ids are top-level (no parent)
+        self._top_level: Dict[UUID, bool] = {}
+
+    # ------------------------------------------------------------------
+    # Chain lifecycle
+    # ------------------------------------------------------------------
+
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        is_top = parent_run_id is None
+        self._top_level[run_id] = is_top
+        if is_top:
+            self._runs[run_id] = {
+                "start": time.time(),
+                "input": _safe_serialize(inputs),
+                "tool_calls": [],
+                "model": None,
+            }
+
+    def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        if not self._top_level.get(run_id):
+            return
+        state = self._runs.pop(run_id, None)
+        if state is None:
+            return
+        latency_ms = int((time.time() - state["start"]) * 1000)
+        self._tracer._send(
+            name=self._name,
+            input=state["input"],
+            output=_safe_serialize(outputs),
+            latency_ms=latency_ms,
+            framework="langchain",
+            model=state.get("model"),
+            tool_calls=state["tool_calls"] or None,
+            metadata=self._metadata,
+            session_id=self._session_id,
+        )
+        self._top_level.pop(run_id, None)
+
+    def on_chain_error(
+        self,
+        error: Union[Exception, KeyboardInterrupt],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        if not self._top_level.get(run_id):
+            return
+        state = self._runs.pop(run_id, None)
+        if state is None:
+            return
+        latency_ms = int((time.time() - state["start"]) * 1000)
+        self._tracer._send(
+            name=self._name,
+            input=state["input"],
+            error=str(error),
+            latency_ms=latency_ms,
+            framework="langchain",
+            model=state.get("model"),
+            tool_calls=state["tool_calls"] or None,
+            metadata=self._metadata,
+            session_id=self._session_id,
+        )
+        self._top_level.pop(run_id, None)
+
+    # ------------------------------------------------------------------
+    # LLM lifecycle (captures model name and token counts)
+    # ------------------------------------------------------------------
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        # Record LLM start time keyed by its own run_id
+        self._runs.setdefault(run_id, {})["llm_start"] = time.time()
+
+        # Propagate model name to the top-level run
+        top = self._find_top_ancestor(parent_run_id)
+        if top and not self._runs[top].get("model"):
+            model = (
+                serialized.get("kwargs", {}).get("model_name")
+                or serialized.get("kwargs", {}).get("model")
+                or serialized.get("id", [None])[-1]
+            )
+            if model:
+                self._runs[top]["model"] = str(model)
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        self._runs.pop(run_id, None)
+
+    # ------------------------------------------------------------------
+    # Tool lifecycle
+    # ------------------------------------------------------------------
+
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        self._runs[run_id] = {
+            "tool_name": serialized.get("name", "unknown"),
+            "tool_input": input_str,
+            "start": time.time(),
+        }
+
+    def on_tool_end(
+        self,
+        output: Any,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        state = self._runs.pop(run_id, None)
+        if state is None:
+            return
+        latency_ms = int((time.time() - state["start"]) * 1000)
+        tool_call = {
+            "name": state["tool_name"],
+            "input": state["tool_input"],
+            "output": str(output)[:500],
+            "latency_ms": latency_ms,
+        }
+        top = self._find_top_ancestor(parent_run_id)
+        if top and top in self._runs:
+            self._runs[top]["tool_calls"].append(tool_call)
+
+    def on_tool_error(
+        self,
+        error: Union[Exception, KeyboardInterrupt],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs,
+    ) -> None:
+        state = self._runs.pop(run_id, None)
+        if state is None:
+            return
+        tool_call = {
+            "name": state.get("tool_name", "unknown"),
+            "input": state.get("tool_input"),
+            "output": f"ERROR: {error}",
+            "latency_ms": int((time.time() - state["start"]) * 1000),
+        }
+        top = self._find_top_ancestor(parent_run_id)
+        if top and top in self._runs:
+            self._runs[top]["tool_calls"].append(tool_call)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    def _find_top_ancestor(self, parent_run_id: Optional[UUID]) -> Optional[UUID]:
+        """Walk up parent chain to find the top-level run_id."""
+        current = parent_run_id
+        while current is not None:
+            if self._top_level.get(current):
+                return current
+            # If current is a nested run, keep climbing — for simplicity return
+            # the immediate parent that is registered as top-level
+            break
+        return current if current in self._runs else None