What an AI agent black box should record, and who should hold it

One entry per event: small enough to keep for years, complete enough to check.

• Event type. What kind of thing happened: an action, a decision, a tool call, an input, an output, a reasoning step, a data access or an error. A short fixed list beats free text, because a reader can count and filter it.
• Input and output, as hashes. The SHA-256 hash of the prompt and of the answer, not the words. Anyone holding the original can show it matches; nobody can read the text from the hash.
• A reasoning summary. One plain line on what the agent did and why ("approved refund 4521 inside its refund limit"). Long enough to read, short enough that it is not the prompt again.
• What it touched. Tool names, record ids and systems: the names of what the agent read or changed, never their contents.
• Which agent, and for whom. The agent's id, tied to its owner and to the mandate it acted under, so the entry can be read against its authority.
• A timestamp. Set by the recorder when the entry is written, not supplied by the agent, so an agent cannot date its own work.
• A sequence number and the previous entry's hash. The number shows a gap. The hash makes every entry depend on all the ones before it.

The IETF Internet-Draft draft-sharif-agent-audit-trail sets out a fuller record format along the same lines: SHA-256 input and output hashes, a prev_hash chain, RFC 8785 (JCS) canonical form and an optional RFC 3161 timestamp. It is an individual draft, at revision -09; its datatracker page says it is "not endorsed by the IETF".

Log hashes, not prompts. A log that holds every customer's words is a second copy of your most sensitive data, kept by whoever holds the log.

Hash the prompt and the answer on your side with SHA-256 and record only the 64-character hex. Keep the originals in your own store, under your own retention rules. When someone needs to check one entry, show them the original and let them hash it: if it matches the hash on the record, it is the text the agent saw or wrote.

Two cautions. A hash of a short, guessable value (a yes or a no, a postcode) can be found by trying every option, so hash the whole prompt, not one field of it. And the data field is for names and ids, never content, because it is stored as written.

A log kept by the thing it describes can leave things out, and nobody outside would know.

The individual Internet-Draft draft-sharif-agent-audit-trail says that, for deployments at its trust level L2 and above, audit records "SHOULD be written by a component independent of the agent", and that the independent component "MUST sign records using its own key, distinct from the agent's key". It gives the reason plainly:

nono, an Apache-2.0 agent sandbox, builds its audit log the same way round. Its audit docs say: "The event log is recorded by the trusted supervisor, not by the sandboxed child."

Dapr has its sidecar, not the workflow code, sign a workflow's history. Its docs say "Every history event produced during a workflow’s lifetime is signed", with the sidecar's mTLS identity. The same docs mark it a preview feature, disabled by default.

The rule under all three: the writer should not be the subject, and the signing key should not be in the subject's hands. If your team runs the agent, your team is part of the subject too. That is why an outside timestamp, or an outside holder, matters to a reader who does not work for you.

Three layers, each closing a gap the one before it leaves open.

• Chain each entry to the last. Hash a fixed, canonical form of each entry together with the previous entry's hash. Change or delete any entry and every hash after it stops matching. The canonical form matters: the same entry must always become the same bytes, which is what RFC 8785 (JCS) is for. A chain alone does not stop the log's keeper rebuilding the whole thing from the edited entry onwards.
• Timestamp the head with an outside authority. Send the hash of the latest entry to an RFC 3161 time-stamping authority, which signs a token saying that hash existed at that time. In the RFC's words, the authority provides a "proof-of-existence" for the datum at an instant in time. After that, nothing up to the stamped head can be rewritten without the token disagreeing, for anyone who holds the token. Entries written since the last stamp are not covered yet.
• Publish heads for others to compare. Certificate Transparency (RFC 6962) goes further: its logs publish signed tree heads, and if a log "attempts to show different things to different people", comparing tree roots and consistency proofs exposes it. Witnesses that countersign each head apply the same idea with more independent parties.

That is nono's own docs, candid about what a signed log is worth without an outside anchor. It holds for any log, APIR's included.

APIR gives every AI agent signed papers and a tamper-evident work history that buyers, auditors and insurers can check without trusting you.

