Audit-event schema

Every governed model call resolves to exactly one audit event. The event is emitted asynchronously by the SDK after the call completes, persisted by the EgisAI control plane on a partitioned table, surfaced live on the Requests dashboard, and streamed to the audit-evidence export ZIP as one CSV row in request_logs.csv. This page is the field-by-field reference an integrator needs to consume the audit event programmatically — whether that’s piping events into your own SIEM, running fairness analytics on the decision logs, or proving control coverage to a SOC 2 auditor.

Every text-bearing field in this schema is sampled from the post-sanitization payload. Raw PII never appears in an audit event by design — see the Privacy contract section below for the invariants the SDK guarantees before writing a row.

Schema version

The fields described here correspond to schema version 2 of the audit event (SDK 0.13.0+, control plane 0.13.0+). Pre-2 events are forward-compatible: missing fields are nullable in the schema and the dashboard treats their absence as “not recorded” rather than as a value. When we add fields, they ship as additive nullable columns. We do not re-write the semantics of existing fields — the EgisAI compliance contract treats historical audit rows as immutable.

One audit event = one model call

A single row in request_logs represents one step of one agent — one LLM call, one tool dispatch, one sub-agent spawn, one policy check. A logical agent task (a “run”) groups many steps under a shared run_id; the run-level roll-up has its own Run schema summarised at the bottom of this page.

Field reference

Identity & correlation

Field	Type	Description
`id`	`int` (bigserial)	Globally unique row identifier. Stable for the lifetime of the row.
`created_at`	`datetime` (UTC, ISO 8601)	When the SDK observed the call. Used as the partition key.
`trace_id`	`string` (≤ 64 chars)	Trace correlation id. Stable across the steps of a single agent task. Use this to stitch this event to your own tracing system.
`org_id`	`uuid`	The workspace the event belongs to.
`agent_id`	`uuid \| null`	The agent identity the SDK attributed the call to (auto-detected from the system prompt fingerprint, or operator-set via `set_context(agent=…)`). `null` for legacy rows.
`api_key_id`	`uuid \| null`	The SDK API key that authenticated the ingest.
`run_id`	`uuid \| null`	Parent run for this step. See Run roll-up.
`step_seq`	`int \| null`	0-indexed step number inside `run_id`.
`step_kind`	`enum`	`model_call` \| `tool_call` \| `sub_agent_spawn` \| `policy_check`.
`framework`	`string \| null`	The agent framework token the SDK detected (`openai_agents`, `claude_agent_sdk`, `langgraph`, `raw`, …).

Provider & call shape

Field	Type	Description
`provider`	`string`	Upstream LLM vendor (`openai`, `anthropic`, `google`, `bedrock`, `custom`).
`model`	`string`	Model name as it was passed to the provider SDK.
`status_code`	`int`	Outcome status: `200` for `allow` / `sanitize`, `403` for `block`, `5xx` for upstream errors.
`stream`	`bool`	Whether the call was a streaming response.
`tool_name`	`string \| null`	Display name of the tool that ran (only when `step_kind = "tool_call"`).

Governance verdict

The verdict triplet is the single most important set of fields for compliance. The SDK records each phase independently so an auditor can ask “which side fired and why” without back-querying the JSONB blobs.

Field	Type	Description
`verdict`	`enum`	Dominant outcome of the call: `allow` \| `sanitize` \| `block`. Precedence is `block > sanitize > allow`.
`risk_level`	`enum`	`critical` \| `high` \| `medium`. Triage severity computed at ingest from the verdict + matched policy + sanitizations.
`enforcement_status`	`enum`	`enforced` \| `advisory`. `advisory` means the policy decided `block` but the framework had already executed the call by the time the SDK could intervene (e.g. AWS Bedrock Agents, where action groups run outside the SDK process). See Enforcement matrix.
`prompt_verdict`	`enum \| null`	Request phase outcome (`allow` \| `sanitize` \| `block`). Always populated on SDK 0.12.4+.
`response_verdict`	`enum \| null`	Response phase outcome. `null` when the prompt was blocked or the framework doesn’t expose a response side.
`prompt_decision`	`object \| null`	Full request-phase decision payload — see Decision object.
`response_decision`	`object \| null`	Full response-phase decision payload.
`policy_reason`	`string \| null`	Short, stable reason code for the primary matching policy (e.g. `prompt_blocked`, `output_pii`, `tool_denied`). Designed for switch-statement consumption.
`matched_policy`	`string \| null`	Display name of the primary matching policy.
`matched_policies`	`array<object> \| null`	Every policy that fired during evaluation, in evaluation order. See Matched-policies array. This is the SOC 2 / ISO 27001 evidence trail — preserved even when a more restrictive verdict dominates.

