How to Trace AI Agent Decisions Across Blockchain Transactions

A blockchain transaction can tell us what happened. It cannot, by itself, explain why an AI agent decided to initiate it. Imagine an AI agent monitoring a decentralised finance application. It reads wallet balances, retrieves liquidity data, evaluates a possible transaction, calls a smart contract, and waits for confirmation. Eventually, the transaction appears on-chain. A monitoring dashboard shows its hash, gas consumption, status, and block number. Everything looks normal.

Then someone notices that the transaction moved assets into a position the user never intended to create. Where did things go wrong? Perhaps the agent interpreted an instruction incorrectly. Perhaps an RPC provider returned stale information. Perhaps the market changed after the agent calculated the expected outcome. Perhaps a policy check passed against an outdated configuration. Or perhaps the transaction executed exactly as designed, but the design itself failed to account for an important condition.

The transaction hash does not answer these questions. Neither does a conventional application log that says a tool call succeeded. To investigate the incident, engineers need to reconstruct the complete path from the original instruction to the final on-chain state. They need to understand which information the agent observed, how it interpreted that information, what action it proposed, which controls approved the action, and what happened during execution. This is where I believe observability needs to evolve.

My work and writing around production AI have repeatedly brought me back to a distinction that is easy to overlook: making a system capable of performing a task is not the same as making its behaviour understandable when something goes wrong. AI agents introduce additional uncertainty because they can select tools, generate plans, and change their approach based on intermediate results. Blockchain introduces another layer of complexity through asynchronous transactions, external data dependencies, network conditions, and state changes that may be difficult or impossible to reverse. Combining the two creates a system that needs visibility into both reasoning-related decisions and deterministic execution.

Blockchain applications need an observability layer that connects what an AI agent intended to do with what the infrastructure actually executed. That layer should not attempt to expose every internal model computation or turn private reasoning into an audit log. It should capture the operational evidence needed to explain decisions, enforce policies, investigate failures, and verify outcomes.

The visibility gap between an AI decision and a blockchain transaction

Traditional blockchain monitoring has a well-understood job. It tracks transactions, blocks, contract events, network health, gas usage, and other indicators of execution. These measurements remain essential. They tell us whether transactions were submitted, whether they were included in a block, whether execution succeeded, and how the network behaved. But consider what happens before an AI-generated transaction reaches the blockchain.

An agent receives a request, retrieves context, calls one or more tools, interprets their responses, evaluates possible actions, and produces a transaction proposal. That proposal passes through authorisation, signing, and submission before the blockchain processes it. Every stage can introduce a different failure. The agent may select the wrong contract. A retrieval service may provide outdated protocol information. An RPC provider may become unavailable. A policy engine may reject a valid transaction because it received malformed input. A signer may refuse an operation that exceeded their authorisation. The transaction may be accepted by an RPC endpoint but remain pending, or it may be included in a block and revert during execution.

A dashboard focused exclusively on the blockchain sees only part of this journey. Likewise, an AI application log may record that the model proposed a swap without establishing whether the proposal was authorised, signed, submitted, or confirmed. The problem is not that either monitoring system is inadequate within its own domain. The problem is that the two systems often describe different parts of the same operation without a shared way to connect them. An AI-native observability layer bridges that gap. It connects the original request, the agent's operational decisions, the data used to support those decisions, the policy checks, the transaction lifecycle, and the resulting on-chain state. The goal is not to replace blockchain explorers, node metrics, or application monitoring. It is to connect their evidence into a single operational picture.

Why are ordinary logs not enough

Logs are useful for recording individual events. A service might log that it retrieved a balance, generated a transaction proposal, or received a transaction receipt. The difficulty begins when an operation crosses several services.

Suppose an agent retrieves data through an RPC gateway, obtains additional information from an indexer, sends a proposal to a policy service, and submits an approved transaction through a signing service. Each component produces its own logs, often with its own request identifiers and timestamps.

