Compliance Evidence & Audit-Trail Agent

Overview

AgentAz™ Specification

A lightweight, design-time governance spec for security review. It documents what this agent is authorized to do — and why — and pairs with whatever policy engine you already run. It does not enforce anything at runtime.

Governance readiness

Machine-readable contract (agentaz.json), validated against the open AgentAz™ JSON Schema — bundled for offline use and published at a permanent URL:

{
  "$schema": "./agentaz.schema.json",
  "version": "1.0.0",
  "last_reviewed": "2026-06-30",
  "agent_id": "compliance-evidence-agent",
  "trust_level": "A3",
  "dna_pattern": "Planning",
  "worst_case_action": "Prepares an incomplete or mis-mapped evidence record for human approval. Cannot file autonomously, modify source systems, or alter prior audit entries.",
  "authority_boundary": "Maps events to a configured control catalog and assembles evidence for approval; source-system write, access-grant, and entry-mutation tools are absent.",
  "tags": [
    "compliance",
    "audit-trail",
    "evidence",
    "human-approval",
    "tamper-evident"
  ],
  "tool_boundary": {
    "auto_executable_tools": [
      "get_event",
      "resolve_actor",
      "classify_resource",
      "lookup_controls",
      "collect_artifacts",
      "score_completeness"
    ],
    "approval_required_tools": [
      "request_signoff",
      "commit_evidence"
    ],
    "execution_tools_absent": false,
    "rollback_required": true
  },
  "output_boundary": {
    "format": "structured_json",
    "never_emits": [
      "source_system_write",
      "grant_access",
      "audit_entry_mutation"
    ]
  },
  "cost_boundary": {
    "max_usd_per_trace_loop": 0.3,
    "alert_threshold_usd": 0.2
  },
  "loop_boundary": {
    "max_reasoning_turns": 8
  },
  "human_handoff": {
    "triggers": [
      "incomplete_evidence",
      "regulated_resource",
      "low_mapping_confidence"
    ],
    "destination": "compliance_owner"
  },
  "audit": {
    "append_only": true,
    "tamper_evident": "hmac_chain",
    "logs": [
      "event",
      "mapping",
      "evidence",
      "completeness_score",
      "approvals"
    ]
  }
}

Building your own agent? Paste its prompt or spec into the AgentAz Compliance Scanner to grade it against this same rubric — or scroll up to run this blueprint live with your own API key.

New to this? Read the AgentAz™ Specification guide — Trust Levels, DNA patterns, and how it complements your runtime.

AgentAz™ is open source under Apache-2.0 — schema (frozen v1.0.0) and source on GitHub.

Governance matrix

A scannable summary of this blueprint's governance coverage, derived from its AgentAz™ specification. It documents the boundaries that already ship — not new functionality.

Agent component mapping

A framework-neutral view of how this blueprint maps to standard agent-architecture components (the vocabulary common to ADK-style frameworks). It describes structure for clarity — not an official integration or certified compatibility.

Failure modes

Specific ways this blueprint can fail, and how it is designed to detect, contain, and recover from each — the boundaries that make it safe to run, stated plainly.

Evaluation

Mapping correctness and evidence completeness together — a confidently wrong 'evidenced' record is the silent risk, so the agent is judged on never filing an incomplete or mis-mapped record, not just on throughput.

Recommended approach. Replay labeled events with known-correct control mappings and required-artifact sets, measuring mapping accuracy and completeness. Separately, adversarially inject tampered, reordered, and truncated log entries and confirm verification catches every one before any record is trusted.

When to use

System prompt

You are a Compliance Evidence agent. Your job is to turn a single operational event into a structured, well-mapped, tamper-evident evidence record — and to escalate rather than guess whenever the mapping or the evidence is uncertain. You do not decide whether the organization is compliant; you assemble and preserve the evidence a human compliance owner and an auditor will judge.

For each event you receive (an access grant, configuration change, deployment, or data-handling action):

1. Establish the facts. Read the event and resolve who acted, on what resource, and when. Classify the resource's sensitivity (e.g. public, internal, confidential, regulated). Never infer facts you cannot ground in the event or a tool result.

2. Map to controls. Look up the applicable controls for this event type and resource class in the configured control catalog. Map only to controls the catalog actually contains — never to a control you believe 'should' apply but cannot find. If the mapping is ambiguous or the catalog returns nothing confident, flag it for human review.

3. Assemble evidence. For each mapped control, collect the artifacts that control requires (approver identity, ticket reference, policy version, diff, timestamps). Record what is present and, explicitly, what is missing.

4. Score completeness and residual risk. Compute how completely the required evidence was gathered against each control's threshold. If completeness is below the control's threshold, or the resource is regulated, or your mapping confidence is low, you must escalate — do not file.

5. Gate the filing. Committing an evidence record is a consequential action. You may not commit it yourself: you call request_signoff to route the prepared record to the named human compliance owner, and only after explicit approval may commit_evidence run. If approval is denied or times out, the record is not filed and the reason is logged.

6. Seal and explain. Once approved, the record is appended to the tamper-evident audit log and you produce a plain-language 'what changed and why it is evidenced' summary that a non-engineer reviewer can read.

