By · Founder, Stacktree · Last updated
Personal Agent Protocol · for companies

How to implement the Personal Agent Protocol.

The spec is long, and you do not have to build it in the order it is written. Stacktree has run every version in production since the first draft. This is the order we would build in again, what each stage is for, what it cost, and where we got it wrong.

The Poppy Simulator checks any company. Free, no sign-up.

How do you implement the Personal Agent Protocol?

Start with one file. Publish /.well-known/poppy.json on your main domain with your name, your domain and one channel, and personal agents can use you signed out. Then add in this order, stopping when your tasks are covered: accept and verify the Poppy-Session header, verify agents from their metadata documents, add OAuth sign-in with a consent page, decide on Device Sign-In, and serve more than one version. Test against an agent you did not write before you call it done.

Before you start: choose the tasks

The adoption guide opens with the right advice: start with the tasks you want agents to do and the interfaces you already have. Write the tasks down and mark each one needs the account or does not. That one column decides how much of the protocol you build.

For us the list was short. Publishing a page to a private link needs no account, and it is most of what people use Stacktree for. Seeing who opened a page, or changing a page later, needs the account. So the signed-out stages carried real value on their own, and we shipped them first.

Stage 1: one file, signed out

This is a complete Version 1.0 document:

{
  "protocol_version": "1.0",
  "organization": { "name": "Example", "domain": "example.com" },
  "apis": [
    {
      "type": "openapi",
      "url": "https://api.example.com/openapi.json",
      "description": "Search the catalog and check stock. No account needed."
    }
  ]
}

Serve it at https://example.com/.well-known/poppy.json, on the domain your customers know, not only on your API host. If you have no OAuth for agents yet, return 404 from /.well-known/oauth-protected-resource on that domain and leave auth out. Check both:

curl -s https://example.com/.well-known/poppy.json
curl -s -o /dev/null -w '%{http_code}\n' \
  https://example.com/.well-known/oauth-protected-resource

You need at least one of three channels. apis lists an OpenAPI description or an MCP server. agent lists your own support agent. web is your website, and it can be the whole file: Clerk's own poppy.json is 88 bytes and offers only web. Our field guide covers every field.

Cost: the smallest stage by far. Most of the time goes on writing descriptions an agent can choose from.

Stage 2: the Session header

Every request a personal agent sends to your APIs carries Poppy-Session, a short-lived token the agent signs for that one request, and Poppy-Version. Two rules (section 5.3):

  • Always accept it. Your gateway or firewall must not reject the headers.
  • Verify it before you rely on it. A stateless catalog endpoint can ignore the header. Anything you keep for a Session, such as a cart, a conversation or a draft, needs the full check first.

Do the check in one place. Ours is one middleware in front of the REST API, the MCP server and the feedback endpoint, and it passes the verified agent, Session and User ID to whatever is behind it. What it checks: the signature, the audience, that the request's method and address match the ones signed, a 60-second freshness window, and that the token's id has not been seen before. Cache the agent's delegation, keyed by a hash of the whole thing, and most requests cost one signature check.

What you get: a stable, pseudonymous User ID for each person, different at every company. You can recognize a returning person, rate-limit one agent, and keep state for someone who never signed in.

Cost: moderate. Every check has to refuse the right things, and that takes longer than accepting the right ones.

Stage 3: who is this agent?

An agent's client_id is an HTTPS address where it publishes its name and public keys (4.1). There is no registration. To trust a signature you fetch that document, so:

  • Fetch it without following redirects, and check that the client_id inside equals the address you fetched.
  • Refuse private and loopback addresses. You are fetching an address a stranger gave you.
  • Cache the document and the keys, and rate-limit new client_id values.
  • Keep an allowlist or a blocklist. Accepting any agent is a choice, not a requirement.
  • Accept PS384 as well as ES256. Version 1.0 made it required.

If your identity provider does not support clients identified by a metadata URL, the guides allow registering the agents you accept by their address and refusing the rest.

