The ARTF Intent Cheat Sheet Every OpenRTB Bid Ops Engineer Needs
本文为原文前 6,000 字符的节选翻译，完整内容请查看原文。
The ARTF Intent Cheat Sheet Every OpenRTB Bid Ops Engineer Needs
On 12 August 2026 IAB Tech Lab posted that ARTF v1.0 is FINAL and ready for production bidstreams. That is the week exit codes on container health checks start standing in for OpenRTB conformance. The Agentic Real Time Framework still ends on the same object buyers parse: a bid request or bid response inside an RTBRequest / RTBResponse envelope. Agents return patches, not replacements. Each patch line carries an intent (why), an operation (add, replace, remove), a semantic path (which auction entity), and a value oneof (ids, adjust_deal, adjust_bid, metrics, or content_data). If you wire agents without a sheet that maps intent to path and payload, you will green-light RPCs that leave deals on impressions that never carried them or shade bids that do not exist yet. This table is for engineers who own the orchestrator: SSP curators, exchange sidecars, DSP shading hooks. It is not a substitute for the ARTF explained guide; it is the bookmark you open when a mutation JSON lands in logs.
2026年8月12日，IAB Tech Lab宣布ARTF v1.0正式发布，并已准备好用于生产环境的竞价流。从那一周开始，容器健康检查的退出代码将开始作为OpenRTB一致性的替代指标。Agentic Real Time Framework（代理实时框架）最终处理的对象仍然是买方解析的同一目标：RTBRequest/RTBResponse信封内的竞价请求或竞价响应。代理返回的是补丁，而非替换。每个补丁行都包含一个意图（原因）、一个操作（添加、替换、删除）、一个语义路径（针对哪个竞价实体）以及一个值（ids、adjust_deal、adjust_bid、metrics或content_data）。如果你在没有意图到路径和负载映射表的情况下连接代理，你将批准那些在从未包含交易的展示位上留下交易，或者对尚不存在的竞价进行遮蔽的RPC。此表专为拥有编排器的工程师准备：SSP策展人、交易所侧挂程序、DSP遮蔽钩子。它不能替代ARTF说明指南；它是当你看到变异JSON进入日志时需要打开的书签。
Intent, lifecycle, path, and where it lands in OpenRTB ARTF splits work by lifecycle. Request-stage intents run at LIFECYCLE_PUBLISHER_BID_REQUEST on the publisher ticket. Response-stage intents run at LIFECYCLE_DSP_BID_RESPONSE when a bid object exists. The host also sends applicable_intents: an ACL of what the agent is allowed to propose. An intent outside that list is policy, not syntax. Semantic paths are not JSON pointers. They name business entities with stable segments such as /imp/imp-1/pmp/deals/deal-premium or /seatbid/seat-1/bid/bid-42. RTBlint resolves paths the same way the reference rules do: imp/{id}, imp/{id}/pmp/deals/{deal id} (or the shorter …/deals/{deal id} form), /user/data/segment, and /seatbid/{seat}/bid/{bid id}.
意图、生命周期、路径及其在OpenRTB中的落地位置。ARTF按生命周期划分工作。请求阶段的意图在发布商票据的LIFECYCLE_PUBLISHER_BID_REQUEST处运行。响应阶段的意图在存在竞价对象时的LIFECYCLE_DSP_BID_RESPONSE处运行。主机还会发送applicable_intents：即代理被允许提出的意图的访问控制列表（ACL）。超出该列表的意图属于策略问题，而非语法问题。语义路径不是JSON指针。它们使用稳定的段来命名业务实体，例如 /imp/imp-1/pmp/deals/deal-premium 或 /seatbid/seat-1/bid/bid-42。RTBlint解析路径的方式与参考规则相同：imp/{id}、imp/{id}/pmp/deals/{deal id}（或更短的…/deals/{deal id}形式）、/user/data/segment 以及 /seatbid/{seat}/bid/{bid id}。
| Intent | Lifecycle | Example semantic path | Payload oneof | OpenRTB field the host applies |
|---|---|---|---|---|
| ACTIVATE_SEGMENTS | Publisher bid request | /user/data/segment | ids | user.data[].segment |
| ACTIVATE_DEALS | Publisher bid request | /imp/imp-1/pmp/deals/deal-premium | ids | Deal id added under imp.pmp.deals[] |
| SUPPRESS_DEALS | Publisher bid request | /imp/imp-1 (remove op) | ids | Named deals removed from imp.pmp.deals[] |
| ADJUST_DEAL_FLOOR | Publisher bid request | /imp/imp-1/pmp/deals/deal-premium | adjust_deal | deals[].bidfloor |
| ADJUST_DEAL_MARGIN | Publisher bid request | /imp/imp-1/pmp/deals/deal-premium | adjust_deal | No OpenRTB 2.6 field (orchestrator only) |
| ADD_METRICS | Publisher bid request | /imp/imp-1 | metrics | imp.metric[] |
| BID_SHADE | DSP bid response | /seatbid/seat-1/bid/bid-42 | adjust_bid | seatbid[].bid[].price |
| ADD_CIDS | Publisher bid request | /user/data/segment | ids or content_data | data[].cids (OpenRTB 2.6-202505+) |
One row worth reading twice: ADD_CIDS on an exchange pinned to an earlier 2.6 snapshot. The intent is legal ARTF. The member may not exist on the wire version the host runs, so apply either no-ops or produces a field downstream DSPs reject. Version negotiation sits outside the mutation list; the envelope does not carry a dated snapshot string for the agent to read.
有一行值得反复阅读：在锁定于较早2.6快照的交易所上使用ADD_CIDS。该意图在ARTF中是合法的。但该成员可能在主机运行的传输版本中不存在，因此要么执行空操作，要么产生下游DSP拒绝的字段。版本协商位于变异列表之外；信封中不包含供代理读取的日期快照字符串。
Rows that pass the envelope and still break the auction ADJUST_DEAL_MARGIN with a perfect protobuf JSON mutation. Floor and margin share the adjust_deal oneof on the wire, but margin is not part of the OpenRTB Deal object. The orchestrator is supposed to apply margin in commercial logic the bid object never sees. Static validation warns with artf.mutation.no_openrtb_target. Treating that warning as success means you billed for a mutation that never changed what buyers parse.
那些通过了信封检查但仍会破坏竞价的行：使用完美的protobuf JSON变异进行ADJUST_DEAL_MARGIN。底价（Floor）和利润（Margin）在传输层共享adjust_deal的oneof，但利润并非OpenRTB交易对象的一部分。编排器应该在竞价对象永远无法看到的商业逻辑中应用利润。静态验证会发出artf.mutation.no_openrtb_target警告。将该警告视为成功意味着你为从未改变买方解析内容的变异计费了。
ACTIVATE_DEALS carrying adjust_bid. Copy-paste from a DSP shading template is the common source. Protobuf JSON parsing succeeds; gRPC returns OK; pass two fails because artf.mutation.payload_intent_mismatch binds ACTIVATE_DEALS to ids, not adjust_bid. The curator thought it activated a deal. The exchange got an illegal oneof.
ACTIVATE_DEALS携带了adjust_bid。这通常源于从DSP遮蔽模板中复制粘贴。Protobuf JSON解析成功；gRPC返回OK；但第二轮验证失败，因为artf.mutation.payload_intent_mismatch将ACTIVATE_DEALS绑定到了ids，而非adjust_bid。策展人以为激活了一笔交易，但交易所收到的是一个非法的oneof。
BID_SHADE at publisher request lifecycle. Shading needs a bid. LIFECYCLE_PUBLISHER_BID_REQUEST has no bid_response payload to target. That is artf.mutation.intent_not_applicable plus missing target payload, not a floor tweak you can forward anyway.
在发布商请求生命周期中使用BID_SHADE。遮蔽需要竞价。LIFECYCLE_PUBLISHER_BID_REQUEST没有可供定位的bid_response负载。这属于artf.mutation.intent_not_applicable加上缺少目标负载，而不是你可以随意转发的底价调整。
ADD_METRICS with Metric.value as a string. ARTF can accept the mutation object; OpenRTB expects a numeric value. Framework v1.0 does not require a third pass after apply, so the failure shows up only if you revalidate the bid request the host will fan out. The longer walkthrough of apply-then-revalidate is in ARTF mutations and bid request validation.
使用字符串类型的Metric.value进行ADD_METRICS。ARTF可以接受该变异对象；但OpenRTB期望的是数值。框架v1.0在应用后不需要第三轮验证，因此只有当你重新验证主机将要分发的竞价请求时，失败才会显现。关于“应用后重新验证”的更详细说明，请参阅《ARTF变异与竞价请求验证》。
Paths that look like JSON pointers. /imp/imp-1/pmp/deals/deal-premium/bidfloor is not a documented semantic reference. You get artf.mutation.path_unrecognized even when the deal id exists on the ticket. Deal floors use ADJUST_DEAL_FLOOR on the deal path, not a fake leaf segment.
看起来像JSON指针的路径。/imp/imp-1/pmp/deals/deal-premium/bidfloor不是文档化的语义引用。即使票据上存在该交易ID，你也会收到artf.mutation.path_unrecognized错误。交易底价应在交易路径上使用ADJUST_DEAL_FLOOR，而不是使用虚假的叶子段。
How you catch it I run three passes on every ARTF hop: envelope and carried OpenRTB as protobuf JSON, each mutation against lifecycle, applicable_intents, path resolution, and intent-specific oneof members, then apply accepted mutations and revalidate OpenRTB so field damage appears on the object buyers will see. The ARTF simulator runs the same engine in a browser: paste an RTBRequest, paste mutations, watch apply-then-revalidate.
如何捕获错误：我在每个ARTF跳点上运行三轮检查：将信封和携带的OpenRTB作为protobuf JSON进行检查，针对生命周期、applicable_intents、路径解析和意图特定的oneof成员检查每个变异，然后应用已接受的变异并重新验证OpenRTB，以便在买方将要看到的对象上显示字段损坏。ARTF模拟器在浏览器中运行相同的引擎：粘贴RTBRequest，粘贴变异，观察“应用后重新验证”的过程。
CLI: $ rtblint validate —type artf-request rtb-request.json $ rtblint validate —type artf-response —request rtb-request.json rtb-response.json $ rtblint validate —type artf-response —apply \ —request rtb-request.json rtb-response.json
命令行工具： $ rtblint validate —type artf-request rtb-request.json $ rtblint validate —type artf-response —request rtb-request.json rtb-response.json $ rtblint validate —type artf-response —apply \ —request rtb-request.json rtb-response.json
MCP tools validate_artf_request and validate_artf_response (with apply when you need post-patch OpenRTB) let an agent implementation call the check on its own output. The RPC can still return OK; the wire contract inside the envelope does not move. rtblint (cargo install rtblint, npm install rtblint-core, MCP rtblint-mcp) is the deterministic check on that object and mutation set. It is independent of IAB Tech Lab and of AAO; the spec does not require it, and nothing in v1.0 replaces pass two before you forward.
MCP工具validate_artf_request和validate_artf_response（当你需要补丁后的OpenRTB时使用apply）允许代理实现对其自身的输出调用检查。RPC仍然可以返回OK；信封内的传输契约不会改变。rtblint（cargo install rtblint, npm install rtblint-core, MCP rtblint-mcp）是对该对象和变异集的确定性检查。它独立于IAB Tech Lab和AAO；规范并不要求它，且v1.0中没有任何内容可以在转发前取代第二轮验证。
Where to go next Rule-level detail when intent and payload disagree: payload intent mismatch. When the agent proposes an intent
下一步：当意图和负载不一致时的规则级细节：payload intent mismatch（负载意图不匹配）。当代理提出一个意图时