agentx-python 0.8.11__tar.gz → 0.8.13__tar.gz

{agentx_python-0.8.11 → agentx_python-0.8.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.8.11
+Version: 0.8.13
 Summary: Official Python SDK for AgentX (https://www.agentx.so/)
 Home-page: https://github.com/AgentX-ai/AgentX-python
 Author: Robin Wang and AgentX Team
@@ -252,7 +252,12 @@ extra:
 | LlamaIndex            | `pip install "agentx-python[llamaindex]"`    | `AgentXLlamaIndexHandler` |
 | AutoGen               | `pip install "agentx-python[autogen]"`       | `AgentXAutoGenObserver`   |
 
-Or plain Python - wrap any function with `@tracer.trace(...)` and it just works, no framework required.
+Or plain Python - wrap any function with `@tracer.trace(...)` and it just works, no framework
+required. Tracing is **platform agnostic**: each integration stamps its platform label
+automatically, a plain trace auto-detects the one orchestration framework imported in the
+process, and `framework="any-name"` labels platforms AgentX has never heard of - the label
+drives the dashboard's framework filter and Monitor's Platforms chart. See
+[Platform detection](TRACING.md#platform-detection).
 
 Running specialist agents in parallel with a `ThreadPoolExecutor`? Wrap each worker body in `tracer.use_span(span)` so their steps land on the parent trace instead of becoming independent traces - see [TRACING.md](TRACING.md) for the full pattern.
 

{agentx_python-0.8.11 → agentx_python-0.8.13}/README.md

@@ -188,7 +188,12 @@ extra:
 | LlamaIndex            | `pip install "agentx-python[llamaindex]"`    | `AgentXLlamaIndexHandler` |
 | AutoGen               | `pip install "agentx-python[autogen]"`       | `AgentXAutoGenObserver`   |
 
-Or plain Python - wrap any function with `@tracer.trace(...)` and it just works, no framework required.
+Or plain Python - wrap any function with `@tracer.trace(...)` and it just works, no framework
+required. Tracing is **platform agnostic**: each integration stamps its platform label
+automatically, a plain trace auto-detects the one orchestration framework imported in the
+process, and `framework="any-name"` labels platforms AgentX has never heard of - the label
+drives the dashboard's framework filter and Monitor's Platforms chart. See
+[Platform detection](TRACING.md#platform-detection).
 
 Running specialist agents in parallel with a `ThreadPoolExecutor`? Wrap each worker body in `tracer.use_span(span)` so their steps land on the parent trace instead of becoming independent traces - see [TRACING.md](TRACING.md) for the full pattern.
 

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx/integrations/_traced_call.py

@@ -143,6 +143,9 @@ def finish_llm_call(
             input=input_repr,
             output=output,
             model=model,
+            # Stamp the provider literal on a span opened without one (adoption keeps an
+            # explicit framework= or a framework integration's label winning over this).
+            framework=framework,
             input_tokens=input_tokens,
             output_tokens=output_tokens,
             cache_read_tokens=cache_read_tokens,

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx/monitor/client.py

@@ -268,6 +268,28 @@ class MonitorClient:
         plus deltas vs the prior window and the run-outcome breakdown."""
         return self._request("GET", "/kpis", params={"window": window})
 
+    def metrics(
+        self,
+        window: str = "1d",
+        *,
+        agent: Optional[str] = None,
+        model: Optional[str] = None,
+        tool: Optional[str] = None,
+        framework: Optional[str] = None,
+        status: Optional[str] = None,
+    ) -> dict:
+        """The Monitor metrics grid's data over a window ("1h".."90d") - bucketed spans by kind,
+        latency percentiles, tokens/cost, tool executions and failures, and platform attribution
+        (`frameworks` window totals + per-bucket `byFramework` - the Platforms chart). Optional
+        filters scope every number the way the dashboard's filter chips do; `framework` matches
+        the platform label traces carry (see TRACING.md's Platform detection), with "other"
+        selecting unlabeled traffic."""
+        params = {"window": window}
+        for key, value in (("agent", agent), ("model", model), ("tool", tool), ("framework", framework), ("status", status)):
+            if value is not None:
+                params[key] = value
+        return self._request("GET", "/metrics", params=params)
+
     def topics(self, window: str = "7d") -> dict:
         """The Topics view's data over a window ("24h", "7d", "30d"): LLM-classified themes of
         sampled production traffic with per-topic counts and sentiment. Empty until Topics is

agentx_python-0.8.13/agentx/tracing/framework_detect.py

@@ -0,0 +1,64 @@
+"""Best-effort agent-framework auto-detection (the "platform agnostic" story).
+
+A span whose framework was neither passed explicitly (``tracer.trace(...,
+framework="...")``) nor adopted from a framework integration (callback handler,
+observer, patched client - see ``_TraceSpan._captured_framework``) gets labeled
+by looking at which known ORCHESTRATION framework is actually imported in this
+process. ``sys.modules`` is the signal - imported, not merely installed - so a
+machine with ten frameworks pip-installed but one in use still resolves.
+
+Only unambiguous answers are given: zero or more than one known framework
+loaded means ``None``, and the span goes out unlabeled rather than mislabeled.
+The user's explicit ``framework=`` always wins, including totally custom names
+for platforms this table has never heard of.
+
+Raw provider SDKs (openai, anthropic, google-genai, ...) are deliberately NOT
+in this table: they are transitive dependencies of nearly every framework, so
+their presence says nothing about what orchestrates the agent - and their
+patched-client integrations already stamp the provider literal on the spans
+they create.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import Optional
+
+# Top-level module name -> the wire literal the matching integration emits.
+# Multiple modules may map to one literal (langgraph is the LangChain family).
+_ORCHESTRATOR_MODULES = {
+    "langchain": "langchain",
+    "langchain_core": "langchain",
+    "langgraph": "langchain",
+    "crewai": "crewai",
+    "llama_index": "llamaindex",
+    "autogen": "autogen",
+    "autogen_agentchat": "autogen",
+    "agents": "openai-agents",  # the OpenAI Agents SDK's import name
+    "google.adk": "google-adk",
+    "semantic_kernel": "semantic-kernel",
+    "haystack": "haystack",
+    "pydantic_ai": "pydantic-ai",
+    "smolagents": "smolagents",
+    "dspy": "dspy",
+}
+
+
+def _looks_like_openai_agents_sdk() -> bool:
+    # "agents" is a name any user package could claim - only trust it when the
+    # OpenAI Agents SDK's own submodules are loaded alongside it.
+    return "agents.run" in sys.modules or "agents.tracing" in sys.modules
+
+
+def detect_framework() -> Optional[str]:
+    """The single unambiguous orchestration framework imported right now, else None."""
+    found: set = set()
+    for module, literal in _ORCHESTRATOR_MODULES.items():
+        if module not in sys.modules:
+            continue
+        if module == "agents" and not _looks_like_openai_agents_sdk():
+            continue
+        found.add(literal)
+        if len(found) > 1:
+            return None
+    return found.pop() if len(found) == 1 else None

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx/tracing/ingest_client.py

@@ -428,6 +428,15 @@ class IngestClient:
                 continue
 
             if resp.status_code in _RETRYABLE_STATUS and attempt < _MAX_RETRIES - 1:
+                # 429 = the engine's bounded ingest queue shedding load (its ADR-0005): honor
+                # Retry-After exactly instead of the generic backoff schedule, so the SDK backs
+                # off in step with the server's own flush cadence.
+                retry_after = resp.headers.get("Retry-After")
+                if resp.status_code == 429 and retry_after:
+                    try:
+                        time.sleep(min(30.0, float(retry_after)))
+                    except ValueError:
+                        pass
                 last_exc = Exception(f"HTTP {resp.status_code}")
                 continue
             if not resp.ok:

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx/tracing/tracer.py

@@ -14,6 +14,7 @@ from agentx.exceptions import CIGateFailure
 from agentx.tracing.ingest_client import IngestClient
 from agentx.tracing.ci_types import CIRun, CIRunResult, CIRunStatus, CIQuestionScore
 from agentx.tracing.eval_scope import EVAL_RUN_SOURCE, current_eval_run_id
+from agentx.tracing.framework_detect import detect_framework
 
 F = TypeVar("F", bound=Callable[..., Any])
 
@@ -125,6 +126,10 @@ class _TraceSpan:
         # Adopted from a merged child run (e.g. AgentXCallbackHandler) when this span itself
         # wasn't opened with an explicit framework= - see _merge_child_run below.
         self._captured_framework: Optional[str] = None
+        # Best-effort auto-detection (framework_detect.py), resolved once at span open so child
+        # spans emitted mid-flight carry the same label the root will. Lowest precedence:
+        # explicit framework= > integration adoption > this. None when ambiguous.
+        self._detected_framework: Optional[str] = None if framework else detect_framework()
         self._input_tokens: int = 0
         self._output_tokens: int = 0
         # Subsets of _input_tokens (not additional tokens) - a prompt-caching write/read, when the
@@ -191,7 +196,7 @@ class _TraceSpan:
             latency_ms=latency_ms,
             error=self._error,
             metadata=metadata,
-            framework=self._framework or self._captured_framework,
+            framework=self._framework or self._captured_framework or self._detected_framework or detect_framework(),
             model=self._model or self._captured_model,
             tool_calls=self.tool_calls or None,
             session_id=self._session_id,
@@ -235,14 +240,18 @@ class _TraceSpan:
         input: Any = None,
         output: Any = None,
         model: Optional[str] = None,
+        framework: Optional[str] = None,
         input_tokens: Optional[int] = None,
         output_tokens: Optional[int] = None,
         cache_read_tokens: Optional[int] = None,
         cache_write_tokens: Optional[int] = None,
     ) -> None:
         """Record one LLM-call child span (e.g. one patched Anthropic call) under this span -
-        name left unset so _merge_child_run auto-numbers it "LLM Call N"."""
+        name left unset so _merge_child_run auto-numbers it "LLM Call N". ``framework`` lets the
+        patched client stamp its provider literal on a span the user opened without one - the
+        adoption in _merge_child_run keeps explicit/integration labels winning."""
         self._merge_child_run(
+            framework=framework,
             execution_steps=[{
                 "duration_ms": duration_ms,
                 "start_time": start_time,
@@ -301,7 +310,7 @@ class _TraceSpan:
         child = _TraceSpan(
             tracer=self._tracer,
             name=name,
-            framework=framework or self._framework or self._captured_framework,
+            framework=framework or self._framework or self._captured_framework or self._detected_framework,
             model=model,
             session_id=self._session_id,
         )
@@ -397,6 +406,13 @@ class _TraceSpan:
         under this span).
         """
         with self._merge_lock:
+            # Adopt framework/model BEFORE emitting child spans: child_span resolves its
+            # framework from this span's fields, so adopting after the emission loops used to
+            # send every CrewAI/AutoGen child out unlabeled while only the root got stamped.
+            if model and not self._captured_model:
+                self._captured_model = model
+            if framework and not self._captured_framework:
+                self._captured_framework = framework
             for step in [] if not emit_steps else (execution_steps or []):
                 self._child_span_count += 1
                 self.child_span(
@@ -463,10 +479,6 @@ class _TraceSpan:
                 self.input = input
             if output is not None:
                 self.output = output
-            if model and not self._captured_model:
-                self._captured_model = model
-            if framework and not self._captured_framework:
-                self._captured_framework = framework
             if input_tokens:
                 self._input_tokens += input_tokens
             if output_tokens:
@@ -520,7 +532,8 @@ class _TraceSpan:
             # to be called from inside another active span.
             span = self._tracer.trace(
                 self.name, metadata=self._metadata, framework=self._framework, model=self._model,
-                session_id=self._session_id,
+                session_id=self._session_id, sync=self._sync, monitor=self._monitor,
+                pattern_ids=self._pattern_ids, agent_id=self._agent_id, span_kind=self._span_kind,
             )
             span.__enter__()
             try:
@@ -542,7 +555,8 @@ class _TraceSpan:
             # See _wrap_sync's comment - same "fresh span per call" reasoning applies here.
             span = self._tracer.trace(
                 self.name, metadata=self._metadata, framework=self._framework, model=self._model,
-                session_id=self._session_id,
+                session_id=self._session_id, sync=self._sync, monitor=self._monitor,
+                pattern_ids=self._pattern_ids, agent_id=self._agent_id, span_kind=self._span_kind,
             )
             span.__enter__()
             try:
@@ -911,6 +925,22 @@ class Tracer:
 
             with client.tracer.trace("support-agent", agent_id="ag_123", sync=True) as span:
                 span.output = call_llm(...)
+
+        ``framework`` names the platform the agent runs on - tracing is platform agnostic, and
+        this label is how the dashboard's framework filter and Monitor's Platforms chart group
+        traffic. Three ways it gets set, strongest first:
+
+        1. **Explicit**: ``framework="langchain"`` - any string works, including platforms
+           AgentX has no integration for (``framework="my-inhouse-runner"``).
+        2. **Integration**: every integration stamps its own literal automatically -
+           ``langchain``, ``crewai``, ``openai-agents``, ``openai``, ``anthropic``,
+           ``google-genai``, ``google-adk``, ``litellm``, ``llamaindex``, ``autogen``,
+           ``moveworks``, ``databricks``.
+        3. **Auto-detection**: with neither of the above, the SDK labels the span with the one
+           known orchestration framework imported in the process (LangChain/LangGraph, CrewAI,
+           LlamaIndex, AutoGen, OpenAI Agents SDK, Google ADK, Semantic Kernel, Haystack,
+           Pydantic AI, smolagents, DSPy). Ambiguous (several imported) or unknown -> the span
+           goes out unlabeled rather than mislabeled.
         """
         return _TraceSpan(
             tracer=self,

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx/version.py

@@ -1,7 +1,7 @@
-VERSION = "0.8.11"
+VERSION = "0.8.13"
 
 # The AgentX-trace-eval release this SDK version is tested against - what `agentx-trace-eval`
 # installs and converges to (see agentx/cli.py). Bump together with VERSION when releasing, so
 # every published SDK names a known-good engine+dashboard pair. Users can override with
 # AGENTX_TRACE_EVAL_VERSION=<tag|latest>.
-ENGINE_VERSION = "v0.3.2"
+ENGINE_VERSION = "v0.3.7"

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.8.11
+Version: 0.8.13
 Summary: Official Python SDK for AgentX (https://www.agentx.so/)
 Home-page: https://github.com/AgentX-ai/AgentX-python
 Author: Robin Wang and AgentX Team
@@ -252,7 +252,12 @@ extra:
 | LlamaIndex            | `pip install "agentx-python[llamaindex]"`    | `AgentXLlamaIndexHandler` |
 | AutoGen               | `pip install "agentx-python[autogen]"`       | `AgentXAutoGenObserver`   |
 
-Or plain Python - wrap any function with `@tracer.trace(...)` and it just works, no framework required.
+Or plain Python - wrap any function with `@tracer.trace(...)` and it just works, no framework
+required. Tracing is **platform agnostic**: each integration stamps its platform label
+automatically, a plain trace auto-detects the one orchestration framework imported in the
+process, and `framework="any-name"` labels platforms AgentX has never heard of - the label
+drives the dashboard's framework filter and Monitor's Platforms chart. See
+[Platform detection](TRACING.md#platform-detection).
 
 Running specialist agents in parallel with a `ThreadPoolExecutor`? Wrap each worker body in `tracer.use_span(span)` so their steps land on the parent trace instead of becoming independent traces - see [TRACING.md](TRACING.md) for the full pattern.
 

{agentx_python-0.8.11 → agentx_python-0.8.13}/agentx_python.egg-info/SOURCES.txt

@@ -64,6 +64,7 @@ agentx/resources/workforce.py
 agentx/tracing/__init__.py
 agentx/tracing/ci_types.py
 agentx/tracing/eval_scope.py
+agentx/tracing/framework_detect.py
 agentx/tracing/ingest_client.py
 agentx/tracing/tracer.py
 agentx_python.egg-info/PKG-INFO
@@ -77,6 +78,7 @@ tests/test_cli_launcher.py
 tests/test_deep_dive_fixes.py
 tests/test_docs_match_sdk.py
 tests/test_eval_scope.py
+tests/test_framework_detect.py
 tests/test_integration.py
 tests/test_integrations.py
 tests/test_judge_scorers.py

agentx_python-0.8.13/tests/test_framework_detect.py

@@ -0,0 +1,125 @@
+"""
+Platform-agnostic framework capture: explicit framework= always wins, integrations stamp their
+literal, and - new - the SDK auto-detects the single unambiguous orchestration framework
+imported in the process (agentx/tracing/framework_detect.py). Also pins the two capture-gap
+fixes: _merge_child_run adopts the framework BEFORE emitting child spans (CrewAI/AutoGen
+children used to go out unlabeled), and _record_llm_call forwards the patched client's provider
+literal onto a user-opened span that has no label of its own.
+
+Same harness as test_span_tree.py: only the ingest_client boundary is mocked, so the real
+_send/_dispatch/child_span paths run and every wire dict is inspectable.
+"""
+from __future__ import annotations
+
+import sys
+import types
+from unittest.mock import MagicMock
+
+import pytest
+
+from agentx.tracing.framework_detect import _ORCHESTRATOR_MODULES, detect_framework
+from agentx.tracing.tracer import Tracer
+
+
+def make_tracer() -> Tracer:
+    return Tracer(ingest_client=MagicMock())
+
+
+def enqueued_wires(tracer: Tracer) -> list:
+    return [call.args[0] for call in tracer._client.enqueue.call_args_list]
+
+
+@pytest.fixture()
+def clean_modules(monkeypatch):
+    """Remove every known orchestrator from sys.modules so each test states its own world."""
+    for module in list(_ORCHESTRATOR_MODULES) + ["agents.run", "agents.tracing"]:
+        monkeypatch.delitem(sys.modules, module, raising=False)
+    return monkeypatch
+
+
+def fake_import(monkeypatch, name: str) -> None:
+    monkeypatch.setitem(sys.modules, name, types.ModuleType(name))
+
+
+def test_detects_single_imported_orchestrator(clean_modules):
+    fake_import(clean_modules, "crewai")
+    assert detect_framework() == "crewai"
+    tracer = make_tracer()
+    with tracer.trace("agent"):
+        pass
+    assert enqueued_wires(tracer)[0]["framework"] == "crewai"
+
+
+def test_no_orchestrator_means_no_label(clean_modules):
+    assert detect_framework() is None
+    tracer = make_tracer()
+    with tracer.trace("agent"):
+        pass
+    assert "framework" not in enqueued_wires(tracer)[0]
+
+
+def test_ambiguous_imports_stay_unlabeled(clean_modules):
+    fake_import(clean_modules, "crewai")
+    fake_import(clean_modules, "llama_index")
+    assert detect_framework() is None
+
+
+def test_langchain_family_collapses_to_one_literal(clean_modules):
+    # langgraph + langchain_core together are ONE framework, not an ambiguity.
+    fake_import(clean_modules, "langchain_core")
+    fake_import(clean_modules, "langgraph")
+    assert detect_framework() == "langchain"
+
+
+def test_agents_module_needs_sdk_submodules(clean_modules):
+    fake_import(clean_modules, "agents")  # could be anyone's package named "agents"
+    assert detect_framework() is None
+    fake_import(clean_modules, "agents.run")
+    assert detect_framework() == "openai-agents"
+
+
+def test_explicit_framework_beats_detection(clean_modules):
+    fake_import(clean_modules, "crewai")
+    tracer = make_tracer()
+    with tracer.trace("agent", framework="my-inhouse-runner"):
+        pass
+    assert enqueued_wires(tracer)[0]["framework"] == "my-inhouse-runner"
+
+
+def test_children_inherit_detected_framework(clean_modules):
+    fake_import(clean_modules, "llama_index")
+    tracer = make_tracer()
+    with tracer.trace("agent") as span:
+        span.child_span("step", duration_ms=5)
+    wires = enqueued_wires(tracer)
+    assert [w.get("framework") for w in wires] == ["llamaindex", "llamaindex"]
+
+
+def test_merge_child_run_adopts_before_emitting_children(clean_modules):
+    # The CrewAI/AutoGen shape: root opened with no framework, the merged sub-run carries it.
+    # Children must go out labeled too - adoption used to happen after emission.
+    tracer = make_tracer()
+    with tracer.trace("crew") as span:
+        span._merge_child_run(
+            framework="crewai",
+            execution_steps=[{"duration_ms": 10, "input": "q", "output": "a"}],
+        )
+    wires = enqueued_wires(tracer)
+    assert len(wires) == 2
+    assert all(w.get("framework") == "crewai" for w in wires)
+
+
+def test_record_llm_call_stamps_provider_on_unlabeled_span(clean_modules):
+    tracer = make_tracer()
+    with tracer.trace("agent") as span:
+        span._record_llm_call(duration_ms=7, model="claude-x", framework="anthropic")
+    root = enqueued_wires(tracer)[-1]
+    assert root["framework"] == "anthropic"
+
+
+def test_record_llm_call_never_overrides_explicit_framework(clean_modules):
+    tracer = make_tracer()
+    with tracer.trace("agent", framework="langchain") as span:
+        span._record_llm_call(duration_ms=7, model="gpt-x", framework="openai")
+    root = enqueued_wires(tracer)[-1]
+    assert root["framework"] == "langchain"