Poppy: el protocol obert perquè els agents personals treballin amb la teva web

Cada cop més gent delega tasques a un agent personal: tornar una jaqueta, canviar un vol, revisar una comanda. La majoria d'aquestes tasques acaben en una empresa, i avui l'empresa només té dues opcions: bloquejar l'agent o deixar que es passi per l'usuari, amb la seva contrasenya i l'accés total.

Cap de les dues funciona bé. Amb el bloqueig, l'agent no pot fer res; amb l'accés total, l'usuari no pot limitar què fa l'agent una vegada dins, i l'empresa no pot distingir un agent d'una persona ni oferir-li un camí millor.

Personal Agent Protocol (Poppy) proposa un terme mig. És un estàndard obert (licència Apache 2.0) que permet que l'empresa decideixi què poden fer els agents i que l'usuari decideixi què pot fer el seu.

L'escala de permisos

Entre «bloquejat» i «accés total» hi ha graus intermedis. Prenem l'exemple d'una empresa de lloguer de sales:

1. Cercar sales: qualsevol agent, sense identificar l'usuari.
2. Veure reserves: només quan l'usuari ja ha iniciat sessió.
3. Reservar: amb l'aprovació de l'usuari.

L'usuari tria si el seu agent pot només llegir, només escriure o totes dues coses. I ho fa sense lliurar la seva contrasenya: l'empresa només sap quin agent li demana què.

Com funciona

1. Descobriment. L'empresa publica un fitxer a /.well-known/poppy.json que descriu qui és, com s'hi pot iniciar sessió i quines APIs, web o agent propi ofereix. L'agent llegeix aquest fitxer i ja sap com parlar-hi.

2. Sessions. Tota l'activitat d'un usuari amb un agent a una empresa és una session, que comença anònima. L'empresa sap quin agent la fa i reconeix l'usuari amb un ID opac: estable, però diferent a cada empresa, de manera que les empreses no poden creuar dades sobre el mateix usuari. L'agent s'identifica amb una URL HTTPS pròpia (el seu client metadata) i signa les peticions amb JWT. Els tokens van lligats a una clau de l'agent (DPoP), així un token copiat no serveix.

3. Inici de sessió. Hi ha tres modalitats:

• Directa: OAuth estàndard. L'usuari entra a la pàgina de l'empresa i aprova els permisos.
• Per dispositiu: l'agent mostra un enllaç i un codi, i l'usuari aprova des del mòbil o el que vulgui.
• Mediada: l'agent envia les credencials de l'usuari a l'empresa. És la més delicada, i l'empresa decideix si l'ofereix.

Els permisos (scopes) bàsics són poppy:read i poppy:write, i l'empresa pot definir-ne de més estrets (per exemple addresses). El resultat de l'inici de sessió és un Account Token (un refresh token OAuth) que permet reconnectar sense tornar a demanar res a l'usuari, fins que ell o l'empresa el revoquin.

4. Tres canals, una sola sessió.

• APIs: OpenAPI 3.x o servidors MCP.
• Web: l'agent navega amb el seu propi navegador i l'empresa li posa una cookie lligada a la sessió.
• Converses: l'agent parla amb l'agent de l'empresa amb text i dades estructurades. Cada missatge indica si l'escriu una persona o una IA, i es pot escalar a un humà.

Com adaptar la teva plataforma web

El principi és l'adopció progressiva: no cal reconstruir res. Pots començar petit i anar afegint capes.

Pas 1. Publica poppy.json. El mínim pràctic és això:

{
  "protocol_version": "0.1",
  "organization": { "name": "La meva empresa", "domain": "exemple.cat" },
  "apis": [
    { "type": "openapi",
      "url": "https://api.exemple.cat/openapi.json",
      "description": "Comandes i devolucions" }
  ]
}

Si només oferixes web, sense auth, funcionaràs només com a lloc públic, amb sessions anònimes.

Pas 2. Prepara el servidor OAuth. Si ja en tens (Keycloak, Auth0, Laravel Passport…), l'aprofites. Cal publicar les metadades RFC 8414 amb el camp poppy_domains, que llista els dominis que declaren aquest issuer. L'agent ho comprova perquè cap domini pugui suplantar un altre.

Pas 3. Accepta sessions d'agents. El token endpoint ha de validar l'assertion JWT i l'client assertion de l'agent, rebutjar jti repetits, vincular el token a la clau DPoP i comprovar-la a cada petició. És la part més tècnica, però es pot fer amb llibreries que ja existeixen.

Pas 4. Defineix els permisos. Decideix quines operacions exigeixen read i quines write, i aplica-ho igual a la web, a les APIs i a l'agent. Fes que cada acció sensible torni sign_in_required o insufficient_scope quan toqui.

Pas 5. Exposa les teves APIs. Descriu-les amb OpenAPI o MCP. Si són MCP, el servidor ha de publicar les seves protected resource metadata.

Pas 6. (Opcional) Web amb sessió d'agent. Crea un browser_session_endpoint que validi l'assertion i posi una cookie pròpia (Secure, HttpOnly, SameSite=Lax). Així la teva web aplica els permisos de la sessió a cada pàgina.

Pas 7. (Opcional) Agent propi. Si tens un assistent d'IA, exposa'l com a protocol poppy amb els endpoints de converses. Pensa en el relleu a una persona: l'agent personal pot demanar parlar amb un humà.

Controls que et queden com a empresa

• Llistes d'agents permesos o bloquejats per client_id.
• Registre previ obligatori, si ho vols.
• Límits de pes (rate limiting) amb HTTP 429.
• Revocació d'agents que facin un mal ús — per exemple, si completen ells mateixos un inici de sessió que només havia de fer l'usuari.

A més, entens millor el comportament dels clients, perquè cada sessió segueix l'usuari per APIs, web i converses.