Poppy, el protocolo del agente personal con la empresa

El recorte que me interesa aquí es el del agente personal frente a una empresa, con descubrimiento, identidad y acceso a la cuenta en el mismo hilo. Es el recorte del Personal Agent Protocol, el Poppy, en el índice de protocolos.

Lo que describe el protocolo

En el sitio canónico, la introducción presenta Poppy como un protocolo abierto sobre el modo en que los agentes personales y las empresas trabajan juntos. La empresa declara cómo pueden interactuar con ella los agentes personales. El agente personal lo usa para entrar con seguridad y obtener acceso a la cuenta de la persona, limitado a lo que esa persona y la empresa acuerden.

La especificación amplía el mismo recorte: el protocolo define cómo un Personal Agent, que actúa por un User, trabaja con una Company en nombre de ese User. Cubre descubrimiento, identidad, acceso a la cuenta e interacciones en APIs, navegación web y conversaciones con el Company Agent. La introducción lista cinco principios: Built on existing standards, con OAuth, JWTs, HTTPS, OpenAPI y MCP donde encajen; Controls, not policy; Secure and private; Progressive adoption; Extensible. La introducción también afirma que el protocolo solo define algo nuevo allí donde ningún estándar cubre la necesidad.

Versión, gobernanza y las dos atribuciones

Hay aquí una tensión que dejo explícita, con las dos atribuciones, y sin un veredicto mío. Sierra, en el post «Releasing Personal Agent Protocol 1.0», afirma que la v1.0 del protocolo is now available. En el sitio canónico, la especificación abre con la frase «This is draft version 1.0», a partir de la release candidate 0.4, y puede incluir correcciones que no son compatibles hacia atrás. La página Path to 1.0 pide construir contra la 1.0 draft, la versión más reciente, y escribe que no se añaden funcionalidades nuevas until 1.0 is published. El changelog llama a la versión actual Draft 1.0 y dice que la lista crece until 1.0 is published. El README del repositorio canónico afirma que the specification is a draft. El ejemplo oficial de poppy.json usa "protocol_version": "1.0", y la spec, en la sección 3.1, dice que this draft is 1.0.

La casa canónica de la documentación y de la kit está en personalagentprotocol.org y en el repositorio https://github.com/personal-agent-protocol/personal-agent-protocol. La especificación y la documentación, incluidos los ejemplos, están bajo la Apache License 2.0. La licencia, según el propio sitio, no cubre los nombres Personal Agent Protocol y Poppy, el logotipo ni el diseño del sitio. Path to 1.0 y el roadmap todavía listan áreas que la draft no cubre, entre ellas payments, push notifications y attachments. El camino oficial de implementación es la spec, las guides y la kit de la empresa en /kit/company.

Cómo usarlo: el flujo de la especificación

Sigo el flujo que describe la spec. Una Company debe publicar su documento poppy.json en https://{domain}/.well-known/poppy.json sobre HTTPS. Las redirecciones solo en HTTPS; el documento solo vale si la URL final tiene el path exactamente /.well-known/poppy.json y ningún query. El campo organization.domain debe ser el host que sirvió el documento. Al menos un canal, entre agent, apis o web, es obligatorio. La adopción puede ser progresiva: la empresa puede empezar solo con el website, solo con APIs o solo con el agent.

Si la empresa ofrece cuenta, debe tener un OAuth issuer. Sin issuer, puede ofrecer sesiones signed-out. El issuer se encuentra mediante protected resource metadata en https://{organization.domain}/.well-known/oauth-protected-resource. El acceso a la cuenta es OAuth, descrito en la propia spec. No hay un paso separado para iniciar la Session: la primera solicitud con un sid nuevo la empieza. El Personal Agent declara la sesión con el header Poppy-Session, un JWT firmado por solicitud. Las solicitudes signed-out llevan solo el header de sesión. Las solicitudes signed-in llevan el header de sesión y el access token. Entran además Poppy-Version y, cuando hay extensiones, Poppy-Extensions.

Los canales de interacción son el website, las APIs OpenAPI o MCP, y las conversaciones con el Company Agent. En las APIs, los tipos definidos en esta versión de la spec son openapi, que apunta a una descripción OpenAPI 3.0 o 3.1, y mcp, que apunta a un endpoint remoto MCP, con transporte Streamable HTTP y versión 2025-06-18 o posterior. Las sesiones Poppy son independientes del ciclo de vida del transporte MCP. Las capas de la tabla 1.1 de la spec son Discovery, Operator recognition (con Web Bot Auth recomendado), Sessions, Account access (OAuth) e Interaction channels.

Hay extensiones opcionales en esta draft 1.0, entre ellas ucp. La extensión oficial del Universal Commerce Protocol, en el sitio del protocolo, describe el encaje así: este protocolo encuentra a la Company, identifica al Personal Agent y a un User seudónimo, y hace el sign-in; el UCP es el protocolo de negocio para las compras cuando el agente ya está allí. Business, Platform y Buyer del UCP corresponden, en esa extensión, a Company, Personal Agent y User. El changelog del protocolo registra que el Personal Agent elige las empresas con las que usa Poppy, y que implementar el protocolo no obliga a usarlo con toda empresa que publica poppy.json.

Un ejemplo oficial

El ejemplo siguiente es de la especificación oficial, sección 3, en https://personalagentprotocol.org/docs/1.0/spec.md. La fuente lo presenta como un documento de ejemplo, poppy.json, publicado por la Company. La propia spec avisa que los ejemplos usan example.com para la Company y agent.example para el Personal Agent, y que tokens, claves y códigos en los ejemplos son placeholders acortados, no valores reales.

{
  "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"
    }
  ]
}

El recorte siguiente es el ejemplo oficial de headers de solicitud en la sección 5.2 de la misma especificación («The Session header»), rotulado en la fuente como «Request headers: Personal Agent → Company». En esa fuente, el ejemplo incluye el access token en el header Authorization. Los tokens permanecen truncados, como en la fuente.

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

El ejemplo oficial con el header Poppy-Extensions está en la sección 3.4 («Versions») de la misma especificación, también rotulado «Request headers: Personal Agent → Company»:

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

Relación con MCP, OpenAPI y UCP

La introducción oficial sitúa a Poppy sobre estándares ya existentes, OAuth, JWTs, HTTPS, OpenAPI y MCP, allí donde encajan. La spec deja el schema de cada API a cargo de esa API, y exige que toda API listada acepte el header de sesión y, cuando hay acceso a la cuenta, los access tokens, y haga cumplir los scopes. El encaje con el UCP está en la extensión oficial que cité arriba.

No pretendo unificar el anuncio de Sierra y el lenguaje de draft del sitio canónico en un solo veredicto. El flujo operativo que sigo es el de la especificación, y esta página entra en el mapa por el índice.

Fuentes