During an incident, engineers may have to search several systems and manually reconstruct the order of events. If an intermediate request was retried, if a response arrived late, or if the agent resumed a workflow after a timeout, that reconstruction becomes even harder. A timestamp alone is not enough to establish causality. Two events can occur close together without belonging to the same workflow, while events from one workflow may appear out of order because different services process them asynchronously.

This is why distributed tracing is a useful foundation. OpenTelemetry provides a vendor-neutral model for collecting traces, metrics, and logs across instrumented services. A trace can represent a larger operation, while individual spans describe the work performed by its components. For a blockchain-connected agent, one trace might represent the attempt to execute a particular user request. Its spans could include context retrieval, transaction planning, policy evaluation, simulation, signing authorisation, RPC submission, and receipt verification. The resulting trace gives engineers a structured way to understand how the operation progressed. However, a trace alone does not establish that the operation was correct. It establishes the relationships between recorded operations and helps reveal where failures or delays occurred.

The observability layer must therefore combine tracing with domain-specific information: transaction identifiers, chain and block references, policy versions, execution status, and the outcome that the user originally requested.

A reference architecture for AI-native blockchain observability

I would design the architecture around six connected layers.

User Request / Business Goal | v AI Agent Runtime | Decision Record | v Context and Tool Layer | | | RPC Indexer Oracle | v Policy and Validation | v Signing and Execution | v Blockchain | v Receipt and State Check | v Observability Platform Traces | Metrics | Logs | v Alerts, Audit, Recovery

The diagram represents a logical architecture rather than a requirement to deploy every component as a separate service. A small application might implement several layers within one process. A larger platform may distribute them across multiple services. What matters is that each stage has a defined responsibility and emits enough structured evidence for the next stage to be observed.

1. Agent runtime instrumentation

The runtime records when an agent begins a task, which tools it invokes, how long each operation takes, and whether the agent produces a proposal or requests additional information. For example, the runtime might record that an agent evaluated three transaction routes, rejected two under its configured constraints, and selected the third for further validation.

It does not need to capture the private chain of thought or every intermediate token. It needs a concise operational record of the decisions and outputs that matter to the workflow.

2. Context provenance

The context layer records where decision-relevant information came from. For blockchain data, useful attributes may include the chain ID, block number, block hash, source provider, observation timestamp, and indexing checkpoint, where applicable.

These attributes help engineers determine whether an agent acted on current and consistent information. A block number should not be treated as a universal freshness guarantee. The system must also consider the network's finality characteristics, the source's progress, and the requirements of the specific operation.

3. Policy and authorisation instrumentation

The policy layer records which rules were evaluated and whether the proposal passed. Useful fields include a policy version, the result of each relevant check, a machine-readable rejection reason, and whether additional authorisation was required. This allows an investigator to distinguish between an agent that proposed an invalid action and a policy engine that incorrectly authorised it.

Sensitive policy details should be access-controlled. The observability system should not become a convenient source of information for someone attempting to bypass security controls.

4. Transaction lifecycle tracking

The execution layer records the transition from proposed transaction to authorisation, submission, inclusion, and verification. The distinction between these states matters. A successful RPC response does not necessarily mean that a transaction was confirmed. A receipt with a successful execution status is stronger evidence of execution, but the application may still need to verify that the resulting state satisfies the original goal.

5. Outcome verification

The final layer compares the intended outcome with the observed result. If the agent intended to transfer a specified amount to an approved destination, the system should verify the relevant transaction and state changes rather than relying solely on a success message returned by the execution service. For more complex operations, such as adjusting a DeFi position, the expected outcome may involve several balances, contract events, and protocol-specific state variables.

The verification rules should be defined for the application rather than inferred solely from the model's natural-language summary.

6. Operational analysis and recovery

Traces, metrics, and structured audit records feed dashboards, alerts, incident investigations, and recovery workflows. An alert might identify repeated RPC failures, a growing number of transactions stuck in a pending state, an increase in policy rejections, or a mismatch between confirmed transactions and expected business outcomes.

