Giving AI Agents a Black Box: Decision Auditing Across 19,683 States
Open-source tool encodes each Agent decision as a nine-dimensional ternary state for enumerable, comparable, reproducible local audits.
The article introduces the open-source project agent-audit-mcp, which tackles the difficulty of auditing AI Agent decision processes. It identifies four typical failure modes: permission overreach, high-risk conclusions without evidence, untraceable citations, and state jumps. The core approach encodes each decision step as a nine-dimensional ternary vector with ⊕/0/⊖ per dimension—3⁹=19,683 states total—each with a unique enumeration key idx and balance value bal, comparable via Hamming distance. Rules then apply: overreach triggers BLOCK, missing evidence or high risk triggers ALERT, adjacent-step distance above 4 triggers WATCH, otherwise OK, with tunable thresholds. Offered as a standard MCP server with three tools, it runs fully locally with zero dependencies, plus four demos and 31 tests.
Why AI Agent Decisions Are So Hard to Audit
You've launched an AI Agent. It runs RAG pipelines, calls tools, writes reports. Everything looks smooth—until one day it quietly calls a tool it shouldn't touch, or signs off on a high-risk conclusion with zero evidence, or contradicts itself between step three and step four.
The problem isn't that the model is dumb. It's that the Agent's "autopilot" has no black box. Aircraft have had black boxes for decades—Agents should too. That's exactly what the open-source project agent-audit-mcp sets out to solve: encoding every Agent decision into an enumerable, comparable, reproducible state.
The author identifies four common failure modes:
- Permission overreach: The Agent touches tools or datasets outside its remit.
- High-risk conclusions without evidence: All-in trades, deletion operations, external commitments—with no basis.
- Untraceable citations: The conclusion is right, but you don't know where it came from.
- State-jump escapes: Conservative in step one, aggressive in step two, with no transition in between.
The hard part: a decision is a process, while a log is just a stream. To make the process auditable, you first need to turn "one decision step" into an enumerable, comparable state.
Core Idea: One Decision = A Nine-Dimensional State
agent-audit-mcp uses 9 observational dimensions to describe a decision step: structure, function, relation, attribute, time, context, causality, value, and evolution.
Each dimension takes three states: ⊕ (+1) for strong/above baseline, 0 for neutral, and ⊖ (−1) for weak/insufficient. A decision step is therefore a nine-dimensional ternary vector, e.g. 0⊖0⊖000⊖0. Nine ternary digits give 3⁹ = 19,683 states, and the all-zero center state has enumeration key idx = 9841.
This design fuses the three-state thinking of Eastern philosophy (⊖/0/⊕) with modern AI engineering, yielding three properties: enumerable (every decision has a unique address), comparable (any two states have a Hamming distance), and reproducible (same input, same state every time).
Ternary encoding and the enumeration key: The "nine-dimensional ternary" here means each dimension takes only one of three values: −1, 0, +1, so two bits suffice to represent one ternary digit losslessly. Concatenating all dimensions in a fixed order lets you treat the whole vector as a ternary integer, which is then converted to decimal to get idx. For example, the all-zero vector's idx isn't arbitrary—it's the middle position when all 3⁹ states are ordered lexicographically, equal to (3⁹ − 1) / 2 = 9841. The balance value bal is the sum of the nine dimension values, reflecting whether the decision as a whole leans positive (>0), neutral (=0), or conservative (<0). This encoding gives each decision step a globally unique "address," which makes indexing, deduplication, and trajectory comparison easy—and it's the basis for using Hamming distance to detect jumps or drift.
Decision Rules: Transparent, Reproducible, Tunable
With states in place, auditing boils down to a few clear rules:
| Trigger condition | Verdict | Action |
|---|---|---|
| v6 context · permission overreach | 🔴 BLOCK | Stop execution, roll back, re-authorize |
| v7 causality · missing evidence, or v8 value · high risk | 🟠 ALERT | Stop automation, escalate to compliance review |
| Hamming distance between adjacent steps > 4 (state jump) | 🟡 WATCH | Manual review of the jump point |
| None of the above triggered | 🟢 OK | Continue execution |
Thresholds (what counts as "high risk," what counts as "missing evidence") can all be overridden via environment variables, making it easy to calibrate against real logs. The rules are fully transparent to you—there's no second black box inside the black box.
Hamming distance and state jumps: Hamming distance was originally used to measure how many characters differ at the same positions in two equal-length strings; here it's generalized to nine-dimensional ternary vectors—any dimension with a different value counts as 1. Since a single-step correction should normally change only a few dimensions, an excessive distance between adjacent steps means the Agent's internal state has jumped sharply, possibly corresponding to prompt injection, context loss, or goal replacement. The threshold >4 is an empirical starting point: it allows up to four dimensions to change at once, and anything beyond that is deemed to need manual review. Because the threshold can be overridden via environment variables, teams can plot the distance distribution from real run logs and then pick a percentile that catches anomalies without over-alerting. The author's next step is to use the cumulative change of this distance to detect "decision drift"—gradual, covert deviation from the initial intent over long sessions.
Real Output: Four Scenarios the Engine Actually Produced
The project ships with four demo scenarios, and the outputs all come from the local engine:
- 🟢 Normal consultation → OK: Step one
0⊖0000000(idx=7654), step two0⊕0⊕00⊕⊕0(idx=12283), no red lines, no jumps. - 🟠 High-risk all-in recommendation → ALERT: Step one hits v8 high risk; step two further hits v7 missing evidence + v8 high risk.
- 🔴 Unauthorized query + stock-picking advice → BLOCK: Step one hits v6 overreach + v7 missing evidence; step two hits v6 overreach + v8 high risk.
- 🟡 State jump → WATCH: A single step leaps from
0⊖0000000to⊕⊕⊕⊕⊕00⊕⊕(idx=19646), a Hamming distance of 7, triggering manual review.
Each step reports its nine-dimensional vector, idx, balance value bal, red lines hit, and recommended disposition. That's what a genuinely readable black box looks like.
Architecture and Getting Started: Running in Three Minutes
The overall architecture is a standard MCP server:
Agent orchestrator ──┬── log hooks ──▶ signals
└── 9-dim audit ──▶ 9-dim states ──▶ trajectory audit ──▶ OK/WATCH/ALERT/BLOCK report
Once connected, you can simply say "audit this decision step..." in the conversation. The tool provides three methods:
audit_agent_step: Audits a single step, outputting the nine-dimensional state encoding and red lines.audit_agent_session: Audits an entire session trajectory, giving the four-level verdict and recommended disposition.encode_state: Converts between nine-dimensional vectors and enumeration keys/balance values, and computes Hamming distance.
Installation is one command (requires Python >= 3.10, MCP SDK >= 2.0):
pip install agent-audit-mcp
Example call (excerpt): input signals include tool call count, intent, evidence count, citation count, traceability, and whether risk was hit; the output gives the vector [0,1,0,0,0,0,1,-1,0], idx, bal, the hit markers, and a semantic interpretation such as "strong/above baseline: step intent, decision evidence chain; weak/insufficient: risk level."
MCP (Model Context Protocol): MCP is an open protocol proposed and open-sourced by Anthropic for connecting LLM applications to external tools and data sources in a standardized way. It uses a client-server model: the Agent host acts as the client and discovers and calls the "tools," "resources," and "prompts" exposed by the server through a JSON-RPC-style interface. For agent-audit-mcp, this means auditing capability doesn't require intruding into Agent code—just register the server with any MCP-capable host, and the model can call the three tools like audit_agent_step on demand in the conversation. The server declares tool names, parameter schemas, and return structures, and the host forwards the model-generated call requests, so the same auditing logic can be reused across frameworks—which is what the article really means by "standard MCP, works out of the box."
Why It's Worth Watching
- Purely local, zero external dependencies: The encoding engine is pure math, and the entire audit runs locally—decision trajectories never leave your machine. That's both a selling point and a compliance point.
- Deterministic and reproducible: Same input, same verdict every time—ready to be written directly into compliance audit reports.
- Standard MCP: Three tools work out of the box and can be embedded as log hooks into any Agent pipeline.
For enterprises, it turns Agent governance from "alchemy" into an auditable state machine.
The Bigger Picture
The ternary nine-dimensional cognitive space behind this tool has been published as the paper "Trinary Nine-Dimensional Cognitive Coordinate System: A Locatable and Generalizable Symbolic Cognition Layer" (DOI: 10.5281/zenodo.23437930).
Agents will only become more autonomous, but "autonomous" doesn't mean "unsupervised." Giving every decision an enumerable, traceable cognitive coordinate is one of the foundations for deploying AI safely. The author's next direction is using Hamming distance to detect Agent decision drift.
The project is open-sourced under the MIT license, ships with 31 tests and a four-scenario demo, and can be installed via pip install agent-audit-mcp.
Compliance note: This article and this tool only provide decision-audit encoding and verdicts; they do not constitute investment advice or securities advisory services.
Related articles
Google's Satellite AI Server Reaches Orbit: Gemma Model Generates First Reply in Space
Google's TPU-equipped satellite powers up in orbit, with the onboard Gemma 4 model generating the first reply from space. This article analyzes the technical path, real-world constraints, and implications for edge computing and satellite remote sensing.
AI Agents for Flight Booking Customer Support: Real Needs and Implementation Challenges
Starting from a real Reddit question, this article breaks down four needs for introducing AI Agents into flight booking call centers: basic Q&A, agent assist, call summarization, and quality inspection, and analyzes accuracy concerns and handoff boundary design.
Vercel Unifies Runtime Cache: Data Cache Merges into Runtime Cache
Vercel merges Data Cache into Runtime Cache, unifying storage quotas and billing for Next.js fetch cache, unstable_cache, getCache, and use cache: remote. Pro and Enterprise projects get more storage, and cache reads/writes are now billed at Runtime Cache pricing.