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

# Context Request

> Operator-generated, bid-safe auction context derived from a valid PlatformRequest — sent to downstream brand agents for bidding

## Overview

A **ContextRequest** is an operator-generated, bid-safe request sent to downstream brand agents after upstream consent, policy, and monetization eligibility have already been resolved. It is derived from a valid [PlatformRequest](/schemas/platform-request), but it is **not** a PlatformRequest.

The ContextRequest is the object that brand agents receive and bid on. It is optimized for:

* **Auction-safe context** — no raw interaction text, no full message history, no internal operator reasoning
* **Operator-enriched intent** — the intent block is operator-generated and downstream-safe, not a pass-through of platform signals
* **Allowed creative constraints** — what formats the platform surface supports
* **Usage restrictions** — explicit may/may-not permissions for data handling
* **Traceability** — every ContextRequest links back to the originating PlatformRequest

<Warning>
  A ContextRequest **MUST NOT** contain raw interaction text, full message history, or internal operator reasoning.
</Warning>

***

## Top-Level Fields

| Field               | Type   | Required | Description                                                                  |
| ------------------- | ------ | -------- | ---------------------------------------------------------------------------- |
| `spec_version`      | string | Yes      | Spec version. **MUST** be `"1.0"`                                            |
| `context_id`        | string | Yes      | Unique identifier for this operator-generated ContextRequest                 |
| `message_id`        | string | Yes      | Canonical message identifier copied from the originating `PlatformRequest`   |
| `timestamp`         | string | Yes      | RFC 3339 timestamp when the operator generated this ContextRequest           |
| `operator`          | object | Yes      | The system that generated the ContextRequest                                 |
| `platform`          | object | Yes      | The upstream AI platform where the interaction originated                    |
| `session`           | object | Yes      | Session identity and turn position                                           |
| `surface`           | object | Yes      | Unified surface descriptor (replaces placement, device, geography, language) |
| `intent`            | object | Yes      | Operator-generated, bid-safe intent classification                           |
| `allowed_formats`   | array  | Yes      | Creative formats the operator allows for this auction                        |
| `auction`           | object | No       | Auction timing constraints                                                   |
| `verticals`         | array  | No       | Normalized topical verticals                                                 |
| `consent`           | object | No       | Downstream-effective consent permissions                                     |
| `usage_constraints` | object | No       | Explicit data usage restrictions for brand agents                            |
| `extensions`        | object | No       | Optional operator-defined extension metadata                                 |

***

## Traceability

Every ContextRequest **MUST** contain:

* A unique `context_id` identifying this specific auction context
* The canonical upstream `message_id` for per-turn traceability

This two-ID design keeps concerns separate:

* `message_id`: upstream canonical message-turn identifier
* `context_id`: operator-generated auction identifier derived from `(session_id, message_id)`

The operator is the author of the ContextRequest; the platform is the source of the upstream interaction.

***

## `operator`

Identifies the system that generated this ContextRequest.

| Field         | Type   | Required | Description         |
| ------------- | ------ | -------- | ------------------- |
| `operator_id` | string | Yes      | Operator identifier |

***

## `platform`

Identifies the upstream AI platform where the user interaction originated. This is **not** the entity generating the ContextRequest — that is the `operator`.

| Field              | Type   | Required | Description                                |
| ------------------ | ------ | -------- | ------------------------------------------ |
| `platform_id`      | string | Yes      | Platform identifier (e.g. `"openai_chat"`) |
| `software`         | object | Yes      | Software identity                          |
| `software.name`    | string | Yes      | Product name                               |
| `software.version` | string | Yes      | Version or model identifier                |

<Note>
  The `platform` block replaces the old `producer` object. The platform is the AI host where the interaction occurred. The operator is the system that generated the ContextRequest. These are two distinct roles.
</Note>

***

## `session`

| Field        | Type    | Required | Description                                                |
| ------------ | ------- | -------- | ---------------------------------------------------------- |
| `id`         | string  | Yes      | Conversation or interaction session identifier             |
| `turn_index` | integer | Yes      | How many turns into the session the user is (minimum: `0`) |

***

## `surface`

A unified surface descriptor that replaces the old fragmented `placement`, `device`, `geography`, and `language` fields.

