agentx-python 0.6.28__tar.gz → 0.6.29__tar.gz

{agentx_python-0.6.28 → agentx_python-0.6.29}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.6.28
+Version: 0.6.29
 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

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/agentx.py

@@ -111,6 +111,50 @@ class AgentX:
                 f"Failed to list workforces: {response.status_code} - {response.reason}"
             )
 
+    def ping(self) -> dict:
+        """Verify the client can actually reach AgentX and that the API key is accepted.
+
+        The constructor is deliberately lazy (no network call - standard SDK behavior, so
+        offline construction and tests work), and trace delivery is fire-and-forget, so a
+        wrong ``base_url`` or ``api_key`` otherwise surfaces only as a one-time warning in
+        logs while traces silently go nowhere. Call this once at startup of a long-running
+        service to fail fast instead::
+
+            client = AgentX.from_env()
+            client.ping()  # raises immediately on a bad URL or key
+
+        Raises :class:`agentx.exceptions.AgentXConnectionError` when the URL is unreachable,
+        :class:`agentx.exceptions.AgentXAuthError` when the key is rejected, and
+        :class:`agentx.exceptions.AgentXAPIError` on any other non-OK response. Returns
+        ``{"ok": True, "base_url": ...}`` on success.
+        """
+        from agentx.exceptions import AgentXAPIError, AgentXAuthError, AgentXConnectionError
+
+        base = api_base()
+        # /monitor/patterns: the cheapest key-authenticated endpoint that exists on both the
+        # hosted API and the self-host engine's SDK-facing router.
+        url = f"{base}/monitor/patterns"
+        try:
+            response = requests.get(url, headers=get_headers(self.api_key), timeout=10)
+        except requests.RequestException as exc:
+            raise AgentXConnectionError(
+                f"Cannot reach AgentX at {base} ({exc.__class__.__name__}: {exc}). "
+                "Check base_url / AGENTX_API_BASE_URL - for self-host it should look like "
+                "http://localhost:4700/api/v1."
+            ) from exc
+        if response.status_code in (401, 403):
+            raise AgentXAuthError(
+                f"AgentX at {base} rejected the API key (HTTP {response.status_code}). "
+                "Check api_key / AGENTX_API_KEY - for self-host, copy the 'Default project "
+                "API key' from the engine's startup log."
+            )
+        if not response.ok:
+            raise AgentXAPIError(
+                f"AgentX at {base} responded HTTP {response.status_code} to the health probe.",
+                status_code=response.status_code,
+            )
+        return {"ok": True, "base_url": base}
+
     def get_profile(self):
         """Get the current user's profile information."""
         url = f"{api_base()}/access/getProfile"

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/evaluations/client.py

@@ -102,6 +102,8 @@ class EvaluationsClient:
         self.datasets = DatasetClient(self)
         self.settings = EvaluationSettingsClient(self)
         self.prompts = PromptClient(self)
+        from agentx.evaluations.tool_schemas import ToolSchemaClient
+        self.tool_schemas = ToolSchemaClient(self)
 
     # ------------------------------------------------------------------
     # Low-level HTTP
@@ -136,7 +138,7 @@ class EvaluationsClient:
         ``retry=False`` disables the backoff loop entirely. Use it for any request that is
         both slow and billable: the loop retries on ``requests.RequestException``, which
         includes read timeouts, so a synchronous endpoint that outlives its timeout would
