Essay
Personal Agent Protocol: how an assistant acts for one customer
Walk through Poppy discovery, a signed-out session, and consent for an account lookup using a missing-delivery example.
“Can I return these headphones?” and “When were my headphones delivered?” sound like neighbouring questions. The first can often be answered from a public policy. The second requires a particular customer’s order history. A good personal assistant should notice the moment a public enquiry becomes an account operation.
Personal Agent Protocol, also called Poppy, describes how a personal agent interacts with a participating company on a user’s behalf. This walkthrough uses the version 1.0 specification. The shop, URLs and order below are fictional.
Start at the company domain
For a store at shop.example, the discovery request starts here:
GET /.well-known/poppy.json HTTP/1.1
Host: shop.exampleRead the supported protocol version and use the corresponding discovery information. If the company offers several conversation protocols, their descriptions help the agent choose a suitable one. A company might offer a returns conversation and a separate order API. The identity of the company and its authorization server matter even when another provider hosts an endpoint. Company discovery and issuer identification
My agent-ready-nextjs skill helps make site content discoverable to assistants. A readable returns page can answer the first question immediately. Supporting Poppy account access is a separate engineering commitment involving sessions, sign-in and authorization.
Three identities in one request
Poppy uses an opaque user identifier scoped to a user–company pair. Two unrelated companies receive different identifiers. Using the customer’s email address, even as input to a deterministic hash, would violate the protocol’s identity rules. Keep the mapping private. The company’s account identifier belongs to a different layer. Sessions and user identifiers, section 5
For API requests, the personal agent sends a signed Poppy-Session header. A delegated key signs the session JWT, and the delegation establishes the link to the personal agent. A company still needs an appropriate access token to release account data. A signed-out session can therefore ask about return windows while the order lookup waits for sign-in.
Ask for access at the boundary
The order read below is a schematic HTTP example. The path is the fictional store’s API, and the angle-bracket values stand for credentials produced by the protocol flows.
GET /orders/481/delivery HTTP/1.1
Host: shop.example
Poppy-Session: <session JWT signed for this request>
Authorization: Bearer <company-issued access token>Suppose the customer declines consent. The assistant can still explain the public return window and offer a link where the customer can check the delivery date themselves. Suppose the customer grants read access and then asks to initiate a refund. Recheck the grant and the company’s supported operations before attempting that separate action.
A practical test uses two fictional retailers and one customer. Verify that the user IDs differ between retailers, that a signed-out request cannot read the order, and that declining the grant produces a useful response. For the complete sign-in exchange, including issuer validation and the requirements for pushed authorization requests, use the implementation guides alongside the normative specification.