agentx-python 0.6.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

agentx/integrations/_perf.py

@@ -29,11 +29,17 @@ def build_performance_summary(
         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.
-        tool_call_steps:    Tool / function call entries — same shape.
+                            ``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) and ``doc_count`` (int).
+                            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 []
@@ -63,6 +69,24 @@ def build_performance_summary(
             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"):
@@ -114,3 +138,89 @@ def build_performance_summary(
             "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/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/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/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,
             })

agentx/integrations/google_genai.py

@@ -16,7 +16,7 @@ Requires: ``pip install "agentx-python[google-genai]"``
 from __future__ import annotations
 
 import time
-from typing import Any, Dict, Optional
+from typing import Any, Dict, List, Optional
 
 from agentx.tracing.tracer import Tracer, _safe_serialize
 from agentx.integrations._perf import build_performance_summary
@@ -49,13 +49,18 @@ def patch_genai_client(
 
 
 def _extract_response_text(response: Any) -> Optional[str]:
-    """Pull the generated text out of a GenerateContentResponse."""
+    """
+    Pull the generated text out of a GenerateContentResponse, falling back to
+    a description of any function_call parts when the response is a pure
+    tool call with no text (Gemini function calling).
+    """
     # Convenience .text property (available on non-streaming responses)
     text = getattr(response, "text", None)
     if text and isinstance(text, str):
         return text
     # Fallback: walk candidates → content → parts
     candidates = getattr(response, "candidates", None) or []
+    function_calls: List[str] = []
     for candidate in candidates:
         content = getattr(candidate, "content", None)
         parts = getattr(content, "parts", None) or []
@@ -63,6 +68,13 @@ def _extract_response_text(response: Any) -> Optional[str]:
             t = getattr(part, "text", None)
             if t and isinstance(t, str):
                 return t
+            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 function_calls:
+        return "[tool call] " + ", ".join(function_calls)
     return None
 
 
@@ -100,6 +112,7 @@ def _patch_generate_content(
                 if usage is not None:
                     input_tokens = getattr(usage, "prompt_token_count", None)
                     output_tokens = getattr(usage, "candidates_token_count", None)
+            input_repr = contents if isinstance(contents, str) else _safe_serialize(contents)
             perf = build_performance_summary(
                 total_duration_ms=latency_ms,
                 execution_steps=[{
@@ -107,12 +120,17 @@ def _patch_generate_content(
                     "duration_ms": latency_ms,
                     "start_time": start_t,
                     "end_time": end_t,
+                    "model": str(model) if model else None,
+                    "input": input_repr,
+                    "output": output,
+                    "inputTokenSize": input_tokens,
+                    "outputTokenSize": output_tokens,
                 }],
                 has_errors=error is not None,
             )
             tracer._send(
                 name=name,
-                input=contents if isinstance(contents, str) else _safe_serialize(contents),
+                input=input_repr,
                 output=output,
                 latency_ms=latency_ms,
                 error=error,
@@ -169,6 +187,8 @@ def _patch_generate_content_stream(
             if last_usage_metadata is not None:
                 input_tokens = getattr(last_usage_metadata, "prompt_token_count", None)
                 output_tokens = getattr(last_usage_metadata, "candidates_token_count", None)
+            input_repr = contents if isinstance(contents, str) else _safe_serialize(contents)
+            output_repr = "".join(accumulated_text) or None
             perf = build_performance_summary(
                 total_duration_ms=latency_ms,
                 execution_steps=[{
@@ -176,13 +196,18 @@ def _patch_generate_content_stream(
                     "duration_ms": latency_ms,
                     "start_time": start_t,
                     "end_time": end_t,
+                    "model": str(model) if model else None,
+                    "input": input_repr,
+                    "output": output_repr,
+                    "inputTokenSize": input_tokens,
+                    "outputTokenSize": output_tokens,
                 }],
                 has_errors=error is not None,
             )
             tracer._send(
                 name=name,
-                input=contents if isinstance(contents, str) else _safe_serialize(contents),
-                output="".join(accumulated_text) or None,
+                input=input_repr,
+                output=output_repr,
                 latency_ms=latency_ms,
                 error=error,
                 framework="google-genai",