-        otherwise be re-invoked — and paid for — up to four times.
+        otherwise be re-invoked, and paid for, up to four times.
         """
         url = f"{base or self._base_url}{path}"
         schedule = [0.0] + (_RETRY_BACKOFF if retry else [])
@@ -483,6 +485,109 @@ class EvaluationsClient:
             **body,
         )
 
+    # ------------------------------------------------------------------
+    # Prompt improvement loop (examples -> propose -> publish). These ride the engine's
+    # /evaluate dialect via _api_root(), same precedent get_report/_analysis already use for
+    # routes that live on the dashboard router (self-host only).
+    # ------------------------------------------------------------------
+
+    def get_prompt_examples(self, prompt_id: str, window: Optional[str] = None) -> dict:
+        params = {"window": window} if window else None
+        return self._request(
+            "GET", f"/evaluate/prompts/{prompt_id}/examples", base=self._api_root, params=params
+        )
+
+    def propose_prompt(self, prompt_id: str) -> dict:
+        # One real judge call - no retry (see _request's retry note).
+        return self._request(
+            "POST", f"/evaluate/prompts/{prompt_id}/propose", base=self._api_root, timeout=180, retry=False
+        )
+
+    def publish_prompt_version(
+        self, prompt_id: str, *, text: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        payload: dict = {"text": text, "source": source}
+        if reasoning is not None:
+            payload["reasoning"] = reasoning
+        if based_on_version is not None:
+            payload["basedOnVersion"] = based_on_version
+        return self._request(
+            "POST", f"/evaluate/prompts/{prompt_id}/versions", base=self._api_root, json=payload
+        )
+
+    # ------------------------------------------------------------------
+    # Tool schema registry (same version-scoped propose/publish loop as prompts)
+    # ------------------------------------------------------------------
+
+    def list_tool_schemas(self) -> List[dict]:
+        data = self._request("GET", "/evaluate/tool-schemas", base=self._api_root)
+        return data.get("toolSchemas", []) if isinstance(data, dict) else data
+
+    def create_tool_schema(self, *, name: str, definition: str, description: Optional[str] = None) -> dict:
+        payload: dict = {"name": name, "definition": definition}
+        if description is not None:
+            payload["description"] = description
+        return self._request("POST", "/evaluate/tool-schemas", base=self._api_root, json=payload)
+
+    def get_tool_schema_examples(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        params = {"window": window} if window else None
+        return self._request(
+            "GET", f"/evaluate/tool-schemas/{tool_schema_id}/examples", base=self._api_root, params=params
+        )
+
+    def propose_tool_schema(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        payload = {"window": window} if window else {}
+        return self._request(
+            "POST", f"/evaluate/tool-schemas/{tool_schema_id}/propose",
+            base=self._api_root, json=payload, timeout=180, retry=False,
+        )
+
+    def publish_tool_schema_version(
+        self, tool_schema_id: str, *, definition: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        payload: dict = {"definition": definition, "source": source}
+        if reasoning is not None:
+            payload["reasoning"] = reasoning
+        if based_on_version is not None:
+            payload["basedOnVersion"] = based_on_version
+        return self._request(
+            "POST", f"/evaluate/tool-schemas/{tool_schema_id}/versions", base=self._api_root, json=payload
+        )
+
+    # ------------------------------------------------------------------
+    # CI gate history + conversation simulation (self-host)
+    # ------------------------------------------------------------------
+
+    def list_gates(self) -> List[dict]:
+        """Recorded CI gate verdicts, newest first - the dashboard's CI Gates history."""
+        data = self._request("GET", "/evaluate/ci/gates", base=self._api_root)
+        return data.get("gates", []) if isinstance(data, dict) else data
+
+    def simulate_conversation(
+        self, *, model: str, system_prompt: str, persona: str, goal: str,
+        max_turns: int = 5, tools: Optional[List[dict]] = None, agent_name: Optional[str] = None,
+    ) -> dict:
+        """Run a persona-driven multi-turn simulation against a prompt (the Playground's
+        "Simulate conversation"). Blocking and judge-billed: one LLM call per simulated turn
+        plus the closing judgment, so expect it to take tens of seconds."""
+        payload: dict = {
+            "model": model,
+            "messages": [{"role": "system", "content": system_prompt}],
+            "persona": persona,
+            "goal": goal,
+            "maxTurns": max_turns,
+        }
+        if tools:
+            payload["tools"] = tools
+        if agent_name:
+            payload["agentName"] = agent_name
+        return self._request(
+            "POST", "/evaluate/playground/simulate", base=self._api_root, json=payload,
+            timeout=600, retry=False,
+        )
+
 
 # ---------------------------------------------------------------------------
 # Helpers

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/evaluations/evaluation_settings.py