The objective is to move beyond reporting that something failed and toward identifying which boundary failed, what evidence supports that conclusion, and what safe action should happen next.

Trace the decision, not just the transaction

Consider a hypothetical agent that is asked to exchange a limited amount of a stablecoin for another asset. The agent retrieves the wallet balance, queries a liquidity pool, calculates an expected output, and proposes a swap. The policy engine checks the spending limit and slippage tolerance. A secure signer authorises the validated transaction, and an RPC endpoint submits it. A useful trace should preserve the relationships between these operations.

Trace: swap_workflow_8f31 | +-- request.received | +-- context.retrieval | +-- wallet.balance | +-- pool.liquidity | +-- price.observation | +-- agent.plan.created | +-- transaction.policy_check | +-- spending_limit: pass | +-- destination_allowlist: pass | +-- slippage_limit: pass | +-- transaction.simulation | +-- transaction.signing_authorized | +-- rpc.transaction_submitted | +-- blockchain.transaction_included | +-- transaction.outcome_verified

This trace is illustrative. In a real implementation, some stages may run concurrently, be retried, or occur in separate traces linked through workflow identifiers. The important feature is the relationship between them. An investigator should be able to start with a failed transaction and work backwards to the exact proposal, policy decision, and observations that supported it. Equally, the investigator should be able to start with an agent decision and follow it forward to the transaction's outcome.

A trace should also distinguish between attempts and logical operations. If an RPC request is retried three times, those attempts should remain visible without making them look like three separate user requests. This distinction becomes particularly valuable when agents resume long-running workflows. A workflow may survive a process restart, wait for a transaction to be included in a block, and continue later. Its operational history should remain connected even if its execution crosses several processes or sessions.

For a production system, I would use a durable workflow or operation identifier to connect the lifecycle, while creating spans for individual execution attempts. Where operations cross tracing boundaries, trace context can be propagated through service calls or linked explicitly. There is one important limitation: traces can be sampled, dropped, or retained for shorter periods than audit records. A security-sensitive application should not rely on sampled traces as its sole record of financial authorisation or execution.

Observability and auditability overlap, but they serve different purposes. Traces help engineers investigate behaviour. A durable audit record preserves the evidence required to establish what the system authorised and executed.

A practical implementation: correlating an agent with an RPC call

An observability design becomes more useful when it can be implemented with ordinary engineering tools. The following Python example uses OpenTelemetry-style instrumentation to create a trace for an agent's blockchain read. It illustrates how an application can associate a chain identifier and block reference with a request. The RPC response parsing and provider implementation are intentionally left outside the example because those depend on the application's client library.

from opentelemetry import trace from opentelemetry.trace import Status, StatusCode tracer = trace.get_tracer("blockchain-agent") def read_balance( rpc_client, wallet_address: str, chain_id: int, block_number: int, ): with tracer.start_as_current_span( "blockchain.read_balance" ) as span: span.set_attribute("blockchain.chain_id", chain_id) span.set_attribute("blockchain.block_number", block_number) span.set_attribute("blockchain.operation", "read_balance") try: # Adapter-specific: query the balance at the # requested block reference. balance = rpc_client.get_balance( wallet_address, block_number=block_number, ) span.set_attribute("rpc.result", "success") return balance except Exception as exc: span.set_attribute("rpc.result", "error") span.set_attribute( "error.type", type(exc).__name__, ) span.record_exception(exc) span.set_status( Status(StatusCode.ERROR, "Balance retrieval failed") ) raise

This is a simplified instrumentation example, not a complete production RPC client. The actual method signature, block-reference format, and error handling must match the provider library being used.

It also deliberately avoids recording the wallet address or balance as unrestricted span attributes. Depending on the application, those values may be sensitive. A controlled internal identifier or appropriately protected audit record can provide correlation without exposing unnecessary financial information in telemetry. There is another useful distinction in this example: the block number is part of the operation's context, not merely a descriptive label. If the agent later creates a transaction based on that observation, the workflow can reference the observation record and evaluate whether the information is still valid for execution. The span tells us which read occurred. The associated decision record tells us why that read mattered.

