Events

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

Field	Type	Description
`id`	string	UUID, server-assigned
`schema_version`	string	Schema version (currently `"1.0"`)

Source fields

Field	Type	Description
`agent_id`	string	Required. Partition key for hash chains
`session_id`	string	Optional. Groups events within a single session
`source`	string	Origin: `sdk`, `mcp-proxy`, `hook`, `otlp`, `cli`
`capture_method`	string	Transport path: `http-api`, `cli-ingest`, `embedded`, `mcp-proxy`, `otlp`

Action fields

Field	Type	Description
`action_type`	string	Event category (see below)
`action_name`	string	Specific action identifier (e.g., `search_database`)
`action_input`	object	Raw JSON input to the action
`action_output`	object	Raw JSON output from the action
`action_status`	string	Result: `success`, `error`, `timeout`
`error_message`	string	Error details when status is `error`

Timing fields

Field	Type	Description
`timestamp`	string	ISO 8601 timestamp
`duration_ms`	integer	Action duration in milliseconds

Integrity fields (server-assigned)

Field	Type	Description
`sequence`	integer	Monotonically increasing per `agent_id`
`hash`	string	SHA-256 hash of this event
`prev_hash`	string	Hash of the previous event in the chain

Dimension fields

Field	Type	Description
`labels`	object	Indexed key-value pairs for filtering. Included in hash chain
`metadata`	object	Unindexed key-value pairs. Included in hash chain
`validation_warnings`	array	Non-fatal validation issues. Excluded from hash chain

Action types

Type	Description
`TOOL_CALL`	Agent invoked a tool or function
`TOOL_RESULT`	Result returned from a tool call
`LLM_CALL`	Request sent to a language model
`LLM_RESPONSE`	Response received from a language model
`CUSTOM`	Application-defined action

Labels vs Metadata

Both are key-value pairs included in the hash chain, but they serve different purposes:

	Labels	Metadata
Storage	Separate indexed table	JSON blob in event row
Queryable	Yes — `?label.env=prod`	No
Policy engine	`labels.key` field access	`metadata.key` field access
Use case	Environment, department, user ID	Model 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.

Getting Started

Core Concepts

SDKs

Integrations

Zero-Code Adapters

Features

Event structure

Field reference

Identity fields

Source fields

Action fields

Timing fields

Integrity fields (server-assigned)

Dimension fields

Action types

Labels vs Metadata

Label context

Validation

​Event structure

​Field reference

​Identity fields

​Source fields

​Action fields

​Timing fields

​Integrity fields (server-assigned)

​Dimension fields

​Action types

​Labels vs Metadata

​Label context

​Validation

Event structure

Field reference

Identity fields

Source fields

Action fields

Timing fields

Integrity fields (server-assigned)

Dimension fields

Action types

Labels vs Metadata

Label context

Validation