@@ -32,6 +32,7 @@ class EvaluationSettingsBuilder:
         rouge_score: bool = False,
         similarity_model: Optional[str] = None,
         sovereignty_models: Optional[List[str]] = None,
+        code_scorers: Optional[List[Dict[str, Any]]] = None,
     ):
         self._client = client
         self._payload: Dict[str, Any] = {
@@ -68,6 +69,11 @@ class EvaluationSettingsBuilder:
                 "enabled": True,
                 "models": list(sovereignty_models),
             }
+        # Sandboxed JS scorers run per result alongside the judge - each entry is
+        # {"name": ..., "enabled": True, "code": "..."} where the code is a JS function body
+        # receiving (input, output, expected, toolCalls) and returning {score, reasoning}.
+        if code_scorers:
+            self._payload["codeScorers"] = list(code_scorers)
 
     def publish(self) -> EvaluationSettings:
         logger.info("Publishing evaluation settings '%s'", self._payload["name"])
@@ -96,6 +102,7 @@ class EvaluationSettingsClient:
         rouge_score: bool = False,
         similarity_model: Optional[str] = None,
         sovereignty_models: Optional[List[str]] = None,
+        code_scorers: Optional[List[Dict[str, Any]]] = None,
     ) -> EvaluationSettingsBuilder:
         return EvaluationSettingsBuilder(
             self._client,
@@ -113,6 +120,7 @@ class EvaluationSettingsClient:
             rouge_score=rouge_score,
             similarity_model=similarity_model,
             sovereignty_models=sovereignty_models,
+            code_scorers=code_scorers,
         )
 
     def get(self, evaluation_settings_id: str) -> EvaluationSettings:

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/evaluations/prompts.py