Decision records: connecting intent to execution

A trace describes how work moved through the system. A decision record describes the operational basis for a consequential action. I would give every transaction proposal a durable identifier and record the relevant context, policy version, and outcome. The record should contain enough information to reconstruct the decision without depending on the original model conversation remaining available. For example:

{ "decision_id": "dec_8f31", "workflow_id": "swap_workflow_8f31", "decision_type": "swap_proposal", "chain_id": 1, "observations": [ { "source": "rpc_provider_a", "type": "wallet_balance", "block_number": 24000100 }, { "source": "protocol_indexer", "type": "pool_liquidity", "indexed_through_block": 24000098 } ], "policy_version": "policy_12", "validation_status": "requires_refresh", "execution_status": "not_authorized" }

The identifiers and block numbers here are fictional. The example illustrates a useful design choice: the agent's decision can be stopped before signing if the application determines that the indexed data does not satisfy the freshness requirement for the intended operation.

The record does not claim that every two-block difference is unsafe. Whether that difference matters depends on the chain, the indexer's behaviour, the transaction, and the application's consistency requirements. A reporting agent might accept the indexed observation. An agent preparing a price-sensitive swap might require a newer observation or an independent validation step. The decision record should make the distinction explicit. It should also be updated as the operation progresses, or linked to append-only lifecycle events, so that the system can distinguish between a proposal, an authorisation, a submission, and a verified outcome.

For high-impact operations, I prefer a design in which the authorisation event is separately recorded and bound to the exact transaction parameters. This reduces the risk that a proposal will be changed after it passes validation. A record should never be treated as proof that an action occurred merely because it says the action was intended. The execution evidence must be independently established.

Build a failure taxonomy before building the dashboard

One of the most common mistakes in monitoring is treating every unsuccessful operation as the same kind of failure. A failed RPC request, an agent decision rejected by policy, a transaction that reverts, and a successful transaction that produces the wrong business outcome are fundamentally different events. They require different responses. I would classify failures by the layer where they occur and the evidence needed to resolve them.

Failure category	Example	Appropriate response
Context integrity	Required data is stale or inconsistent	Refresh, reconcile, or reject the decision
Agent planning	The proposal does not satisfy the task constraints	Reject the proposal and investigate the planning failure
Policy enforcement	Transaction exceeds a configured limit	Block execution and record the violated rule
Infrastructure	RPC timeout or indexer lag	Apply bounded retry or use an approved alternative source
Transaction lifecycle	The transaction remains pending or is replaced	Reconcile the known transaction state before taking action
On-chain execution	The transaction is included, but reverts	Inspect the receipt and relevant execution details
Outcome mismatch	Transaction succeeds, but the intended result is not achieved	Trigger investigation and an application-specific recovery process
Observability failure	Required telemetry or audit evidence is missing	Raise a monitoring-integrity alert and apply the appropriate fail-safe policy

The category alone does not determine the response. A timeout might be transient, while a timeout during transaction submission may leave the outcome uncertain. A policy rejection may be the correct behaviour rather than an incident. The system should preserve the distinction between an expected refusal, a recoverable operational failure, and a security-relevant anomaly. This is particularly important for AI agents. If a system is evaluated only on its task-completion rate, it may appear that policy rejections are failures to be eliminated. In reality, a correctly rejected unsafe transaction can be a sign that the controls are working.

The right metric is not simply how often the agent completes a task. It is whether the system completes legitimate tasks while reliably preventing unauthorised or invalid actions.

What should the monitoring dashboard actually show?

An AI-native blockchain dashboard should help an operator answer three questions quickly:

Is the system healthy?
Are agents making decisions based on sufficiently reliable information?
Are authorised actions producing the expected outcomes?