| Field              | Type   | Required | Description                                                                                           |
| ------------------ | ------ | -------- | ----------------------------------------------------------------------------------------------------- |
| `channel`          | string | Yes      | `"conversation"`, `"search_result"`, `"assistant_panel"`, `"embedded_assistant"`, `"voice_assistant"` |
| `interaction_mode` | string | Yes      | `"text"`, `"voice"`, `"multimodal"`                                                                   |
| `platform`         | string | Yes      | `"web"`, `"mobile"`, `"desktop_app"`, `"browser_extension"`, `"api"`, `"other"`                       |
| `form_factor`      | string | No       | `"mobile"`, `"desktop"`, `"tablet"`, `"speaker"`, `"other"`                                           |
| `country`          | string | No       | ISO 3166-1 alpha-2 country code (e.g. `"US"`)                                                         |
| `locale`           | string | No       | BCP 47 locale (e.g. `"en-US"`)                                                                        |

***

## `auction`

Timing constraints for the auction.

| Field               | Type    | Required | Description                                               |
| ------------------- | ------- | -------- | --------------------------------------------------------- |
| `latency_budget_ms` | integer | No       | Maximum time in milliseconds brand agents have to respond |
| `context_window_ms` | integer | No       | Time window within which the auction context is valid     |

***

## `intent`

The `intent` in a ContextRequest is **operator-generated** and **downstream-safe**. It is used for bidding and creative selection. It may differ from any platform-provided or platform-derived intent found earlier in the upstream pipeline. That difference is valid and expected.

| Field             | Type   | Required | Description                                                                                                  |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------ |
| `type`            | string | Yes      | `"commercial"`, `"transactional"`, `"informational"`, `"navigational"`, `"support"`, `"unsafe"`, `"unknown"` |
| `subtype`         | string | No       | Interaction pattern (e.g. `"comparison"`, `"product_discovery"`)                                             |
| `decision_phase`  | string | Yes      | `"awareness"`, `"research"`, `"consideration"`, `"decision"`, `"action"`, `"post_purchase"`, `"support"`     |
| `confidence`      | number | Yes      | Calibrated confidence score (`0.0`–`1.0`)                                                                    |
| `summary`         | string | Yes      | Operator-generated bid-safe summary. **MUST NOT** contain raw user queries or message content                |
| `relevance_score` | number | No       | Operator-computed relevance score for auction ranking (`0.0`–`1.0`)                                          |
| `iab_content`     | object | No       | IAB Content Taxonomy mapping for the classified intent                                                       |

### `intent.iab_content`

IAB content taxonomy mapping derived from the operator's classification. Brand agents use this for vertical targeting and creative selection.

| Field              | Type   | Required | Description                                   |
| ------------------ | ------ | -------- | --------------------------------------------- |
| `taxonomy`         | string | Yes      | Taxonomy name (e.g. `"IAB Content Taxonomy"`) |
| `taxonomy_version` | string | Yes      | Taxonomy version (e.g. `"3.1"`)               |
| `tier1`            | string | Yes      | Top-level IAB category                        |
| `tier2`            | string | No       | Second-level IAB category                     |
| `tier3`            | string | No       | Third-level IAB category                      |
| `tier4`            | string | No       | Fourth-level IAB category                     |

<Warning>
  The `intent` block **MUST NOT** include `classification_reasoning` or any internal operator logic. Only expose the outputs that brand agents need to act on: type, phase, confidence, summary, and relevance score.
</Warning>

***

## `allowed_formats`

Creative formats allowed by the operator for this auction.

Valid values: `"weave"`, `"tail"`, `"product_card"`, `"bridge"`

***

## `verticals`

Array of normalized topical verticals identified by the operator (e.g. `["crm", "smb_software"]`).

***

## `consent`

Downstream-effective consent permissions. Brand agents do not receive the full upstream consent envelope — only the permissions relevant to their participation.

| Field                 | Type    | Description                                                   |
| --------------------- | ------- | ------------------------------------------------------------- |
| `agent_participation` | boolean | Whether the user has consented to brand agent participation   |
| `measurement`         | boolean | Whether the user has consented to measurement and attribution |

***

## `usage_constraints`

Explicit usage restrictions that downstream brand agents **MUST** respect.

| Field                   | Type    | Description                                                                  |
| ----------------------- | ------- | ---------------------------------------------------------------------------- |
| `may_store`             | boolean | Whether the brand agent may store the context data                           |
| `may_train`             | boolean | Whether the brand agent may use the data for model training                  |
| `may_forward`           | boolean | Whether the brand agent may forward the data to third parties                |
| `retention_ttl_seconds` | integer | Maximum retention time in seconds. Data **MUST** be discarded after this TTL |