Stage 4: sign-in and the consent page

This is standard OAuth with a short list of Poppy's own choices (4.8). In the order they tend to fail:

  1. Metadata that points both ways. Your domain's protected resource metadata names your authorization server, and that server's metadata lists https://yourdomain under protected_resources. The guides warn that this second field is the one an existing issuer is most likely to lack, and adding it may need a release from your vendor. Check it before you plan anything else.
  2. Your own scope names. There are no poppy: scopes for your API. Use the scopes your API already has, and describe each in auth.scopes by what it allows and when an agent should ask. Ours are the same two our MCP connectors use.
  3. Direct Sign-In. Authorization code with PKCE, S256 only. Match redirect_uri exactly. Return iss on every redirect, errors included: we missed it on two error paths and agents are told to reject a redirect without it.
  4. The consent page. Name the agent and show the domain of its client_id, because the agent picks its own name and the domain is the part a person can trust. Say "connect", not "sign in with". Tell the person to continue only if they just asked that agent to do this. List every scope in plain words, every time: since 1.0 the agent sends prompt=consent, and you must not skip the page for scopes granted before.
  5. Tokens. Ours: refresh tokens that last 90 days, Bearer access tokens that last an hour, and a token asked for with a resource works only at that resource. DPoP is optional in 1.0.
  6. Sign-out. Revoke the agent's refresh tokens, and let a person disconnect an agent from their account settings. The Session carries on signed out.

Decide now what no agent may ever reach. Ours is billing, API keys and the list of connected agents: those return 403 owner_only whatever the scopes.

Cost: the most of any stage. We had a first version live in two days on an OAuth server we already ran, and spent the next four weeks correcting it. Do not start here.

Stage 5: Device Sign-In, or not

Device Sign-In is for agents that cannot receive a browser redirect: glasses, a speaker, a phone call. The agent shows a link and a short code, and the person approves on any device. It is also easier to use for phishing, since anyone can start a request and send someone the link. The spec requires you to follow RFC 10027's best practices, which means a written risk assessment, and the guides say a company with high-value accounts, such as a bank, may offer Direct Sign-In only.

If you offer it: codes that last about 10 minutes, a verification page on your own domain or your issuer's, opening the link must approve nothing, ask the person to confirm the code matches, and show the consent page every time. We wrote the assessment, and its main result was the owner-only list above. Device Sign-In, explained has the requests, the risk and what our assessment found.

Stage 6: more than one version

Agents do not all upgrade on the day you do. Publish each version's document at its own address, accept each by its Poppy-Version header, and list the older ones under supported_versions. Static files are enough.

We learned this the hard way. Moving from 0.2 to 0.3 we had no way to serve both, so we switched, and every agent on 0.2 was cut off that day. Since 0.4 we run versions side by side: today 1.0, 0.4 and 0.3 all answer. If you start on 1.0 you start with the compatibility rule already in force, and this stage is mostly one check on one header.

Stage 7: test with an agent you did not write

Our tests were written from our own reading of the spec, so they could only confirm that reading. We learned more from a test agent built from the spec text alone and pointed at the live site. Three ways to get the same effect:

  • The official validator, part of the kit below. It runs as a test personal agent and each check names the requirement it tests.
  • The Poppy Simulator. Choose Test a company and enter a domain. It runs discovery, a signed-out Session, your APIs and both kinds of sign-in, then sends requests a company must refuse and checks that you refuse them. Every request and response is shown. How we built it and what it found.
  • A real agent. Sierra says Meta's Muse looks for poppy.json first on every site it visits. Watch your logs for the first Session that is not yours.

Then file an implementation report in the protocol's repository. The maintainers read them: they went through our first report point by point against the next version's text.

The official kit

The protocol ships a Company implementation kit for 1.0. It has two parts: a skill that a coding agent follows, and a validator.

# Claude Code
/plugin marketplace add personal-agent-protocol/personal-agent-protocol
/plugin install personal-agent-protocol@personal-agent-protocol

