Shopware and personal agents: self-hosted and cloud, proxy and native Free & Pro

Shopware 6 runs either on your own hosting or on Shopware’s cloud editions, and it is built API-first, with a Store API for the storefront’s own use. Both facts matter for the Personal Agent Protocol. This page is as of 16 October 2026. Agent Adapt is a WooCommerce plugin and has no Shopware app; it is not affiliated with or endorsed by Shopware, Sierra or Meta.

Self-hosted Shopware

You control the web server, so /.well-known/poppy.json is yours. Either serve a file there, or proxy it to a provider’s hosted document. It has to be a proxy, not a redirect: since 16 October 2026 the protocol says the document speaks for the host that serves it after any redirects, so a redirect to the provider’s host no longer counts. With nginx, inside the server block and before Shopware’s front-controller rule:

location = /.well-known/poppy.json {
    proxy_pass https://hosted-document-address-for-your-store;
    proxy_ssl_server_name on;
    proxy_set_header Host hosted-document-host;
}

The Host header is the hosted document’s hostname (agents.getagentadapt.com for Agent Adapt’s hosted Company), which the provider needs to pick the right site.

With Apache, mod_proxy, mod_proxy_http and mod_ssl enabled, in the virtual host (.htaccess does not accept these directives), SSLProxyEngine on and ProxyPass /.well-known/poppy.json https://hosted-document-address-for-your-store in the virtual host (not .htaccess, which does not accept them). Test with curl -sI: you want a 200 with content-type: application/json and no location: header.

The provider, a hosted Company, runs the issuer and agent API for your domain and reads your catalogue through Shopware’s Admin or Store API with credentials you create. The customer pays on your checkout. Agent Adapt’s hosted Company is such a provider: built and running, in early access by email, and not yet on sale; [email protected] takes requests.

Shopware cloud editions

On the cloud editions you do not have a web server configuration, and a redirect set in Shopware’s own tools would not do, because since 16 October 2026 the document must be served on your domain. If your DNS is on Cloudflare with the proxy on, a Cloudflare Worker answers the path before Shopware does and serves the provider’s document on your domain, as described in Serving poppy.json with a Cloudflare Worker; check Shopware’s own documentation on putting a CDN or proxy in front of a cloud shop first. That is the route we can point to on the cloud editions.

A native implementation

Because Shopware’s storefront already works through the Store API (product search, product detail, cart, customer login, orders), a plugin or app that implements the protocol natively has most of its building blocks. What it adds is the protocol’s identity and consent layer:

1. poppy.json and the issuer’s OAuth metadata, generated from the sales channel’s domain and settings, with dpop_signing_alg_values_supported listing ES256 (required by section 3.2 since 16 October 2026).
2. Agent verification by published identity and keys, and a block list. See How your store knows which agent is calling.
3. Key-bound Session Tokens with a signed proof checked on every call.
4. A consent page on the shop’s domain, OAuth authorization code with PKCE, a device-code flow if you want speakers and cars, and refusal of admin accounts at sign-in and on every request.
5. An OpenAPI description of the agent-facing subset of the Store API: search, product, policies, cart, orders, addresses, behind one scope check.
6. A single-use checkout link that loads the agent’s cart into the customer’s browser context and lands on your checkout, because agents cannot pay under the protocol’s current draft.

The sequence an agent follows is in An agent’s first visit. A Shopware app that does this could be listed in the Shopware Store; one that runs the issuer on your own domain is a plugin on self-hosted installs.

Sales channels and domains

Each sales channel domain that should be agent-ready needs poppy.json at its root, and the issuer it names must list the domain in poppy_domains. Several domains can share one issuer and count as one business under the protocol.

Common questions

Is there an Agent Adapt app for Shopware?

No. Agent Adapt is a WooCommerce plugin. This page exists because the questions and options are the same.

Does the Store API’s own login count as the protocol’s sign-in?

No. The protocol needs an OAuth issuer that identifies the agent, shows the customer a consent page and binds tokens to the agent’s key. The Store API’s customer login is what the implementation would call after the customer has consented.

Does the customer still pay on my checkout?

No. The customer pays on your checkout. The agent hands over a link.

Where is the specification?

personalagentprotocol.org, Draft 0.2, Apache 2.0.