Performance & cost

Field	Type	Description
`latency_ms`	`int`	Wall-clock time spent inside the upstream model call.
`policy_latency_ms`	`int`	Wall-clock time spent in the SDK gate before forward (policy evaluation, including any LLM-judge round trip).
`prompt_chars`	`int`	Character count of the prompt at evaluation time.
`tokens_in`	`int \| null`	Tokens billed by the upstream provider for the prompt.
`tokens_out`	`int \| null`	Tokens billed by the upstream provider for the response.
`policy_tokens_in`	`int`	Tokens the SDK consumed running LLM-backed policies.
`policy_tokens_out`	`int`	Tokens generated by LLM-backed policies.
`cost_usd`	`decimal \| null`	Operator-visible cost estimate (provider tokens + governance tokens) in USD.

Compliance-safe text previews

These fields are populated by the SDK after passing through label-based PII redaction and a 2 KB truncation, so any value in these columns is guaranteed to be compliance-safe — typed labels (<SSN>, <EMAIL>) in place of values, bounded size, never raw PII.

Field	Type	Description
`request_text`	`string \| null`	What the model saw, post-redaction.
`request_text_before_redaction`	`string \| null`	Only set when `verdict = "sanitize"`. The pre-mutation state with PII collapsed to typed labels so the dashboard can render a before/after diff.
`response_preview`	`string \| null`	Post-redaction snippet of the model’s response.
`error`	`string \| null`	Truncated error string when the upstream call failed.
`intent_summary`	`string \| null`	One-line natural-language narrative of “what the agent tried to do and what EgisAI did.” Capped at 220 characters.
`decision_narrative`	`object \| null`	Business-language story rendered on the dashboard decision card.

Sanitization tally

When verdict = "sanitize", sanitizations records what was masked, in count-and-shape form only — never the original value.

{
  "sanitizations": [
    { "type": "ssn",          "count": 1, "pattern": "###-##-####" },
    { "type": "email",        "count": 2, "pattern": "<EMAIL>" },
    { "type": "credit_card",  "count": 1, "pattern": "####-####-####-####" }
  ]
}

Field	Type	Description
`type`	`string`	One of the PII categories the SDK knows how to detect (see `GET /v1/sdk/pii-types` for the live catalog).
`count`	`int`	Number of times this type was masked in this call.
`pattern`	`string`	The mask shape applied to each occurrence. Operators see this on the request-detail drawer so they can recognise what the post-sanitization payload looked like.

The privacy contract is non-negotiable: a sanitization record carries count and mask shape only. There is no field that ever holds the original value, the original value’s hash, or anything from which the original value could be reconstructed.

Decision object

Both prompt_decision and response_decision use the same shape. null means the phase did not run (typically because the request phase blocked the call and the response never came back).

{
  "verdict": "block",
  "reason_code": "tool_denied",
  "reason": "Tool 'shell.exec' is on the deny list for this agent.",
  "matched_policy": "no-shell-tools",
  "matched_policies": [
    {
      "name": "no-shell-tools",
      "type": "deny_tool_call",
      "verdict": "block",
      "reason_code": "tool_denied",
      "message": "Tool 'shell.exec' is on the deny list for this agent."
    }
  ]
}

Field	Type	Description
`verdict`	`enum`	Phase verdict — `allow` \| `sanitize` \| `block`.
`reason_code`	`string \| null`	Short stable code for the primary match. Codes are documented in Verdicts.
`reason`	`string \| null`	Human-readable reason rendered on the dashboard.
`matched_policy`	`string \| null`	Display name of the primary matching policy.
`matched_policies`	`array<object>`	Every policy that fired in this phase. Same shape as the top-level Matched-policies array.

Matched-policies array

Each entry records one rule that saw the data, with its individual verdict and reason. The array is preserved in evaluation order — including rules whose verdict was dominated by a more restrictive match — so historical review is accurate.

{
  "matched_policies": [
    {
      "name": "pii-prompt-scan",
      "type": "pii_scan",
      "verdict": "sanitize",
      "reason_code": "prompt_pii",
      "message": "Redacted 1 SSN, 2 emails.",
      "sanitize_types": ["ssn", "email"],
      "sanitize_mask_char": "*"
    },
    {
      "name": "no-shell-tools",
      "type": "deny_tool_call",
      "verdict": "block",
      "reason_code": "tool_denied",
      "message": "Tool 'shell.exec' is on the deny list for this agent."
    }
  ]
}