I would organise the dashboard around those questions rather than presenting every available metric on one screen. The first view should show operational health: RPC latency, provider errors, indexer lag, agent task latency, queue depth, and transaction lifecycle distribution. The second should focus on decision integrity: stale-context rejections, inconsistent-observation detections, policy rejection reasons, simulation failures, and the proportion of transaction proposals requiring refresh or human approval. The third should focus on outcomes: pending transactions, confirmed execution results, reverted transactions, unresolved submissions, and mismatches between intended and observed state changes.

The following chart illustrates how a dashboard might compare decision outcomes over a hypothetical monitoring period. These are invented figures for demonstration, not measurements from a deployed system.

<Chart content={{"chartType": "bar", "meta":{"title": "Illustrative outcomes for 1,000 transaction proposals", "description":"Hypothetical counts showing why monitoring should distinguish approved execution from rejected or unresolved proposals."}, "xKey": "outcome", "series":[{"dataKey": "count","label": "Proposals", "valueFormat": "integer"}], "yAxisMin":0, "data":[{"outcome": "Executed", "count":720}, {"outcome": "Policy rejected", "count":140}, {"outcome": "Refresh required", "count":90}, {"outcome": "Unresolved", "count":50}]}}/>

The value of this chart is not the particular proportions. Real systems will vary significantly by workload, protocol, and risk policy. The useful idea is that a single task success percentage conceals several different operational states.

For example, an increase in refresh-required proposals may indicate that an indexer is falling behind, that the application's freshness threshold is too strict, or that the workload has become more sensitive to rapidly changing data. A rise in unresolved submissions may indicate RPC instability or a problem with transaction-state reconciliation.

The dashboard should make it possible to move from a metric to the relevant traces and decision records. A number without a path to investigation is often a poor operational tool.

Metrics that tell us whether the system is becoming more reliable

Observability is most useful when it helps teams identify a deteriorating condition before it becomes a serious incident. For blockchain-connected AI agents, I would start with a small set of operational indicators and expand them as the system's risks become better understood.

Context freshness. Measure the age of decision-critical observations at the time a proposal is authorised, not only when the data is retrieved. Where appropriate, measure the difference between the observation's block reference and the relevant indexing checkpoint.

Decision rejection rate. Track proposals rejected because of invalid assumptions, missing information, or policy violations. Break the metric down by reason so that an increase can be investigated rather than treated as a generic failure.

Transaction lifecycle latency. Measure time spent preparing, validating, signing, submitting, waiting for inclusion, and verifying outcomes. This helps distinguish slow agent reasoning from slow blockchain infrastructure.

Unresolved transaction rate. Track operations whose final state cannot yet be established. A pending or uncertain transaction should remain unresolved until the application has sufficient evidence to classify it.

Outcome mismatch rate. Measure how often an operation reaches a technically successful execution state without achieving its defined application-level objective.

Audit completeness. Measure whether consequential actions have the required decision, authorisation, transaction, and outcome records. Missing evidence is itself an operational concern.

These metrics should have explicit definitions. For example, an outcome mismatch rate needs a clear definition of success for each operation type. A token transfer may be verified through the relevant transaction and state changes, while a more complex DeFi operation may require several application-specific checks. Thresholds should also be established from the application's risk model and observed baseline rather than copied from an unrelated system.

I would avoid optimising the entire platform around one composite reliability score. Averages can hide rare but serious failures. A low average latency does not compensate for an unsafe transaction, and a high task-completion rate does not establish that authorisation controls are effective. For critical controls, direct measurements of violations and execution outcomes are more useful than a single headline number.

Observability must not become another attack surface

An observability platform can contain valuable information about how an AI agent operates, which contracts it interacts with, what policies constrain it, and how its execution infrastructure is configured. That information needs protection.

Logging every prompt, tool response, wallet identifier, and transaction parameter without considering their sensitivity can expose financial activity or reveal details that attackers could use to target the system. I would apply data minimisation at the instrumentation layer. Record the information required to understand a decision, but avoid collecting private keys, signing credentials, recovery phrases, or other secrets. Sensitive prompt content and user information should be redacted or access-controlled according to the application's requirements.

