Open-Source Recorder Deposition: Using Hash Chains to Prove Agent Behavior Wasn't Tampered With

When an AI Agent goes wrong—refunding the wrong order, calling a tool it shouldn't have—the record afterward is usually a JSON file or a single row in a dashboard, editable by anyone with permissions. Rule documents also tend to get quietly revised after the fact. A developer released Deposition, an open-source tool built on nights and weekends, on Reddit to address this trust gap: making every step of an Agent's behavior verifiable and non-repudiable.

Core Mechanism: Hash Chain and Ed25519 Signatures

Using Deposition is lightweight: wrap the Agent in a decorator, and it records every LLM call and tool call into a hash-chained jsonl file. Each event's hash covers the previous event, so if someone edits, deletes, or reorders an event, depo verify can pinpoint exactly which event broke the chain.

The hash chain itself has a known weakness: if someone modifies the content and recomputes the hashes for the entire file, the chain still looks intact. The developer added optional Ed25519 signatures specifically to cover this "full rewrite" scenario. According to him, this upgrades the record from "tamper-evident" to "forgery-proof."

You might not have noticed, but this design doesn't aim to encrypt everything—it focuses on verifiability. The recorded content remains readable, but modifications leave traces.

A hash chain is a tamper-evident structure that links data blocks in sequence: each block's hash includes the hash of the previous block, forming a one-way dependency. Any modification to historical data causes all subsequent hashes to change, allowing verifiers to locate the altered position. This structure is widely used in blockchains and audit logs, but its security premise is that an attacker cannot recompute the entire chain—if an attacker can rewrite all content and recompute the hashes, the chain itself cannot prove its own integrity.

Ed25519 is a digital signature algorithm based on elliptic curves, known for high security and performance. The signer generates a signature over a message using a private key, and the verifier validates it with the public key, ensuring the message's origin is authentic and untampered. In Deposition, Ed25519 signatures sign the hash chain's "head" or overall digest, so that even if an attacker rewrites the entire file and recomputes the hashes, they cannot forge the signature—elevating protection from "tamper-evident" to "forgery-proof."

Sealing Authorization Scope into the Trace with mandate

One of the two designs the developer values most: at initialization, you can pass in a "mandate" declaring constraints such as allowed tools, maximum cost, and maximum steps. This mandate is sealed into the same trace. Then depo audit compares the run record against the mandate, identifies which event crossed the line, and links it to the model turn that caused the violation.

This effectively places "what the Agent was allowed to do" and "what the Agent actually did" into the same immutable evidence chain. Compared to specifications scattered across documents, the value here is: when assigning blame after the fact, no party's verbal account of "what the rules were at the time" is needed.

A mandate in Agent systems refers to a pre-declared set of behavioral constraints, typically including the list of allowed tools, resource limits (such as maximum cost and maximum steps), and acceptable scope of operations. Unlike runtime dynamic policies, the mandate is fixed and sealed at initialization as the baseline for subsequent auditing.

In Deposition, the mandate is written into the same hash-chained trace, ensuring it is tamper-proof. During auditing, depo audit compares actual events against the mandate item by item, flagging violations and linking them to specific model turns. This design binds "what the rules are" and "what happened" into the same evidence chain, eliminating post-hoc disputes over verbal accounts of the rules.

Every Tool Call Can Be Traced Back to the Model Message That Initiated It

The second highlight is causal traceability. Every tool call links back to the model message that requested it, so the replay viewer can trace backward and answer "why did it do this." For debugging abnormal Agent behavior, this is more useful than seeing a string of isolated events—you can see the decision chain, not just the outcome.

On the tool-capture front, the author claims compatibility with LangGraph 1.2, CrewAI, OpenAI Agents SDK, Pydantic AI, and AutoGen. He emphasizes that he didn't just follow the documentation but tested against the real packages, placing probes on tool functions. This approach did uncover problems: the most obvious hook in Pydantic AI was actually wrong. Such first-hand verification details are rare among tools that advertise "supports X framework."

Causal traceability refers to recording causal dependencies between events in complex systems, not just chronological order. For AI Agents, this means every tool call should be linked to the model message that triggered it (such as the LLM's decision output), forming a traceable decision chain.

Deposition places probes on tool functions, capturing call context and linking it to the model turn that initiated the call. The replay viewer can trace backward to answer "why it did this," helping developers debug abnormal behavior. This design goes beyond the isolated event recording of traditional logs, providing visibility into the decision chain.

Known Limitations and Positioning

The author proactively lists unsupported scenarios: streaming responses are not captured—requests are recorded, but responses are marked as uncaptured; signing keys are stored on the same machine as the trace, making security weaker than it sounds. Both points are documented in the README.

On positioning, he makes clear that Deposition is not intended to replace LangSmith or Langfuse—those are monitoring tools, whereas Deposition targets the scenario where "someone later asks you to prove what the Agent did." The project uses the Apache 2.0 license, has no required dependencies, and most of the 14 examples can run without an API key.

An Unanswered Question

The question the author poses at the end of the post is actually more worth pondering than the tool itself: if you were to hand a trace to someone who doesn't trust you—a customer, an auditor, or your own security team—what would they want to see in it that your logs today don't include?

This touches on a structural gap in AI Agent deployment: the more capable the system, the more rigid the need for authorization boundaries and after-the-fact evidence, yet most existing observability tools assume "the recorder is trustworthy." Deposition's value isn't that it's already complete, but that it puts a frequently skipped question on the table and offers a concrete implementation that can be attacked and tested.