Field	Type	Description
`name`	`string`	Operator-set policy name as it appeared at the moment of evaluation.
`type`	`string`	Policy type (`pii_scan`, `deny_regex`, `allow_model`, `semantic_guard`, `deny_tool_call`, `deny_bash_command`, `deny_mcp_call`, `deny_db_query`, `deny_financial_action`, `max_prompt_chars`, `deny_output_regex`).
`verdict`	`enum`	This rule’s individual verdict — may be dominated by another rule in the same evaluation.
`reason_code`	`string`	Short stable code for the rule’s match.
`message`	`string`	Human-readable description.
`sanitize_types`	`array<string>` (optional)	When the rule’s verdict is `sanitize`, the PII categories it masked.
`sanitize_mask_char`	`string` (optional)	The mask character applied.

Run roll-up

A Run is one logical agent task: the framework-detected outer call, plus every step (LLM call / tool dispatch / sub-agent spawn) the agent made inside it. Run rows live in a separate table and are exported to runs.csv. The run roll-up carries the worst-of-steps verdict so a single line on the dashboard’s Runs page tells the operator the strongest enforcement outcome across the entire task. Per-step detail lives in the request_logs rows that point at it via run_id / step_seq.

Field	Type	Description
`run_id`	`uuid`	Stable identifier.
`started_at` / `ended_at`	`datetime`	Task window.
`agent_id`	`uuid`	The agent that ran the task.
`framework`	`string`	Detected framework token.
`step_count`	`int`	Number of `request_logs` rows attributed to this run.
`verdict`	`enum`	Worst-of-steps verdict (`block` > `sanitize` > `allow`).
`risk_level`	`enum`	Worst-of-steps severity.
`enforcement_status`	`enum`	Worst-of-steps enforcement (`advisory` if any step was advisory).
`tokens_in` / `tokens_out`	`int`	Sum across steps.
`policy_tokens_in` / `policy_tokens_out`	`int`	Sum across steps.
`cost_usd`	`decimal`	Sum across steps.
`latency_ms` / `policy_latency_ms`	`int`	Sum across steps.
`intent_summary`	`string \| null`	Run-level natural-language headline.
`identity_source`	`string`	How the SDK attributed the agent (system-prompt fingerprint, explicit set_context, API-key binding).
`identity_hash`	`string`	Stable fingerprint hash for de-duplication.
`error`	`string \| null`	Run-level error if the task failed.

Privacy contract

The SDK guarantees the following invariants before any audit event leaves your environment:

No raw PII fields. Every text-bearing field (request_text, request_text_before_redaction, response_preview, error, intent_summary) is sampled from the post-sanitization payload, after typed labels have replaced detected PII. The pre-sanitization payload is never serialised to an audit event.
Sanitization records are count-only. sanitizations[].count and sanitizations[].pattern are the only signal — never the original matched values, never a reversible hash.
Fail closed on PII. If the local PII engine errors mid-evaluation, the call is treated as if PII was detected and the audit event records the failure outcome rather than the un-scanned payload.
Bounded size. Text previews are capped at 2 KB so a misconfigured payload can’t bloat your audit volume unbounded.
Deterministic evaluation order. Phase 1 (deterministic local checks) always runs before Phase 2 (LLM-backed checks) on each side; a Phase 1 block short-circuits Phase 2 and the audit event records exactly which phase decided.

These invariants are tested in the SDK’s regression suite — see the public source at egisai/tests/test_smoke_privacy_contract.py.

Accessing audit events

Surface	Use case	Cadence
Dashboard Requests page	Operator review, ad-hoc filtering	Live (SSE)
Audit-evidence export ZIP	Auditor evidence, periodic SIEM ingest	On-demand
Per-request API (Enterprise)	Programmatic ingest, custom analytics	Real-time
SIEM webhook (Enterprise, roadmap)	Stream-to-SIEM	Streaming

The audit-evidence export is the supported path for procurement-style evidence reviews — see Audit-evidence export for the ZIP layout and the framework-control mapping shipped in the manifest.

What’s next

Verdicts

The three verdicts and what each one means in detail.

Audit-evidence export

The ZIP-of-CSVs format auditors actually consume.

Two-phase governance

Why request and response decisions are recorded independently.

Enforcement matrix

Where enforcement_status = "advisory" happens and why.

​Schema version

​One audit event = one model call

​Field reference

​Identity & correlation

​Provider & call shape

​Governance verdict

​Performance & cost

​Compliance-safe text previews

​Sanitization tally

​Decision object

​Matched-policies array

​Run roll-up

​Privacy contract

​Accessing audit events

​What’s next

Verdicts

Audit-evidence export

Two-phase governance

Enforcement matrix

Schema version

One audit event = one model call

Field reference

Identity & correlation

Provider & call shape

Governance verdict

Performance & cost

Compliance-safe text previews

Sanitization tally

Decision object

Matched-policies array

Run roll-up

Privacy contract

Accessing audit events

What’s next