High-cardinality fields also deserve attention. Putting arbitrary wallet addresses, transaction hashes, or user identifiers into metric labels can cause monitoring systems to consume excessive memory and storage. These values are generally better suited to trace attributes or structured records than to unrestricted metric dimensions.

Audit integrity is another consideration. A system should make it difficult for an ordinary agent process to alter or delete the records of its own consequential actions. Depending on the threat model, this can involve append-only storage, restricted write permissions, integrity checks, and separation between the execution service and the audit service.

A hash-linked audit log can help detect certain forms of modification, but it does not automatically prove that the recorded events are complete or truthful. If the application fails to record an event in the first place, an integrity mechanism cannot reconstruct it.

Finally, observability must not silently become a dependency that fails open. If the system cannot produce a required authorisation record for a high-impact transaction, it may need to block execution or require a controlled fallback. For a low-risk reporting task, temporary telemetry loss might instead trigger an alert while the task continues. The correct response depends on the risk and on which records are essential to safe operation.

How I would introduce this architecture in a real engineering team

A full observability platform can become complicated quickly. It is tempting to instrument every service, define dozens of metrics, and build a large dashboard before understanding which questions the team actually needs to answer. I would start with one consequential workflow and instrument it end-to-end.

For example, select a transaction-preparation workflow that reads contract state, generates a proposal, applies policy checks, and submits an authorised transaction. Assign a stable workflow identifier, connect the relevant spans, and record the minimum decision and execution evidence.

Next, introduce controlled failure tests. Simulate an unavailable RPC provider, an indexer that falls behind, a policy rejection, a reverted transaction, and a submission timeout. Confirm that each scenario produces a distinct classification and that engineers can reconstruct the workflow without manually searching unrelated logs.

Then introduce the dashboard and define the expected behaviour for unresolved states. Ensure that an uncertain submission cannot trigger a duplicate transaction simply because an agent assumes the previous attempt failed. Only after these basics work would I expand the architecture to additional workflows and services. This approach makes observability an engineering capability that grows with the system rather than a separate reporting project. It also gives the team something measurable to improve: fewer unexplained failures, faster incident investigation, more complete decision records, and stronger evidence that authorisation and execution behave as intended.

The future is decision-level observability

As AI agents become more capable of interacting with financial infrastructure, the meaning of a successful operation will need to become more precise. A successful model response does not necessarily mean that a valid transaction was proposed. A successful RPC call does not mean that a transaction was confirmed. A confirmed transaction does not necessarily mean that the user's intended outcome was achieved.

Each stage needs its own evidence, and those stages need to remain connected. This is the architectural shift I find most important: moving from monitoring individual components to observing the complete lifecycle of an autonomous decision.

Blockchain explorers will continue to provide valuable visibility into on-chain activity. Application logs will continue to explain local execution. Distributed traces will continue to connect work across services. But AI-driven applications need an additional layer that connects those sources to the intent, constraints, and outcome of each consequential action.

That layer must also recognise its own limits. Observability can help engineers understand what happened, detect unexpected behaviour, and improve recovery. It cannot guarantee that an agent will never make a bad decision, replace a sound authorisation model, or reverse a transaction that has already been confirmed.

Its purpose is to make the system's behaviour sufficiently visible that problems can be detected, investigated, and addressed before uncertainty becomes an unmanaged operational risk. For me, this is one of the important engineering challenges in moving AI beyond demonstrations and into production. The more autonomy we introduce, the less acceptable it becomes to treat the final output as the only evidence that matters.

We need to observe not just what the agent did, but the path from its intended action to the verified result. In blockchain applications, that path crosses probabilistic reasoning, external data, policy decisions, distributed services, and deterministic execution. Making those boundaries visible is what turns observability from a collection of dashboards into a foundation for operating autonomous systems responsibly.

The next generation of AI infrastructure will need to make these systems not only capable of acting, but also understandable when their actions do not go as planned.