An AI agent deleted a file, called a tool and burned through tokens. Six months later, who can prove that last night’s log was not edited? The AgentLens AI agent audit trail answers with a hash-chained journal. The agentkitai/agentlens repository is small and young. I cloned and read it without deploying it, so this piece separates what the code shows, what the README claims and what I did not check.
The project is worth a look for one reason. Most agent observability tools measure. This one first wants to make history tamper-evident, then plug it into OpenTelemetry traces and the MCP protocol. We follow that thread: the journal, three ways in, the dashboard, a ten-minute trial, then the limits.
Facts as of 9 November 2026. The repository is MIT-licensed (I read the LICENSE file, author Amit Paz). The 50 latest commits I fetched run from 2 July to 1 August 2026. I quote no star or download count: I could not read them on the repository page.
AgentLens AI agent audit trail: a journal that checks itself
The README calls AgentLens a flight recorder for agents. Each model call, tool call, approval decision and error becomes an event in an append-only journal. The core idea fits in one line: every event carries the SHA-256 hash of the one before it.
The code in packages/core/src/hash.ts backs this up. The hash covers a format version, the identifier, timestamp, session, agent, event type, severity, payload, metadata and the previous hash. A session starts from null. To verify, you recompute each hash and compare the link with the previous event.
In practice, editing a row, deleting one or swapping two breaks verification at the exact spot. Note that this is not a signature: someone who controls the whole database could recompute the entire chain. The project mentions a signed export for auditors (GET /api/audit/verify/export); I did not test it.
Source : github.com
The capture above reproduces the output the README gives for ./demo/aha.sh. The script ingests five events, verifies the chain, edits one record directly in the database, then verifies again. I did not run it: this is the output the project advertises.
Three ways to feed the audit trail
OpenTelemetry, no SDK
If your agent already emits spans following the OpenTelemetry GenAI conventions, point the OTLP exporter at the server, which listens on port 3400:
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:3400
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:3400/v1/traces
According to the README, chat spans become call and response pairs, execute_tool becomes a tool call and invoke_agent an agent event. One trace maps to one session. Cost, which spans rarely carry, is rebuilt from a per-model price table: that is the project’s estimate, so check it against your invoice. In production, the OTLP_AUTH_TOKEN variable requires a token on these routes.
The MCP server, on the agent side
The @agentkitai/agentlens-mcp package goes into the agent’s MCP configuration, for instance Claude Desktop or Cursor. The docs/guide/mcp-integration.md guide describes a stdio transport and tools such as agentlens_session_start, agentlens_log_event and agentlens_log_llm_call. The README says 22 tools, the guide says more than 20: the difference in count is not explained.
A reliability caveat applies. Here the agent itself decides to call the logging tool. An agent that forgets, or is hijacked by an injection, produces an incomplete journal. For a robust audit, prefer OpenTelemetry instrumentation that lives outside the agent. MCP tool risks are covered in our article on MCP tool poisoning.
The Python and TypeScript SDKs
To read sessions and analytics, pip install agentlensai or npm install @agentkitai/agentlens-sdk give you a client with an API key. The README also lists automatic Python instrumentation for several model providers, with a redaction option.
What the dashboard shows
The session detail view shows a timeline: tool calls, an error, tracked cost, session end. A Chain Valid badge shows the chain state. The capture comes from the repository (demo folder, MIT licence) and shows demo data: a 45-second Research Agent session costing 0.3420 dollars.
Source : github.com
The Health page gives each agent a score out of 100 built from several dimensions. I did not read the formula, so I do not judge it.
Source : github.com
Trying AgentLens in ten minutes
-
Install Docker, then run the image the project publishes. According to the README,
AUTH_DISABLED=trueis for local trials only.
docker run -p 3400:3400 -e AUTH_DISABLED=true -e JWT_SECRET=dev-secret ghcr.io/agentkitai/agentlens Open
http://localhost:3400. Without Docker, the README offersnpx @agentkitai/agentlens-server(Node.js 20 or later).To see the chain break, clone the repository and run
./demo/aha.sh(Docker required).Then point an instrumented agent at port 3400 with the OTLP variables above.
For a shared setup, the repository ships a Docker Compose file with Postgres, Redis, authentication and TLS. By default SQLite is enough to test.
Limits and open questions
- Maturity. The repository is young and only one author appears in the licence. I could not read the stars or the issue pace.
- Compliance. The README cites Article 12 of the EU AI Act. That is not a certification: a hash chain helps record-keeping, it replaces neither legal analysis nor a retention policy.
- Integrity. Without an external anchor for the head hash, a fully rewritten database stays undetectable.
- Data. Prompts and outputs can contain secrets. Turn on redaction and encrypt the disk.
- Dynatrace. Nothing links AgentLens to Dynatrace. It receives OTLP, but it is neither an exporter nor an official integration.
Best practices
- Instrument the agent from outside (OpenTelemetry) rather than asking it to log itself.
- Record the head hash regularly in a third-party system to anchor the chain.
- Keep the same conversation identifier in your APM and the audit trail so you can correlate traces and evidence.
- Turn off
AUTH_DISABLEDas soon as the server leaves your workstation. - Tie spend to alerts: see the token cost of an AI agent.
For local coding-agent monitoring, compare with Observal, and for the limits to impose on agents, read guardrails for AI agents in production.
Frequently asked questions
Does AgentLens replace an observability tool such as Dynatrace?
No. It keeps a record of what an agent did and shows that the record has not changed. SLOs, infrastructure correlation and root cause analysis stay with your observability platform.
Does the hash chain prevent tampering?
It makes tampering detectable, not impossible. Whoever rewrites the whole chain produces a consistent journal. Anchor the head hash outside the database to close that door.
Can I use it in production?
That is your call: the project is young and I have not stress-tested it. Start with a non-critical agent, with authentication, redaction and backups.
Conclusion
AgentLens offers a simple, useful idea: an agent journal you can verify again. Read it for the hash-chain pattern, try it with the demo, and do not promote it to production before testing its limits. For the span attributes to emit, see the OpenTelemetry GenAI conventions.
This blog is independent and not affiliated with Dynatrace LLC. AgentLens belongs to its authors. The captures come from the project repository (MIT licence); I did not run the software.
Originally published on span.observer. French version: https://span.observer/fr/agentlens-audit-agents-ia/.



Top comments (0)