diff --git a/docs/00-EXAMPLE.md b/docs/00-EXAMPLE.md index 3adc1fd..fb18f73 100644 --- a/docs/00-EXAMPLE.md +++ b/docs/00-EXAMPLE.md @@ -27,6 +27,7 @@ The Agentic RTB Framework (ARTF) defines a standard for implementing agent servi - **Deal Management** - Activate, suppress, and adjust deals dynamically - **Bid Shading** - Optimize bid prices using intelligent pricing strategies - **Metrics Addition** - Add viewability and other metrics to impressions +- **Embeddings** - Attach Agentic Audiences data segments with required embeddings to the bid request ### Key Principles @@ -226,7 +227,9 @@ message MetricsPayload { #### DataPayload -Used for adding content data, including content IDs in `data.ext.cids`. +Used for content data (`ADD_CIDS`) and for Agentic Audiences segments with embeddings (`ADD_EMBEDDINGS`) via the `data` field. + +For `ADD_EMBEDDINGS`, each `data.segment` **must** include `ext.aa` (OpenRTB Agentic Audiences envelope; see [openrtb2.x#188](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/pull/188)). ```protobuf message DataPayload { @@ -234,23 +237,26 @@ message DataPayload { } ``` +See [docs/intents/add-embeddings.md](intents/add-embeddings.md) for intent-specific usage. + --- ## Intents and Operations ### Intent Enum -| Value | Name | Description | -|-------|----------------------|------------------------------------------------| -| 0 | `INTENT_UNSPECIFIED` | Unspecified (invalid) | -| 1 | `ACTIVATE_SEGMENTS` | Activate user segments by external segment IDs | -| 2 | `ACTIVATE_DEALS` | Activate deals by external deal IDs | -| 3 | `SUPPRESS_DEALS` | Suppress deals by external deal IDs | -| 4 | `ADJUST_DEAL_FLOOR` | Adjust the bid floor of a specific deal | -| 5 | `ADJUST_DEAL_MARGIN` | Adjust the deal margin of a specific deal | -| 6 | `BID_SHADE` | Adjust the bid price of a specific bid | -| 7 | `ADD_METRICS` | Add metrics to an impression | -| 8 | `ADD_CIDS` | Add extended content IDs | +| Value | Name | Description | +|-------|----------------------|-------------------------------------------------------| +| 0 | `INTENT_UNSPECIFIED` | Unspecified (invalid) | +| 1 | `ACTIVATE_SEGMENTS` | Activate user segments by external segment IDs | +| 2 | `ACTIVATE_DEALS` | Activate deals by external deal IDs | +| 3 | `SUPPRESS_DEALS` | Suppress deals by external deal IDs | +| 4 | `ADJUST_DEAL_FLOOR` | Adjust the bid floor of a specific deal | +| 5 | `ADJUST_DEAL_MARGIN` | Adjust the deal margin of a specific deal | +| 6 | `BID_SHADE` | Adjust the bid price of a specific bid | +| 7 | `ADD_METRICS` | Add metrics to an impression | +| 8 | `ADD_CIDS` | Add extended content IDs | +| 9 | `ADD_EMBEDDINGS` | Add Agentic Audiences data segment(s) with embeddings | ### Operation Enum @@ -273,6 +279,7 @@ message DataPayload { | `BID_SHADE` | AdjustBidPayload | `/seatbid/{seat}/bid/{bidId}` | | `ADD_METRICS` | MetricsPayload | `/imp/{id}` | | `ADD_CIDS` | DataPayload | `/site/content/data` (`data.ext.cids`) | +| `ADD_EMBEDDINGS` | DataPayload | `/user/data` | Detailed guides for each intent live in `docs/intents/`. @@ -421,7 +428,8 @@ The container image must include an `agent-manifest` label with JSON metadata: "ACTIVATE_DEALS", "SUPPRESS_DEALS", "ADJUST_DEAL_FLOOR", - "BID_SHADE" + "BID_SHADE", + "ADD_EMBEDDINGS" ], "dependencies": {}, "health": { @@ -495,17 +503,51 @@ The container image must include an `agent-manifest` label with JSON metadata: } ``` +### Add Embeddings + +```json +{ + "intent": "ADD_EMBEDDINGS", + "op": "OPERATION_ADD", + "path": "/user/data", + "content_data": { + "data": [ + { + "name": "data-provider", + "segment": [ + { + "id": "seg-ctx-001", + "name": "descriptive-name", + "ext": { + "aa": { + "ver": "1.0.0", + "vector": "mpkZPq5HYb5SuJ4+PQrXPo/C9T7NzEy97FE4Pilcj74=", + "dimension": 8, + "model": "sbert-mini-ctx-001", + "type": [2] + } + } + } + ] + } + ] + } +} +``` + --- ## References - [IAB Tech Lab Agentic RTB Framework v1.0](https://iabtechlab.com/standards/artf/) - [OpenRTB v2.6 Specification](https://iabtechlab.com/standards/openrtb/) +- [IAB OpenRTB Agentic Audiences community extension](https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/community_extensions/agentic-audiences.md) +- [OpenRTB protobuf `Segment.ext.aa` (openrtb2.x#188)](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/pull/188) - [gRPC Documentation](https://grpc.io/docs/) - [Protocol Buffers](https://protobuf.dev/) - [OCI Container Specification](https://opencontainers.org/) --- -*Document Version: 1.0.0* -*Last Updated: November 2025* +*Document Version: 1.1.0* +*Last Updated: September 2026* diff --git a/docs/intents/add-embeddings.md b/docs/intents/add-embeddings.md new file mode 100644 index 0000000..a12f08d --- /dev/null +++ b/docs/intents/add-embeddings.md @@ -0,0 +1,55 @@ +# ADD_EMBEDDINGS + +Attaches user data segments carrying Agentic Audiences embeddings. + +**Payload:** `DataPayload` via the `data` field. Each segment **must** include `ext.aa`. + +**Eligible paths:** +- `/user/data` — targets the user. + +**Payload fields:** +- `data`: list of OpenRTB Data objects to attach to the user +- `data.name`: data provider name +- `data.segment`: segments from the provider +- `data.segment.id`: segment identifier +- `data.segment.name`: segment name +- `data.segment.ext.aa`: **required** Agentic Audiences embedding envelope + - `ver` — embedding schema/spec version + - `vector` — base64 Float32 little-endian (RFC 4648) + - `dimension` — number of Float32 values + - `model` — producing model identifier + - `type` — signal types: `1`=identity, `2`=contextual, `3`=reinforcement + +**Dependency:** OpenRTB protobuf `Segment.ext.aa` — [openrtb2.x#188](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/pull/188). + +## Example mutation + +```json +{ + "intent": "ADD_EMBEDDINGS", + "op": "OPERATION_ADD", + "path": "/user/data", + "content_data": { + "data": [ + { + "name": "data-provider", + "segment": [ + { + "id": "seg-ctx-001", + "name": "descriptive-name", + "ext": { + "aa": { + "ver": "1.0.0", + "vector": "mpkZPq5HYb5SuJ4+PQrXPo/C9T7NzEy97FE4Pilcj74=", + "dimension": 8, + "model": "sbert-mini-ctx-001", + "type": [2] + } + } + } + ] + } + ] + } +} +``` diff --git a/proto/agenticrtbframework.proto b/proto/agenticrtbframework.proto index e3be382..2477d32 100644 --- a/proto/agenticrtbframework.proto +++ b/proto/agenticrtbframework.proto @@ -99,7 +99,8 @@ message Mutation { // Metrics or telemetry data MetricsPayload metrics = 103; - // Content data + // Content data (also used by ADD_EMBEDDINGS; + // each segment must include ext.aa — see OpenRTB Segment.ext.aa) DataPayload content_data = 104; } @@ -143,6 +144,10 @@ enum Intent { // Add extended content IDs ADD_CIDS = 8; + // Add Agentic Audiences embeddings to BidRequest.user.data segments + // Uses DataPayload (content_data); each segment must include ext.aa + ADD_EMBEDDINGS = 9; + // More intents can be added in the future // Reserved for experimental/test intents