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:
successmeans the call completed without raising an error — nothing more. An agent call that returns cleanly after doing the wrong thing is stillsuccess.failuremeans 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 |
basissays how Provantix knows:declared(the emitter said so, so the seal covers it),derived(read from standard telemetry attributes such ascloud.region,faas.invoked_regionandcloudflare.colowhen the record arrived) oredge(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
extasactor_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.