diff --git a/docs/00-EXAMPLE.md b/docs/00-EXAMPLE.md index ac8a9d8..8ce0c40 100644 --- a/docs/00-EXAMPLE.md +++ b/docs/00-EXAMPLE.md @@ -25,7 +25,7 @@ The Agentic RTB Framework (ARTF) defines a standard for implementing agent servi - **Segment Activation** - Activate user segments based on bid request data - **Deal Management** - Activate, suppress, and adjust deals dynamically -- **Bid Shading** - Optimize bid prices using intelligent pricing strategies +- **Bid Shading**, **Bid Valuation** - Optimize bid prices using intelligent pricing strategies - **Metrics Addition** - Add viewability and other metrics to impressions ### Key Principles @@ -114,6 +114,7 @@ The request message sent from the orchestrator to the agent. | `tmax` | int32 | Yes | Maximum response time in milliseconds | | `bid_request` | BidRequest | Yes | OpenRTB v2.6 bid request | | `bid_response` | BidResponse | No | OpenRTB v2.6 bid response (if available) | +| `object_ids` | IDsPayload | No | Optional intent-specific object IDs associated with the bid request | | `ext` | Extensions | No | Extension fields | ### RTBResponse @@ -193,6 +194,22 @@ message AdjustBidPayload { } ``` +#### AdjustBidValuationPayload + +Used for bid valuation responses. + +```protobuf +message BidValuationResult { + string id = 1; // Object ID from the RTBRequest payload that the bid valuation applies to + float value_factor = 2; // Adjusted bid valuation factor contributing to perceived bid request value +} + +message AdjustBidValuationPayload { + // List of bid valuation results pertaining to the object IDs originally passed via the RTBRequest payload + repeated BidValuationResult results = 1; +} +``` + #### AddMetricsPayload Used for adding impression metrics. @@ -219,6 +236,8 @@ message AddMetricsPayload { | 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 content IDs to an impression | +| 9 | `BID_VALUATION` | Adjust perceived value based on sideband information (e.g. ad groups, campaigns, contextual data) made available to the agent by the orchestrator or via outside sources | ### Operation Enum @@ -239,6 +258,7 @@ message AddMetricsPayload { | `ADJUST_DEAL_FLOOR` | AdjustDealPayload | `/imp/{id}/pmp/deals/{dealId}` | | `ADJUST_DEAL_MARGIN` | AdjustDealPayload | `/imp/{id}/pmp/deals/{dealId}` | | `BID_SHADE` | AdjustBidPayload | `/seatbid/{seat}/bid/{bidId}` | +| `BID_VALUATION` | AdjustBidValuationPayload | `/imp/{id}` | | `ADD_METRICS` | AddMetricsPayload | `/imp/{id}/metric` | --- @@ -386,7 +406,8 @@ The container image must include an `agent-manifest` label with JSON metadata: "ACTIVATE_DEALS", "SUPPRESS_DEALS", "ADJUST_DEAL_FLOOR", - "BID_SHADE" + "BID_SHADE", + "BID_VALUATION" ], "dependencies": {}, "health": { @@ -460,6 +481,35 @@ The container image must include an `agent-manifest` label with JSON metadata: } ``` +### Bid Valuation + +```json +{ + "intent": "ADJUST_BID_VALUATION", + "op": "OPERATION_ADD", + "adjust_bid_valuation": { + "results": [ + { + "id": "1234", + "value_factor": 1 + }, + { + "id": "4321", + "value_factor": 0.6 + }, + { + "id": "10101", + "value_factor": 0.75 + }, + { + "id": "20202", + "value_factor": 1 + } + ] + } +} +``` + --- ## References @@ -472,5 +522,5 @@ The container image must include an `agent-manifest` label with JSON metadata: --- -*Document Version: 1.0.0* -*Last Updated: November 2025* +*Document Version: 1.1.0* +*Last Updated: September 2026* diff --git a/proto/agenticrtbframework.proto b/proto/agenticrtbframework.proto index d5782de..01d56b1 100644 --- a/proto/agenticrtbframework.proto +++ b/proto/agenticrtbframework.proto @@ -1,6 +1,6 @@ edition = "2023"; -package com.iabtechlab.bidstream.mutation.v1; +package com.iabtechlab.bidstream.mutation.v2; // Import OpenRTB definitions for BidRequest and BidResponse import "com/iabtechlab/openrtb/v2.6/openrtb.proto"; @@ -31,8 +31,14 @@ message RTBRequest { // List of intents the server is eligibible to send back repeated Intent applicable_intents = 7; + // Object IDs for intent BID_VALUATION + oneof value { + // List of object identifiers referencing "sideband" information + IDsPayload object_ids = 100; + } + // Extension fields - Ext ext = 99; + Ext ext = 199; message Ext { extensions 500 to max; @@ -101,6 +107,9 @@ message Mutation { // Content data DataPayload content_data = 104; + + // Payload for bid valuation + AdjustBidValuationPayload adjust_bid_valuation = 105; } // Reserved for experimental/test payloads @@ -143,6 +152,9 @@ enum Intent { // Add extended content IDs ADD_CIDS = 8; + // Adjust bid valuation with factors + ADJUST_BID_VALUATION = 9; + // More intents can be added in the future // Reserved for experimental/test intents @@ -202,3 +214,15 @@ message DataPayload { // List of data to add repeated com.iabtechlab.openrtb.v2.BidRequest.Data data = 1; } + +message BidValuationResult { + // Object ID from the RTBRequest payload that the bid valuation applies to + string id = 1; + // Adjusted bid valuation factor + float value_factor = 2; +} + +message AdjustBidValuationPayload { + // List of bid valuation results pertaining to the object IDs originally passed via the RTBRequest payload + repeated BidValuationResult results = 1; +} \ No newline at end of file