🤖 🌸 Personal Agent Protocol

Python and TypeScript SDKs for the Personal Agent Protocol: both implement version 0.4 (2026-11-06), the draft as of upstream 46beb21, and its Operations extension v2. See Compatibility, Migration, the conformance report, and Support.

PAP lets a personal agent discover and talk to a company's agent on behalf of a person. The company remains responsible for its identity, authorization, data, and actions; the personal agent does not need the person's company password or a copy of their account data.

Understand PAP in one minute

A typical interaction has five parts:

1. Discover — the personal agent reads the company's public /.well-known/poppy.json document.
2. Start a Session — the personal agent names a new Session itself, signed out, and signs a Session JWT for each request.
3. Converse — the personal agent can ask questions without disclosing the person's company identity.
4. Sign in when required — the company opens its own authorization page. Credentials remain between the person and the company.
5. Continue safely — the same conversation resumes with an access token for the scopes the person approved, beside the signed Session header.

sequenceDiagram
    actor Person
    participant PA as Personal agent
    participant Company as Company agent
    participant Auth as Company authorization server

    PA->>Company: Discover /.well-known/poppy.json
    Company-->>PA: Agent, API, and authorization endpoints
    PA->>PA: Start a signed-out Session, no request sent
    PA->>Company: Start a conversation, with a signed Session header
    Company-->>PA: Sign-in required for account data
    PA-->>Person: Open the company's sign-in page
    Person->>Auth: Sign in and approve scopes
    Auth-->>PA: Refresh token and access token
    PA->>Company: Continue the same conversation, with the access token
    Company-->>PA: Account-aware response

The SDKs implement these protocol and security mechanics. They do not decide what an agent should say, which model it should use, or whether a proposed action is appropriate for a person.

Install and discover a company

Python

python -m pip install personal-agent-protocol

import asyncio

from personal_agent_protocol import DiscoveryClient


async def main() -> None:
    async with DiscoveryClient() as client:
        company = await client.discover("example.com")
        print(company.document.organization.name)
        print(company.document.agent.protocols)


asyncio.run(main())

TypeScript

npm install @datalayer/personal-agent-protocol

import { discoverCompany } from '@datalayer/personal-agent-protocol';

const company = await discoverCompany('example.com');
console.log(company.document.organization.name);
console.log(company.document.agent.protocols);

Discovery is deliberately a small first example. Production Session, sign-in, and conversation flows also require host-owned signing keys, delegated key custody, token storage, and browser handoff. Those capabilities are provided through Reactor rather than hidden global state.

Reactor is the extension foundation

Both SDKs are built on Datalayer Reactor, a typed plugin and contribution system. An application assembles a PAP host from explicit contributions for:

• discovery transport and URL-safety policy;
• protocol profiles and extension handlers;
• clocks and cryptographic randomness;
• signing, delegated keys, and Session JWTs;
• pairwise identity, token storage, and caching;
• browser handoff and authorization-state storage;
• CLI commands supplied by PAP or third-party extensions.

This architecture keeps the protocol core portable while allowing a desktop application, browser application, server, or test harness to provide the security and platform behavior appropriate to its environment. Missing or ambiguous security contributions fail closed.

Python accepts a host-assembled Reactor PluginPlatform:

from reactor import PluginManifest

from personal_agent_protocol import DiscoveryClient, build_pap_reactor


async def discover_with_host() -> None:
    platform, owned_http = build_pap_reactor(
        plugins=[
            (PluginManifest(name="my-security", version="1"), my_security_plugin)
        ]
    )
    try:
        async with DiscoveryClient(reactor=platform) as client:
            company = await client.discover("example.com")
            print(company.document.organization.name)
    finally:
        platform.stop()
        if owned_http is not None:
            await owned_http.aclose()

TypeScript can build a host or receive an existing ReactorPlatformView:

import {
  buildPapReactor,
  discoverCompany,
} from '@datalayer/personal-agent-protocol';

const reactor = buildPapReactor({}, [mySecurityPlugin]);
const company = await discoverCompany('example.com', { reactor });

See the Reactor repository for the plugin model and contribution lifecycle.

What is implemented

Python and TypeScript share fixtures and cover the same principal protocol surface:

