Agent Audit/Documentation
DOCSSDK · adapters · schema · API · CLI

Documentation.

Everything you need to instrument an agent, emit hash-chained receipts, and verify the chain. The SDK is source-inspectable under commercial licence by paying customers — engineering teams can audit the code end-to-end before it runs in production.

Looking for click-paths?

Setup guides with provider-specific tabs.

Six step-by-step guides covering install, SSO, SCIM, integrations, packs and retention. Google, Azure, Okta, Auth0, Slack and Teams click-paths included.

Open setup guides →
Agent Audit setup guides hub with six cards: install, SSO, SCIM, integrations, evidence packs, retention.

Quickstart.

Five minutes from pip install to your first receipt in the dashboard. You'll need an Agent Audit account and an API key, both issued on request on the Free Dev tier.

1. Install the SDK

Licensed, not open source. Install and use are permitted only once we've authorised your access — request access first.

pip install agentaudits

Python 3.10+ is required. Node and Go SDKs are Q4 2026.

2. Get an API key

  1. Sign in at dashboard.
  2. Open Settings → API keys and click Create key.
  3. Copy the key shown once. Store it in your secrets manager.

Expose the key to the SDK via the AGENTAUDIT_API_KEY environment variable, or pass it explicitly to the client.

3. Emit your first receipt

import os
from agentaudit import Client

audit = Client(
    api_key=os.environ["AGENTAUDIT_API_KEY"],
    agent_id="claims-triage-v3",
)

with audit.session(session_id="claim-2025-09-001") as s:
    s.record_llm_call(
        model="gpt-4o",
        prompt="Triage this claim ...",
        completion="Recommend manual review because ...",
        tokens_in=812, tokens_out=143,
    )
    s.record_tool_call(
        name="lookup_policy",
        args={"policy_id": "POL-44192"},
        result={"status": "active", "limit_gbp": 50000},
    )
    s.record_decision(
        outcome="route_to_human",
        confidence=0.62,
        rationale="Above policy limit threshold.",
    )

Refresh the dashboard — your receipts appear in Receipts within a few seconds.

What just happened. Every record_* call wrote a hash-chained, signed receipt to the local disk buffer, then async-batched it to the managed cloud. Your agent never blocked on the network.

OpenAI Agents SDK.

One-line adapter — wraps the Agents SDK runner so every LLM call, tool invocation and sub-agent spawn is recorded.

from agents import Agent, Runner
from agentaudit.adapters.openai import instrument

instrument(api_key="aa_live_...", agent_id="support-bot-v1")

agent = Agent(
    name="Support bot",
    instructions="Answer customer questions...",
    tools=[lookup_order, refund_order],
)
result = Runner.run_sync(agent, "Where is my order?")

Hooks captured: on_agent_start, on_agent_end, on_llm_call, on_tool_call, on_handoff. Parent-child span linkage is preserved across sub-agents.

Claude Agent SDK.

from anthropic import Anthropic
from agentaudit.adapters.claude_agent import instrument

instrument(api_key="aa_live_...", agent_id="research-bot-v1")

client = Anthropic()
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=[...],
    messages=[{"role": "user", "content": "Find me ..."}],
)

Tool-use blocks, tool-result blocks and multi-turn message history are all captured as linked receipts.

Model Context Protocol.

Protocol-level instrumentation — captures every tool call made through any MCP-compatible host (Claude Desktop, Cursor, Zed, your own host).

from mcp.server import Server
from agentaudit.adapters.mcp import audit_server

server = Server("my-mcp-server")
# ... register tools ...

# Wrap the server with audit instrumentation:
audit_server(server, api_key="aa_live_...", agent_id="mcp-fileops")
server.run()

Every tools/call, resources/read and prompts/get request produces a receipt with the client identity (host name, session id) attached.

LangChain & CrewAI.

LangChain ships as a callback handler that you pass via config={"callbacks":[handler]} or set globally. CrewAI ships as a one-line installer that wires into the v0.30+ event bus. Both capture chain steps, agent decisions, tool invocations, and final outputs as hash-chained receipts.

