agentx-python 0.6.1__tar.gz → 0.6.3__tar.gz

{agentx_python-0.6.1/agentx_python.egg-info → agentx_python-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-python
-Version: 0.6.1
+Version: 0.6.3
 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.3/agentx/integrations/_perf.py

@@ -0,0 +1,226 @@
+"""
+Shared helper for building a performance_summary that matches the AgentX
+platform agent format.
+
+External framework integrations collect:
+  - execution_steps  — LLM inference calls (name, duration_ms, start_time, end_time)
+  - tool_call_steps  — function/tool invocations (same shape)
+
+``build_performance_summary`` merges them into the full structure expected by
+the backend ingest endpoint and the AgentX UI.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def build_performance_summary(
+    total_duration_ms: float,
+    execution_steps: Optional[List[Dict[str, Any]]] = None,
+    tool_call_steps: Optional[List[Dict[str, Any]]] = None,
+    retrieval_steps: Optional[List[Dict[str, Any]]] = None,
+    has_errors: bool = False,
+) -> Dict[str, Any]:
+    """
+    Return a ``performance_summary`` dict compatible with the AgentX platform
+    agent format.
+
+    Args:
+        total_duration_ms:  Wall-clock duration of the entire run.
+        execution_steps:    LLM call entries — each must have ``name``,
+                            ``duration_ms``, and optionally ``start_time`` /
+                            ``end_time`` as Unix floats, plus ``model``,
+                            ``input``, ``output``, ``inputTokenSize``,
+                            ``outputTokenSize`` for per-call drill-down.
+        tool_call_steps:    Tool / function call entries — same shape, plus
+                            optional ``input`` / ``output``.
+        retrieval_steps:    RAG / vector-store retrieval entries — same shape,
+                            plus optional ``query`` (str), ``doc_count`` (int)
+                            and ``output`` (the retrieved content).
+        has_errors:         Set to True when the run ended with an exception.
+
+    None of these fields are truncated here — callers decide what to capture.
+    """
+    execution_steps = execution_steps or []
+    tool_call_steps = tool_call_steps or []
+    retrieval_steps = retrieval_steps or []
+
+    # Merge all items with their phase type, sort by start_time
+    all_items: List[tuple[Dict[str, Any], str]] = (
+        [(s, "execution_step") for s in execution_steps]
+        + [(t, "tool_call") for t in tool_call_steps]
+        + [(r, "retrieval") for r in retrieval_steps]
+    )
+    all_items.sort(key=lambda x: x[0].get("start_time") or 0)
+
+    unified: List[Dict[str, Any]] = []
+    out_steps: List[Dict[str, Any]] = []
+    out_tools: List[Dict[str, Any]] = []
+    out_retrievals: List[Dict[str, Any]] = []
+
+    for order, (item, phase_type) in enumerate(all_items, start=1):
+        entry: Dict[str, Any] = {
+            "name": item["name"],
+            "duration_ms": round(float(item["duration_ms"]), 3),
+            "start_order": order,
+            "phase_type": phase_type,
+        }
+        if item.get("start_time") is not None:
+            entry["start_time"] = item["start_time"]
+        if item.get("end_time") is not None:
+            entry["end_time"] = item["end_time"]
+        # Per-step drill-down detail — untruncated, present when the caller
+        # captured it (e.g. an LLM call's model/prompt/completion, a tool
+        # call's args/result, or a retrieval's returned documents).
+        if item.get("model"):
+            entry["model"] = item["model"]
+        if item.get("input") is not None:
+            entry["input"] = item["input"]
+        if item.get("output") is not None:
+            entry["output"] = item["output"]
+        # Per-call token usage — populated for LLM call execution_steps by
+        # integrations that read it off the provider response (e.g. Anthropic's
+        # response.usage), so performance_summary carries a token breakdown
+        # per call, not just the trace-level input_tokens/output_tokens total.
+        # Named to match PromptTrace.inputTokenSize/outputTokenSize on the backend.
+        if item.get("inputTokenSize") is not None:
+            entry["inputTokenSize"] = item["inputTokenSize"]
+        if item.get("outputTokenSize") is not None:
+            entry["outputTokenSize"] = item["outputTokenSize"]
+        # Retrieval-specific fields
+        if phase_type == "retrieval":
+            if item.get("query"):
+                entry["query"] = item["query"]
+            if item.get("doc_count") is not None:
+                entry["doc_count"] = item["doc_count"]
+        unified.append(entry)
+
+        flat = {k: v for k, v in entry.items() if k != "phase_type"}
+        if phase_type == "execution_step":
+            out_steps.append(flat)
+        elif phase_type == "tool_call":
+            out_tools.append(flat)
+        else:
+            out_retrievals.append(flat)
+
+    tools_total_ms = round(sum(t["duration_ms"] for t in out_tools), 3)
+    retrievals_total_ms = round(sum(r["duration_ms"] for r in out_retrievals), 3)
+
+    return {
+        "total_duration_ms": round(float(total_duration_ms), 3),
+        "todo_tasks_enabled": None,
+        "main_phases": [],
+        "tool_calls": out_tools,
+        "mcp_tool_calls": [],
+        "action_tool_calls": [],
+        "delegate_calls": [],
+        "execution_steps": out_steps,
+        "knowledge_retrievals": out_retrievals,
+        "todo_operations": [],
+        "detailed_phases": [],
+        "active_phases": [],
+        "has_errors": has_errors,
+        "memory_actions": None,
+        "unified_timeline": unified,
+        "statistics": {
+            "total_main_phases": 0,
+            "total_tool_calls": len(out_tools),
+            "total_mcp_tool_calls": 0,
+            "total_action_tool_calls": 0,
+            "total_delegate_calls": 0,
+            "total_execution_steps": len(out_steps),
+            "total_knowledge_retrievals": len(out_retrievals),
+            "total_todo_operations": 0,
+            "main_phases_total_ms": 0,
+            "tool_calls_total_ms": tools_total_ms,
+            "knowledge_retrievals_total_ms": retrievals_total_ms,
+            "mcp_tool_calls_total_ms": 0,
+            "todo_operations_total_ms": 0,
+        },
+    }
+
+
+def _merge_steps(
+    summary: Dict[str, Any],
+    steps: List[Dict[str, Any]],
+    *,
+    phase_type: str,
+    target_key: str,
+    stats_count_key: str,
+    stats_total_ms_key: str,
+    extra_fields: tuple = (),
+    default_name_prefix: str = "Step",
+) -> Dict[str, Any]:
+    """Fold externally-recorded steps into an already-built ``performance_summary``."""
+    if not steps:
+        return summary
+
+    next_order = len(summary.get("unified_timeline", [])) + 1
+    for i, item in enumerate(steps):
+        entry: Dict[str, Any] = {
+            "name": item.get("name") or f"{default_name_prefix} {i + 1}",
+            "duration_ms": round(float(item.get("duration_ms") or 0), 3),
+            "start_order": next_order + i,
+            "phase_type": phase_type,
+        }
+        if item.get("start_time") is not None:
+            entry["start_time"] = item["start_time"]
+        if item.get("end_time") is not None:
+            entry["end_time"] = item["end_time"]
+        for field in extra_fields:
+            value = item.get(field)
+            if value not in (None, ""):
+                entry[field] = value
+
+        summary["unified_timeline"].append(entry)
+        summary[target_key].append({k: v for k, v in entry.items() if k != "phase_type"})
+
+    summary["unified_timeline"].sort(key=lambda x: x.get("start_time") or 0)
+    summary["statistics"][stats_count_key] = len(summary[target_key])
+    summary["statistics"][stats_total_ms_key] = round(
+        sum(r["duration_ms"] for r in summary[target_key]), 3
+    )
+    return summary
+
+
+def merge_retrieval_steps(
+    summary: Dict[str, Any],
+    retrieval_steps: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """
+    Fold externally-recorded retrieval steps (e.g. from ``Tracer.record_retrieval``,
+    used for hand-rolled RAG lookups the framework integration can't see) into an
+    already-built ``performance_summary``.
+    """
+    return _merge_steps(
+        summary,
+        retrieval_steps,
+        phase_type="retrieval",
+        target_key="knowledge_retrievals",
+        stats_count_key="total_knowledge_retrievals",
+        stats_total_ms_key="knowledge_retrievals_total_ms",
+        extra_fields=("query", "doc_count", "output"),
+        default_name_prefix="Retrieval",
+    )
+
+
+def merge_tool_call_steps(
+    summary: Dict[str, Any],
+    tool_call_steps: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    """
+    Fold externally-recorded tool calls (e.g. from ``Tracer.record_tool_call``,
+    used when a tool executes outside a framework integration's visibility —
+    such as a manual Anthropic tool-use loop) into an already-built
+    ``performance_summary``.
+    """
+    return _merge_steps(
+        summary,
+        tool_call_steps,
+        phase_type="tool_call",
+        target_key="tool_calls",
+        stats_count_key="total_tool_calls",
+        stats_total_ms_key="tool_calls_total_ms",
+        extra_fields=("input", "output"),
+        default_name_prefix="Tool Call",
+    )

{agentx_python-0.6.1 → agentx_python-0.6.3}/agentx/integrations/anthropic.py

@@ -22,6 +22,34 @@ from agentx.tracing.tracer import Tracer, _safe_serialize
 from agentx.integrations._perf import build_performance_summary
 
 
+def _extract_output_text(response: Any) -> Optional[str]:
+    """
+    Extract the assistant's text reply from a Messages API response, falling
+    back to a description of any tool_use blocks when the response is a pure
+    tool call with no accompanying text.
+    """
+    content = getattr(response, "content", None) if response is not None else None
+    if not content:
+        return None
+    texts = []
+    tool_calls = []
+    for block in content:
+        block_type = getattr(block, "type", None)
+        if block_type == "text":
+            text = getattr(block, "text", None)
+            if text:
+                texts.append(text)
+        elif block_type == "tool_use":
+            name = getattr(block, "name", "unknown")
+            tool_input = getattr(block, "input", None)
+            tool_calls.append(f"{name}({tool_input})")
+    if texts:
+        return "\n".join(texts)
+    if tool_calls:
+        return "[tool call] " + ", ".join(tool_calls)
+    return None
+
+
 def patch_anthropic_client(
     client: Any,
     tracer: Tracer,
@@ -77,10 +105,7 @@ def _patch_create(
             input_tokens = None
             output_tokens = None
             if response is not None:
-                try:
-                    output = response.content[0].text if response.content else None
-                except Exception:
-                    output = str(response)[:500]
+                output = _extract_output_text(response)
                 try:
                     usage = getattr(response, "usage", None)
                     if usage is not None:
@@ -88,30 +113,54 @@ def _patch_create(
                         output_tokens = getattr(usage, "output_tokens", None)
                 except Exception:
                     pass
-            perf = build_performance_summary(
-                total_duration_ms=latency_ms,
-                execution_steps=[{
-                    "name": "LLM Call 1",
-                    "duration_ms": latency_ms,
-                    "start_time": start_t,
-                    "end_time": end_t,
-                }],
-                has_errors=error is not None,
-            )
-            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,
-                performance_summary=perf,
-                input_tokens=input_tokens,
-                output_tokens=output_tokens,
-            )
+
+            active_span = tracer.current_span
+            if active_span is not None:
+                # Part of a `with tracer.trace(...)` block (e.g. a multi-call
+                # agentic loop) — attach as one LLM-call step on that span's
+                # trace instead of sending an independent trace per call.
+                if error is not None:
+                    active_span.set_error(error)
+                active_span._record_llm_call(
+                    duration_ms=latency_ms,
+                    start_time=start_t,
+                    end_time=end_t,
+                    input=_safe_serialize(input_messages),
+                    output=output,
+                    model=model,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                )
+            else:
+                perf = build_performance_summary(
+                    total_duration_ms=latency_ms,
+                    execution_steps=[{
+                        "name": "LLM Call 1",
+                        "duration_ms": latency_ms,
+                        "start_time": start_t,
+                        "end_time": end_t,
+                        "model": model,
+                        "input": _safe_serialize(input_messages),
+                        "output": output,
+                        "inputTokenSize": input_tokens,
+                        "outputTokenSize": output_tokens,
+                    }],
+                    has_errors=error is not None,
+                )
+                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,
+                    performance_summary=perf,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                )
 
     patched_create._agentx_patched = True
     messages_resource.create = patched_create
@@ -148,7 +197,7 @@ def _patch_stream(
                 output_tokens = None
                 try:
                     final = ctx.get_final_message()
-                    output = final.content[0].text if final.content else None
+                    output = _extract_output_text(final)
                     usage = getattr(final, "usage", None)
                     if usage is not None:
                         input_tokens = getattr(usage, "input_tokens", None)
@@ -162,6 +211,11 @@ def _patch_stream(
                         "duration_ms": latency_ms,
                         "start_time": start_t,
                         "end_time": end_t,
+                        "model": kwargs.get("model"),
+                        "input": _safe_serialize(kwargs.get("messages")),
+                        "output": output,
+                        "inputTokenSize": input_tokens,
+                        "outputTokenSize": output_tokens,
                     }],
                     has_errors=error is not None,
                 )

{agentx_python-0.6.1 → agentx_python-0.6.3}/agentx/integrations/crewai.py

@@ -22,6 +22,7 @@ import time
 from typing import Any, Dict, Optional
 
 from agentx.tracing.tracer import Tracer, _safe_serialize
+from agentx.integrations._perf import build_performance_summary
 
 
 class AgentXCrewObserver:
@@ -64,15 +65,38 @@ class AgentXCrewObserver:
 
             # Collect task outputs as tool_calls for observability
             tool_calls = []
+            execution_steps = []
             if result is not None:
                 task_outputs = getattr(result, "tasks_output", []) or []
                 for task_out in task_outputs:
+                    description = getattr(task_out, "description", "task")
+                    name = description[:100]  # display label only — full text goes in "input"
+                    task_output = str(getattr(task_out, "raw", ""))
                     tool_calls.append(
                         {
-                            "name": getattr(task_out, "description", "task")[:100],
-                            "output": str(getattr(task_out, "raw", ""))[:500],
+                            "name": name,
+                            "input": description,
+                            "output": task_output,
                         }
                     )
+                    execution_steps.append({
+                        "name": name,
+                        "duration_ms": 0,
+                        "input": description,
+                        "output": task_output,
+                    })
+
+            if not execution_steps:
+                # No per-task breakdown available — record the whole kickoff
+                # as a single step so the trace still gets timing detail.
+                execution_steps.append({"name": self._name, "duration_ms": latency_ms})
+            else:
+                # Task-level timing isn't exposed by CrewOutput; attribute the
+                # total latency evenly across tasks so the timeline still sums
+                # to the measured wall-clock duration.
+                per_step_ms = latency_ms / len(execution_steps)
+                for step in execution_steps:
+                    step["duration_ms"] = per_step_ms
 
             self._tracer._send(
                 name=self._name,
@@ -84,6 +108,11 @@ class AgentXCrewObserver:
                 tool_calls=tool_calls or None,
                 metadata=self._metadata,
                 session_id=self._session_id,
+                performance_summary=build_performance_summary(
+                    total_duration_ms=latency_ms,
+                    execution_steps=execution_steps,
+                    has_errors=error is not None,
+                ),
             )
 
     def observe(

{agentx_python-0.6.1 → agentx_python-0.6.3}/agentx/integrations/google_adk.py

@@ -36,7 +36,11 @@ except ImportError as exc:  # pragma: no cover
 
 
 def _content_to_text(content: Any) -> Optional[str]:
-    """Extract plain text from a google.genai types.Content object."""
+    """
+    Extract plain text from a google.genai types.Content object, falling back
+    to a description of any function_call parts when there's no text (Gemini
+    function calling — the model responded with a pure tool call).
+    """
     if content is None:
         return None
     if isinstance(content, str):
@@ -45,11 +49,32 @@ def _content_to_text(content: Any) -> Optional[str]:
     if not parts:
         return None
     texts = []
+    function_calls = []
     for part in parts:
         text = getattr(part, "text", None)
         if text and isinstance(text, str):
             texts.append(text)
-    return " ".join(texts) if texts else None
+            continue
+        fc = getattr(part, "function_call", None)
+        if fc is not None:
+            name = getattr(fc, "name", "unknown")
+            args = getattr(fc, "args", None)
+            function_calls.append(f"{name}({args})")
+    if texts:
+        return " ".join(texts)
+    if function_calls:
+        return "[tool call] " + ", ".join(function_calls)
+    return None
+
+
+def _contents_to_text(contents: Any) -> Optional[str]:
+    """Extract plain text from an LlmRequest's ``contents`` (a list of Content)."""
+    if contents is None:
+        return None
+    if not isinstance(contents, (list, tuple)):
+        contents = [contents]
+    texts = [t for t in (_content_to_text(c) for c in contents) if t]
+    return "\n".join(texts) if texts else None
 
 
 class AgentXADKPlugin(BasePlugin):
@@ -152,25 +177,31 @@ class AgentXADKPlugin(BasePlugin):
     ) -> None:
         inv_id = callback_context.get_invocation_context().invocation_id
         state = self._runs.get(inv_id)
