trace-agent-server 0.0.3__tar.gz → 0.2.0__tar.gz

trace_agent_server-0.2.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: trace-agent-server
+Version: 0.2.0
+Summary: TraceAgent FastAPI backend server.
+Author-email: Enrique Javier Villar Cea <villarcea.enriquejavier@gmail.com>, Javier Rodriguez Castellano <javirodriguezcastellano@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/LixusSoftware/TraceAgent
+Project-URL: Repository, https://github.com/LixusSoftware/TraceAgent
+Project-URL: Issues, https://github.com/LixusSoftware/TraceAgent/issues
+Keywords: agent,observability,tracing,llm,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: trace-agent-sdk
+Requires-Dist: fastapi<1.0.0,>=0.115.0
+Requires-Dist: httpx<1.0.0,>=0.27.0
+Requires-Dist: openai<4.0.0,>=1.52.0
+Requires-Dist: opentelemetry-proto<2.0.0,>=1.28.0
+Requires-Dist: pydantic<3.0.0,>=2.8.0
+Requires-Dist: pydantic-settings<3.0.0,>=2.3.0
+Requires-Dist: sqlalchemy<3.0.0,>=2.0.32
+Requires-Dist: uvicorn[standard]<1.0.0,>=0.30.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0.0,>=8.3.2; extra == "dev"
+Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == "dev"
+Provides-Extra: providers
+Requires-Dist: anthropic>=0.42.0; extra == "providers"
+Requires-Dist: google-generativeai>=0.8.0; extra == "providers"
+Provides-Extra: langchain
+Requires-Dist: trace-agent-langchain; extra == "langchain"
+Provides-Extra: pydantic-ai
+Requires-Dist: trace-agent-pydantic-ai; extra == "pydantic-ai"
+
+# TraceAgent Server
+
+![GitHub Release](https://img.shields.io/github/v/release/LixusSoftware/TraceAgent)
+![GitHub Stars](https://img.shields.io/github/stars/LixusSoftware/TraceAgent)
+![GitHub License](https://img.shields.io/github/license/LixusSoftware/TraceAgent)
+![Tests](https://github.com/LixusSoftware/TraceAgent/actions/workflows/test.yml/badge.svg)
+![Docker Build](https://github.com/LixusSoftware/TraceAgent/actions/workflows/build-docker.yml/badge.svg)
+[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)
+
+FastAPI backend for TraceAgent. Stores runs, generates timelines, execution graphs, and explanations.
+
+## Install
+
+```bash
+pip install trace-agent-server[providers]
+```
+
+## Run
+
+```bash
+# With the included CLI
+trace-agent-server --host 0.0.0.0 --port 8000
+
+# Or directly with uvicorn
+uvicorn trace_agent_server.main:app --reload
+```
+
+## Tracing agents through OpenTelemetry
+
+The server is also an OTLP/HTTP receiver: an agent that already emits OpenTelemetry spans following the
+[GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (Pydantic AI does) is
+traced by pointing its exporter at `POST /v1/traces`, with nothing from TraceAgent installed in the agent.
+
+```python
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from pydantic_ai import Agent
+from pydantic_ai.capabilities import Instrumentation
+from pydantic_ai.models.instrumented import InstrumentationSettings
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:8000/v1/traces")))
+
+agent = Agent("openai:gpt-4o", capabilities=[Instrumentation(settings=InstrumentationSettings(tracer_provider=provider))])
+agent.run_sync("hello")
+provider.shutdown()  # a short script must flush before exiting
+```
+
+- One run is created per trace (the trace id is the run id), named after `gen_ai.agent.name`. Add a `trace_agent.run_id`
+  resource attribute to attach the spans to a run you created with the SDK instead.
+- `invoke_agent` spans become chain steps, `chat` spans model calls and `execute_tool` spans tools. Event times and
+  durations come from the spans; the run gets its provider, model, token totals and tool counters. Other spans are ignored.
+- The run ends when its last agent span ends, also when the agent runs under a web server span or calls other agents.
+- An agent whose output goes through an output function (`output_type=my_function`) also records that function as a tool
+  (`final_result` by default), because Pydantic AI emits an `execute_tool` span for it. It counts in the run's tool total
+  and shows up as a tool choice. The framework capability only records the agent's regular tools, so the two routes differ
+  by that one tool for such agents. Structured output (`output_type=SomeModel`) is not affected.
+- Prompts and outputs are summarized. Full payloads are stored only if `TRACE_AGENT_CAPTURE_FULL_PAYLOADS` is on.
+- Protobuf and JSON bodies are accepted, gzip included. Use either this or the framework integrations for an agent, not
+  both, or its run is recorded twice.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TRACE_AGENT_DATABASE_URL` | `sqlite:///./trace_agent.db` | Database URL (SQLite or PostgreSQL) |
+| `TRACE_AGENT_OTLP_ENABLED` | `true` | Accept OpenTelemetry traces on `POST /v1/traces` |
+| `TRACE_AGENT_OTLP_MAX_BODY_BYTES` | `10000000` | Largest accepted OTLP request, after decompression |
+| `TRACE_AGENT_CAPTURE_FULL_PAYLOADS` | `true` | Keep full payloads, not only summaries |
+| `TRACE_AGENT_OPENAI_API_KEY` | - | OpenAI API key |
+| `TRACE_AGENT_OPENAI_BASE_URL` | - | OpenAI-compatible base URL (e.g. LM Studio) |
+| `TRACE_AGENT_AUDIT_ENABLE_GUARDRAILS` | `false` | Enable prompt injection and PII checks |
+| `TRACE_AGENT_AUDIT_METRICS_ENABLED` | `true` | Expose Prometheus `/metrics` endpoint |
+
+## License
+
+MIT

trace_agent_server-0.2.0/README.md

@@ -0,0 +1,78 @@
+# TraceAgent Server
+
+![GitHub Release](https://img.shields.io/github/v/release/LixusSoftware/TraceAgent)
+![GitHub Stars](https://img.shields.io/github/stars/LixusSoftware/TraceAgent)
+![GitHub License](https://img.shields.io/github/license/LixusSoftware/TraceAgent)
+![Tests](https://github.com/LixusSoftware/TraceAgent/actions/workflows/test.yml/badge.svg)
+![Docker Build](https://github.com/LixusSoftware/TraceAgent/actions/workflows/build-docker.yml/badge.svg)
+[![Website](https://img.shields.io/badge/website-traceagent.vercel.app-blue)](https://traceagent.vercel.app)
+
+FastAPI backend for TraceAgent. Stores runs, generates timelines, execution graphs, and explanations.
+
+## Install
+
+```bash
+pip install trace-agent-server[providers]
+```
+
+## Run
+
+```bash
+# With the included CLI
+trace-agent-server --host 0.0.0.0 --port 8000
+
+# Or directly with uvicorn
+uvicorn trace_agent_server.main:app --reload
+```
+
+## Tracing agents through OpenTelemetry
+
+The server is also an OTLP/HTTP receiver: an agent that already emits OpenTelemetry spans following the
+[GenAI semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/) (Pydantic AI does) is
+traced by pointing its exporter at `POST /v1/traces`, with nothing from TraceAgent installed in the agent.
+
+```python
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from pydantic_ai import Agent
+from pydantic_ai.capabilities import Instrumentation
+from pydantic_ai.models.instrumented import InstrumentationSettings
+
+provider = TracerProvider()
+provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:8000/v1/traces")))
+
+agent = Agent("openai:gpt-4o", capabilities=[Instrumentation(settings=InstrumentationSettings(tracer_provider=provider))])
+agent.run_sync("hello")
+provider.shutdown()  # a short script must flush before exiting
+```
+
+- One run is created per trace (the trace id is the run id), named after `gen_ai.agent.name`. Add a `trace_agent.run_id`
+  resource attribute to attach the spans to a run you created with the SDK instead.
+- `invoke_agent` spans become chain steps, `chat` spans model calls and `execute_tool` spans tools. Event times and
+  durations come from the spans; the run gets its provider, model, token totals and tool counters. Other spans are ignored.
+- The run ends when its last agent span ends, also when the agent runs under a web server span or calls other agents.
+- An agent whose output goes through an output function (`output_type=my_function`) also records that function as a tool
+  (`final_result` by default), because Pydantic AI emits an `execute_tool` span for it. It counts in the run's tool total
+  and shows up as a tool choice. The framework capability only records the agent's regular tools, so the two routes differ
+  by that one tool for such agents. Structured output (`output_type=SomeModel`) is not affected.
+- Prompts and outputs are summarized. Full payloads are stored only if `TRACE_AGENT_CAPTURE_FULL_PAYLOADS` is on.
+- Protobuf and JSON bodies are accepted, gzip included. Use either this or the framework integrations for an agent, not
+  both, or its run is recorded twice.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TRACE_AGENT_DATABASE_URL` | `sqlite:///./trace_agent.db` | Database URL (SQLite or PostgreSQL) |
+| `TRACE_AGENT_OTLP_ENABLED` | `true` | Accept OpenTelemetry traces on `POST /v1/traces` |
+| `TRACE_AGENT_OTLP_MAX_BODY_BYTES` | `10000000` | Largest accepted OTLP request, after decompression |
+| `TRACE_AGENT_CAPTURE_FULL_PAYLOADS` | `true` | Keep full payloads, not only summaries |
+| `TRACE_AGENT_OPENAI_API_KEY` | - | OpenAI API key |
+| `TRACE_AGENT_OPENAI_BASE_URL` | - | OpenAI-compatible base URL (e.g. LM Studio) |
+| `TRACE_AGENT_AUDIT_ENABLE_GUARDRAILS` | `false` | Enable prompt injection and PII checks |
+| `TRACE_AGENT_AUDIT_METRICS_ENABLED` | `true` | Expose Prometheus `/metrics` endpoint |
+
+## License
+
+MIT

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trace-agent-server"
-version = "0.0.3"
+version = "0.2.0"
 description = "TraceAgent FastAPI backend server."
 readme = "README.md"
 authors = [
@@ -29,7 +29,8 @@ dependencies = [
   "trace-agent-sdk",
   "fastapi>=0.115.0,<1.0.0",
   "httpx>=0.27.0,<1.0.0",
-  "openai>=1.52.0,<2.0.0",
+  "openai>=1.52.0,<4.0.0",
+  "opentelemetry-proto>=1.28.0,<2.0.0",
   "pydantic>=2.8.0,<3.0.0",
   "pydantic-settings>=2.3.0,<3.0.0",
   "sqlalchemy>=2.0.32,<3.0.0",
@@ -53,6 +54,9 @@ providers = [
 langchain = [
   "trace-agent-langchain",
 ]
+pydantic-ai = [
+  "trace-agent-pydantic-ai",
+]
 
 [project.scripts]
 trace-agent-server = "trace_agent_server.cli:main"

trace_agent_server-0.2.0/src/trace_agent_server/api/otlp.py

@@ -0,0 +1,50 @@
+"""OTLP/HTTP trace receiver: point an OpenTelemetry exporter at ``<server>/v1/traces``."""
+
+from __future__ import annotations
+
+import json
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+from opentelemetry.proto.collector.trace.v1.trace_service_pb2 import ExportTraceServiceResponse
+from sqlalchemy.orm import Session
+
+from trace_agent_server.db import get_session
+from trace_agent_server.services.otlp import ingest_spans
+from trace_agent_server.services.otlp_decode import BodyTooLarge, OtlpDecodeError, decode_traces, decompress
+
+# Not under /api: OTLP exporters append /v1/traces to the endpoint they are given.
+router = APIRouter()
+
+
+@router.post("/v1/traces")
+async def receive_traces(request: Request, session: Session = Depends(get_session)) -> Response:
+    settings = request.app.state.settings
+    if not settings.otlp_enabled:
+        raise HTTPException(status_code=404, detail="The OTLP receiver is disabled.")
+
+    limit = settings.otlp_max_body_bytes
+    declared = request.headers.get("content-length")
+    if declared and declared.isdigit() and int(declared) > limit:
+        raise HTTPException(status_code=413, detail=f"Request body is over {limit} bytes.")
+
+    content_type = request.headers.get("content-type")
+    try:
+        body = decompress(await request.body(), request.headers.get("content-encoding"), limit)
+        spans = decode_traces(body, content_type)
+    except BodyTooLarge as exc:
+        raise HTTPException(status_code=413, detail=str(exc)) from exc
+    except OtlpDecodeError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    result = ingest_spans(session, spans, capture_full=settings.capture_full_payloads)
+    session.commit()
+
+    is_json = (content_type or "").split(";")[0].strip().lower() == "application/json"
+    if is_json:
+        partial = {"partialSuccess": {"rejectedSpans": result.rejected}} if result.rejected else {}
+        return Response(content=json.dumps(partial), media_type="application/json")
+    response = ExportTraceServiceResponse()
+    if result.rejected:
+        response.partial_success.rejected_spans = result.rejected
+        response.partial_success.error_message = "Some spans could not be understood."
+    return Response(content=response.SerializeToString(), media_type="application/x-protobuf")

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/api/runs.py

@@ -42,6 +42,12 @@ from trace_agent_server.services.events import create_artifact, record_event
 from trace_agent_server.services.explanation import derive_explanation
 from trace_agent_server.services.graph import build_decision_graph, build_execution_graph
 from trace_agent_server.services.provider import ProviderTurnRequest
+from trace_agent_server.services.run_lifecycle import (
+    apply_llm_usage,
+    complete_run,
+    fail_run_with,
+    record_tool_result,
+)
 from trace_agent_server.services.run_summary import (
     build_command_chain,
     build_execution_metadata,
@@ -458,80 +464,7 @@ def store_tool_results(
     capture_full = getattr(request.app.state.settings, "capture_full_payloads", True)
 
     for result in payload.results:
-        started_event = record_event(
-            session,
-            run,
-            actor="sdk",
-            event_type="tool.started",
-            summary=f"Started {result.name}.",
-            status="running",
-            step_id=result.step_id,
-            tool_name=result.name,
-            payload_hash=stable_hash(result.args),
-            payload_full={"args": result.args} if capture_full else None,
-            metadata={"call_id": result.call_id, "args_summary": summarize_value(result.args)},
-        )
-        if result.status == "succeeded":
-            run.tool_count += 1
-            completed_event = record_event(
-                session,
-                run,
-                actor="sdk",
-                event_type="tool.succeeded",
-                summary=result.output_summary or f"{result.name} completed.",
-                status="succeeded",
-                step_id=result.step_id,
-                tool_name=result.name,
-                duration_ms=result.duration_ms,
-                payload_hash=result.output_hash,
-                payload_full={"output_summary": result.output_summary} if capture_full else None,
-                metadata={"call_id": result.call_id, "artifact_count": len(result.artifacts)},
-            )
-        else:
-            run.tool_count += 1
-            run.error_count += 1
-            completed_event = record_event(
-                session,
-                run,
-                actor="sdk",
-                event_type="tool.failed",
-                summary=result.error_summary or f"{result.name} failed.",
-                status="failed",
-                step_id=result.step_id,
-                tool_name=result.name,
-                duration_ms=result.duration_ms,
-                error_code=result.error_code,
-                payload_hash=result.output_hash,
-                payload_full={"error_summary": result.error_summary} if capture_full else None,
-                metadata={"call_id": result.call_id, "artifact_count": len(result.artifacts)},
-            )
-
-        for artifact_input in result.artifacts:
-            artifact = create_artifact(
-                session,
-                run,
-                source_event_id=completed_event.id,
-                kind=artifact_input.kind,
-                label=artifact_input.label,
-                summary=artifact_input.summary,
-                content_hash=stable_hash({"kind": artifact_input.kind, "label": artifact_input.label, "summary": artifact_input.summary}),
-                metadata=artifact_input.metadata,
-            )
-            run.artifact_count += 1
-            record_event(
-                session,
-                run,
-                actor="sdk",
-                event_type="artifact.created",
-                summary=artifact.summary,
-                status="created",
-                step_id=result.step_id,
-                tool_name=result.name,
-                artifact_refs=[artifact.id],
-                metadata={"artifact_label": artifact.label, "call_id": result.call_id},
-            )
-
-        started_event.status = "completed"
+        record_tool_result(session, run, result, capture_full=capture_full)
 
     session.commit()
     return {"status": "ok", "recorded": len(payload.results)}
@@ -755,6 +688,14 @@ def store_observations(
             event_type = "llm.started" if observation.status == "running" else "llm.completed"
             if observation.status == "failed":
                 event_type = "llm.failed"
+            if observation.status == "succeeded":
+                apply_llm_usage(
+                    run,
+                    provider=observation.provider,
+                    model=observation.model,
+                    prompt_tokens=observation.metadata.get("prompt_tokens"),
+                    completion_tokens=observation.metadata.get("completion_tokens"),
+                )
             record_event(
                 session,
                 run,
@@ -861,42 +802,7 @@ def finish_run(
     session: Session = Depends(get_session),
 ) -> dict[str, Any]:
     run = _get_run_or_404(session, run_id)
-    final_summary = summarize_value(payload.final_output) if payload.final_output is not None else "Run finished without final output."
-    run.final_output_summary = final_summary
-    run.status = "completed"
-    run.ended_at = utcnow()
-    completed_event = record_event(
-        session,
-        run,
-        actor="proxy",
-        event_type="run.completed",
-        summary=final_summary,
-        status="completed",
-        payload_hash=stable_hash(payload.final_output),
-    )
-    for artifact_input in payload.artifacts:
-        artifact = create_artifact(
-            session,
-            run,
-            source_event_id=completed_event.id,
-            kind=artifact_input.kind,
-            label=artifact_input.label,
-            summary=artifact_input.summary,
-            content_hash=stable_hash({"kind": artifact_input.kind, "label": artifact_input.label, "summary": artifact_input.summary}),
-            metadata=artifact_input.metadata,
-        )
-        run.artifact_count += 1
-        record_event(
-            session,
-            run,
-            actor="proxy",
-            event_type="artifact.created",
-            summary=artifact.summary,
-            status="created",
-            artifact_refs=[artifact.id],
-            metadata={"artifact_label": artifact.label},
-        )
-    derivation = derive_explanation(session, run)
+    derivation = complete_run(session, run, payload.final_output, payload.artifacts)
     session.commit()
     return {"status": "completed", "run_id": run.id, "decisions": len(derivation["decisions"])}
 
@@ -908,21 +814,7 @@ def fail_run(
     session: Session = Depends(get_session),
 ) -> dict[str, Any]:
     run = _get_run_or_404(session, run_id)
-    run.status = "failed"
-    run.ended_at = utcnow()
-    run.error_count += 1
-    run.final_output_summary = payload.error_summary
-    record_event(
-        session,
-        run,
-        actor="proxy",
-        event_type="run.failed",
-        summary=payload.error_summary,
-        status="failed",
-        error_code=payload.error_code,
-        payload_hash=stable_hash(payload.error_summary),
-    )
-    derive_explanation(session, run)
+    fail_run_with(session, run, payload.error_code, payload.error_summary)
     session.commit()
     return {"status": "failed", "run_id": run.id}
 

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/config.py

@@ -43,6 +43,8 @@ class Settings(BaseSettings):
     audit_otel_exporter_endpoint: str | None = None
     audit_otel_exporter_protocol: str = "grpc"
     capture_full_payloads: bool = True
+    otlp_enabled: bool = True
+    otlp_max_body_bytes: int = 10_000_000
 
     model_config = SettingsConfigDict(
         env_prefix="TRACE_AGENT_",

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/main.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
+from trace_agent_server.api.otlp import router as otlp_router
 from trace_agent_server.api.runs import router as runs_router
 from trace_agent_server.config import Settings, get_settings
 from trace_agent_server.db import Base, create_session_factory
@@ -67,6 +68,7 @@ def create_app(settings: Settings | None = None) -> FastAPI:
         return {"status": "ok"}
 
     app.include_router(runs_router)
+    app.include_router(otlp_router)
     return app
 
 

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/schemas.py

@@ -57,6 +57,7 @@ class ToolResultInput(BaseModel):
     call_id: str
     name: str
     step_id: str
+    parent_step_id: str | None = None
     status: Literal["succeeded", "failed"]
     args: dict[str, Any] = Field(default_factory=dict)
     output_summary: str | None = None

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/services/compare.py

@@ -9,6 +9,7 @@ from trace_agent_server.services.run_summary import (
     build_patch_activity,
     build_timeline_groups,
     build_tool_chain,
+    event_total_tokens,
 )
 
 
@@ -537,8 +538,8 @@ def _align_timeline(left_items: list[dict[str, Any]], right_items: list[dict[str
 
 
 def _overview_diff(left_run: Run, right_run: Run, left_events: list[Event], right_events: list[Event]) -> dict[str, Any]:
-    left_token_total = sum(int((event.event_metadata.get("usage") or {}).get("total_tokens") or 0) for event in left_events if event.type == "model.responded")
-    right_token_total = sum(int((event.event_metadata.get("usage") or {}).get("total_tokens") or 0) for event in right_events if event.type == "model.responded")
+    left_token_total = sum(event_total_tokens(event) for event in left_events)
+    right_token_total = sum(event_total_tokens(event) for event in right_events)
 
     duration_ms_delta = None
     if left_run.ended_at is not None and right_run.ended_at is not None:

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/services/events.py

@@ -63,14 +63,16 @@ def record_event(
     payload_full: dict[str, Any] | None = None,
     metadata: dict[str, Any] | None = None,
     turn_id: str | None = None,
+    timestamp: datetime | None = None,
 ) -> Event:
+    """Record an event; ``timestamp`` overrides "now" for sources that report when it happened."""
     run.last_event_seq += 1
     run.updated_at = utcnow()
     event = Event(
         run_id=run.id,
         turn_id=turn_id,
         seq=run.last_event_seq,
-        timestamp=utcnow(),
+        timestamp=timestamp or utcnow(),
         step_id=step_id,
         parent_step_id=parent_step_id,
         actor=actor,

{trace_agent_server-0.0.3 → trace_agent_server-0.2.0}/src/trace_agent_server/services/explanation.py

@@ -57,8 +57,14 @@ def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
             )
         )
 
+    # Framework integrations (LangChain, Pydantic AI) report tools only through
+    # /tool-results and never emit tool.requested: there, the start of a tool is
+    # the moment the agent chose it.
+    requested_steps = {event.step_id for event in events if event.type == "tool.requested" and event.step_id}
+
     for event in events:
-        if event.type == "tool.requested":
+        derived_request = event.type == "tool.started" and event.step_id not in requested_steps
+        if event.type == "tool.requested" or derived_request:
             tool_name = event.tool_name or "unknown tool"
             add_decision(
                 seq=event.seq,
@@ -69,7 +75,8 @@ def derive_explanation(session: Session, run: Run) -> dict[str, Any]:
                 evidence_event_ids=[event.id],
                 outcome="requested",
             )
-            key = (tool_name, event.summary)
+            # "Started X." is identical for every call, so tell calls apart by their arguments.
+            key = (tool_name, (event.payload_hash or event.summary) if derived_request else event.summary)
             loop_tracker[key].append(event)
             if len(loop_tracker[key]) >= 3:
                 add_flag(