# LangChain — per-invocation
import agentaudit
from agentaudit.adapters import langchain_handler

agentaudit.init(api_key="aa_live_...", agent_id="claims_triage_v3")
handler = langchain_handler()

agent_executor.invoke(
    {"input": "Triage claim CL-2026-001"},
    config={"callbacks": [handler]},
)

# CrewAI — global, install once
import agentaudit
from agentaudit.adapters import instrument_crewai

agentaudit.init(api_key="aa_live_...", agent_id="claims_triage_v3")
instrument_crewai()

crew.kickoff()

Receipt schema v1.

Every action — LLM call, tool call, decision, data access, external side-effect — produces one receipt. Receipts are immutable, hash-chained to the previous receipt in the session, and (on Professional+) signed with a customer-held key.

{
  "schema_version": "1",
  "event_id":       "01J6Q7T8K3N4P5R6S7V8W9XAYZ",
  "agent_id":       "claims-triage-v3",
  "session_id":     "claim-2025-09-001",
  "trace_id":       "abc123...",
  "span_id":        "def456...",
  "parent_span_id": null,
  "ts":             "2026-06-07T18:14:22.331Z",
  "actor":          { "type": "agent", "id": "claims-triage-v3" },
  "action":         {
    "type":         "llm_call",
    "name":         "gpt-4o",
    "params_hash":  "sha256:..."
  },
  "resource":       {
    "type":         "claim",
    "id":           "claim-2025-09-001",
    "classification": ["PII", "financial"]
  },
  "authority":      {
    "scope":        ["claim:read", "policy:read"],
    "granted_by":   "role:claims-triage",
    "delegation":   ["svc:intake", "role:claims-triage"],
    "status":       "in_force"
  },
  "input_hash":     "sha256:...",
  "output_hash":    "sha256:...",
  "redacted_input":  "Triage this claim ...",
  "redacted_output": "Recommend manual review ...",
  "prev_hash":      "sha256:...",
  "signature":      "ecdsa-p256:..."
}

Field reference

FieldRequiredNotes
event_idyesULID, monotonic per session.
agent_idyesCustomer-chosen logical agent identifier.
session_idyesGroups receipts that share a hash chain.
trace_id / span_idyesW3C Trace Context compatible.
action.typeyesOne of llm_call, tool_call, decision, data_access, external_action, handoff.
resource.classificationnoArray of data-class tags — drives policy and audit pack content.
authority.scopenoPermissions in force for the actor at the instant of the action — what it was authorised to do, pinned at capture, not reconstructed later.
authority.delegationnoDelegation chain the authority descends from (grantor → actor) — records on whose behalf the action was taken.
authority.statusnoWhether that authority was in force, in scope and not revoked at the action time. Distinguishes it happened from it was allowed.
input_hash / output_hashyesSHA-256 of the canonical-JSON encoded raw bodies — before redaction.
prev_hashyesSHA-256 of the previous receipt's body — forms the chain.
signaturePro+ECDSA-P256, customer-held key on Professional+; absent on Free Dev / Starter.
The as-of record. A receipt captures not just what the agent did but the authority it held as of that instant — scope, delegation chain and revocation status, pinned at capture rather than reconstructed from whatever the permission system says later. Each receipt is a single signed, independently timestamped, byte-for-byte reproducible artefact. See it demonstrated on a live record in the interactive proof.

PII redaction

Redaction runs inside the SDK, before anything leaves your perimeter. The redacted_* fields are what ship; the *_hash fields prove the original was bound to the chain.

Default detectors: email, phone (E.164 + UK/US locals), credit card (Luhn), UK National Insurance, US SSN, IBAN, IP address, common name patterns (spaCy small model, optional). Configure via Client(redaction=...).

You're in control. Raw inputs and outputs never leave your process. The input_hash and output_hash let auditors verify that the redacted version corresponds to the original — without ever seeing the original.

Hash chain

Each receipt's body is hashed with SHA-256. The next receipt in the session embeds that hash as its prev_hash. Tamper with any receipt and every subsequent prev_hash stops replaying.