-        if state and not state["model"]:
-            model = getattr(llm_request, "model", None)
-            if model:
-                state["model"] = str(model)
-        # Push start time onto the per-invocation stack.
+        model = getattr(llm_request, "model", None)
+        model_str = str(model) if model else None
+        if state and not state["model"] and model_str:
+            state["model"] = model_str
+        # Push start time + this call's model/input onto the per-invocation
+        # stack, so after_model_callback can pair them back up.
         # ADK creates different CallbackContext objects for before vs after, so
         # id(callback_context) cannot be used as a key across the two calls.
         if inv_id not in self._model_starts:
             self._model_starts[inv_id] = []
-        self._model_starts[inv_id].append(time.time())
+        self._model_starts[inv_id].append({
+            "start": time.time(),
+            "model": model_str,
+            "input": _contents_to_text(getattr(llm_request, "contents", None)),
+        })
 
     async def after_model_callback(
         self, *, callback_context: Any, llm_response: Any
     ) -> None:
         inv_id = callback_context.get_invocation_context().invocation_id
         state = self._runs.get(inv_id)
-        # Pop the earliest queued start time (FIFO — model calls are sequential)
+        # Pop the earliest queued call (FIFO — model calls are sequential)
         starts = self._model_starts.get(inv_id, [])
-        start_t = starts.pop(0) if starts else None
+        call_start = starts.pop(0) if starts else None
+        start_t = call_start.get("start") if call_start else None
         end_t = time.time()
 
         if state is None:
