Poppy, o protocolo do agente pessoal com a empresa

O recorte que me interessa aqui é o do agente pessoal diante de uma empresa, com descoberta, identidade e acesso à conta no mesmo fio. É o recorte do Personal Agent Protocol, o Poppy, no índice de protocolos.

O que o protocolo descreve

No site canônico, a introdução apresenta o Poppy como um protocolo aberto sobre o modo como agentes pessoais e empresas trabalham juntos. A empresa declara como os agentes pessoais podem interagir com ela. O agente pessoal usa o protocolo para entrar com segurança e obter acesso à conta da pessoa, limitado ao que essa pessoa e a empresa acordarem.

A especificação amplia o mesmo recorte: o protocolo define como um Personal Agent, agindo por um User, trabalha com uma Company em nome desse User. Cobre descoberta, identidade, acesso à conta e interações em APIs, navegação na web e conversas com o Company Agent. A introdução lista cinco princípios: Built on existing standards, com OAuth, JWTs, HTTPS, OpenAPI e MCP onde couberem; Controls, not policy; Secure and private; Progressive adoption; Extensible. A introdução também afirma que o protocolo só define algo novo onde nenhum padrão cobre a necessidade.

Versão, governança e as duas atribuições

Há aqui uma tensão que eu deixo explícita, com as duas atribuições, sem um veredito meu. A Sierra, no post «Releasing Personal Agent Protocol 1.0», afirma que a v1.0 do protocolo is now available. No site canônico, a especificação abre com a frase «This is draft version 1.0», a partir da release candidate 0.4, e pode incluir correções que não são compatíveis para trás. A página Path to 1.0 pede que se construa contra a 1.0 draft, a versão mais recente, e escreve que não se acrescentam funcionalidades novas until 1.0 is published. O changelog chama a versão atual de Draft 1.0 e diz que a lista cresce until 1.0 is published. O README do repositório canônico afirma que the specification is a draft. O exemplo oficial de poppy.json usa "protocol_version": "1.0", e a spec, na seção 3.1, diz que this draft is 1.0.

A casa canônica da documentação e da kit está em personalagentprotocol.org e no repositório https://github.com/personal-agent-protocol/personal-agent-protocol. A especificação e a documentação, incluindo os exemplos, estão sob a Apache License 2.0. A licença, segundo o próprio site, não cobre os nomes Personal Agent Protocol e Poppy, o logotipo ou o desenho do site. A Path to 1.0 e o roadmap ainda listam áreas que a draft não cobre, entre elas payments, push notifications e attachments. O caminho oficial de implementação é a spec, os guides e a kit da empresa em /kit/company.

Como usar: o fluxo da especificação

Sigo o fluxo que a spec descreve. Uma Company deve publicar o documento poppy.json em https://{domain}/.well-known/poppy.json sobre HTTPS. Redirecionamentos só em HTTPS; o documento só vale se a URL final tiver o path exatamente /.well-known/poppy.json e nenhum query. O campo organization.domain deve ser o host que serviu o documento. Pelo menos um canal, entre agent, apis ou web, é obrigatório. A adoção pode ser progressiva: a empresa pode começar só com o website, só com APIs ou só com o agent.

Se a empresa oferece conta, deve ter um OAuth issuer. Sem issuer, pode oferecer sessões signed-out. O issuer é encontrado via protected resource metadata em https://{organization.domain}/.well-known/oauth-protected-resource. O acesso à conta é OAuth, descrito na própria spec. Não há um passo separado para iniciar a Session: o primeiro pedido com um sid novo a começa. O Personal Agent declara a sessão com o header Poppy-Session, um JWT assinado por request. Pedidos signed-out levam só o header de sessão. Pedidos signed-in levam o header de sessão e o access token. Entram ainda Poppy-Version e, quando há extensões, Poppy-Extensions.

Os canais de interação são o website, as APIs OpenAPI ou MCP, e as conversas com o Company Agent. Nas APIs, os tipos definidos nesta versão da spec são openapi, apontando para uma descrição OpenAPI 3.0 ou 3.1, e mcp, apontando para um endpoint remoto MCP, com transporte Streamable HTTP e versão 2025-06-18 ou posterior. As sessões Poppy são independentes do ciclo de vida do transporte MCP. As camadas da tabela 1.1 da spec são Discovery, Operator recognition (com Web Bot Auth recomendado), Sessions, Account access (OAuth) e Interaction channels.

