Agent fleets in enterprises today log tool invocations ad-hoc. One team wraps the LLM client and dumps JSON via print. Another decorates individual tool handlers with custom metrics. A third relies on whatever debug hooks the agent SDK happens to expose. The result is a fleet of agents with incompatible audit trails, inconsistent identity binding, and silent gaps that surface only during incidents or compliance review — when reconstructing what an agent did, on whose authority, in what order, becomes a forensic exercise rather than a database query.
This pattern was tolerable when agents called read-only APIs in product demos. It stops being tolerable when agents provision infrastructure, approve expense reports, modify access permissions, or operate on regulated data. As US enterprises and federal agencies adopt agentic AI under the NIST AI Risk Management Framework, evidence-grade tool-call logging is a foundational control for the Govern and Measure functions — without it, agents cannot be operated accountably in regulated workflows. The absence of a uniform evidence layer is no longer an operational inconvenience; it is a governance liability.
Enterprises deploying autonomous agents should treat tool-call logging as a first-class compliance layer — implemented once, in a shared library, and required of every agent that touches enterprise systems. The result is a fleet that shares a single evidence schema, a single identity-binding mechanism, and a single audit-grade trail across teams and agent frameworks. This pattern is what makes a multi-team agent deployment auditable rather than approximately auditable.
An agentic system runs a loop: user prompt → LLM reasoning → tool invocation → tool response → LLM reasoning → user response. A single user prompt can fan out into many tool calls within one assistant turn, and a multi-turn conversation can produce hundreds of invocations across sessions. The Evidence-Logged Agent Loop inserts a logging tap on the tool-call edge of that loop. Every invocation — success or failure — produces one evidence record. Records are correlated by a tuple bound to the user request at ingress, propagated through request-scoped context, and present on every record without explicit threading by tool authors.
A log entry qualifies asevidence— usable for compliance, audit, or forensic review — only if it carries all five of the following properties.
These five are the load-bearing constraints of the pattern:
The name matters. “Logging” is what every system does. The Evidence-Logged Agent Loop is a specific instance of logging that satisfies these five constraints and operates at the granularity of the agentic reasoning loop. Companion patterns in this series reference EGAL by name. The Delegated Boundary OAuth (DBO) [6] pattern supplies the inbound identity EGAL records; Stateless HTTP Container Isolation (SHCI) [7] supplies the request-scoped context EGAL propagates.
A reference implementation comprises three components: a logging tap, an evidence schema, and an identity-and-correlation middleware. The combination is delivered as a single class agents inherit from, so adoption is a one-line change.
Override the tool-invocation entry point to capture every call uniformly, including failures:
async def call_tool(self, name: str, arguments: dict): start = time.monotonic() timestamp = datetime.now(timezone.utc).isoformat(timespec="milliseconds") + "Z" try: result = await super().call_tool(name, arguments) duration_ms = int((time.monotonic() - start) * 1000) payload = self._build_payload( name, arguments, _extract_response(result), error=None, duration_ms=duration_ms, timestamp=timestamp, ) logger.info("tool_invocation %s", json.dumps(payload)) asyncio.create_task(self._post_evidence(payload)) return result except Exception as exc: duration_ms = int((time.monotonic() - start) * 1000) payload = self._build_payload( name, arguments, response=None, error=str(exc), duration_ms=duration_ms, timestamp=timestamp, ) logger.error("tool_error %s", json.dumps(payload)) asyncio.create_task(self._post_evidence(payload)) raise
Three design choices deserve note. Both success and failure paths emit the same schema — one query covers both. The sink write is dispatched asynchronously so tool latency is unaffected by evidence delivery. The structured logger is always written; the HTTP evidence service is optional and additive.
A flat JSON object with the minimum fields required to support the five evidence-grade properties:
{ "assistantTurnId": "turn-...", "conversationId": "conv-...", "sessionId": "session-...", "requestId": "req-...", "toolName": "search_records", "agentId": "example-agent", "request": { "query": "..." }, "response": { "results": [ ... ] }, "isError": false, "durationMs": 142, "timestamp": "2026-05-15T08:30:00.123Z"}
The first four identifiers form the correlation tuple: requestId is unique per user-visible request, sessionId groups requests within a session, conversationId groups sessions within a conversation, and assistantTurnId identifies a single reasoning turn that may produce multiple tool calls. Together they support every common forensic query: "what did the agent do for user X during incident Y", "show every tool call in conversation Z", "what happened in this specific turn".
agentId records which agent or server executed the call — necessary when a fleet of specialized agents share an evidence store. isError is redundant with response.error but enables index-friendly filtering. The schema is intentionally flat and additive; any new field is opt-in for consumers, and removal requires a versioning step.
Identity arrives at the agent boundary in request headers and must be propagated to every tool handler without explicit threading. An ASGI middleware extracts the user token from the Authorization header on ingress, resolves it against the enterprise identity provider once per request, and stores both the token and the resolved claims in request-scoped context:
class _ContextHeaderMiddleware(BaseHTTPMiddleware): async def dispatch(self, request, call_next): auth = request.headers.get("authorization", "") if auth.lower().startswith("bearer "): token = auth[len("bearer "):] _user_token_var.set(token) await _resolve_user_context_from_idp(token) _conversation_id_var.set(request.headers.get("x-agent-conversation-id", "")) _session_id_var.set(request.headers.get("x-agent-session-id", "")) _assistant_turn_id_var.set(request.headers.get("x-agent-turn-id", "")) _request_id_var.set(request.headers.get("x-agent-request-id", "")) return await call_next(request)
The correlation identifiers are platform-injected. On AWS Bedrock AgentCore they arrive as x-amzn-bedrock-agentcore-runtime-custom-*; on other runtimes the prefix differs. The pattern itself is runtime-agnostic — what matters is that correlation identifiers are received at the boundary and propagated through request-scoped state, not reconstructed downstream.
EGAL writes every record twice: to a structured logger (always, synchronously, into whatever log aggregator the team already operates) and to an evidence service (optional, asynchronously, with the user’s token in the Authorization header for server-side access control). This is not redundancy; it is audience separation. The structured logger serves engineers debugging tool behavior in near-real-time. The evidence service serves compliance and audit: centralized retention, ACL’d by identity, tamper-evidence concentrated in one downstream system. A small agent deployment may run only the logger; a regulated enterprise will run both, without forking the library.
Fits when:
Doesn’t fit when:
Operator decisions the pattern does not make for you:
EGAL does not sign records or enforce append-only storage. Tamper-evidence is an operator responsibility: the library emits records; the sink (S3 Object Lock, WORM storage, retention-locked log indices) makes them durable. Adopters should treat unsigned, mutable log streams as engineering telemetry, not as compliance evidence, until the sink layer is configured accordingly.
The pattern also logs tool arguments verbatim. Tools that accept personally identifiable information or regulated data will propagate that data into the evidence corpus unless the operator configures a redaction hook. EGAL exposes the hook point; it does not decide what to scrub. Teams deploying in HIPAA, GDPR, or comparable regimes must define redaction rules before production rollout, not after the first audit.
Finally, EGAL assumes a shared library can intercept every tool invocation in the agent framework the team uses. Frameworks that expose no central call path, or that allow tools to bypass the observability layer through direct HTTP calls, will produce incomplete evidence corpora. The compensating control is mandatory adoption enforced at CI and deployment gates: agents that do not inherit from the observability library do not reach production. Partial fleet coverage is worse than no coverage, because it creates the illusion of auditability.
As US enterprises and federal programs adopt the NIST AI RMF [1], the Measure function requires that automated agent actions produce queryable, identity-bound evidence. EGAL is the instrumentation layer that makes that requirement operational. DBO [6] supplies the identity field; SHCI [7] keeps the runtime stateless enough for correlation to work; the Unified RAG Evaluation Schema (URES) [8] consumes the same identity and session fields when measuring retrieval quality across suppliers.
[1] National Institute of Standards and Technology, “Artificial Intelligence Risk Management Framework (AI RMF 1.0),” NIST, 2023.
[2] National Institute of Standards and Technology, “AI RMF Playbook — Govern and Measure Functions,” NIST, 2023.
[3] OpenTelemetry, “Semantic Conventions for Generative AI,” OpenTelemetry, 2025.
[4] Model Context Protocol, “Model Context Protocol Specification,” Anthropic, 2025.
[5] Amazon Web Services, “Amazon Bedrock AgentCore observability,” AWS Documentation, 2026.
[6] N. Selvaraj, “The Delegated Boundary OAuth Pattern: Identity Propagation Across MCP Gateways for Enterprise Agentic AI,” Medium, 2026.
[7] N. Selvaraj, “Stateless HTTP Container Isolation: Why MCP Servers on Serverless Runtimes Must Disable Session Routing,” Medium, 2026.
[8] N. Selvaraj, “Unified RAG Evaluation Schema: Cross-Supplier Quality Measurement for Amazon Bedrock and Agentic Workloads,” Medium, 2026.
The Evidence-Logged Agent Loop: Structured Tool-Call Logging for Agentic Systems was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.