***

## Processing Rules

1. **Not a PlatformRequest.** A ContextRequest is derived from a PlatformRequest, but the operator is the author. The platform is the source of the upstream interaction.

2. **No raw interaction leakage.** A ContextRequest MUST NOT contain raw `query_text`, raw `messages`, or `classification_reasoning`. The `intent.summary` is the only natural-language field, and it is operator-generated and sanitized.

3. **Intent may differ from upstream.** The intent in a ContextRequest is operator-generated. It may differ from any platform-provided or platform-derived intent in the originating PlatformRequest. That difference is valid and expected — the operator applies its own classification, normalization, and policy.

4. **Usage constraints are binding.** If `usage_constraints.may_store` is `false`, the brand agent MUST NOT persist the context data beyond the auction. If `retention_ttl_seconds` is set, the brand agent MUST discard data after that TTL.

5. **Consent is downstream-scoped.** The `consent` block contains only the permissions relevant to brand agents, not the full upstream consent model.

***

## Example

```json theme={null}
{
  "spec_version": "1.0",
  "context_id": "ctx_92fA1",
  "message_id": "msg_92fA1_turn_003",
  "timestamp": "2026-03-26T18:22:00Z",

  "operator": {
    "operator_id": "operator_x"
  },

  "platform": {
    "platform_id": "openai_chat",
    "software": {
      "name": "chatgpt",
      "version": "4.3-mini"
    }
  },

  "session": {
    "id": "sess_001",
    "turn_index": 3
  },

  "surface": {
    "channel": "conversation",
    "interaction_mode": "text",
    "platform": "web",
    "form_factor": "desktop",
    "locale": "en-US",
    "country": "US"
  },

  "auction": {
    "latency_budget_ms": 500
  },

  "allowed_formats": ["weave", "tail", "product_card"],

  "intent": {
    "type": "commercial",
    "subtype": "comparison",
    "decision_phase": "decision",
    "confidence": 0.87,
    "summary": "User is evaluating CRM tools and narrowing down options.",
    "relevance_score": 0.87,
    "iab_content": {
      "taxonomy": "IAB Content Taxonomy",
      "taxonomy_version": "3.1",
      "tier1": "Business and Finance",
      "tier2": "Business",
      "tier3": "Business I.T."
    }
  },

  "verticals": ["crm", "smb_software"],

  "consent": {
    "agent_participation": true,
    "measurement": true
  },

  "usage_constraints": {
    "may_store": false,
    "may_train": false,
    "may_forward": false,
    "retention_ttl_seconds": 300
  }
}
```

***

## What Changed from the Previous Schema

| Before                                                                       | After                                                               | Why                                                                             |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Single reused upstream request identifier                                    | `context_id` + `message_id`                                         | Separate operator-generated auction ID from upstream message ID                 |
| `producer` (mixed platform/operator identity)                                | `operator` + `platform` (distinct blocks)                           | The operator generates the ContextRequest; the platform is the upstream source  |
| `publisher`, `placement`, `device`, `geography`, `language`, `platform_type` | `surface` (unified object)                                          | Eliminates fragmentation and redundancy                                         |
| `classification_reasoning` in intent                                         | Removed                                                             | Internal operator reasoning is a leakage risk and should not reach brand agents |
| `intent_confidence` + `confidence` (duplicated)                              | Single `confidence` field                                           | Removes duplication                                                             |
| `consent` (full upstream envelope)                                           | `consent` (downstream-scoped: `agent_participation`, `measurement`) | Brand agents only need their effective permissions                              |
| `usage_constraints.disallowed` (string array)                                | `may_store`, `may_train`, `may_forward`, `retention_ttl_seconds`    | Explicit boolean permissions are clearer and enforceable                        |
| `context` (nested wrapper)                                                   | Flat top-level fields                                               | Removes unnecessary nesting for a bid-optimized object                          |

***

## Related

* [Platform Request](/schemas/platform-request) — The upstream request that the ContextRequest is derived from
* [Bid](/schemas/bid) — The response brand agents send back to the operator
* [Platform Response](/schemas/platform-response) — The operator's auction outcome after evaluating bids