Skip to content

Add new BID_VALUATION intent and additional payload for intermediate transformation #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
arpadmiklos-ttd wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add new BID_VALUATION intent and additional payload for intermediate transformation #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a5b795c
Added new bid valuation intent and related structures
arpadmiklos-ttd Aug 3, 2026
fa27200
Updated example doc
arpadmiklos-ttd Aug 3, 2026
e029f8e
Updated proto and docs based on ARTG discussion feedback
arpadmiklos-ttd Sep 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 54 additions & 4 deletions docs/00-EXAMPLE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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

Expand All @@ -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` |

---
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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
Expand All @@ -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*
28 changes: 26 additions & 2 deletions proto/agenticrtbframework.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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";
Expand Down Expand Up @@ -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

@adrian-vaca-humanes-wt adrian-vaca-humanes-wt Aug 18, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With this we can one can take the deals or segments from the RTB section and interpret the host wants those scored.

For discussion:

What should the semantic be if the caller/host passes imp[].pmp.deals[] or user.data[].segment[] as empty lists? Invalid request, or would the expectation be for it to still return something? Because for example, if the container receives an embedding it could issue ACTIVATE_DEAL and ACTIVATE_SEGMENT and at the same time a ADJUST_BID_VALUATION for those. While applicable_intents could be a signal of the type of types of IDs expected back in this scenario, I wonder if intents should support inputs other than what one may shoehorn as an extension, for example, in this empty list scenario where the container is supposed to give it its best shot, a topK input could be useful. And yes, this could also just be default configuration of the container or come through an extension.

@arpadmiklos-ttd arpadmiklos-ttd Aug 18, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These IDs are representations of an advertiser's entities on the buyer side, and the purpose of this BID_VALUATION addition is to allow third parties to contribute to the advertiser asset (say, campaign or ad group) valuation decision made by the DSP against the incoming bid request. As such, these do not correlate to individual deals or contextual segments or any other field in the bid request.

IMO if we want to add functionality to attribute relative value/worth to deals or segments, that should be covered by another intent separate from this PR, and the discussion point you raised would be germane to that.

On a closely related note, I think the standard could be improved in terms of either explicitly associating intents and payloads more unequivocally, or at least clarifying expectations. For example, a container responding with mutations using the ACTIVATE_SEGMENTS intent could well supply IDsPayload as sets of flat segment IDs, or DataPayload instances that have segments plus and additional name and ID or even content IDs, and I'm not sure what the expectation from an orchestrator is in this case.

@adrian-vaca-humanes-wt adrian-vaca-humanes-wt Aug 18, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I got ahead of myself by thinking of these object IDs as references to objects in a partial OpenRTB payload. From there, I moved toward semantics that could be implemented today using deal IDs and segment IDs as examples. More generally, though, I was exploring whether this could be generalized regardless of ID type—particularly the semantics of an empty list, where the orchestrator could treat the container as a recommender. But you may be right that recommendation or candidate discovery belongs in a separate intent specification altogether.

Setting that discussion aside, do you envision distinct ID-type-specific valuation containers, where each container can score only one type of ID? If so, would there be an implicit, out-of-band agreement about what the opaque IDs represent for that intent?

@arpadmiklos-ttd arpadmiklos-ttd Aug 18, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current 1.0 version of this standard doesn't specify such ID types even though IDsPayload is already used in different contexts, that's why I didn't add ID types here. When someone works with us to implement a container that supports ADJUST_BID_VALUATION, they will know what to expect based on out-of-band conventions (not part of this spec).

Indeed we probably should add an ID type field, or create different variants of the IDsPayload message to ensure these payload IDs align with the expected type and that the container can actually work with them. Unfortunately, both would be a breaking change.

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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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;
}