Company implementation kit

The Company implementation kit helps a Company implement its side of Personal Agent Protocol on the systems it already has. It has two parts:

• implement-personal-agent-protocol, a skill for coding agents. The agent follows it to survey the Company’s systems, write a design, and build the implementation in milestones.
• A validator: a command-line tool that acts as a test Personal Agent against a deployment and reports which requirements it meets.

The kit follows draft 0.2 of the spec. It covers the Company side only. It doesn’t cover building a Personal Agent.

Requirements

• A coding agent with access to the repositories you’ll change. Any agent that supports skills, or can fetch a URL, works.
• Node 22.18 or later, for the validator. It has no dependencies.
• A deployment the validator can reach over HTTPS, in any environment. A test environment is best, since the validator starts real Sessions and sends test messages to your company agent.
• An HTTPS URL you control, to host the public files of the validator’s test Personal Agent.

Install

The skill is implement-personal-agent-protocol. Every method installs the same files, from skills/implement-personal-agent-protocol in the repository.

/plugin marketplace add personal-agent-protocol/personal-agent-protocol
/plugin install personal-agent-protocol@personal-agent-protocol

$skill-installer install https://github.com/personal-agent-protocol/personal-agent-protocol/tree/main/skills/implement-personal-agent-protocol

npx skills add personal-agent-protocol/personal-agent-protocol --skill implement-personal-agent-protocol

Follow https://personalagentprotocol.org/kit/company/SKILL.md to add Personal Agent Protocol support to our systems.

Usage

Ask the agent to add Personal Agent Protocol support. The skill works in five steps and keeps its working files in plan/ in your repository.

1. Survey. The agent reads your code and configuration and runs survey, which sends only GET requests to your domain. It records your identity provider, API gateway, MCP servers, support platform, and anything else relevant in plan/survey.md, and asks you about what it can’t find.
2. Design. The agent maps each part of the protocol onto those systems, using the patterns in the kit, and writes plan/design.md. You choose the scope: which interfaces, sign-in types, and scopes, and which Personal Agents to allow. Building starts only after you approve the design.
3. Build. The agent builds one milestone at a time and runs check --milestone after each, fixing failures before moving on.
4. Verify. The agent runs check against your deployment with --design plan/design.md, then works through checklist.md for the requirements the validator can’t test, such as logging and consent wording.
5. Report. report drafts an implementation report from plan/feedback.md and the latest results. You review it and file it (Feedback).

The milestones:

A Company that offers only its website stops after publishing poppy.json without auth.

Architecture

An example of what a Company adds and changes. It starts from a typical application: a website on a CDN, a mobile app, an identity provider, an API gateway in front of backend services, and a support platform. Your own components will differ, and the design step maps the protocol onto what you actually run.

Before

After

• Discovery. The CDN also serves poppy.json and the OAuth server metadata.
• Tokens. A new token endpoint verifies each Personal Agent’s signed identity and issues Session Tokens bound to its DPoP key. When a Personal Agent signs a User in, the existing identity provider authenticates the User and records consent. The token endpoint also remembers the IDs of recent DPoP proofs, for the acceptance window, to reject a reused one. Any store it already uses will do.
• Session records. A new table holds each Session, its scopes, and its Account Token, so every component can look up who a request is for and what it may do.
• APIs and MCP. The API gateway accepts Session Tokens, checks DPoP proofs and scopes, and passes the User to backend services that don’t change. If you have an MCP server, it stays as it is: the gateway accepts Bearer Session Tokens for it, as the protocol requires for MCP. The protocol doesn't require an MCP server.
• Web. A browser session endpoint in the web app turns a Personal Agent’s signed assertion into the site’s usual cookie, linked to the Session, and the cookie check applies the Session’s scopes.
• Conversations. A conversation endpoint carries messages between the Personal Agent and your support platform’s company agent, including handoff to a person.

Validator

The validator is in the skill, at validate/index.ts. It acts as a test Personal Agent against your deployment, and each check quotes the requirement it tests. The agent runs it after each milestone. To run it yourself:

node <skill-dir>/validate/index.ts help

The kit’s validate/README.md covers its commands, the test identity, and what it checks.

Feedback

The spec is a draft. While it works, the agent logs anything in the spec that is unclear, missing, or contradictory, and any problem with the kit, in plan/feedback.md. report turns that log into an implementation report with your domains replaced by example.com. Nothing is sent until you file it.

If a check looks wrong, use the “Disagree?” link in its output. It opens an issue with the check and its requirement filled in. See also how to give feedback and the implementation guides.