From 80bddf2a0530ef31751453c22549d679fee55019 Mon Sep 17 00:00:00 2001 From: Robin Date: Wed, 26 Aug 2026 01:17:11 -0700 Subject: [PATCH 1/2] feat(tracing): spans state their kind The tracer knew what every span was and said so for exactly one of them. record_retrieval stamped metadata.kind = "retrieval", because the RAG judges needed {context} and nothing else would do. Tool spans and LLM spans carried no marker at all, so the backend guessed - and the UI's guess ended in "everything else is a tool", which drew tool calls that never happened. child_span now takes span_kind and puts it on the wire, and the three places that already know stamp it: trace_tool_call and the merged framework tool calls say "tool", merged LLM steps say "llm", retrievals say "retrieval" alongside the metadata they already wrote. The LangChain handler's own span tree does the same, including "chain" for the graph nodes it emits. The flat tool_calls dual-write is untouched. That list is what the engine's Tool failure check reads and it is a different thing from the span's kind - one is "this interaction made these calls", the other is "this span is a call". Nothing here is required: a span that says nothing still classifies the way it did, by the backend's fallback ladder. Stating it just means the answer stops depending on whether the span happened to be named "LLM Call N". Co-Authored-By: Claude Fable 5 --- agentx/integrations/langchain.py | 4 ++++ agentx/tracing/tracer.py | 13 +++++++++++++ 2 files changed, 17 insertions(+) diff --git a/agentx/integrations/langchain.py b/agentx/integrations/langchain.py index 1bf5bd6..c8fce1f 100644 --- a/agentx/integrations/langchain.py +++ b/agentx/integrations/langchain.py @@ -455,6 +455,7 @@ def resolve_parent(parent_id: Any): input=node.get("input"), output=node.get("output"), error=node.get("error"), + span_kind="chain", ) llm_count = 0 @@ -470,6 +471,7 @@ def resolve_parent(parent_id: Any): model=step.get("model"), input_tokens=step.get("inputTokenSize"), output_tokens=step.get("outputTokenSize"), + span_kind="llm", ) for tc in tool_calls: resolve_parent(tc.get("parent_run_id")).child_span( @@ -480,6 +482,7 @@ def resolve_parent(parent_id: Any): input=tc.get("input"), output=tc.get("output"), error=None if tc.get("success", True) else str(tc.get("output") or "Tool call failed"), + span_kind="tool", ) for step in state.get("retrieval_steps", []): resolve_parent(step.get("parent_run_id")).child_span( @@ -490,6 +493,7 @@ def resolve_parent(parent_id: Any): input=step.get("query"), output=step.get("output"), metadata={"kind": "retrieval"}, + span_kind="retrieval", ) def on_chain_end( diff --git a/agentx/tracing/tracer.py b/agentx/tracing/tracer.py index ce8460c..a686625 100644 --- a/agentx/tracing/tracer.py +++ b/agentx/tracing/tracer.py @@ -262,6 +262,7 @@ def child_span( error: Optional[str] = None, tool_calls: Optional[List[Dict[str, Any]]] = None, metadata: Optional[Dict[str, Any]] = None, + span_kind: Optional[str] = None, ) -> "_TraceSpan": """ Send one real child-span row parented to this span, with explicit timing (the caller's @@ -318,6 +319,11 @@ def child_span( wire["tool_calls"] = child.tool_calls if metadata: wire["metadata"] = _safe_serialize(metadata) + # What kind of step this is, stated rather than left for the backend to guess from the + # span's name and which columns happen to be null. Same idea as LangSmith's run_type and + # Langfuse's observation type; the engine folds other vocabularies onto its own. + if span_kind: + wire["span_kind"] = span_kind if child._session_id: wire["session_id"] = child._session_id wire["span_id"] = child._span_id @@ -383,6 +389,9 @@ def _merge_child_run( output_tokens=step.get("outputTokenSize"), cache_read_tokens=step.get("cacheReadTokenSize"), cache_write_tokens=step.get("cacheWriteTokenSize"), + # Stated, so a step named anything other than "LLM Call N" still classifies - + # the backend's name regex was the only thing holding this together. + span_kind="llm", ) for tc in tool_calls or []: # Some callers' tool_calls dicts (e.g. langchain.py's, which sets these on the @@ -399,6 +408,7 @@ def _merge_child_run( input=tc.get("input"), output=tc.get("output"), error=None if tc.get("success", True) else str(tc.get("output") or "Tool call failed"), + span_kind="tool", ) # Also mirror onto this span's own flat tool_calls list, sent in this span's own # wire payload on __exit__ (see tool_calls=self.tool_calls or None below). The @@ -424,6 +434,7 @@ def _merge_child_run( input=step.get("query"), output=step.get("output"), metadata={"kind": "retrieval"}, + span_kind="retrieval", ) if self.input is None and input is not None: @@ -665,6 +676,7 @@ def record_tool_call( input=input, output=output, error=error, + span_kind="tool", ) # The child span above is only for the trace detail's span tree - the engine's # built-in "Tool failure" check and the dashboard's Tool quality column read the @@ -781,6 +793,7 @@ def record_retrieval( input=query, output=output, metadata={"kind": "retrieval"}, + span_kind="retrieval", ) @contextmanager From 76e9d5b486b73e613541da7116dba839148d9dda Mon Sep 17 00:00:00 2001 From: Robin Date: Wed, 26 Aug 2026 01:42:43 -0700 Subject: [PATCH 2/2] feat(tracing): root spans can state their kind too child_span took span_kind; tracer.trace() did not, so the one span that most often knows what it is - the root - had no way to say. An agentic turn and a single flat LLM call both arrive as a root carrying a model, and the engine deliberately refuses to guess between them from structure alone, which leaves saying so as the only way to tell them apart. with client.tracer.trace("rag-agent", span_kind="agent") as span: Optional, as everywhere else: a root that says nothing classifies the way it always did. Co-Authored-By: Claude Fable 5 --- agentx/tracing/tracer.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/agentx/tracing/tracer.py b/agentx/tracing/tracer.py index a686625..bf33311 100644 --- a/agentx/tracing/tracer.py +++ b/agentx/tracing/tracer.py @@ -71,6 +71,7 @@ def __init__( monitor: bool = False, pattern_ids: Optional[List[str]] = None, agent_id: Optional[str] = None, + span_kind: Optional[str] = None, ) -> None: self._tracer = tracer self.name = name @@ -84,6 +85,10 @@ def __init__( # from a prior GET /agents lookup) to pin this trace to that exact agent. None (the # default) resolves from `name` alone server-side, one stable agent per distinct name. self._agent_id = agent_id + # What kind of step this span is ("agent", "llm", ...), stated rather than left to the + # backend's fallback ladder. Optional: a root that says nothing still classifies the way + # it always did, which for the common flat trace (root carries the model) is "llm". + self._span_kind = span_kind # When True, __exit__ sends synchronously (blocking) instead of enqueueing, so trace_id # is populated by the time the `with` block exits - see Tracer.trace()'s sync param. self._sync = sync @@ -183,6 +188,7 @@ def __exit__(self, exc_type, exc_val, tb): cache_write_tokens=self._cache_write_tokens or None, span_id=self._span_id, parent_span_id=self._parent_span_id, + span_kind=self._span_kind, started_at_unix_nano=str(int(self._start * 1_000_000_000)) if self._start else None, ) return False # never suppress exceptions @@ -836,6 +842,7 @@ def trace( monitor: Optional[bool] = None, pattern_ids: Optional[List[str]] = None, agent_id: Optional[str] = None, + span_kind: Optional[str] = None, ) -> _TraceSpan: """ Return a :class:`_TraceSpan` that works as both a decorator and a @@ -901,6 +908,7 @@ def trace( monitor=monitor, pattern_ids=pattern_ids, agent_id=agent_id, + span_kind=span_kind, ) def flush(self, timeout: float = 5.0) -> bool: @@ -1140,6 +1148,8 @@ def _send(self, sync: bool = False, **kwargs) -> Optional[str]: wire["started_at_unix_nano"] = payload["started_at_unix_nano"] if "agent_id" in payload: wire["agent_id"] = payload["agent_id"] + if "span_kind" in payload: + wire["span_kind"] = payload["span_kind"] pending_tool_calls, self._pending_tool_calls = self._pending_tool_calls, [] if pending_tool_calls: