Skip to main content
Every action an AI agent takes is captured as a ProvenLogEvent. Events follow a versioned schema (v1.0) designed for forward compatibility.

​
Event structure

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "schema_version": "1.0",
  "agent_id": "my-agent",
  "session_id": "session-123",
  "source": "sdk",
  "capture_method": "embedded",
  "action_type": "TOOL_CALL",
  "action_name": "search_database",
  "action_input": {"query": "revenue Q4"},
  "action_output": {"results": 42},
  "action_status": "success",
  "error_message": null,
  "timestamp": "2026-02-17T00:00:00Z",
  "duration_ms": 150,
  "sequence": 1,
  "hash": "sha256...",
  "prev_hash": "sha256...",
  "labels": {"env": "prod", "dept": "finance"},
  "metadata": {"model": "claude-sonnet-4-5-20250929"},
  "validation_warnings": []
}

​
Field reference

​
Identity fields

FieldTypeDescription
idstringUUID, server-assigned
schema_versionstringSchema version (currently "1.0")

​
Source fields

FieldTypeDescription
agent_idstringRequired. Partition key for hash chains
session_idstringOptional. Groups events within a single session
sourcestringOrigin: sdk, mcp-proxy, hook, otlp, cli
capture_methodstringTransport path: http-api, cli-ingest, embedded, mcp-proxy, otlp

​
Action fields

FieldTypeDescription
action_typestringEvent category (see below)
action_namestringSpecific action identifier (e.g., search_database)
action_inputobjectRaw JSON input to the action
action_outputobjectRaw JSON output from the action
action_statusstringResult: success, error, timeout
error_messagestringError details when status is error

​
Timing fields

FieldTypeDescription
timestampstringISO 8601 timestamp
duration_msintegerAction duration in milliseconds

​
Integrity fields (server-assigned)

FieldTypeDescription
sequenceintegerMonotonically increasing per agent_id
hashstringSHA-256 hash of this event
prev_hashstringHash of the previous event in the chain

​
Dimension fields

FieldTypeDescription
labelsobjectIndexed key-value pairs for filtering. Included in hash chain
metadataobjectUnindexed key-value pairs. Included in hash chain
validation_warningsarrayNon-fatal validation issues. Excluded from hash chain

​
Action types

TypeDescription
TOOL_CALLAgent invoked a tool or function
TOOL_RESULTResult returned from a tool call
LLM_CALLRequest sent to a language model
LLM_RESPONSEResponse received from a language model
CUSTOMApplication-defined action

​
Labels vs Metadata

Both are key-value pairs included in the hash chain, but they serve different purposes:
LabelsMetadata
StorageSeparate indexed tableJSON blob in event row
QueryableYes — ?label.env=prodNo
Policy enginelabels.key field accessmetadata.key field access
Use caseEnvironment, department, user IDModel name, SDK version

​
Validation

ProvenLog uses best-effort validation. Only a missing agent_id is fatal — all other issues are stored as validation_warnings on the event. The philosophy: audit gaps are worse than imperfect records.