@@ -51,5 +51,24 @@ class PromptClient:
         second lookup method."""
         return self._client.get_prompt(name, version=version)
 
+    def examples(self, prompt_id: str, window: Optional[str] = None) -> dict:
+        """The merged evidence (worst eval-run results + low-rated online-evaluator traffic)
+        a propose() call will rewrite from - version-scoped to the prompt's current version."""
+        return self._client.get_prompt_examples(prompt_id, window=window)
+
+    def propose(self, prompt_id: str) -> dict:
+        """Ask the judge for a rewrite grounded in examples(). Returns the proposal
+        (revisedText/reasoning/sourceBreakdown) without publishing anything."""
+        return self._client.propose_prompt(prompt_id)
+
+    def publish_version(
+        self, prompt_id: str, *, text: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        """Publish a new version (the human-approval step of the propose flow)."""
+        return self._client.publish_prompt_version(
+            prompt_id, text=text, source=source, reasoning=reasoning, based_on_version=based_on_version
+        )
+
     def list(self) -> List[Prompt]:
         return self._client.list_prompts()

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/evaluations/runner.py

@@ -271,6 +271,13 @@ class EvaluationRunContext:
     # UI reads, computed once in the API.
     # ------------------------------------------------------------------
 
+    def results(self) -> list:
+        """Per-result rows for this run (rating, justification, code scorer rows, trace ids,
+        latency/tokens, similarity metrics) - what the dashboard's run detail table shows,
+        fetched fresh from the engine."""
+        detail = self._client.get_run(self.run_id)
+        return detail.get("results", []) if isinstance(detail, dict) else []
+
     @property
     def run_id(self) -> str:
         """The server-side run id - handy for fetching the run's full results afterwards."""
@@ -401,6 +408,7 @@ class EvaluationsRunner:
         self.datasets = client.datasets
         self.settings = client.settings
         self.prompts = client.prompts
+        self.tool_schemas = client.tool_schemas
 
     def list_models(self, provider: Optional[str] = None) -> List[ModelInfo]:
         """List the LLM models AgentX supports - the same set selectable for
@@ -409,6 +417,20 @@ class EvaluationsRunner:
         against."""
         return self._client.list_models(provider)
 
+    def list_gates(self) -> list:
+        """Recorded CI gate verdicts, newest first (the dashboard's CI Gates history)."""
+        return self._client.list_gates()
+
+    def simulate_conversation(self, **kwargs) -> dict:
+        """Persona-driven multi-turn simulation against a prompt - see
+        EvaluationsClient.simulate_conversation for parameters."""
+        return self._client.simulate_conversation(**kwargs)
+
+    def get_run(self, run_id: str) -> dict:
+        """Run summary + per-result rows by id, without needing the EvaluationRunContext that
+        created it (e.g. from a separate process)."""
+        return self._client.get_run(run_id)
+
     def get_analysis_status(self, run_id: str) -> AnalysisStatus:
         """Check on an in-progress ``.analyze()`` job by run id, without needing
         the ``EvaluationRunContext`` that started it (e.g. from a separate

agentx_python-0.6.29/agentx/evaluations/tool_schemas.py

@@ -0,0 +1,48 @@
+"""Tool schema registry client, surfaced as ``client.evaluations.tool_schemas``.
+
+The tool-definition analog of the prompt registry: register the JSON definition your agent
+actually passes to its LLM, let production failures accumulate as evidence against it, then
+propose -> validate -> publish improved versions. See the dashboard's Improve > Tools & MCPs.
+"""
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.evaluations.client import EvaluationsClient
+
+
+class ToolSchemaClient:
+    def __init__(self, client: "EvaluationsClient"):
+        self._client = client
+
+    def list(self) -> List[dict]:
+        return self._client.list_tool_schemas()
+
+    def create(self, *, name: str, definition: str, description: Optional[str] = None) -> dict:
+        return self._client.create_tool_schema(name=name, definition=definition, description=description)
+
+    def get_or_create(self, *, name: str, definition: str, description: Optional[str] = None) -> dict:
+        """Idempotent register: returns the existing schema of this name if present."""
+        existing = next((t for t in self.list() if t.get("name") == name), None)
+        if existing:
+            return existing
+        return self.create(name=name, definition=definition, description=description)
+
+    def examples(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        """Failure evidence recorded against this tool (agent-tool-failure signals, low-rated
+        eval results that called it) - what propose() rewrites from."""
+        return self._client.get_tool_schema_examples(tool_schema_id, window=window)
+
+    def propose(self, tool_schema_id: str, window: Optional[str] = None) -> dict:
+        """Judge-written definition rewrite grounded in examples(). Nothing is published."""
+        return self._client.propose_tool_schema(tool_schema_id, window=window)
+
+    def publish_version(
+        self, tool_schema_id: str, *, definition: str, source: str = "proposed",
+        reasoning: Optional[str] = None, based_on_version: Optional[int] = None,
+    ) -> dict:
+        return self._client.publish_tool_schema_version(
+            tool_schema_id, definition=definition, source=source,
+            reasoning=reasoning, based_on_version=based_on_version,
+        )

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/exceptions.py

@@ -15,6 +15,10 @@ class AgentXAuthError(AgentXError):
     """Invalid or missing API key."""
 
 
+class AgentXConnectionError(AgentXError):
+    """The AgentX API (or self-host engine) could not be reached at the configured base_url."""
+
+
 class AgentXAPIError(AgentXError):
     """Unexpected API error."""
 

agentx_python-0.6.29/agentx/monitor/agents.py

@@ -0,0 +1,28 @@
+"""Agent registry helpers, surfaced as ``client.monitor.agents`` (self-host).
+
+Agents in self-host are lightweight name rows - normally auto-created the first time a trace
+arrives under a name. These helpers exist for flows that need the agent id before any traffic
+(e.g. enabling a monitoring profile up front).
+"""
+from __future__ import annotations
+
+from typing import List, Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.monitor.client import MonitorClient
+
+
+class MonitorAgentClient:
+    def __init__(self, client: "MonitorClient"):
+        self._client = client
+
+    def list(self) -> List[dict]:
+        return self._client.list_agents()
+
+    def create(self, name: str) -> dict:
+        return self._client.create_agent(name)
+
+    def ensure(self, name: str) -> dict:
+        """Get-or-create by name - idempotent, safe to re-run."""
+        existing = next((a for a in self.list() if a.get("name") == name), None)
+        return existing if existing is not None else self.create(name)

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/monitor/client.py

@@ -84,6 +84,10 @@ class MonitorClient:
         self.signals = MonitorSignalClient(self)
         self.profile = MonitorProfileClient(self)
         self.online_evaluators = MonitorOnlineEvaluatorClient(self)
+        from agentx.monitor.sessions import MonitorSessionClient
+        from agentx.monitor.agents import MonitorAgentClient
+        self.sessions = MonitorSessionClient(self)
+        self.agents = MonitorAgentClient(self)
 
     # ------------------------------------------------------------------
     # Low-level HTTP
@@ -97,8 +101,17 @@ class MonitorClient:
     def _workspace_params(self) -> Optional[dict]:
         return {"workspaceId": self._workspace_id} if self._workspace_id else None
 
-    def _request(self, method: str, path: str, timeout: int = 30, **kwargs) -> Any:
-        url = f"{self._base_url}{path}"
+    def _api_root(self) -> str:
+        """The API base with the ``/monitor`` suffix removed - for the handful of self-host
+        routes that live on the engine's other routers (ingest sessions, agent-monitoring
+        calibration/tuning/portability), same precedent EvaluationsClient._api_root sets."""
+        suffix = "/monitor"
+        if self._base_url.endswith(suffix):
+            return self._base_url[: -len(suffix)]
+        return self._base_url
+
+    def _request(self, method: str, path: str, timeout: int = 30, base: Optional[str] = None, **kwargs) -> Any:
+        url = f"{base or self._base_url}{path}"
         last_exc: Optional[Exception] = None
         for attempt, wait in enumerate([0.0] + _RETRY_BACKOFF):
             if wait:
@@ -228,6 +241,80 @@ class MonitorClient:
         profile = data.get("profile")
         return MonitorProfile(**profile) if profile else None
 
+    # ------------------------------------------------------------------
+    # Agents (the engine's SDK-facing /agents router - self-host)
+    # ------------------------------------------------------------------
+
+    def list_agents(self) -> List[dict]:
+        data = self._request("GET", "/agents", base=self._api_root())
+        return data.get("agents", []) if isinstance(data, dict) else data
+
+    def create_agent(self, name: str) -> dict:
+        data = self._request("POST", "/agents", base=self._api_root(), json={"name": name})
+        return data.get("agent", data) if isinstance(data, dict) else data
+
+    # ------------------------------------------------------------------
+    # Sessions (self-host)
+    # ------------------------------------------------------------------
+
+    def run_session_coherence_check(self, session_id: str) -> dict:
+        """One judge call over the assembled session - the dashboard's "Check coherence"
+        button. Raises AgentXMonitorError if the engine has no judge key configured."""
+        data = self._request(
+            "POST", f"/agent-monitoring/sessions/{session_id}/coherence-check",
+            base=self._api_root(), timeout=180,
+        )
+        return data.get("score", data) if isinstance(data, dict) else data
+
+    def list_session_spans(self, session_id: str) -> List[dict]:
+        data = self._request("GET", f"/ingest/sessions/{session_id}/spans", base=self._api_root())
+        return data.get("spans", []) if isinstance(data, dict) else data
+
+    # ------------------------------------------------------------------
+    # Model portability (self-host): replay a trace's input against other models
+    # ------------------------------------------------------------------
+
+    def run_model_portability(self, trace_id: str, model_ids: List[str]) -> dict:
+        """Replay the trace's captured input against ``model_ids`` and judge each output -
+        the dashboard trace detail's "Compare models" action. One LLM call per candidate
+        plus judging, so expect tens of seconds."""
+        return self._request(
+            "POST", f"/agent-monitoring/traces/{trace_id}/portability",
+            base=self._api_root(), json={"modelIds": model_ids}, timeout=300,
+        )
+
+    # ------------------------------------------------------------------
+    # Judge tuning (self-host): calibrate an online evaluator against recorded
+    # ground truth, then rewrite/validate/publish its criteria
+    # ------------------------------------------------------------------
+
+    def get_online_evaluator_calibration(self, evaluator_id: str, window: str = "7d") -> dict:
+        return self._request(
+            "GET", f"/agent-monitoring/online-evaluators/{evaluator_id}/calibration",
+            base=self._api_root(), params={"window": window},
+        )
+
+    def propose_online_evaluator_tuning(self, evaluator_id: str, window: str = "7d") -> dict:
+        data = self._request(
+            "POST", f"/agent-monitoring/online-evaluators/{evaluator_id}/tune",
+            base=self._api_root(), json={"window": window}, timeout=300,
+        )
+        return data.get("proposal", data) if isinstance(data, dict) else data
+
+    def validate_online_evaluator_tuning(
+        self, evaluator_id: str, criteria: dict, window: str = "7d"
+    ) -> dict:
+        return self._request(
+            "POST", f"/agent-monitoring/online-evaluators/{evaluator_id}/tune/validate",
+            base=self._api_root(), json={**criteria, "window": window}, timeout=600,
+        )
+
+    def publish_online_evaluator_tuning(self, evaluator_id: str, criteria: dict) -> dict:
+        return self._request(
+            "POST", f"/agent-monitoring/online-evaluators/{evaluator_id}/tune/publish",
+            base=self._api_root(), json=criteria, timeout=60,
+        )
+
     def update_profile(self, agent_id: str, payload: dict) -> MonitorProfile:
         data = self._request(
             "PUT", f"/profiles/{agent_id}", json=self._with_workspace(payload)

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/monitor/online_evaluators.py

@@ -121,6 +121,27 @@ class MonitorOnlineEvaluatorClient:
     def delete(self, evaluator_id: str) -> None:
         self._client.delete_online_evaluator(evaluator_id)
 
+    def calibration(self, evaluator_id: str, window: str = "7d") -> dict:
+        """How often this evaluator's verdicts agreed with recorded ground truth (outcomes,
+        user feedback, human re-scores) in the window - including the disagreement cases a
+        tune() proposal would rewrite from."""
+        return self._client.get_online_evaluator_calibration(evaluator_id, window)
+
+    def tune(self, evaluator_id: str, window: str = "7d") -> dict:
+        """Judge-written rewrite of this evaluator's own criteria, grounded in calibration
+        disagreements. Returns the proposal (criteria + reasoning + changes); publishes nothing."""
+        return self._client.propose_online_evaluator_tuning(evaluator_id, window)
+
+    def validate_tuning(self, evaluator_id: str, criteria: dict, window: str = "7d") -> dict:
+        """Exact re-judging: candidate criteria re-judge the cases the current criteria got
+        wrong plus a control set they got right, measured against recorded reality. `criteria`
+        is {acceptanceCriteria, rejectionCriteria, evaluationCriteria} from tune()."""
+        return self._client.validate_online_evaluator_tuning(evaluator_id, criteria, window)
+
+    def publish_tuning(self, evaluator_id: str, criteria: dict) -> dict:
+        """Publish tuned criteria onto the evaluator's config (the human-approval step)."""
+        return self._client.publish_online_evaluator_tuning(evaluator_id, criteria)
+
     def ratings(self, evaluator_id: str, window: str = "7d") -> List[OnlineEvaluatorRatingPoint]:
         """Bucketed average-rating-over-time for this evaluator. ``window`` is one of
         ``"24h"``, ``"7d"``, ``"30d"``."""

