Structured Logging Schema for Agent Actions

A structured logging schema for agent actions must start with the span. Failures happen inside tool execution chains, where a final answer that looks right can hide an unauthorized action or a repeating call. The schema must connect execution, identity, reasoning, and policy decisions in a record that engineers can reconstruct and test for integrity.

Why the session response is the wrong unit for logging agent failures

Conventional application logging assumes that the execution path is fairly easy to predict. An error points toward the operation or line that failed, while a terminal success flag describes the request’s outcome. Agents break that assumption. The same prompt can lead to different tool-call sequences from one session to the next, and the mistake that causes the failure may happen several steps before the failure becomes visible in the tool-call sequence. A reasoning step that selects the wrong tool or invents a parameter is not explained by the final response.

A customer-support agent looping on the same tool call illustrates the mismatch. Each call can return a successful HTTP response, so the access log is full of requests that look healthy. The failure is in the sequence itself. Other failures happen when agents cannot parse tool errors and keep retrying, or when they treat prompt-injection payloads in retrieved data as trusted input. Response-level logs also leave user intent disconnected from downstream tasks, omit the justification for calls, and collapse the agent’s authority into a generic service account.

The span as the atomic unit of capture and what it must contain

The replacement unit is a span representing one agent decision or action. Its type distinguishes a tool call, reasoning step, state transition, or memory operation so downstream systems can query comparable events. Structured inputs keep arguments, queries, or prior state, while structured outputs keep raw returns or retrieved entries. These fields make the operation inspectable in isolation. Start time, end time, and duration then locate it within the wider execution and support latency analysis.

Errors and retries need equally predictable structure. A typed error state supports alerting, while retry count and parent retry context distinguish an initial failure from the attempts that followed it. Trace ID, parent span ID, and session ID connect the operation to its causal path and enclosing session. Together, these fields support investigation and replay preparation. They also let debugging interfaces, evaluation layers, alerting systems, and analytics pipelines consume the same record without negotiating separate parsing rules.

Amazon Bedrock Agents exposes step-by-step reasoning trace events inline in the InvokeAgent response stream and supports model invocation logging to CloudWatch and Amazon S3 through distinct delivery paths. Their granularity nevertheless reflects the need to inspect intermediate operations. A typed span lets consumers use that detail without each having to work out how to read a free-form JSON blob.

Four nested layers that turn spans into a reconstructable audit chain

Execution spans answer what happened, but authorization requires a second layer. Each span needs agent_id to identify the model instance and version, parent_identity to identify the authorizing human or system, and delegation_scope to record the session’s granted permissions. User or tenant identifiers show who owns the session. The 2026 Singapore Consensus on agentic risk management names Traceable Identity and Auditability as distinct design principles, reinforcing the need to preserve both authority and evidence.

The third layer answers why the agent acted. Vispute & Kadam’s AER paper from Oracle Cloud Infrastructure, published in 2026, defines reasoning provenance as normalized, queryable records of intent, observation, inference, and the conclusions shaping an agent’s strategy. Execution state alone cannot generally reconstruct those records faithfully. Versioned plans, revision rationale, evidence chains, and structured verdicts with confidence scores make the explanation available for analysis. Knowing that an agent deleted a file is different from knowing why it judged deletion appropriate.

The fourth layer records which policy applied to the decision. Each decision record captures input state, policy evaluated, decision made, evidence used, and confidence score. This turns policy investigation into a queryable operation. Engineers can look at how re-planning changed the plan after the first step or compare low-confidence verdicts with cases where humans disagreed across investigations. Solozobov’s 2026 reconstructability metric paper found replay preconditions unmet in every scored trace because the retained evidence could not reconstruct the decision supporting the safety claim.

OpenTelemetry GenAI semantic conventions as the shared vocabulary, and where they stop

OpenTelemetry GenAI semantic conventions supply a shared vocabulary for portable span records. The gen_ai.* namespace covers model calls, tool calls, agent invocations, and sessions, with operations including chat, invoke_agent, execute_tool, embeddings, and create_agent. Backends that use the conventions can read those records in the same way. This makes them less dependent on field definitions that each tracer makes up for itself. Langfuse, Arize Phoenix, OpenLLMetry, and Laminar support the conventions, although Phoenix translates them into OpenInference and OpenLLMetry’s convergence varies by package.

The conventions remain at Development stability as of April 2026. They are usable and widely adopted, but attribute names can change. The deprecation of gen_ai.system in favor of gen_ai.provider.name makes that migration risk concrete. Teams should pin instrumentation to a versioned release and track the changelog. That approach preserves interoperability while making changes deliberate.

The more consequential limit is the tool boundary. An execute_tool span describes the tool operation without standardizing the integration behavior inside it. OAuth exchanges, third-party HTTP requests, retries, rate-limit handling, pagination, and incoming webhooks remain outside the GenAI conventions’ scope. The shared vocabulary therefore does not complete the execution record. A tool span can locate a failure without explaining which internal operation caused it.

What engineering teams must instrument manually beyond the standard

To close that gap, teams must add child spans beneath each execute_tool parent. These should cover OAuth token exchanges, outbound HTTP requests and responses, retry attempts with backoff, rate-limit encounters, and pagination cycles. This hierarchy shows agent choices separately from what the downstream API does. Without it, the tool boundary remains an opaque interval. With this hierarchy, an investigation can attribute failure to the agent’s arguments or the service receiving them.