@@ -182,6 +213,15 @@ class AgentXADKPlugin(BasePlugin):
         if text:
             state["output"] = text
 
+        # Token counts for this call
+        usage = getattr(llm_response, "usage_metadata", None)
+        call_input_tokens = getattr(usage, "prompt_token_count", None) if usage is not None else None
+        call_output_tokens = getattr(usage, "candidates_token_count", None) if usage is not None else None
+        if call_input_tokens is not None:
+            state["input_tokens"] += int(call_input_tokens)
+        if call_output_tokens is not None:
+            state["output_tokens"] += int(call_output_tokens)
+
         # Execution step
         if start_t is not None:
             steps = state["execution_steps"]
@@ -190,14 +230,13 @@ class AgentXADKPlugin(BasePlugin):
                 "duration_ms": (end_t - start_t) * 1000,
                 "start_time": start_t,
                 "end_time": end_t,
+                "model": call_start.get("model") if call_start else None,
+                "input": call_start.get("input") if call_start else None,
+                "output": text,
+                "inputTokenSize": call_input_tokens,
+                "outputTokenSize": call_output_tokens,
             })
 
-        # Token counts
-        usage = getattr(llm_response, "usage_metadata", None)
-        if usage is not None:
-            state["input_tokens"] += int(getattr(usage, "prompt_token_count", None) or 0)
-            state["output_tokens"] += int(getattr(usage, "candidates_token_count", None) or 0)
-
     # ------------------------------------------------------------------
     # Tool callbacks
     # ------------------------------------------------------------------
