Glossary: the words in the protocol and in Agent Adapt Free & Pro

Terms with a capital letter are the Personal Agent Protocol’s own, used with the meaning its specification (Draft 0.1) gives them. The rest are WooCommerce’s, OAuth’s or ours.

Account Token. The long-lived credential an agent receives when a customer signs it in. It is only ever presented to the store’s token endpoint, to get fresh Session Tokens, and it can narrow what was approved but never widen it. In Agent Adapt it lasts 90 days, and it is what Disconnect on the Connected agents tab revokes.

Agent. Short for Personal Agent, below.

Agents screen. WooCommerce → Agents, the list of every agent that has visited your store, with sessions, orders and a Block control. With Pro it also holds your policy.

Allowlist (Pro). A mode in which your store accepts only the agents you have ticked and refuses every other, before it is even recorded.

Block. Refusing an agent, by its Client ID, from its next request onwards, everywhere in the store. Blocking does not delete anything; unblocking restores customers’ existing approvals.

Browser session. The protocol’s way for an agent’s own web browser to join a Session on the store’s website, so the browser sees the same cart and sign-in as the agent’s API calls. Agent Adapt’s endpoint for it is /agent-adapt/browser-session. The browser is refused the dashboard, the login page, account details, payment methods and checkout.

Checkout link (checkout handoff). Agent Adapt’s answer to the protocol’s open question of payment: a single-use link, valid for 30 minutes, that adds the agent’s cart to the customer’s own browser cart and takes them to your checkout. Advertised as the extension getagentadapt.com/checkout-handoff.

Client ID. An agent’s identity: the HTTPS address of its client metadata document. Shown on the Agents screen and on the customer’s consent page.

Client metadata document. The public JSON an agent publishes at its Client ID, naming itself and pointing at its public keys (jwks_uri) and its redirect addresses.

Company. The protocol’s word for a business that implements it. Your store.

Connected agents. The tab in My Account where a customer sees each agent connected to their account, what it may do, when it was last used, and a Disconnect button.

Consent page. The page on your store, after sign-in, where the customer sees which agent is asking, ticks what it may do, and presses Allow or Decline. Titled Connect your assistant.

Device Sign-In. Sign-in by code, for assistants that cannot open a link for the customer (a speaker, a car). The assistant shows a code; the customer enters it at your-store/agent-adapt/device. Codes last 10 minutes.

Direct Sign-In. Sign-in by link. The agent sends the customer to your store, where they sign in as usual and approve the agent on the consent page. Standard OAuth authorization code flow with PKCE.

Discovery. The first step of any visit: fetching poppy.json and the OAuth metadata it points to.

DPoP. Demonstrating Proof of Possession (RFC 9449). The mechanism that binds a Session Token to a key the agent holds, so each API call carries a signed, single-use proof and a copied token is useless alone.

Event. A record of something an agent did at your store: a search, a cart change, a checkout link, an order, a sign-in. Kept in your database for 90 days by default, shown in Pro’s Agent insights and sent by Pro’s webhooks.

Extension. A named addition to the protocol. The draft defines operations; anything else is named with its author’s domain. Agents list the extensions they support, and a store sends an extension only to agents that list it.

Issuer. The address of your store’s OAuth server, https://your-store/agent-adapt. Everything to do with tokens and sign-in hangs off it.

JWKS. JSON Web Key Set: an agent’s published public keys, fetched by your store from the agent’s jwks_uri and used to verify its signatures.

MCP. Model Context Protocol, an open standard for giving an AI application tools. One of the two API types the protocol lets a store offer. Agent Adapt Pro runs an MCP server.

Mediated Sign-In. The protocol’s optional third sign-in type, where the agent submits the customer’s credentials to the store. Agent Adapt does not offer it.

OpenAPI. A standard way of describing an HTTP API. Agent Adapt publishes its agent API’s description at /wp-json/agent-adapt/v1/openapi.json, generated from the same code that answers the calls.

Operation (Pro). A change proposed by an agent and performed only after the customer approves its exact terms: cancelling a paid order with a refund, sending a return request, changing a saved address. Each has a revision; only the latest can be confirmed; an operation is performed at most once; unconfirmed proposals expire after 15 minutes.

Order attribution. WooCommerce’s own record of where an order came from. Orders through a checkout link show the agent’s name as the source, with medium personal_agent and campaign agent-adapt.

Personal Agent. Software acting on a person’s behalf: an assistant in a messaging app, a browser, a phone, a speaker, a car. It belongs to the person, not to the store.

Policy (Pro). Your store’s rules on top of each customer’s approval: which actions are available at all, your return window, a per-agent cap (view only, or signed-out shopping only), and the allowlist. Policy can only narrow what an agent may do.

poppy.json. The discovery document, at /.well-known/poppy.json. See What poppy.json is.

Rate limit. A cap on how often an agent may do something: 300 API calls a minute per Session, for example. Over the limit, the store answers 429 with Retry-After.

Revision. See Operation.

Scope. What a customer has allowed an agent to do with their account. The protocol defines poppy:read (view) and poppy:write (make changes); Agent Adapt Pro adds addresses. The consent page shows them in plain words.

Session. One visit by one agent for one customer at your store. It starts signed out and can be signed in to exactly one account. It ends after 30 days without use.

Session Token. The short-lived, DPoP-bound token an agent presents on every API call. Lasts an hour; the agent renews it. Your store stores only its hash.

Site Health. Tools → Site Health, where Agent Adapt adds six checks of the hosting facts that decide whether agents can reach your store.

Standing permission. A customer’s advance approval that lets an agent confirm some operations without asking each time. Refunds and address changes in Agent Adapt always require the customer’s approval of the specific terms, so a standing permission is refused for them.

Token endpoint. /agent-adapt/oauth/token, where an agent starts and renews Sessions, exchanges a sign-in code and uses an Account Token.

User. The protocol’s word for the person an agent acts for. Your customer.

User ID. The opaque, stable identifier an agent gives a person at a particular store, so the store can recognise a returning agent-and-customer pair before any sign-in. It must not be derived from personal information, and Agent Adapt stores it only hashed.