Magento 2 Poppy Module: Discoverable to AI Agents

Magento 2 Poppy module: publishes /.well-known/poppy.json so personal agents such as Meta’s Muse find the store, and verifies their signed sessions. Free, MIT.

Shopify switched the Personal Agent Protocol (Poppy) on for every store, and Meta’s Muse looks for it first on every site it visits. This module gives a Magento 2 store the same thing: a /.well-known/poppy.json built from store config, a link to the store’s UCP profile when one is really there, and an endpoint that verifies the signed Poppy-Session header agents send. Best fit for stores that want to be found by personal agents now, without opening sign-in or checkout to them.

Typical impact: one config switch and one deploy to a store that passes the official Poppy validator, with Foundation 38 passed and 0 failed, and no customer data or checkout exposed to agents.

Who it is for

  • Magento Open Source stores competing with Shopify stores that publish a Poppy file automatically.
  • Stores already running a UCP module such as angeo/module-ucp, which want personal agents to find that profile through the protocol they check first.
  • Agencies and tech leads who need a tested baseline for agent discovery before they scope signed-in agent shopping.

Who should skip it

  • Stores that need agents to sign in, see order history or act on a customer account. That needs an OAuth 2 issuer, which this module does not provide.
  • Stores without an HTTPS base URL per store view. Without one the module publishes nothing.
  • Teams that only want a UCP catalog. Install a UCP module; Poppy only points to it.

What it does

  • /.well-known/poppy.json per host. organization.domain comes from the store’s secure base URL, so every website gets its own file with the domain the protocol requires. The name falls back from the module setting to Store Information to the store name. Cached publicly for 300 seconds.
  • An honest UCP link. extensions.ucp appears only when the admin switch is on and a known UCP module is enabled and switched on for that store. Switch the UCP module off and the link disappears, so agents never follow a dead profile. Other UCP modules are one di.xml entry.
  • Signed-out agent Sessions. GET /poppy/v1/tasks verifies the Poppy-Session JWT and its delegation (ES256 or PS384) with Magento’s own JWT code, no new dependency. Agent metadata fetches are HTTPS only, size and time capped, and pinned to the resolved IP. An admin blocklist and allowlist decide which agents get in.
  • Agent feedback. Agents report tasks they could not do in the shop at POST /poppy/v1/feedback, with a verified Session. Reports appear in an admin grid under Reports > Poppy > Agent Feedback, capped at 50 per agent and 500 per store view per hour, and deleted after 90 days.
  • No tokens, no sign-in. The module never issues access tokens and refuses Bearer tokens with the error the spec asks for.

Before and after

Before

  • /.well-known/poppy.json answers 404, so a personal agent falls back to scraping the storefront.
  • A UCP profile, if installed, is only found by agents that already know to look for it.
  • The store cannot tell which agent is calling.

After

  • Personal agents find the store’s name, domain, website and UCP profile through one file.
  • The file follows store config and the UCP module’s on/off state, per website.
  • Agents prove who they are with a signed Session; blocked agents get invalid_session.
  • The merchant sees which tasks agents tried and could not finish, in an admin grid.

Installation

composer require brocode/module-poppy
bin/magento module:enable BroCode_Poppy
bin/magento setup:upgrade
bin/magento cache:flush

Then switch it on under Stores > Configuration > General > Personal Agent Protocol (Poppy): Publish /.well-known/poppy.json for discovery, Accept Personal Agent Sessions for the tasks endpoint, Accept Feedback Reports for the feedback endpoint, Advertise UCP when a UCP module serves /.well-known/ucp. setup:upgrade adds two tables, brocode_poppy_session and brocode_poppy_feedback; daily cron jobs remove idle Sessions and reports older than 90 days.

Compatibility

  • PHP 8.2 or later
  • Magento 2.4 Open Source; tested on 2.4.8-p5 with PHP 8.4
  • Optional: angeo/module-ucp + angeo/module-ucp-catalog for the UCP profile (tested); other UCP modules through di.xml
  • The storefront has to run on HTTPS

FAQ

Does this make my Magento store work with Meta’s Muse?

It publishes the file Muse looks for first and passes the official validator. Muse then knows the store, its website and its UCP profile. Buying through an agent still depends on what the UCP module behind it offers.

Does the module implement UCP?

No. It links to a UCP profile served by another module and only lists it while that module is switched on for the store.

Can agents sign in to customer accounts with it?

No. Poppy sign-in needs an OAuth 2 authorization server with refresh tokens and consent, which Magento 2 does not ship. The module covers the signed-out part of the protocol.

How do I check it works?

curl -s https://<host>/.well-known/poppy.json returns the document, and curl -s https://<host>/poppy/v1/tasks answers {"error":"invalid_session"} without a signed header. The validator from the official company kit then checks a live Session end to end.

What does the agent feedback show?

One row per report: date, store view, the agent’s client ID, the task in a short phrase and what the agent tried. The User ID is not stored, and the text is shown escaped because an agent wrote it.

Does it slow down storefront pages?

No. Storefront pages do not check the Poppy-Session header and stay fully cached. Only the Poppy endpoints do any verification.

Related reading

Related Topics

Ask a module question or suggest improvements

Tell us your use case and the module context. Spam protection is handled by ALTCHA.




More Projects