sylius-agent-ready — a shop that agents can use.

Discovery is free, data may cost

The x402 middleware answers a route with HTTP 402 and the payment requirements an agent can meet. It is off by default — installing a bundle must not start asking for money.

Once it is switched on, a boundary applies that lives in the code and not in the documentation: only data routes are gated. Never the storefront, never the checkout, and explicitly never the discovery documents. A /.well-known/* behind a paywall does not make a shop profitable, it makes it invisible.

An agent with a valid OAuth token passes through without paying. Both routes are stated in the same 402 response — a known agent pays by contract, an unknown one per request.

The purchase stays with the human wherever the law requires it

The ACP bundle knows two states. By default it declares the catalogue and withholds the checkout — because an agent that reads checkout in the capabilities will try to buy through the API.

For a shop with age-restricted products that is not an option: the purchase has to happen in a visible browser session where age can be verified. Every feed entry therefore carries age_restriction, so that an agent does not mistake a restricted product for ordinary goods.

This is not a gap in the implementation. ACP and UCP both provide a checkout session handoff for exactly this case — the agent prepares, the human completes. If your range carries no such requirements, you enable the checkout with one line of configuration.

Seventeen packages that do not know each other

One package per protocol means the API catalogue has to know what the others offer — without knowing them. A foundation package solves that: koh/sylius-agent-contracts. It ships no endpoint of its own, only interfaces, registries and a request context.

A class that implements one of these interfaces is registered automatically across the container — including from your own App\ namespace, without any wiring. If you want your magazine in llms.txt, you write twenty-five lines and you are done.

The effect shows when you remove something: if a package is not installed, its entry disappears everywhere at once — from llms.txt, from the API catalogue, from the Link headers. There is no place where a capability lingers that nobody serves any more.

Installing is not enough

composer require koh/sylius-agent-ready

A metapackage cannot register bundles, import routes or set a firewall entry. Three steps stay manual, and the shop is not agent-ready until all three are done. The most important one is the third.

The firewall exception has to sit above the Sylius firewalls. Sylius' shop_regex is a catch-all and matches /.well-known/… as well — and that firewall is stateful. Without an exception every crawler request starts a session, and every response carries Set-Cookie: not cacheable, for documents whose entire purpose is to come from a shared cache. An access_control entry does not help — it only takes effect after a firewall has already matched.

And: delete public/robots.txt. The web server answers it from disk before Symfony is asked at all, and shadows the dynamic route silently.

Whether everything is in place is answered by a command that actually calls every announced endpoint:

bin/console koh:agent:check

It finds the fault no unit test sees, because both halves are correct in themselves: a bundle announces an endpoint, llms.txt and the API catalogue dutifully advertise it — and the route was never imported. Agents run into a 404 while every document looks correct.