agentx_python-0.6.29/agentx/monitor/sessions.py

@@ -0,0 +1,21 @@
+"""Session helpers, surfaced as ``client.monitor.sessions`` (self-host)."""
+from __future__ import annotations
+
+from typing import List, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from agentx.monitor.client import MonitorClient
+
+
+class MonitorSessionClient:
+    def __init__(self, client: "MonitorClient"):
+        self._client = client
+
+    def coherence_check(self, session_id: str) -> dict:
+        """Judge the assembled multi-turn session for consistency/drift (one judge call).
+        Returns the score row: rating, justification, spanCount, driftSpanId."""
+        return self._client.run_session_coherence_check(session_id)
+
+    def spans(self, session_id: str) -> List[dict]:
+        """Every span in the session (roots and children), oldest first."""
+        return self._client.list_session_spans(session_id)

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx/tracing/ingest_client.py

@@ -66,6 +66,12 @@ class IngestClient:
             }
         )
 
+        # First delivery failure per client logs at WARNING (visible under default logging) -
+        # the tracer is fire-and-forget by design, so a wrong base_url or rejected key would
+        # otherwise fail silently forever with an empty dashboard as the only symptom. Repeat
+        # failures stay at DEBUG to avoid log spam. client.ping() is the fail-fast startup check.
+        self._delivery_warning_emitted = False
+
         self._queue: queue.Queue[Optional[Dict[str, Any]]] = queue.Queue(maxsize=_QUEUE_MAX)
         self._worker = threading.Thread(target=self._drain, daemon=True, name="agentx-ingest")
         self._worker.start()
