Skip to main content

Extensions

PAP extensions add optional wire capabilities. Reactor extensions add or replace SDK implementation components. They complement one another but are not the same abstraction.

Negotiate a PAP extension​

A company advertises support in its discovery document:

{
  "extensions": {
    "operations": {
      "version": "1",
      "endpoint": "https://api.example.com/poppy/operations"
    }
  }
}

A personal agent advertises compatible extensions in its client metadata. Protocol-defined extensions use plain names. Third-party names begin with a domain controlled by their author, such as example.com/gift-wrap. Both sides ignore unknown extensions and unknown fields.

Negotiate in code​

Both SDKs negotiate the same way: an extension is used only when the company and the agent both list it, at the same major version, and this SDK implements that version (SUPPORTED_EXTENSIONS: Operations version 1).

from personal_agent_protocol.extensions import negotiate_extensions
from personal_agent_protocol.models import ExtensionDescriptor

company = {
    "operations": ExtensionDescriptor(version="1", endpoint="https://api.example.com/poppy/operations"),
    "example.com/gift-wrap": ExtensionDescriptor(version="2"),
}
agent = {"operations": ExtensionDescriptor(version="1")}
assert negotiate_extensions(company, agent) == {"operations": "1"}
import { negotiateExtensions } from '@datalayer/personal-agent-protocol';

const negotiated = negotiateExtensions(
  {
    operations: { version: '1', endpoint: 'https://api.example.com/poppy/operations' },
    'example.com/gift-wrap': { version: '2' },
  },
  { operations: { version: '1' } },
);
console.log(negotiated); // { operations: '1' }

The Operations behavior itself lives in OperationsClient (Python and TypeScript), negotiated with operations_endpoint() / operationsEndpoint(); see the Operations guide. The SDK has no contribution point for other extensions' behavior yet: a third-party extension is used by the host's own code once negotiation says both sides list it.

Extensions cannot weaken mandatory protocol checks such as issuer binding, secret redaction, proof verification, replay protection, or exact operation revision approval.