Internet Engineering Task Force A. Jurkovikj Internet-Draft 10 December 2025 Intended status: Best Current Practice Expires: 13 June 2026 HTTP Profile for Synchronized Resource State (Agentic State Transfer) draft-jurkovikj-httpapi-agentic-state-00 Abstract HTTP resources are frequently exposed in multiple representations (e.g., text/html for rendering and application/json for processing) via Content Negotiation. However, standard HTTP concurrency controls (such as ETags) are typically scoped to the byte sequence of a specific representation. This creates a synchronization gap where a client modifying one representation cannot guarantee consistency with the underlying state of another representation, leading to race conditions and "lost updates" in multi-client environments. This document specifies _Agentic State Transfer_ (AST), an HTTP profile for managing _Canonical Resource State_ (CRS) across multiple synchronized representations of the same resource. It defines the use of _Semantic Validators_ (Content Identity) to track the logical state of a resource independent of its serialization. It further mandates the use of Optimistic Concurrency Control via If-Match headers for state-changing operations, ensuring that mutations applied by automated agents are atomic and consistent across all views. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 13 June 2026. Jurkovikj Expires 13 June 2026 [Page 1] Internet-Draft Agentic State Transfer December 2025 Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. The Synchronization Problem . . . . . . . . . . . . . . . 4 1.2. Canonical Resource State (CRS) . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. The AST Profile . . . . . . . . . . . . . . . . . . . . . . . 6 3.1. Representation Roles . . . . . . . . . . . . . . . . . . 6 3.2. Semantic Validators (The SBR ETag) . . . . . . . . . . . 6 3.2.1. ETag Computation (Informative) . . . . . . . . . . . 6 3.3. Discovery (rel="state") . . . . . . . . . . . . . . . . . 7 3.4. Read Semantics . . . . . . . . . . . . . . . . . . . . . 7 3.4.1. Reading the SBR . . . . . . . . . . . . . . . . . . . 7 3.4.2. Reading Projections . . . . . . . . . . . . . . . . . 8 3.5. Write Semantics (The Safe Write Protocol) . . . . . . . . 8 3.5.1. Conflict Resolution (Informative) . . . . . . . . . . 10 4. Client immediately refetches . . . . . . . . . . . . . . . . 11 5. Client reapplies mutation with fresh ETag . . . . . . . . . . 11 5.1. SBR Endpoint Headers . . . . . . . . . . . . . . . . . . 11 5.2. Caching Considerations . . . . . . . . . . . . . . . . . 11 5.2.1. SBR Caching . . . . . . . . . . . . . . . . . . . . . 11 5.2.2. Projected Representation Caching . . . . . . . . . . 12 6. Computing and Managing Semantic Validators . . . . . . . . . 12 6.1. Canonicalization . . . . . . . . . . . . . . . . . . . . 13 6.2. Storage Models . . . . . . . . . . . . . . . . . . . . . 13 6.3. Relationship to Application Backends . . . . . . . . . . 13 6.4. Non-AST Resources and Fallback Behavior . . . . . . . . . 14 7. Integrity and Transport . . . . . . . . . . . . . . . . . . . 14 7.1. Separation of State and Integrity . . . . . . . . . . . . 14 8. Discovery of Synchronized Representations . . . . . . . . . . 15 8.1. The state Relation (SBR Discovery) . . . . . . . . . . . 16 8.2. The alternate Relation (General Cross-Representation Navigation) . . . . . . . . . . . . . . . . . . . . . . . 16 8.3. Bidirectional Linking . . . . . . . . . . . . . . . . . . 16 Jurkovikj Expires 13 June 2026 [Page 2] Internet-Draft Agentic State Transfer December 2025 8.4. Profile Advertisement . . . . . . . . . . . . . . . . . . 17 9. Security Considerations . . . . . . . . . . . . . . . . . . . 17 9.1. Consistency and Race Conditions . . . . . . . . . . . . . 17 9.2. Information Leakage via Divergence . . . . . . . . . . . 18 9.3. Validator Guessing . . . . . . . . . . . . . . . . . . . 18 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 10.1. Link Relation Type Registration . . . . . . . . . . . . 19 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 11.1. Normative References . . . . . . . . . . . . . . . . . . 19 11.2. Informative References . . . . . . . . . . . . . . . . . 20 Appendix A. Appendix A. Implementation Status . . . . . . . . . 20 A.1. WordPress Dual-Native Implementation . . . . . . . . . . 20 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 21 1. Introduction The architecture of the World Wide Web allows a single logical resource (identified by a URI) to be represented in multiple formats. A common pattern in modern systems is to expose: * a _Rendered Representation_ (e.g., text/html) for human agents, and * a _Structural Representation_ (e.g., application/json) for automated agents. In AST terminology, rendered representations are typically _Projected Representations_, while a structural representation MAY serve as the _State-Bearing Representation (SBR)_ when it exposes the full Canonical Resource State. HTTP provides mechanisms for content negotiation [RFC9110], and defines validators such as ETag for caching and conditional requests. However, in most deployments: * validators are derived from a particular representation's bytes, and * concurrency control, if present at all, is scoped to a single representation. This creates a _synchronization gap_: two clients interacting with different representations of the same logical resource can unwittingly overwrite each other's work. AST addresses this problem by treating the _Canonical Resource State_ (CRS) as the primary object of synchronization, and by standardizing how HTTP validators are used as _Semantic Validators_ for that CRS. Jurkovikj Expires 13 June 2026 [Page 3] Internet-Draft Agentic State Transfer December 2025 1.1. The Synchronization Problem Consider a resource /article/123 exposed both as HTML and JSON. 1. _Client A (Browser)_ retrieves the HTML representation. 2. _Client B (Automated Agent)_ retrieves the JSON representation. 3. Client A submits an edit via an HTML form, updating the underlying database record. 4. Client B, unaware of the change, computes an update based on its stale JSON representation and submits a PUT or PATCH request. In typical HTTP APIs, at least one of the following is true: * there is no ETag at all; * the ETag is tied to the bytes of a specific representation (e.g., JSON only); or * the server does not enforce preconditions (If-Match). As a result, Client B's request may succeed, even though: * its view of the resource is stale, and * the update logically conflicts with Client A's change. This is the classic _Lost Update_ problem, now exacerbated by the growing use of automated agents acting as first-class editors. 1.2. Canonical Resource State (CRS) To address this, AST introduces the concept of _Canonical Resource State_ (CRS): CRS is the authoritative, logical state of the resource, independent of any particular representation or serialization. For example, the CRS might be: * a database row (or set of rows), * a document or AST (abstract syntax tree), * a domain object in application memory, or Jurkovikj Expires 13 June 2026 [Page 4] Internet-Draft Agentic State Transfer December 2025 * in a WordPress CMS, the post record in wp_posts with fields like post_content, post_title, post_status, and associated metadata. Representations such as HTML, JSON, or Markdown are derived _from_ the CRS and are considered projections of that state. AST defines a profile where: 1. *Shared Identity* -- All HTTP representations of an AST resource are projections of the same CRS. 2. *Semantic Validation* -- Validators (ETag values) are derived from the CRS, not a specific representation's bytes, so that a change to the CRS invalidates all representations together. 3. *Mandatory Concurrency* -- State-changing operations on AST resources MUST provide a precondition (If-Match) based on the CRS validator. This enables safe interaction by automated agents and human clients, ensuring they participate in the same state transition model. 2. Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals. *Canonical Resource State (CRS)* The underlying, authoritative logical state of a resource (e.g., the database record or abstract syntax tree). The CRS is the atomic unit of concurrency. *State-Bearing Representation (SBR)* A specific representation (e.g., application/json) that exposes the CRS in a lossless, deterministic format. The SBR serves as the Concurrency Lock for the resource. Its ETag represents the version of the CRS. *Projected Representation* A representation derived from the CRS for a specific consumption pattern (e.g., text/html for rendering, text/csv for analysis). Projected Representations are Read-Only with respect to the CRS; they reflect the state but do not govern it. *Semantic Validator* The Strong ETag associated with the SBR. It changes if and only if the CRS changes. Jurkovikj Expires 13 June 2026 [Page 5] Internet-Draft Agentic State Transfer December 2025 *AST Resource* A resource that conforms to this profile. 3. The AST Profile This section defines the Agentic State Transfer (AST) profile. It specifies how clients synchronize state across multiple representations by pivoting on the State-Bearing Representation (SBR). 3.1. Representation Roles For a given AST Resource, the server MUST designate exactly one representation as the State-Bearing Representation (SBR). All other representations are considered Projected Representations. * The SBR acts as the source of truth for state synchronization. * Projected Representations are derivative views. While they MAY have their own caching validators (ETags) based on their specific byte sequences, they MUST NOT be used as the basis for state- changing preconditions on the CRS. 3.2. Semantic Validators (The SBR ETag) The server MUST assign a Strong ETag to the SBR. This ETag serves as the Semantic Validator for the resource. * *Determinism*: The SBR ETag MUST change whenever the CRS changes. * *Scope*: The SBR ETag MUST NOT be reused as the ETag for Projected Representations, as this would confuse standard HTTP caches. *Canonicalization*: Implementations MAY compute the SBR ETag from a deterministic canonical serialization of the CRS (e.g., JSON Canonicalization Scheme, RFC 8785 [RFC8785]). This ensures that logically identical states produce identical validators, regardless of field ordering or formatting variations. See Section 4.1 for detailed guidance. 3.2.1. ETag Computation (Informative) The SBR ETag MUST be a strong validator as defined in [RFC9110]. Implementations MAY compute the SBR ETag using any method that satisfies both the determinism and strong validator requirements. Common approaches include: Jurkovikj Expires 13 June 2026 [Page 6] Internet-Draft Agentic State Transfer December 2025 * *Content Hash*: SHA-256 or similar cryptographic hash over the canonicalized SBR bytes (e.g., "sha256-YWJjMTIz..."). This is RECOMMENDED for interoperability, as it allows clients to verify state equivalence without server coordination and naturally produces strong validators. * *Version Counter*: Monotonic version number from the data store (e.g., "v42" or "rev-1234"). This is simple but requires centralized version tracking. The version must increment on every CRS change to maintain strong validator semantics. The content hash approach provides the strongest guarantee that identical CRS values produce identical ETags across different server instances or time periods, which aids debugging and distributed deployments. 3.3. Discovery (rel="state") To enable clients consuming a Projected Representation (e.g., HTML) to discover the SBR for synchronization or editing, servers SHOULD include a Link header with the state relation type. The type attribute MUST be present to indicate the media type of the SBR, enabling clients to determine how to interact with it. *Example* (response for GET /article/123.html): http HTTP/1.1 200 OK Content-Type: text/html ETag: "html-v1" Link: ; rel="state"; type="application/json" 3.4. Read Semantics 3.4.1. Reading the SBR Clients SHOULD use the SBR ETag for conditional requests (If-None- Match) on the SBR URI. The server MUST return 304 Not Modified if the CRS has not changed. On a 304 response, the server SHOULD include the current SBR ETag in the response headers. Clients MUST NOT use the SBR ETag as If-None-Match against Projected endpoints. Projected endpoints have their own byte-specific validators. *Example: HEAD Request to Fetch SBR Validator* Clients MAY use HEAD to obtain the current SBR ETag without transferring the full representation body: Jurkovikj Expires 13 June 2026 [Page 7] Internet-Draft Agentic State Transfer December 2025 ```http HEAD /api/article/123 HTTP/1.1 Host: example.com Accept: application/json HTTP/1.1 200 OK Content-Type: application/json ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" Content-Length: 4521 ``` This allows clients to check for state changes with minimal bandwidth usage before deciding whether to fetch the full representation. 3.4.2. Reading Projections Clients MAY cache Projected Representations using their specific ETags. However, clients MUST recognize that a Projected Representation may be stale relative to the CRS if the SBR ETag has changed. 3.5. Write Semantics (The Safe Write Protocol) To modify the Canonical Resource State, clients MUST perform the mutation against the SBR Endpoint (or an endpoint explicitly bound to the SBR's validator). Clients *MUST NOT* use a Projected Representation's ETag as an If- Match precondition for CRS mutations. Only the SBR's own ETag is valid for concurrency control. 1. *Precondition*: The client obtains the current SBR ETag (via GET or HEAD on the SBR URI). 2. *Mutation*: The client sends the state-changing request (PUT, POST, PATCH) including the If-Match header set to the SBR ETag. 3. *Verification*: * If the If-Match header is missing, servers SHOULD respond with 428 Precondition Required [RFC6585]. Servers MAY respond with 400 Bad Request if 428 is not supported by the implementation environment, provided the error body clearly indicates the missing precondition requirement. * If the provided ETag does not match the current CRS version, the server MUST respond with 412 Precondition Failed. * If the provided ETag matches the current CRS version, the server MUST accept the write (subject to authorization), update the CRS, and invalidate all Projected Representations. Jurkovikj Expires 13 June 2026 [Page 8] Internet-Draft Agentic State Transfer December 2025 *Note*: For endpoints that do *not* implement AST semantics, servers MAY accept unconditional writes as in traditional HTTP APIs. See the "Non-AST Resources and Fallback Behavior" section for guidance on mixed deployments. 4. *Response*: Upon a successful write, the server SHOULD return the new SBR ETag in the response headers, allowing the client to chain subsequent updates immediately. 5. *Error Bodies*: For 412, 428, and 400 (when used for missing preconditions) responses, servers SHOULD return a Problem Details body [RFC7807] to assist automated clients in resolving the conflict. *Example: 428 Response for Missing Precondition* When a client attempts a state-changing operation without If-Match, the server SHOULD return a 428 response: ```http PATCH /api/article/123 HTTP/1.1 Host: example.com Content- Type: application/json HTTP/1.1 428 Precondition Required Content-Type: application/ problem+json { "type": "https://example.com/errors/precondition-required", "title": "Precondition Required", "status": 428, "detail": "If-Match header is required for CRS mutations" } ``` *Alternative: 400 Response When 428 Is Not Available* If the server environment does not support 428, it MAY use 400 with a clear error message: ```http PATCH /api/article/123 HTTP/1.1 Host: example.com Content- Type: application/json HTTP/1.1 400 Bad Request Content-Type: application/problem+json { "type": "https://example.com/errors/missing-precondition", "title": "Missing Required Precondition", "status": 400, "detail": "If-Match header is required for state-changing operations on AST resources" } ``` *Example: 412 Response with Problem Details* When a client's If-Match precondition fails, the server SHOULD return a Problem Details response indicating the current state: Jurkovikj Expires 13 June 2026 [Page 9] Internet-Draft Agentic State Transfer December 2025 ```http PATCH /api/article/123 HTTP/1.1 Host: example.com Content- Type: application/json If-Match: "sha256-ABC123OLDVALUE456789STALE012" HTTP/1.1 412 Precondition Failed Content-Type: application/ problem+json ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" { "type": "https://example.com/errors/precondition-failed", "title": "Precondition Failed", "status": 412, "detail": "The resource state has changed since you last read it.", "current-etag": "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F", "provided-etag": "sha256-ABC123OLDVALUE456789STALE012" } ``` The inclusion of the current ETag in the error response allows the client to immediately refetch the latest state without an additional round trip. 3.5.1. Conflict Resolution (Informative) When a client receives a 412 Precondition Failed response, it SHOULD follow one of these resolution strategies: 1. *Refetch and Retry*: Fetch the current SBR to obtain the new ETag and state, then reapply the intended mutation and retry with the updated ETag. 2. *Three-Way Merge*: If the client maintains the original state it read, the changes it intended to make, and can obtain the current server state, it MAY attempt an automatic merge (similar to version control systems). This is only appropriate when changes affect non-overlapping fields or can be deterministically combined. 3. *User Intervention*: Present the conflict to the user (human or automated decision system) for manual resolution, showing both the client's intended changes and the server's current state. 4. *Abort*: Abandon the update if the conflict indicates the client's view is too stale or the changes are incompatible. Servers MAY assist conflict resolution by including the current state or a conflict diff in the 412 response body (see Problem Details example above). This reduces round trips and provides clients with immediate context for resolution. *Retry Example:* Jurkovikj Expires 13 June 2026 [Page 10] Internet-Draft Agentic State Transfer December 2025 ```http # Client receives 412 HTTP/1.1 412 Precondition Failed Content-Type: application/problem+json ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" 4. Client immediately refetches GET /api/article/123 HTTP/1.1 If-None-Match: "sha256-ABC123OLDVALUE456789STALE012" HTTP/1.1 200 OK ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" { ...current state... } 5. Client reapplies mutation with fresh ETag PATCH /api/article/123 HTTP/1.1 If-Match: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" ``` 5.1. SBR Endpoint Headers To ensure correct caching and transfer behavior, SBR endpoints SHOULD include the following headers: * *Cache-Control*: SBR responses SHOULD include Cache-Control: no- transform to prevent intermediaries from modifying the representation (which would invalidate the Semantic Validator). * *Vary*: If the SBR supports compression or other content transformations, servers SHOULD set Vary: Accept-Encoding to ensure caches distinguish between compressed and uncompressed variants. * *Accept-Ranges*: SBR endpoints SHOULD include Accept-Ranges: none if range requests would break the semantic integrity of the representation (e.g., partial JSON structures). *Example SBR Response Headers:* http HTTP/1.1 200 OK Content-Type: application/json ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" Cache-Control: no-cache, no- transform Vary: Accept-Encoding Accept-Ranges: none Content-Digest: sha-256=:RK63H5GH1GQJQM8A7LN7RP8VNR7FVXWH1TQKJM8QZH4=: 5.2. Caching Considerations 5.2.1. SBR Caching SBR endpoints SHOULD follow these caching practices: Jurkovikj Expires 13 June 2026 [Page 11] Internet-Draft Agentic State Transfer December 2025 * *Non-Negotiated SBR*: Prefer a single canonical media type for the SBR to avoid cache fragmentation. * *Strong ETag*: The SBR MUST expose a strong ETag as the Semantic Validator. * *Cache-Control*: Use Cache-Control: no-cache, no-transform to require revalidation while allowing storage. If the SBR contains sensitive or user-specific data, use Cache-Control: private or no- store as appropriate. * *Vary*: Set Vary: Accept-Encoding if compression is applied to allow caches to distinguish between compressed and uncompressed variants. * *Accept-Ranges*: Consider Accept-Ranges: none to prevent partial- byte range requests that could create ambiguity in state validation. * *304 Revalidation*: Support conditional requests with If-None- Match and respond with 304 Not Modified when the SBR ETag matches. * *ETag Scope*: Do NOT reuse the SBR ETag on Projected endpoints, as this would conflate semantic and byte-level validation. 5.2.2. Projected Representation Caching Projected Representations SHOULD be cached using standard HTTP caching mechanisms: * *Representation-Specific ETags*: Use their own ETags based on the byte content of each projection. * *Standard Cache-Control*: Apply appropriate Cache-Control directives (e.g., max-age, public, private) based on the projection's volatility and sensitivity. * *Client-Side Invalidation*: Clients that perform CRS mutations SHOULD invalidate their own cached Projected Representations after a successful write or upon receiving a 412 Precondition Failed response. Note that shared caches and intermediaries will not automatically invalidate projections based on SBR changes. 6. Computing and Managing Semantic Validators AST does not mandate a single algorithm for computing Semantic Validators. However, interoperability and predictability benefit from consistent approaches. Jurkovikj Expires 13 June 2026 [Page 12] Internet-Draft Agentic State Transfer December 2025 6.1. Canonicalization A common pattern is to derive the Semantic Validator from a canonical serialization of the CRS. For example: 1. Serialize the CRS to a structured format (for example, JSON). 2. Canonicalize the serialization (for example, by sorting keys and controlling numeric formats). 3. Compute a hash over the canonical form (for example, SHA-256). 4. Encode and prefix the hash to produce the ETag value. Servers *SHOULD* ensure that: * fields that are purely operational or volatile (for example, last access timestamps) are excluded from the canonical form; and * the canonicalization process is deterministic across deployments. Servers MAY use [RFC8785] JSON Canonicalization Scheme (JCS) or an equivalent deterministic procedure. 6.2. Storage Models Servers MAY: * compute Semantic Validators on demand from the CRS; or * store precomputed Semantic Validators alongside the CRS. When validators are stored: * they *SHOULD* be updated atomically with the CRS; and * they *MUST* be invalidated or recomputed whenever the CRS changes. When validators are computed on demand, implementations *SHOULD* ensure that the cost of computing the validator is small relative to the cost of generating the representation. 6.3. Relationship to Application Backends AST is agnostic to how applications store and manage CRS. For example: Jurkovikj Expires 13 June 2026 [Page 13] Internet-Draft Agentic State Transfer December 2025 * a SQL application might treat a row (or set of rows) as CRS, with the Semantic Validator derived from a version column and relevant fields; * a document store might treat a document body plus metadata as CRS; * a CMS might treat a block tree or content graph as CRS. The only requirement is that the Semantic Validator change whenever the logical CRS changes, regardless of how many representations exist. 6.4. Non-AST Resources and Fallback Behavior Servers MAY implement AST for some resources and not others. For resources that do not follow AST: * servers MAY continue to use representation-specific ETags as byte validators; * servers MAY accept unconditional writes (no If-Match required), as in traditional HTTP APIs; and * clients MUST NOT assume AST semantics. Servers SHOULD clearly document which resources implement AST. 7. Integrity and Transport In standard HTTP usage, ETags often serve a dual purpose: validating the semantic state for caching/concurrency, and validating the integrity of the response bytes (to detect transport corruption). In the AST profile, the State-Bearing Representation (SBR) ETag serves as the *Semantic Validator* for the Canonical Resource State (CRS). Projected Representations MAY have their own representation- specific ETags for caching purposes, but these MUST NOT be used as Semantic Validators for concurrency control. 7.1. Separation of State and Integrity To allow clients to verify the integrity of the payload bytes independently of the semantic state, AST servers *SHOULD* use the Content-Digest header field defined in [RFC9530]. Jurkovikj Expires 13 June 2026 [Page 14] Internet-Draft Agentic State Transfer December 2025 * *ETag (SBR)*: validates the _Canonical Resource State_ (logical truth) and is used with If-Match and If-None-Match for concurrency control. * *ETag (Projected)*: MAY be used for caching individual representations, but MUST NOT be used for state-changing preconditions. * *Content-Digest*: validates the _representation bytes_ (wire truth) and is used to verify that the transfer completed successfully. Clients *MUST NOT* send If-Match or If-None-Match preconditions using a Projected Representation's ETag when interacting with the SBR endpoint. Only the SBR's own ETag participates in concurrency control logic. *Example Response (SBR):* http HTTP/1.1 200 OK Content-Type: application/json ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" Content-Digest: sha- 256=:RK63H5GH1GQJQM8A7LN7RP8VNR7FVXWH1TQKJM8QZH4=: *Example Response (Projected):* http HTTP/1.1 200 OK Content-Type: text/html ETag: "html-v1" Link: ; rel="state"; type="application/json" Content- Digest: sha-256=:X8Z9Y7W6V5U4T3S2R1Q0P9O8N7M6L5K4=: This separation allows intermediaries and clients to detect transport corruption without conflating it with state changes. In AST, the SBR ETag serves as a semantic validator for the Canonical Resource State. Clients SHOULD use Content-Digest for verifying byte integrity of the transfer. Outside of AST contexts, traditional ETag usage for caching and integrity remains unchanged. 8. Discovery of Synchronized Representations To enable agents to discover different representations of the same AST resource, servers *SHOULD* expose relationships between representations using the HTTP Link header [RFC8288]. Jurkovikj Expires 13 June 2026 [Page 15] Internet-Draft Agentic State Transfer December 2025 8.1. The state Relation (SBR Discovery) As defined in Section 3.3, Projected Representations SHOULD include a Link header with rel="state" pointing to the State-Bearing Representation (SBR). This allows clients consuming a Projected Representation to discover the SBR for synchronization or editing. The state relation identifies the authoritative SBR for concurrency control purposes. Clients MUST use the ETag from the state target (the SBR) for all If-Match and If-None-Match preconditions on state- changing operations. *Example* (Projected Representation response): http HTTP/1.1 200 OK Content-Type: text/html ETag: "html-v1" Link: ; rel="state"; type="application/json" 8.2. The alternate Relation (General Cross-Representation Navigation) The alternate link relation type is *RECOMMENDED* for general navigation between synchronized representations of the same AST resource. When providing an alternate link: * the type attribute *MUST* be present to indicate the media type of the target representation (for example, application/json, text/ html); and * the profile attribute *MAY* be used to indicate a specific schema or capability set of the target representation. *Example* (SBR response linking to Projected): http HTTP/1.1 200 OK Content-Type: application/json ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" Link: ; rel="alternate"; type="text/html" *Note:* The state relation specifically identifies the SBR for concurrency control purposes. In contrast, rel="alternate" is for general cross-representation navigation and does *not* imply concurrency semantics. Clients MUST NOT assume that a representation linked via alternate participates in the AST concurrency protocol. 8.3. Bidirectional Linking To ensure agents can navigate between representations regardless of their entry point, linking *SHOULD* be bidirectional. Jurkovikj Expires 13 June 2026 [Page 16] Internet-Draft Agentic State Transfer December 2025 * If Representation A links to Representation B, then Representation B *SHOULD* link back to Representation A (or to a canonical URI that resolves to A). This ensures that an agent encountering a structural representation (for example, JSON) can identify the corresponding rendered representation (for example, HTML) for attribution, verification, or human inspection. 8.4. Profile Advertisement To enable clients to detect whether a resource implements AST semantics, servers SHOULD advertise this using the profile link relation [RFC6906] via one of the following mechanisms: *Link Header with Profile Relation:* http HTTP/1.1 200 OK Content-Type: application/json Link: ; rel="profile" ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" *Content-Type Profile Parameter:* http HTTP/1.1 200 OK Content-Type: application/json; profile="https://datatracker.ietf.org/doc/draft-jurkovikj-http- agentic-state/" ETag: "sha256-RK63H5GH1GQJQM8A7LN7RP8VNR7F" This allows clients to detect AST resources and apply appropriate concurrency control workflows (If-Match preconditions, 412 handling, etc.) instead of assuming traditional HTTP semantics. 9. Security Considerations This profile relies on existing HTTP security mechanisms. However, the synchronization of multiple representations introduces specific security considerations. 9.1. Consistency and Race Conditions The primary security benefit of AST is the prevention of race conditions (Lost Updates). By enforcing If-Match checks against the CRS, the server ensures that an agent cannot overwrite state changes made by another client, even if those changes were made via a different representation. Applications *SHOULD* treat failed preconditions (412, 428) as an expected outcome in concurrent editing scenarios and provide appropriate conflict resolution mechanisms. Jurkovikj Expires 13 June 2026 [Page 17] Internet-Draft Agentic State Transfer December 2025 9.2. Information Leakage via Divergence If the access control policies for different representations diverge, there is a risk of information leakage. * Servers *MUST* ensure that the authorization requirements for accessing a structural representation (for example, JSON) are at least as strict as those for the rendered representation (for example, HTML). * Servers *MUST* ensure that a structural representation does not expose sensitive data that is redacted in the rendered representation, unless the client is explicitly authorized to see the raw state. If different audiences see different subsets of the CRS, the server SHOULD either: * maintain separate CRS domains with separate Semantic Validators; or * apply view-specific filtering consistently to all representations exposed to that audience. 9.3. Validator Guessing Because Semantic Validators are often derived from content (for example, a hash), they may be susceptible to offline guessing attacks if the content has low entropy. Implementations *SHOULD* ensure that: * validators have sufficient entropy; or * validators are combined with a secret salt; or * validators are derived from internal versioning mechanisms rather than directly from plaintext content, if the content version itself is sensitive. Validators MUST NOT be treated as authentication or authorization tokens. 10. IANA Considerations Jurkovikj Expires 13 June 2026 [Page 18] Internet-Draft Agentic State Transfer December 2025 10.1. Link Relation Type Registration This document requests registration of the "state" link relation type in the Link Relation Type Registry defined by [RFC8288]: * *Relation Name*: state * *Description*: Refers to the State-Bearing Representation (SBR) of the current resource for concurrency control. The target is the authoritative CRS view and exposes the strong ETag used for If- Match and If-None-Match on CRS-affecting operations. * *Reference*: This document (Sections 3.3 and 6.1) * *Notes*: The target's media type SHOULD be suitable for machine processing (e.g., application/json). Clients MUST use the target's strong ETag (not the source representation's ETag) as the validator for CRS preconditions. The type attribute SHOULD be present on the link to indicate the target's media type. 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017. [RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022. [RFC8288] Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/ RFC8288, October 2017. [RFC6585] Nottingham, M. and R. Fielding, "Additional HTTP Status Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012. [RFC9530] Polli, R. and L. Pardue, "Digest Fields", RFC 9530, DOI 10.17487/RFC9530, February 2024. [RFC7807] Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016. Jurkovikj Expires 13 June 2026 [Page 19] Internet-Draft Agentic State Transfer December 2025 [RFC6906] Wilde, E., "The 'profile' Link Relation Type", RFC 6906, DOI 10.17487/RFC6906, March 2013. 11.2. Informative References [RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, June 2022. [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, March 2010. [RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, DOI 10.17487/RFC8785, June 2020. [RFC6902] Bryan, P., Ed. and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Patch", RFC 6902, DOI 10.17487/RFC6902, April 2013. [RFC7386] Hoffman, P. and J. Snell, "JSON Merge Patch", RFC 7386, DOI 10.17487/RFC7386, October 2014. [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016. Appendix A. Appendix A. Implementation Status *Note to RFC Editor*: Please remove this section before publication. This section records the status of known implementations of the AST profile at the time of publication. Based on [RFC7942], reviewers are invited to report implementation experiences. A.1. WordPress Dual-Native Implementation *Organization*: Independent implementation *Description*: A WordPress plugin implementing the AST profile for content management and template synchronization. *Implementation Details*: * *SBR Endpoint*: Exposes WordPress posts and templates as application/json representations at /wp-json/dual-native/v1/ posts/{id} and /wp-json/dual-native/v1/design/templates/... Jurkovikj Expires 13 June 2026 [Page 20] Internet-Draft Agentic State Transfer December 2025 * *Semantic Validators*: Uses SHA-256 content hashes as strong ETags, formatted as "sha256-{base64}", computed from canonicalized JSON representation of the CRS. * *Concurrency Control*: Enforces If-Match preconditions on all state-changing operations (POST, PATCH). Returns 412 Precondition Failed on ETag mismatches and 428 Precondition Required when If- Match is missing. * *Projected Representations*: HTML rendering at canonical WordPress URLs with rel="state" Link headers pointing to the SBR endpoint. * *Discovery*: Implements rel="state" link relations on HTML responses and rel="alternate" on SBR responses. * *Multi-Bot Testing*: Demonstrated in production with multiple concurrent agents. Testing showed 89.4% bandwidth savings for monitoring workloads and zero lost updates (vs. 67% lost with standard WordPress REST API). *Maturity*: Production use since November 2025. *Coverage*: Implements all normative requirements of this specification including SBR designation, strong ETag generation, If- Match enforcement, 412/428 error handling with Problem Details (RFC 7807), and Link header discovery. *Licensing*: Open source *Contact*: antunjurkovic@gmail.com Author's Address Antun Jurkovikj Email: antunjurkovic@gmail.com Jurkovikj Expires 13 June 2026 [Page 21]