Agent Action Record schema

The Agent Action Record (AAR) is Provantix's canonical event: an open export profile, version 1.0. Nothing in it is platform-specific, so emitters written against this schema work against any conforming control plane.

Top-level fields

Field Type Required Description
profile_version string yes Always 1.0
event_id string yes Content-addressed id; same action, same id, same day or not
tenant_id string yes Your organization tenant
emitter_id string yes Emitter (collector) id; scopes event ids
observed_at ISO 8601 yes When the action happened (UTC recommended)
system string yes Registry slug of the emitting system, e.g. openai, internal-tools
vantage enum no inside (default), boundary, destination, identity
agent object yes Who acted (below)
action object yes What was done (below)
actor object no The human or system that authorized it
data object no Data classes and redaction commitments
model object no Model call details for call_model
correlation object no Trace/span/session ids
quality object no Outcome, error class, latency
location object no Where it ran and what it acted on, as short codes (below)

quality — outcome is not success

quality.outcome is a technical signal, not a verdict:

  • success means the call completed without raising an error — nothing more. An agent call that returns cleanly after doing the wrong thing is still success.
  • failure means the call raised or returned an error.
  • Absent (or unknown) means the emitter did not report one.

Neither value says whether the task itself succeeded. Judge task success from the target, the arguments summary and any joined destination record, not from quality.outcome alone. (The name quality predates the quality-assessment work; when evaluation records ship, they will live under a separate evaluation field so the two never share a word.)

agent

Field Description
vendor Who built the agent runtime, e.g. acme, cruzclaw
vendor_agent_id The agent's stable id in the vendor's terms, e.g. support-copilot
version Optional deployed version
principal The workload identity that acted (resolved against the system of record)
client_id OAuth client id or equivalent
token_actor Who the token belongs to, when different from the acting principal

vendor + vendor_agent_id together drive attribution: a matching agent record attributes at 0.95 confidence.

action

Field Description
action_type One of the 18 action types (see Action types)
target_system The system acted on, e.g. erp, gmail, postgres
target_entity_type Kind of entity, e.g. purchase_order, email_message
target_entity_id The specific entity
operation Free-form operation name, e.g. approve, send
tool_name For call_tool: the tool invoked
field_names Fields touched, for writes
data_classes e.g. pii, financial (see full list below)
external_recipient For sends: who received it

location

Where an action happened, as short codes. It is optional, and a record without it is unchanged and still verifies.

"location": {
  "runtime": { "provider": "aws", "region": "eu-west-1", "zone": "eu-west-1a", "country": "IE", "basis": "declared" },
  "target":  { "region": "us-east-1", "country": "US", "basis": "declared" }
}
Part Meaning Personal data
runtime Where the agent's code ran: provider, region, zone, country No
target Where the system acted on lives: region, country No
  • basis says how Provantix knows: declared (the emitter said so, so the seal covers it), derived (read from standard telemetry attributes such as cloud.region, faas.invoked_region and cloudflare.colo when the record arrived) or edge (a boundary source observed it). A declared location is the emitter's claim and is never shown as verified.
  • Only short codes are accepted: a provider, a region, a zone, a two-letter country and a basis. A city, an address, coordinates or free text is refused: a sealed record that carries one is rejected with malformed_record.
  • The person's location is separate. Where an organization has turned on Where people are in Settings, the country and region of the person or client behind an action, when the telemetry names them, are kept inside the erasable ext as actor_location. It is never a city, an address or an IP, and it is erased with the person's other data.
  • Runtime, target and the person's location are counted separately and never added together.

data classes

pii, phi, pci, financial, hr, secret, customer, internal, public, unknown.

Minimal example

{
  "profile_version": "1.0",
  "event_id": "evt_01m5…",
  "tenant_id": "ten_org_01m…",
  "emitter_id": "emi_01m…",
  "observed_at": "2026-10-21T09:41:03Z",
  "system": "internal-tools",
  "agent": { "vendor": "acme", "vendor_agent_id": "support-copilot" },
  "action": {
    "action_type": "execute",
    "target_system": "erp",
    "target_entity_id": "po-123"
  }
}

Use buildAAR() from the SDK rather than assembling JSON by hand; it fills profile_version, event_id and observed_at and validates the enums.