The Personal Agent Protocol (Poppy), explained for businesses

What Poppy is

The Personal Agent Protocol, called Poppy for short, is an open protocol for how personal AI agents work with businesses. It is published at personalagentprotocol.org, and it defines two sides:

• The Personal Agent: the assistant acting for a person.
• The Company: the business the agent deals with.

This guide is about the Company side: what your business has to offer so that any compliant agent can work with it, without a separate integration for each assistant.

The five building blocks

1. Discovery: poppy.json

A business publishes a small JSON document at https://your-domain/.well-known/poppy.json. It names the organization and points to its authorization server, its APIs and the extensions it supports. An agent that reads it knows how to proceed.

2. Agent identity

Agents don't log in with a shared API key. Each agent publishes its own client metadata and public keys, and proves who it is with a signed assertion (OAuth 2.0 private_key_jwt, RFC 7523). The business can decide which agents it accepts.

3. Sessions and proof of possession

The agent gets a session token that is bound to its key with DPoP (RFC 9449). Every request carries a fresh proof signed by that key, so a copied token on its own is not enough.

4. Customer sign-in

A session starts signed out. To act on a customer's account, the agent asks the customer to sign in with the business, typically with a short code on the business's own page (Device Authorization Grant, RFC 8628). The assistant never sees the customer's password. The result is an account token that the business can revoke at any time.

5. APIs and operations

The business exposes what agents may do through standard interfaces (an OpenAPI description, or an MCP server). For actions that change something, the operations extension adds a safe pattern:

• the agent proposes an operation and gets back its exact terms and a summary;
• the customer approves that exact revision;
• the agent confirms it, and the business runs it at most once;
• if the terms change, the old approval no longer applies;
• every operation has a final state and a result.

What it means in practice

Imagine a customer telling their assistant: "Return the jacket I bought last week."

1. The assistant reads the shop's poppy.json.
2. It starts a session with its own key.
3. The customer signs in on the shop's page, with a code the assistant shows them.
4. The assistant lists the customer's orders and proposes returning one.
5. The shop answers with exact terms: this order, this refund, this method.
6. The customer approves; the assistant confirms; the shop processes the return once.

What a business has to implement

Supporting Poppy on the Company side means building and running:

• the discovery document and OAuth server metadata;
• client authentication with each agent's published keys;
• DPoP validation with replay protection;
• the device sign-in flow and account tokens, with revocation;
• an API description agents can use;
• the operations extension: revisions, approvals, confirmation, idempotency and final states.

On top of the protocol, a business also needs its own controls: rules for each action, review by its team, limits, a record of what happened, and a way to stop everything.

Building it yourself versus a gateway

You can implement the protocol directly; the specification and the official implementation kit are public. The cost is the security engineering, and keeping up as the protocol evolves.

Allowfy implements the Company side of Poppy as a gateway. It hosts discovery, authorization, sessions, customer sign-in and operations, and adds the business controls: rules per action with limits on amounts and over time, customer approval of exact terms, team review, an emergency stop, and a signed ledger. Your system connects through a signed webhook, or through the open-source allowfy package.

Check your implementation

Whatever you choose, you can test a domain against the protocol with the free, open-source Allowfy Check: it runs 111 checks and quotes the requirement behind each result.