@@ -104,9 +110,11 @@ class IngestClient:
         try:
             resp = self._session.post(self._endpoint, json=payload, timeout=10)
         except requests.RequestException as exc:
+            self._warn_delivery(f"{exc.__class__.__name__}: {exc}")
             logger.debug("agentx ingest sync send error: %s", exc)
             return None
         if not resp.ok:
+            self._warn_delivery(f"HTTP {resp.status_code}", status=resp.status_code)
             logger.debug("agentx ingest sync HTTP %d: %s", resp.status_code, resp.text[:200])
             return None
         try:
@@ -310,6 +318,29 @@ class IngestClient:
     # Internal
     # ------------------------------------------------------------------
 
+    def _warn_delivery(self, detail: str, status: Optional[int] = None) -> None:
+        if self._delivery_warning_emitted:
+            return
+        self._delivery_warning_emitted = True
+        if status in (401, 403):
+            hint = (
+                "the API key was rejected - check api_key / AGENTX_API_KEY (for self-host, copy "
+                "the 'Default project API key' from the engine's startup log)"
+            )
+        else:
+            hint = (
+                "check base_url / AGENTX_API_BASE_URL (for self-host it should look like "
+                "http://localhost:4700/api/v1)"
+            )
+        logger.warning(
+            "AgentX traces are NOT being delivered to %s (%s) - %s. "
+            "Call client.ping() at startup to fail fast on misconfiguration. "
+            "Further delivery failures will log at DEBUG only.",
+            self._endpoint,
+            detail,
+            hint,
+        )
+
     def _drain(self) -> None:
         while True:
             payload = self._queue.get()
