> ## Documentation Index
> Fetch the complete documentation index at: https://docs.provenlog.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> The ProvenLogEvent schema and action types

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

## Event structure

```json theme={null}
{
  "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:

```python theme={null}
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](/sdks/python#labels-and-context) and [TypeScript SDK](/sdks/typescript#labels-and-context) 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.