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
Use labels for values you need to filter on, scope policies to, or group in dashboards — for example env, dept, loan_id, or user_id. Use metadata for informational fields you want hashed into the audit record but don’t need to query — model name, SDK version, prompt token counts, etc.

​
Label context

Labels are short identifiers (e.g. loan_id = "LN-2024-4821"), but dashboards often need richer information — the borrower name, the loan amount, the origination date. Label context lets you attach that business data to a label value so it can appear alongside events in the UI without being stored on every event. Both SDKs expose a set_context / setContext method that sends a fire-and-forget PUT to store the context: 
client = ProvenLogClient(
    agent_id="loan-processor",
    labels={"loan_id": "LN-2024-4821"},
)

# Attach business data to the loan_id label value
client.set_context("loan_id", {
    "borrower": "Alice Rivera",
    "amount": 420000,
    "stage": "underwriting",
})
Context is keyed by (label_key, label_value) and upserted — calling set_context again for the same pair replaces the previous data. Transport errors are logged as warnings and never raise, so context pushes won’t interrupt your agent. See the Python SDK and TypeScript SDK guides for full usage details.

​
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.