Agent spawning must appear as a distinct typed span, with parent-child relationships preserved from orchestrator to sub-agent rather than inferred from adjacent outputs and inputs. Rhodes & Kang’s 2026 Proof of Execution paper from AlphaBitCore formalizes an execution as a contract, an Execution Causal Event Stream, and replay context. Its causal event stream must stay unbroken when work passes from one agent to another. Otherwise, deterministic replay lacks part of the execution it is supposed to reconstruct.

Decision-level entries add sub-millisecond latency but accumulate substantial storage volume, with typical workflows producing tens of structured records. Teams should keep every decision for failed workflows and token-budget-exceeded workflows but sample only a small share of successful execution telemetry. Sensitive content needs a different treatment. Hashes or structured references belong in the main log, with full content retained in a separately access-controlled store, so investigation remains possible without placing plaintext prompts, documents, or credentials throughout the observability pipeline.

Why reconstructability requires more than complete spans

Completeness does not establish that a record is trustworthy. All four layers can exist while entries remain open to silent modification or reasoning fields merely repeat an agent’s unsupported account. The AER paper addresses unsupported self-reported reasoning through independent interception of tool calls at the stdio, shell, and filesystem layers. Those observations allow post-hoc reconciliation against self-reported reasoning and produce per-investigation fidelity scores.

Tamper-evidence addresses the integrity of the retained history. The Proof of Execution framework combines its execution triple with five validator-checkable invariants, extending the evidence requirement beyond a sequence of readable events. Hash-chained records link each entry to a hash of its predecessor. WORM storage provides another audit-storage control. For consequential agents, schema design and tamper-evidence are inseparable because a reconstructable account must also expose alteration.

EU AI Act Article 12 requires high-risk AI systems to have the technical means to record events automatically throughout the system’s lifetime so their operation can be overseen. ISO/IEC 42001 Annex A.6.2.8 requires tamper-evident event recording across the AI system life cycle, while cryptographic integrity is a recommended, nonmandatory best practice. Enforcing the schema strictly, protecting integrity, and keeping records for as long as the applicable requirements call for serve a different purpose from debugging records kept for a short time.

How Middleware and observability platforms implement this schema today, and where gaps remain

The OpenAI Agents SDK supplies typed spans by default for agent runs, tool calls, handoffs, and guardrails. Langfuse, Phoenix, and LangSmith provide execution trace visualization built on or compatible with the GenAI conventions. Bedrock’s trace stream also shows each step as its own agents run. These capabilities reduce the work of recording and navigating an execution tree, but do not establish the entire audit chain.

Naitive is a purpose-built option for the remaining agent-observability gap. Its positioning centers on structured log capture, schema enforcement, and query interfaces designed for agent action records. That focus makes schema fit a direct evaluation criterion. Naitive’s support for verified reasoning provenance and a complete proof-of-execution system needs to be assessed separately from capture and visualization.

The AER paper identifies normalized reasoning provenance as a missing native primitive in LangGraph, LangSmith, Langfuse, Datadog, and the GenAI conventions. Natural-language trace content and extensible metadata can approximate it, but do not make intent, observation, and inference consistent first-class fields. The Proof of Execution model similarly exceeds current commercial implementations of tamper-evidence. The build-versus-buy decision therefore turns on which layers a platform supplies and which the team must add. Defaults can support debugging well while leaving partial identity coverage, minimal reasoning provenance, and no tamper-evidence suitable for consequential audit claims.

A reference schema and the decisions teams must make when implementing it

A reference JSON envelope should place all four layers in one record per step. Its identifiers are trace_id, span_id, parent_span_id, session_id, and user_id or tenant_id, followed by agent_id, parent_identity, and delegation_scope. Span metadata includes span_type, start_time, end_time, and duration_ms, with types covering tool calls, reasoning, state transitions, memory operations, handoffs, and guardrails. These define the record’s position and authority. Execution data then supplies structured input_arguments, raw output_result, error_type, retry_count, and token_usage.

The reasoning portion contains intent, observation, inference, plan_version, and revision_rationale. Decision fields add policy_evaluated, policy_version, decision, evidence_used, confidence_score, and policy_decision, with the last recording the guardrail outcome as Permit/Deny. Integrity fields are prior_entry_hash and entry_hash. Teams should adapt this reference design’s field names to their chosen GenAI attribute conventions, including the gen_ai.provider.name migration, and extend the envelope with domain-specific fields.

Three implementation decisions determine how this envelope survives production use. The first is sampling, with every span retained for failed and token-budget-exceeded workflows and a low sampling rate for successful workflow spans. Identity, delegation, and decision fields must be kept every time, even when sampling is used. The second is sensitive-content handling, using structured references or hashes in the main record and retaining plaintext in a separately access-controlled store. Fields such as tool_params_hash keep a way to check command integrity without putting sensitive arguments throughout ordinary logs.

The third decision is separation of storage paths. Execution spans and reasoning provenance go to the observability stack with short-to-medium retention, while identity, delegation, decision, and integrity fields go to a WORM-protected audit store with retention aligned to applicable regulation. These records should not share one undifferentiated retention tier. The schema remains a living contract as agent architectures develop. When orchestrators add sub-agents, parent_span_id preserves the execution relationship and parent_identity preserves the authority relationship, allowing handoffs to extend that contract without a breaking change.