@@ -338,8 +369,10 @@ class IngestClient:
                 last_exc = Exception(f"HTTP {resp.status_code}")
                 continue
             if not resp.ok:
+                self._warn_delivery(f"HTTP {resp.status_code}", status=resp.status_code)
                 logger.debug("agentx ingest HTTP %d: %s", resp.status_code, resp.text[:200])
                 return
             return
 
+        self._warn_delivery(str(last_exc))
         logger.debug("agentx ingest failed after retries: %s", last_exc)

agentx_python-0.6.29/agentx/version.py

@@ -0,0 +1 @@
+VERSION = "0.6.29"

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.6.28
+Version: 0.6.29
 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

{agentx_python-0.6.28 → agentx_python-0.6.29}/agentx_python.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ agentx/evaluations/redaction.py
 agentx/evaluations/reporting.py
 agentx/evaluations/results.py
 agentx/evaluations/runner.py
+agentx/evaluations/tool_schemas.py
 agentx/evaluations/tracing.py
 agentx/evaluations/adapters/__init__.py
 agentx/evaluations/adapters/http_endpoint.py
@@ -41,11 +42,13 @@ agentx/integrations/moveworks.py
 agentx/integrations/openai.py
 agentx/integrations/openai_agents.py
 agentx/monitor/__init__.py
+agentx/monitor/agents.py
 agentx/monitor/client.py
 agentx/monitor/models.py
 agentx/monitor/online_evaluators.py
 agentx/monitor/patterns.py
 agentx/monitor/profile.py
+agentx/monitor/sessions.py
 agentx/monitor/signals.py
 agentx/resources/__init__.py
 agentx/resources/agent.py

agentx_python-0.6.28/agentx/version.py

@@ -1 +0,0 @@
-VERSION = "0.6.28"