# Other coding agents
npx skills add personal-agent-protocol/personal-agent-protocol \
  --skill implement-personal-agent-protocol

The skill works in five steps: survey your code and your live site (GET requests only), write a design for you to approve, build in milestones, verify against your deployment, and draft an implementation report. The milestones are Foundation, Interfaces, Sign-in and, optionally, Extensions. The validator needs Node 22.18 or later, a deployment it can reach over HTTPS, and an HTTPS address you control for the test agent's public files. Some requirements cannot be tested by a tool, such as consent wording and logging, and the kit lists those for you to review by hand.

We did not use the kit for our own build, so we cannot tell you how well it works. Its milestones run in the same order as this page: the file and Sessions, then interfaces, then sign-in.

What we would do differently

  • Ship signed-out first, and sooner. It is a fraction of the work, and it is the part agents can use without anyone approving anything.
  • Check the metadata before writing code. Our worst fault was one field in a document we had not thought about: the protected resource metadata at the root of our API host named our MCP server instead of the host. A personal agent that took it literally would have asked for the wrong token.
  • Build the outside test agent first. Ours came a week after we went live. It should have come before.
  • Plan for versions from the first day. Cutting off agents on an old version is avoidable, and we did it once.
  • Protect what you already have. Our authorization server also signs in Claude and ChatGPT connectors. We keep a test that runs their sign-in with every Poppy change switched on. More on running both.

The full write-ups are public: Draft 0.1, Version 0.3 and Version 1.0.

FAQ

Frequent questions

How long does it take to implement the Personal Agent Protocol? +
The signed-out start is one static file and can ship the day you write it. Account access is the expensive part: agent identity, a consent page and the token rules. We had a first version live two days after the first draft, on an OAuth server we already ran, and spent the next four weeks correcting it.
What is the minimum a company has to do? +
Publish /.well-known/poppy.json with protocol_version, your organization name and domain, and at least one of apis, web or agent. A company that offers only its website can stop there, with no auth section. Clerk's own file is 88 bytes and lists only web.
Do I need to build an OAuth server? +
Only for account access, and usually you extend the one you have. It must accept agents identified by a metadata URL instead of a registered client, list your domain under protected_resources in its metadata, and show a consent page. Check protected_resources first: the guides call it the field an existing issuer is most likely to be missing.
Is there an official tool to help? +
Yes. The Company implementation kit at personalagentprotocol.org/kit/company is a skill for coding agents plus a validator. The skill surveys your systems, writes a design for you to approve and builds in milestones. The validator acts as a test personal agent against your deployment. It needs Node 22.18 or later.
How do I test a Personal Agent Protocol implementation? +
With an agent you did not write. Your own tests encode your own reading of the spec. Use the official kit's validator, or the Poppy Simulator, which takes any domain, runs discovery, a signed-out Session, your APIs and sign-in, then sends requests you must refuse and checks that you do.
Do I have to verify the Poppy-Session header on every request? +
You must accept it everywhere, and verify it before you rely on anything it says. A stateless catalog endpoint can ignore it. An account endpoint can rely on the access token alone. Carts, conversations and anything else kept for a Session need the full check.
Should I offer Device Sign-In? +
Offer Direct Sign-In first. Device Sign-In suits agents with no browser, such as glasses or a phone call, but it is easier to use for phishing, and the spec requires a risk assessment under RFC 10027. A company whose accounts hold money or other high-value access may reasonably offer Direct Sign-In only.
What happens when the protocol changes? +
From 1.0, a newer 1.x version must not break a company built for an older one. To move, publish the new version's document, accept both by the Poppy-Version header, and list the old document under supported_versions. Our move from 0.4 to 1.0 was two code changes.
Keep reading

Related guides

References

Sources and further reading

See a finished one first.

Stacktree runs Version 1.0 in production. Read our poppy.json, or open the simulator and watch an agent discover us, start a Session and publish a page. Free, no sign-up.

Sign up free →