• Insert-only. The database refuses edits and deletes; entries are only added. A deleted entry would break the sequence and every link after it, and deleting an agent that still has entries is refused.
• SHA-256 hash-chained. Each entry's hash covers the agent, its sequence number, the event type, the input and output hashes, the reasoning summary, the data touched, the time and the previous entry's hash. The specification sets out the exact canonical text.
• Written by the database. For agents that run on APIR, database triggers write the entry when the agent is registered, acts, has an incident, is assessed, contained, audited or graded. For an agent that runs anywhere else, the same writer takes its events through POST https://apir.ai/api/v1/events and sets the time itself. Either way the entries are what the agent and its owner put on the record: the owning organisation can record events for its own agents.
• Timestamped every night. Once a day, at midnight UTC, the heads of the agents' chains are combined into a Merkle root that freeTSA, an outside RFC 3161 authority, timestamps, so a later rewrite of anything before a stamp would no longer match it. For an agent with a public passport, anyone can fetch the token from the verify-black-box endpoint and check the stamp themselves, and an owner's free export carries the tokens too. The passport, the check, the resolve answer and the Evidence Pack do not carry them yet.
• Checked by anyone, free. Once an agent holds a public passport, apir.ai/verify-passport recomputes its chain (links, content and sequence) on APIR's side on every open, and apir.ai/check-agent answers who it is, what it may do, how many events its log book holds and when the last one was. A private passport gets no chain check for outsiders, and an agent's events are not public: recomputing them offline takes the export from its owner. No account. How to verify an AI agent walks through both.

For an outside agent, prompts and outputs need never reach APIR: input_hash and output_hash take only a 64-character SHA-256 hex, and anything else is refused. The summary and data fields are stored as written, so keep content out of them.

Register the agent, keep its key, and send one call after each thing it does. Up to 50 events go in one call.

1. 1. Register the agent and get its key

   Sign in and register the agent at apir.ai/agents/connect. It can run on any model or framework. The page shows the agent's id and its API key, the key just once, so store it as APIR_API_KEY in your agent's secrets. The first agent is free; each further agent's papers are AUD 49, once.

2. 2. Send an event with curl

   Hash the prompt and the answer on your side, then send the hashes. The types that count as conduct are action, decision and tool_call; input, output, reasoning, data_access and error are recorded too.

   # Hash on your side. The prompt and the answer never leave your machine.
   IN=$(printf '%s' "$PROMPT" | sha256sum | cut -d' ' -f1)     # macOS: shasum -a 256
   OUT=$(printf '%s' "$ANSWER" | sha256sum | cut -d' ' -f1)
   
   curl -X POST https://apir.ai/api/v1/events \
     -H "Authorization: Bearer $APIR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"agent_id": "'"$APIR_AGENT_ID"'",
          "events": [{"type": "decision",
                      "summary": "Approved refund 4521 inside its refund limit",
                      "input_hash": "'"$IN"'", "output_hash": "'"$OUT"'",
                      "data": {"tool": "refunds", "record": "order:4521"}}]}'

3. 3. Or from Python, standard library only

   The same call, hashing locally. Set a User-Agent that names your agent: requests carrying Python's default urllib User-Agent are turned away at the edge.

   import hashlib, json, os, urllib.request
   
   def sha256(text):
       return hashlib.sha256(text.encode("utf-8")).hexdigest()
   
   def record(event_type, summary, prompt=None, answer=None, data=None):
       """One event into the agent's Black Box. Only hashes of the prompt and answer leave this machine."""
       body = {"agent_id": os.environ["APIR_AGENT_ID"], "events": [{
           "type": event_type,                  # action, decision or tool_call (also input, output, reasoning, data_access, error)
           "summary": summary,                  # one plain line, up to 1,000 characters
           "input_hash": sha256(prompt) if prompt else None,
           "output_hash": sha256(answer) if answer else None,
           "data": data or {},                  # names and ids of what it touched, never content; up to 8 KB
       }]}
       req = urllib.request.Request(
           "https://apir.ai/api/v1/events", data=json.dumps(body).encode("utf-8"), method="POST",
           headers={"Authorization": "Bearer " + os.environ["APIR_API_KEY"], "Content-Type": "application/json",
                    "User-Agent": "my-agent/1.0"})  # name your agent: Python's default urllib User-Agent is refused
       with urllib.request.urlopen(req, timeout=10) as r:
           return json.load(r)                  # each event's sequence number and chain hash
   
   # record("decision", "Approved refund 4521 inside its refund limit", prompt, answer, {"tool": "refunds", "record": "order:4521"})