Hard rules: you have no tool that can modify a source system, grant or revoke access, or alter a prior audit entry — if a task seems to need one, escalate. Prefer 'I could not confidently map this' over a confident wrong mapping; a false 'compliant' record is the most damaging output you can produce. Log every mapping decision, its basis, and its confidence.

Simulate run

Try the agent with a sample task. This is a frontend-only preview that shows how the kit would plan and execute — no API calls, nothing leaves your browser.

Run it live

The scripted preview above is canned. This runs the real agent loop — the kit's actual system prompt and tools — against the model, using your own API key. Tools are still mocks, and high-risk tools are blocked by the same runtime gate the run.py demo enforces. Your key stays in your browser.

Setup guide

Architecture

1. 1
   Event intakeReceives a single operational event (access grant, config change, deployment, or data-handling action) with its actor, resource, and timestamp.
2. 2
   Context & sensitivity resolutionResolves the acting identity and classifies the affected resource's sensitivity tier, which determines how strict the evidence requirements are.
3. 3
   Control mappingLooks up the applicable controls for this event type and resource class in the configured control catalog. Low-confidence or empty mappings are flagged, not forced.
4. 4
   Evidence assemblyFor each mapped control, collects the artifacts it requires (approver, ticket, policy version, diff, timestamps) and records present-vs-missing items explicitly.
5. 5
   Completeness & residual-risk scoringScores evidence completeness against each control's threshold and computes residual risk from sensitivity and mapping confidence.
6. 6
   Approval & sign-off gategateA human compliance owner reviews the prepared record. Filing is blocked until explicit sign-off; incomplete, regulated, or low-confidence records cannot pass automatically.
7. 7
   Commit & sealgateOn approval, appends the record to the append-only, HMAC-chained audit log and emits a plain-language summary of what changed and why it is evidenced.

1. 1. Establish the facts

   Read the event, resolve the acting identity, and classify the resource's sensitivity. Ground every fact in the event or a tool result — no inference.

2. 2. Map to the control catalog

   Look up applicable controls for this event type and resource class. Map only to controls the catalog contains; flag ambiguous or empty mappings for human review rather than guessing.

3. 3. Assemble the evidence

   For each mapped control, collect the required artifacts and record explicitly what is present and what is missing.

4. 4. Score completeness and residual risk

   Compute completeness against each control's threshold. Below threshold, regulated resource, or low mapping confidence forces an escalation.

5. 5. Gate the filing

   Call request_signoff to route the prepared record to the human compliance owner. commit_evidence only runs after explicit approval; denial or timeout means the record is not filed and the reason is logged.

6. 6. Seal the record

   On approval, append to the append-only, HMAC-chained audit log so the entry is tamper-evident and the chain can be verified later.

7. 7. Explain it

   Produce a plain-language 'what changed and why it is evidenced' summary a non-engineer reviewer can read and trust.

Examples

Event: access_grant · actor: e.lee (engineer) · resource: analytics-dashboard (internal) · approver ticket: ACC-4821 · policy: access-v7

Mapped to access-control + change-approval controls. All required artifacts present (approver, ticket, policy version, timestamps). Completeness 100%. Routed for sign-off; on approval, sealed to the audit log with a summary: 'Internal dashboard access granted to e.lee under ACC-4821, approved per access-v7.'

Event: config_change · resource: billing-pii-store (regulated) · ticket: present · approver: MISSING · policy: data-handling-v3

Mapped to data-handling + change-approval controls. Completeness 60% — required approver artifact missing — and resource is regulated. The agent does NOT file. It escalates to the compliance owner with the specific gap itemized: 'Approver reference absent; regulated resource; cannot evidence change-approval control.'

Event: deployment · resource: shared-inference-service (confidential) · catalog match confidence: 0.41

The agent reports it could not confidently map the event and routes it to a human with both candidate controls and the evidence gathered so far, rather than committing a guess. No record is filed until the mapping is confirmed.

Implementation notes

• The control catalog is the source of truth, and it is yours. lookup_controls reads the controls your compliance team defines; the agent never asserts a mapping to a control it cannot find in your catalog. This keeps mapping correctness grounded in your authoritative source, not a model's recollection of a standard.
• Start the catalog small and real. ISO 42001 and the SOC 2 Common Criteria are the most agent-relevant starting points; map a handful of high-frequency event types first and expand. Treat the catalog as a living document with an owner, not a frozen file.
• The audit log is append-only and HMAC-chained: every entry is signed over its own fields and the previous entry's signature, so any later mutation, reorder, or deletion fails verification. Pin the latest signature (the chain head) in separate storage to detect tail truncation.
• commit_evidence and request_signoff are the only approval-gated tools, and they are the only tools that write anything. There is intentionally no tool that can modify a source system, grant access, or alter a prior entry — the absence is the safety property.
• Wire request_signoff to wherever your compliance owners already work (Slack, email, a review queue). A denied or timed-out approval must leave the record unfiled, not filed-by-default.
• The agent records and preserves; it does not opine on compliance. Keep that boundary visible in any UI so reviewers and auditors understand a human still makes the determination.

Variations

This blueprint and the AgentAz™ specification live in the central AgentKits registry — open source under Apache-2.0 (code & schema) and CC‑BY‑4.0 (text).

Tutorial

Frequently asked questions

Related kits