Event Schema

Every event the wrapper SDK emits is a CloudEvents 1.0 envelope wrapping an AGT AuditEntry with a Wytness envelope sidecar. The canonical-shape data payload is byte-comparable across Python and TypeScript — same wire format, same dashboard view.

Three layers of trust on every event

Wytness inherits two cryptographic properties from AGT and adds two of its own. Each event carries all four:

Reads as: who → what (intact) → who-attested → without-seeing-the-secrets. AGT owns identity + chain; Wytness owns non-repudiation + privacy. The layers do not overlap; they compose.

CloudEvents envelope

Each POST batch is a JSON array of CloudEvents 1.0 envelopes. The wrapper batches up to batchSize (default 100) entries or up to flushIntervalMs (default 5000 ms), whichever comes first.

1[
2  {
3    "specversion": "1.0",
4    "id": "<uuid>",
5    "source": "wytness-agt",
6    "type": "AuditEntry",
7    "datacontenttype": "application/json",
8    "time": "2026-05-22T00:00:00.000Z",
9    "data": {
10      "timestamp": "2026-05-22T00:00:00.000Z",
11      "agent_id": "billing-agent",
12      "event_type": "tool_invocation",
13      "action": "send_invoice",
14      "policy_decision": "allow",
15      "entry_hash": "<AGT-supplied SHA-256 hex>",
16      "previous_hash": "<previous entry_hash>",
17      "entry_id": "<uuid>",
18      "data": {
19        "customer": { "email": "EMAIL_3c866e6f" },
20        "amount": 99.99
21      },
22      "outcome": "success",
23      "resource": "https://billing.example.com/invoices"
24    },
25    "wytness_envelope": {
26      "envelope_version": 2,
27      "key_id": "<16-char base64url SHA-256(pubkey)>",
28      "signature_ed25519": "<base64 Ed25519 sig over canonical_json({data, id, time, type})>",
29      "pseudonymization_version": "1"
30    }
31  }
32]

Content-Type

The wrapper POSTs to /ingest with one of three Content-Types — the backend branches on it:

Canonical shape — the data payload

The inner data object is the AGT AuditEntry in canonical snake_case shape. Python emits this shape natively; TypeScript transforms its camelCase AGT-TS entry at the sink boundary so the wire bytes are identical.

New fields in AGT 4.0.0+ (forward-compatible)

AGT 4.0.0 (shipped 2026-06-01) added five fields to AuditEntry that flow through the wrapper's canonical-shape transform. The Wytness wrapper SDKs (wytness-ai 1.12.0 — Python + TypeScript) pin the AGT 5.0 train (Python 4.1.0 / TypeScript 5.0.0) and emit these fields automatically on every event.

Skill provenance (AGT 5.0 train)

The AGT 5.0 train adds skill-audit metadata — provenance for the skill/tool implementation an agent invoked. The wrapper carries it as an optional skill_audit_metadata object on the canonical payload (omitted when absent — events without it are byte-identical to before). On TypeScript the source field is part of AGT's hash-covered audit entry, so it is chain-protected end-to-end.

Wytness envelope sidecar

When signEnvelope is true (the default), each event carries an additional wytness_envelope object outside the CloudEvents-spec fields:

Encrypted token map (when pseudonymisation matched)

For every event where the SDK pseudonymised at least one value, a per-event encrypted_token_map is attached inside the data payload. It maps pseudonyms back to originals, encrypted with ChaCha20-Poly1305 using a fresh ephemeral X25519 keypair per event. Only the holder of your X25519 private key can decrypt it — see PII Protection — Revealing PII.

AGT-supplied hash chain

AGT writes each AuditEntry as a hash-chained record: entry_hash = SHA-256(canonical(entry)), and the next entry's previous_hash points at it. Any tamper to a historical entry breaks the chain forward. The wrapper does not produce this chain — it inherits it intact from AGT and surfaces it on the dashboard Integrity Verifier and the Evidence Pack PDFs.

Schema versioning

Related

• SDK API reference
• PII Protection
• Verifying reports — how the three layers compose into the Integrity Verifier verdict
• Built on AGT