Há extensões opcionais nesta draft 1.0, entre elas ucp. A extensão oficial do Universal Commerce Protocol, no site do protocolo, descreve o encaixe assim: este protocolo encontra a Company, identifica o Personal Agent e um User pseudónimo, e faz o sign-in; o UCP é o protocolo de negócio para as compras quando o agente já está lá. Business, Platform e Buyer do UCP correspondem, nessa extensão, a Company, Personal Agent e User. O changelog do protocolo registra que o Personal Agent escolhe as empresas com as quais usa o Poppy, e que implementar o protocolo não obriga a usá-lo com toda empresa que publica poppy.json.

Um exemplo oficial

O exemplo abaixo é da especificação oficial, seção 3, em https://personalagentprotocol.org/docs/1.0/spec.md. A fonte o apresenta como um documento de exemplo, poppy.json, publicado pela Company. A própria spec avisa que os exemplos usam example.com para a Company e agent.example para o Personal Agent, e que tokens, chaves e códigos nos exemplos são placeholders encurtados, não valores reais.

{
  "protocol_version": "1.0",
  "organization": {
    "name": "Example Company",
    "domain": "example.com",
    "logo_uri": "https://example.com/logo.png"
  },
  "auth": {
    "scopes": {
      "orders:read": "See your orders, returns, and bookings. Needed to track an order or find one to change",
      "orders:write": "Exchange or return items, and change bookings. Needed for any change to an order",
      "addresses": "See and change your saved shipping addresses. Not needed to enter an address at checkout",
      "poppy:browser-sign-in": "Use the website signed in, with the other access you approve"
    },
    "scope_hints": {
      "orders:read": { "changes": "none", "personal_data": true },
      "orders:write": { "changes": "irreversible", "personal_data": true },
      "addresses": { "changes": "reversible", "personal_data": true }
    }
  },
  "agent": {
    "protocols": [
      {
        "type": "poppy",
        "endpoint": "https://api.example.com/poppy/conversations",
        "description": "Anything about your orders, returns, account, and our products"
      }
    ]
  },
  "web": {
    "browser_session_endpoint": "https://example.com/poppy/browser-session"
  },
  "tasks": {
    "endpoint": "https://api.example.com/poppy/tasks"
  },
  "apis": [
    {
      "type": "openapi",
      "url": "https://api.example.com/openapi.json",
      "description": "Orders, returns, and exchanges"
    },
    {
      "type": "mcp",
      "url": "https://mcp.example.com/mcp",
      "description": "Product search and sizing"
    }
  ]
}

O recorte seguinte é o exemplo oficial de headers de pedido na seção 5.2 da mesma especificação («The Session header»), rotulado na fonte como «Request headers: Personal Agent → Company». Nessa fonte, o exemplo inclui o access token no header Authorization. Os tokens permanecem truncados, como na fonte.

Poppy-Session: eyJ0eXAiOiJwb3BweS1zZXNzaW9uK2p3dCIs…
Poppy-Version: 1.0
Authorization: Bearer eyJhbGciOi…Qp4w

O exemplo oficial com o header Poppy-Extensions está na seção 3.4 («Versions») da mesma especificação, também rotulado «Request headers: Personal Agent → Company»:

Poppy-Session: eyJ0eXAiOiJwb3BweS1zZXNzaW9uK2p3dCIs…
Poppy-Version: 1.0
Poppy-Extensions: "operations";v="3", "links";v="1"

Relação com MCP, OpenAPI e UCP

A introdução oficial situa o Poppy sobre padrões já existentes, OAuth, JWTs, HTTPS, OpenAPI e MCP, onde eles cabem. A spec deixa o schema de cada API a cargo dessa API, e exige que toda API listada aceite o header de sessão e, quando há acesso à conta, os access tokens, e faça cumprir os scopes. O encaixe com o UCP está na extensão oficial que citei acima.

Não pretendo unificar o anúncio da Sierra e a linguagem de draft do site canônico num só veredito. O fluxo operativo que eu sigo é o da especificação, e esta página entra no mapa pelo índice.

Fontes