4. 4. Read the answer

   A 201 lists each event with its sequence number and chain hash. A 400 names the first thing wrong with the body, 401 means the key is wrong, 403 that it cannot write events, 404 that the agent is not in the key's organisation, and 429 that a burst of more than 600 events a minute on one key was turned away. If a batch stops partway, the events before the failure are on the record and the answer says how many.

5. 5. Let it earn its papers

   After five conduct events the Trust Genome grades the agent. Its owner writes its mandate, which APIR signs. At a score of 70 or more it is issued a signed passport, and once the owner makes the passport public anyone can check it by name at apir.ai/check-agent, free. Below 70 the check returns no record.

Full reference: APIR for developers and the API documentation.

It proves what was recorded and shows any later change. It does not prove nothing was left out.

• The events are what the agent and its owner put on the record, whether the agent runs on APIR or anywhere else. The log book proves what was recorded and shows any later change, not that the record is complete. An agent that never sends an event leaves no entry.
• APIR operates the writer. The chain shows a change to any past entry. Every night the chain heads are combined into a Merkle root that an outside RFC 3161 authority timestamps, so a later rewrite of anything before a stamp would no longer match it; entries written since the last stamp rest on APIR's word until the next one.
• APIR has no outside witnesses and publishes no chain heads to a transparency log. The nightly timestamp tokens are kept by APIR and are not yet given out with the passport, the check, the resolve answer or the Evidence Pack, so an outsider cannot yet check them.
• The database refuses edits and deletes, through triggers someone with owner rights could switch off. A deleted entry would break the sequence and every link after it. Deleting an agent that still has entries is refused.
• The chain check runs on APIR's side, for public passports. A private passport gets no chain check for outsiders, and an agent's events are not public: recomputing them offline takes the export from its owner.
• A hash proves which text was used only to someone who holds the text. Lose the original and the hash still shows something was recorded, but not what it said.
• The record does not show the agent was right, or that its mandate was wise.
• APIR holds no SOC 2, ISO 27001 or penetration test report.

We don't promise results. We prove whatever happens.

What is an AI agent black box?

A log of what an AI agent did, one entry per action, decision or tool call, kept so that a change to any past entry shows. Like a flight recorder, it is there for the people who were not in the room. APIR's Agent Black Box is SHA-256 hash-chained, the database refuses edits to it, and its chain heads are timestamped every night by an outside RFC 3161 authority; the token is public for an agent with a public passport.

What should an AI agent audit log contain?

For each event: its type, the input and output as SHA-256 hashes, a one-line reasoning summary, the data touched (names and ids, not content), a timestamp set by the recorder, a sequence number and the hash of the previous entry. Add which agent it was and the authority it acted under.

Should I log prompts?

Not in the audit log. Hash each prompt and answer with SHA-256 on your side and record the hash; keep the originals under your own retention rules. Anyone holding the original can prove it matches the hash, and nobody can read the text from it.

How do I make an agent log tamper-evident?

Chain each entry to the hash of the one before it, have something other than the agent write it, and have the latest hash timestamped by an outside RFC 3161 authority on a schedule. Tamper-evident means a change shows, not that a change is impossible.

Who should hold an AI agent's log?

Not the agent alone, and ideally not the team that runs it alone. A writer the agent cannot reach, plus an outside timestamp or an outside holder, means a reader need not take the operator's word. APIR holds the log book for agents registered with it and says plainly where that stops: it operates the writer, and its nightly outside timestamp tokens, which would show a rewrite of anything before a stamp, are public only for agents with a public passport and in an owner's export.

How do I send my agent's events to APIR?

Register the agent at apir.ai/agents/connect to get its id and API key. Then POST https://apir.ai/api/v1/events with Authorization: Bearer and a JSON body holding agent_id and up to 50 events, each with a type, a one-line summary and, optionally, input_hash and output_hash (SHA-256 hex) and a small data object. The answer gives each event's sequence number and chain hash.