The first receipt's prev_hash is a constant sentinel (sha256:0000…0000). The session's chain head is committed to the receipt store as it advances and — on Professional+ — sent to an RFC 3161 Time-Stamping Authority for notarisation on every chain-head advance.

Verify CLI.

Every evidence pack ships with a verification CLI command. Anyone — your auditor, your insurer, your regulator — can re-run it independently. No contact with Agent Audit required.

pip install agentaudits
agentaudit-verify ./eu-ai-act-12-pack.json
# → Verifying chain head 8f3e2a1b…
# → 412 of 412 receipts intact
# → ✓ Chain verified — nothing altered
# → Sequence continuous: no gaps, no backdated entries
# → ✓ Complete — nothing hidden
# → RFC 3161 notarisation: ✓ valid at 2026-06-01T09:14:22Z
# → Signature (ECDSA-P256): ✓ matches customer key fingerprint a3:c8:…

Exit code 0 on a clean chain; 1 on first-break, with the failing event_id printed to stderr.

RFC 3161 notarisation

Professional+ tiers post each chain head to an RFC 3161 Time-Stamping Authority on every chain-head advance. The TSA's signed timestamp proves the chain existed in that state at a point in time — court-admissible in EU and UK courts.

The notarisation receipt is embedded in every export pack and verified by the CLI without network access.

REST API — Ingest.

The SDK ingests through the same public REST API. If you're on a stack we don't yet have an SDK for, instrument directly.

POST /api/v1/receipts

Append one or many receipts to a session chain. Receipts must arrive in monotonic event_id order per session — the server rejects out-of-order or duplicate event ids.

curl -X POST https://www.agentaudit.co.uk/api/v1/receipts \
  -H "Authorization: Bearer aa_live_..." \
  -H "Content-Type: application/json" \
  --data @receipts.json

Request body: { "receipts": [<Receipt>, <Receipt>, ...] }. Up to 1,000 receipts per request. Returns 201 with the chain head hash, or 409 on a chain conflict.

REST API — Query.

GET /api/v1/receipts

Filter receipts by agent, session, resource id, classification tag, and time range. Cursor-paginated; limit caps at 1,000.

GET /api/v1/receipts?agent_id=claims-triage-v3
                   &from=2026-06-01T00:00:00Z
                   &to=2026-06-07T23:59:59Z
                   &classification=PII
                   &limit=500

GET /api/v1/agents

List distinct agents seen in the tenant, with last-seen timestamp and receipt counts.

GET /api/v1/customers

List distinct resource ids (typically your end-customer ids) seen in receipts, with aggregated classification tags.

REST API — Export packs.

POST /api/v1/packs/eu-ai-act-12

Generate an EU AI Act Article 12 evidence pack for an (agent, period) pair. Returns a signed manifest and a download URL for the printable PDF + machine-readable JSON.

POST /api/v1/packs/eu-ai-act-12
{
  "agent_id":    "claims-triage-v3",
  "period_from": "2026-04-01T00:00:00Z",
  "period_to":   "2026-06-30T23:59:59Z"
}

Pack types available now: eu-ai-act-12, ico-sar, board-audit, fca-sysc, nist-ai-rmf, insurance-claim — all six ship today.

GET /api/v1/packs/eu-ai-act-12/manifest

Returns the signed manifest only — no PDF — for an (agent, period) pair. Used by the dashboard's Integrity page and by the CLI in air-gapped re-verification.

REST API — API keys.

MethodPathPurpose
GET/api/v1/keysList active and revoked keys for the tenant.
POST/api/v1/keysCreate a key. Raw key returned once.
DELETE/api/v1/keys/{id}Revoke. Any SDK still using it gets 401.

Scopes: ingest, read. Combine in the scopes array on create. Keys can be set to expire — recommended 30–365 days; the dashboard surfaces rotation prompts.

Need something not documented here? The docs are an MVP and we know it. If you're integrating and hit a gap, email info@vpnetworks.co.uk — we answer within four working hours and the next iteration of the docs gets your question.