"Why did the Agent do that?"
If you are building Agentic systems today, this is the question that keeps you up at night. AI Agents are inherently non-deterministic. They loop, they reason, and they call multiple tools in sequences that are hard to predict. When a multi-step task fails, a traditional stack trace is useless. You don't just need to know where the code crashed; you need to know what the AI was thinking.
In this seventeenth article, and the conclusion of our Engine volume, we explore how apcore integrates with OpenTelemetry (OTel) to turn the "Black Box" of AI reasoning into a transparent, traceable "Glass Box."
In traditional distributed tracing, a "Span" represents a single unit of work—like an HTTP request or a database query. In apcore, we introduce the Thought Span.
Every time the Executor.call()
method is triggered, apcore automatically wraps the execution in an OpenTelemetry span. This span isn't just a timer; it’s a rich container of AI-specific metadata:
One of the most powerful features of apcore is its ability to propagate the trace_id
across network boundaries.
Imagine a user makes a request to your web frontend. That request enters a fastapi-apcore
adapter, triggers an Orchestrator Agent, which then calls a tool module, which finally queries a PostgreSQL database.
Because apcore is W3C Trace-Context compatible, the same trace_id
is carried through the entire journey. When you open a tool like Jaeger, Grafana Tempo, or Honeycomb, you don't just see system logs. You see the entire "Thought Chain" of the AI connected to the actual system performance.
Tracing tells you the Why; Metrics tell you the How Much. apcore exposes Prometheus-ready metrics that give you a bird's-eye view of your Agentic workforce:
description
or documentation
needs improvement.Enabling this deep insight doesn't require complex boilerplate. In most apcore SDKs, it’s a matter of registering the TracingMiddleware
:
from apcore import Executor
from apcore.observability.tracing import TracingMiddleware
executor = Executor(registry)
executor.add_middleware(TracingMiddleware()) # Now everything is traceable
By standardizing observability at the protocol level, we ensure that every implementation—whether in Python, Rust, or TS—contributes to the same global visibility.
Reliability in the Agentic Era is impossible without transparency. apcore Observability 2.0 bridges the gap between software engineering and AI reasoning. It gives SREs and Developers the tools they need to monitor, debug, and optimize autonomous systems with professional precision.
We have now deconstructed the core of apcore:
Now that you understand the Engine, it’s time to build. In Volume III, we’ll move to Practical Implementation, starting with the apcore-toolkit: the Swiss Army Knife for module developers.
This is Article #17 of the Building the AI-Perceivable World series. Transparency is the bedrock of Trust.
GitHub: aiperceivable/apcore