Python additionally provides a SQLite pairwise-identity reference provider. The portable TypeScript entry rejects obvious local and private literal addresses. Its explicit server entry adds NodeUrlSafetyPolicy and createResolvingFetch (A/AAAA resolution, every address global, the vetted one dialled), JoseSigner, and the checks a company makes of a Session header:

import {
  JoseSigner,
  NodeUrlSafetyPolicy,
} from '@datalayer/personal-agent-protocol/server';

Duplicate JSON members are rejected at Python and TypeScript trust boundaries.

What is not implemented yet

Every flow of draft 0.4 and Operations v2 is implemented in both SDKs and both reference companies: discovery, Sessions, Direct, Device and Mediated Sign-In, refresh tokens, DPoP, OpenAPI and MCP, conversations with SSE, handoff and close, browser sessions, feedback, and Operations. What remains:

• production backends the host contributes: the SDK ships no KMS/HSM signer or durable delegated key custody, no durable token store, and only in-memory company stores and replay caches (check_store checks a durable one);
• helpers the Guides suggest but the host decides today: choosing among the sign-in methods, matching a task's scopes to a held refresh token, and revoking the previous refresh token after a wider sign-in;
• rate limits and RateLimit headers in the reference companies (a host can contribute pap.company.rateLimit), and redaction hooks for logs and traces;
• in Node, socket pinning for metadata fetches (an egress proxy closes the DNS-rebinding interval meanwhile).

Each open or partial requirement is listed with its reason in Protocol coverage.

Security boundary

PAP credentials belong to the host, not to an agent model or tool call.

• Access tokens, refresh tokens, Session JWTs, authorization codes, and pairwise identifiers must not enter prompts or model-visible tool results.
• Direct Sign-In requires host-provided state storage, browser handoff, and signing contributions.
• Session requests fail closed until suitable pap.signer and pap.sessionSigner contributions are installed.
• Every redirect from a protocol endpoint is refused; caller-supplied Authorization, DPoP, and Poppy-Session headers are rejected.
• CLI profiles store configuration only—never tokens or private keys.

The guides explain these boundaries at each flow rather than treating them as application conventions.

Command line

The Python distribution installs an extensible pap command. Its command groups use Reactor's datalayer.reactor.cli entry-point contract.

pap config set domain example.com --profile work
pap config show --profile work --json
pap company verify --profile work --json
pap extensions list --profile work

See the CLI guide for configuration precedence, security boundaries, machine-readable output, and third-party extensions.

Examples and first consumer

The examples/pydantic-ai directory contains small, focused Python examples. Each example teaches one feature—discovery, identity, Sessions, Direct Sign-In, Browser Session, cryptography, conversations, or Session transport—without giving protocol secrets to the model.

Datalayer Agent Runtimes is the first consumer of these SDKs. Its Personal Agent Protocol gallery turns the same features into interactive Reactor/Loop applications, including a guided person-to-company journey rendered with the runtime's real message UI. The gallery's local company simulators are deterministic and clearly identified; the PAP clients, transports, validation, and parsed exchanges are real.

The entry @datalayer/personal-agent-protocol/decks ships the four cases as decks: PAP_DECKS, PAP_DECK_IDS and papDeck(id), each with its yaml and the same deck parsed as spec. It brings in yaml and nothing of the SDK.

Each implemented feature should have all three learning layers:

1. a focused SDK example in this repository;
2. a Docusaurus guide with an explanation and Mermaid sequence diagram;
3. an interactive Agent Runtimes example when a UI materially clarifies the flow.

Develop the SDKs

Clone the repository, then install the dependencies for the SDK you are changing.

Python

python -m pip install -e '.[test,lint,typing,examples]'
python -m pytest personal_agent_protocol/__tests__

TypeScript

The TypeScript package is at the repository root. Sources and tests live under src/; published JavaScript and declarations are emitted to lib/.

npm install
npm test

The shared fixtures are in fixtures/. Documentation is a Docusaurus site in docs/.

Learn more

• Documentation
• Overview
• Specification
• Implementation guides
• Extensions
• Open topics
• Datalayer Reactor
• Datalayer Agent Runtimes

License

BSD 3-Clause. See LICENSE.