Back to Articles

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.

November 22, 20263 min readPoppyPersonal Agent Protocol

“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

Discoverpoppy.json
ChooseAPI or conversation
RequestSigned session
Discovery gives the assistant a company-specific starting point and descriptions of the available interfaces.

For a store at shop.example, the discovery request starts here:

GET /.well-known/poppy.json HTTP/1.1
Host: shop.example

Read 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

Personal agentWhich software is calling?
Pairwise user IDWhich user at this company?
Account grantWhich account actions were approved?
A company can recognise a returning session participant before the customer grants access to an account.

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

Direct sign-in puts consent on the company’s page. The code returns through the redirect flow. Token exchange precedes the account request.Customer to Personal agent: Find delivery date. Personal agent to Company: Start direct sign-in. Customer to Company: Sign in and consent. Company to Personal agent: Authorization code. Personal agent to Company: Exchange code. Personal agent to Company: Read order. Company to Personal agent: Delivery date.CustomerPersonal agentCompanyFind delivery dateStart direct sign-inSign in and consentAuthorization codeExchange codeRead orderDelivery date
Direct sign-in puts consent on the company’s page. The code returns through the redirect flow. Token exchange precedes the account request.

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.