@@ -222,10 +261,12 @@ class AgentXADKPlugin(BasePlugin):
         start_t = self._tool_starts.pop(id(tool_context), None)
         end_t = time.time()
         tool_name = getattr(tool, "name", "unknown")
+        tool_input = _safe_serialize(tool_args)
+        tool_output = str(result) if result is not None else None
         tool_call: Dict[str, Any] = {
             "name": tool_name,
-            "input": _safe_serialize(tool_args),
-            "output": str(result)[:500] if result is not None else None,
+            "input": tool_input,
+            "output": tool_output,
         }
         if start_t is not None:
             tool_call["latency_ms"] = max(0, int((end_t - start_t) * 1000))
@@ -236,6 +277,8 @@ class AgentXADKPlugin(BasePlugin):
                 "duration_ms": (end_t - start_t) * 1000,
                 "start_time": start_t,
                 "end_time": end_t,
+                "input": tool_input,
+                "output": tool_output,
             })
 
     async def on_tool_error_callback(
@@ -253,10 +296,12 @@ class AgentXADKPlugin(BasePlugin):
         start_t = self._tool_starts.pop(id(tool_context), None)
         end_t = time.time()
         tool_name = getattr(tool, "name", "unknown")
+        tool_input = _safe_serialize(tool_args)
+        tool_output = f"ERROR: {error}"
         tool_call: Dict[str, Any] = {
             "name": tool_name,
-            "input": _safe_serialize(tool_args),
-            "output": f"ERROR: {error}",
+            "input": tool_input,
+            "output": tool_output,
         }
         if start_t is not None:
             tool_call["latency_ms"] = max(0, int((end_t - start_t) * 1000))
@@ -267,4 +312,6 @@ class AgentXADKPlugin(BasePlugin):
                 "duration_ms": (end_t - start_t) * 1000,
                 "start_time": start_t,
                 "end_time": end_t,
+                "input": tool_input,
+                "output": tool_output,
             })