Skip to content

AI Worker

Experimental

Hyvä Commerce AI features are experimental. Review generated content before accepting or publishing it.

AI Worker helps Hyvä Commerce handle longer AI jobs, such as creating a page, improving content or generating an image. It acts as middleware between Magento and your chosen AI provider: sending the request and bringing the result back to your store. You choose where to host it.

Use Node for local development and a serverless service such as Cloudflare Workers for production. Both run the longer AI connections outside Magento's PHP processes, leaving those processes available for your store. You can also host the same worker on your own production Node service.

The package contains the worker files for each setup, including a PHP fallback. PHP lets requests run before an external worker is configured.

PHP is not recommended for streaming or production

Long requests occupy your store's PHP capacity and remain subject to its server timeouts. Treat the PHP fallback as a baseline or backup.

Choose the Features You Need

These integrations require a Hyvä Commerce subscription. The open-source Hyvä AI base module and providers supply their shared foundation.

Task What to install and configure
Translate CMS fields CMS AI Translations and a provider. Direct PHP works; a worker is available for supported providers.
Plan or generate a page or section CMS AI Worker integration, AI Worker and a supported text provider.
Rewrite fields, optimise pages or create reusable components CMS AI Worker integration with Generation enabled and a configured worker.
Generate images CMS AI Worker integration, AI Worker and an image model from Gemini or OpenAI.

See AI Features for the editing workflows, Setup for package installation and Feature Configuration for models and execution choices. Manual editing and manual translations do not need AI credentials.

Where Should I Host the Worker?

Your environment Recommended setup
Local development Node, directly or in Docker. It can reach a private Magento installation without a public tunnel.
Production Cloudflare Workers. The service manages the worker infrastructure, so your team does not have another server to maintain.
Production with your own worker hosting Node in production. Use this when your team wants to manage the service, HTTPS, updates, capacity and monitoring.

Local and production Node use the same software. Production adds hosting configuration and supervision. Node, Docker, Warden and Cloudflare all use the same worker.js; other hosting platforms may need an adapter. PHP implements the worker flow inside Magento. All use worker version 1.0.0.

Your AI model still runs at the provider, even when the worker runs locally. Provider usage charges still apply.

What Will My Store Use?

These rules apply after the worker secrets and provider credentials are saved. Enable External Worker and Enable PHP Worker are independent switches; either can provide the worker required by an AI feature.

Your settings What happens
External enabled with URL; PHP enabled The external worker runs the request first. PHP takes over if it cannot start the request.
External enabled with URL; PHP disabled Only the external worker runs requests. An outage stops worker requests.
External disabled or URL empty; PHP enabled PHP runs the configured AI features on this store, even if an external URL remains saved.
External disabled or URL empty; PHP disabled No worker is available. Enable PHP or enable an external worker with its URL.

A backup does not fix an invalid provider API key, unavailable model or provider usage limit. If a worker has already started a generation, PHP does not start another copy. The existing job can still deliver its result; if it fails, the feature shows the failure or uses its normal job retry process.

Keep PHP backup enabled only if the store can spare PHP capacity during an external outage. Turn it off if protecting storefront capacity matters more than continuing AI work during that outage.

How the Packages Fit Together

+-----------------------------------------+
| Hyvä AI: shared foundation              |
+-----------------------------------------+
    |                           |
    v                           |
+---------------------------+   |
| Provider packages         |   |
| OpenAI, Anthropic, Gemini |   |
| and others                |   |
+---------------------------+   |
    |                           |
    v                           v
+-----------------------------------------+
| Hyvä Commerce AI Worker                 |
| Streaming, tools, images and            |
| background jobs                         |
+-----------------------------------------+
    |
    v
+-----------------------------------------+
| Commerce features                       |
| CMS generation and other AI workflows   |
+-----------------------------------------+

The open-source Hyvä AI module provides the shared foundation. Individual provider packages supply credentials, models, options and the PHP adapters used to communicate with their APIs. AI Worker adds the execution features used by Hyvä Commerce. Feature integrations decide what to generate and how to validate and save it.

In Run requests using, choose AI Worker to use the setup above. Direct PHP is the base AI module's separate option for short requests; it does not use the worker or its backup settings.

Set up AI Worker, then use Test Connection to check the external worker and PHP backup separately.