Mago AI Assistant

Meet Mago

Running a Magento store means living in the admin panel: digging through reports, hunting for that one configuration setting, flushing the cache after every deploy. Mago puts a chat window in your admin and does that work with you.

Type a question in plain language and Mago answers with live data from your own store — revenue, best sellers, customers, configuration, content. Tell it to change something and it does it for you, but only after you've confirmed. It streams its answer as it works, shows numbers as stat cards, charts and tables where that helps, and never touches anything your admin role doesn't allow.

Why merchants like it

• Free, forever. Mago is open source under the MIT licence — no licence fee, no seats, no subscription. You only pay your AI provider for what you use, and Mago keeps its prompts small so a typical action costs a few cents.
• Your AI, your key. Bring your own Anthropic or OpenAI key (or Gemini, Azure, DeepSeek, Ollama and more). Requests go straight from your store to your provider — there is no Mago server in between.
• Nothing changes without your OK. Reading is instant; every write asks first. Irreversible actions such as cancelling an order or issuing a refund show their impact before you confirm.
• Follows your admin roles. Read and write access run through Magento's own ACL, so every admin sees exactly what their role allows.
• Answers you can act on. Stat cards, charts, tables and record lists, plus deep links straight into the admin page you need.
• Grows with the community. Agencies and module vendors add new skills as addons, without touching core.

What you can ask

See docs/skills-examples.md for more example prompts per skill.

Features

• Natural language chat in the Magento admin panel
• Real-time streaming responses via SSE
• Built-in skills for sales analytics, store configuration, content management, and admin navigation
• Slash commands — /cache flush, /cache clean <type>, /index status, /index reindex run directly against Magento, no AI round-trip
• Extensible architecture — third-party modules can register custom skills via DI
• ACL-based permissions — read/write access controlled per admin role
• Write confirmation — every write asks first; irreversible actions (cancel, refund, delete) show their impact and need an explicit acknowledgement, several writes in one turn become a tick list
• Answer widgets — stat cards, charts, tables and record lists in the answer where the data allows it (see docs/ui-components.md)
• Write confirmation — destructive actions always require explicit user approval
• Form access — reads and stages field changes on the admin form open in the browser (including unsaved edits), but never saves: changes are only staged into the form's own fields, same as typing them in, and the administrator's own Save click is what persists anything
• Multi-provider — Anthropic, OpenAI, Azure, Google Gemini, DeepSeek, Hugging Face, OpenRouter, Ollama and LM Studio, through MageOS_AiBase
• Documentation grounding — answers admin how-to questions from Magento/Adobe Commerce docs, fetched into your database (optional)

Requirements

• PHP >= 8.2
• Magento >= 2.4.8 or Mage-OS >= 1.1
• An API key for one of the supported providers

Installation

Anthropic and OpenAI are included out of the box. For other providers (Azure, Gemini, DeepSeek, Ollama, LM Studio, etc.) install the matching Symfony AI bridge — see composer.json suggests.

composer require mago-assistant/magento2-mago
bin/magento module:enable MageOS_AiBase MagoAssistant_Mago
bin/magento setup:upgrade

Configuration

First add a provider under Stores > Configuration > Mage-OS > AI Configuration: pick the backend, paste the API key, choose a model, and use Test Connection to check it answers.

Then, under Stores > Configuration > Mago Assistant:

1. Enable the module (General)
2. Pick the AI Service the assistant runs on (API Settings). Leave it on Automatic to use the first usable one, which is what a single-provider store wants.

New add-ons in the chat panel (off by default)

Stores > Configuration > Mago Assistant > Add-ons > Show new add-ons puts the newest Mago add-ons in the panel's welcome state. It is off by default, because switching it on lets the store reach out to a host that is not yours: https://askmago.com/addons.json, a public JSON document, fetched the first time an administrator opens the panel and then cached for a week.

The request carries nothing about the store beyond what any HTTP request carries — its server address and the user agent MagoAssistant-Mago. There is no query string, no store identifier and no account behind it, which is why the feed is a static file rather than an endpoint that answers per installation. With the setting off, nothing is fetched and the panel asks for nothing.

How tools reach Magento

Tools run Magento's web API routes inside the PHP process that handles the chat, as the admin who is chatting: the route's ACL resources are checked against that admin's role, and nothing goes over HTTP. There is no internal URL to configure and no admin token is created. The former Internal API URL and Verify TLS Certificate settings are removed, along with their saved values.

Voice input (off by default)

Stores > Configuration > Mago Assistant > Voice Input > Enabled adds a microphone button next to Send. Press it, speak, and the words are added to the input as you talk. Recording stops at the first pause or when you press the button again, and the cursor goes back to the input: check the text and press Enter or Send yourself. Nothing is sent by voice alone.

The browser does the speech recognition, so the audio goes to the browser vendor's speech service (Google for Chrome), not to Mago or the AI provider. That is why the setting is off by default, and why each administrator sees a short notice the first time they press the button in a browser. The browser listens in the administrator's own interface locale (Account Settings > Interface Locale): someone with an English admin who speaks Dutch should switch that to Dutch. The button only appears in browsers with built-in speech recognition, such as Chrome, Edge and Safari.

Built-in Skills

See docs/skills-examples.md for example prompts per skill and docs/skills-roadmap.md for the full roadmap of planned skills.

Slash commands

Typing / in the chat shows the available commands. These run without the AI provider and reply instantly:

Write commands need the MagoAssistant_Mago::assistant_write ACL resource plus a write grant on the underlying skill. See docs/skills-architecture.md for registering your own commands.

The answer widgets and skill cards the chat panel renders are documented in docs/ui-components.md; docs/ui-components-examples.md shows every component with sample data and the call behind it. To add a widget of your own from another module, follow docs/widgets.md. page_form reads the admin form currently open in the browser and can stage new field values for the administrator to confirm — it never writes to the database itself, only into the same fields the administrator would type into, so their own Save button is what persists anything. See docs/form-access.md for what it can see, which forms are excluded, and the directive contract it uses to reach the browser.

Documentation grounding

When enabled, the assistant can answer "how do I…" questions from the official Magento admin documentation instead of guessing. The docs_search skill runs a MySQL FULLTEXT search over an indexed copy of the docs and cites the source page it used.

Configuration

Stores > Configuration > Mago Assistant > Documentation

How the corpus is built

A cron job (mago_docs group, its own process) indexes the docs into the mago_doc table (~5 MB). To index immediately instead of waiting for the cron:

bin/magento mago:docs:index --force

Sync is cheap to run often because it is change-detected by git tree SHA: an unchanged source repo costs a single API call and skips re-fetching entirely. This is why the default schedule can safely be raised when you feed docs that update more often than the Mage-OS mirror. On a real change, every help/**.md is fetched (including _includes/, needed to resolve {{$include}} partials), Experience League markup is normalized to plain text, and the table is swapped in a single transaction — a failed sync keeps the previous corpus, and searches keep answering from the old corpus until the new one is committed. Only one sync runs at a time: a second invocation (cron overlapping a manual run, or a double-started command) reports another sync is already running and exits instead of interfering.

Why MySQL FULLTEXT (not embeddings)

Retrieval uses a MySQL FULLTEXT index rather than vector embeddings so the feature works on any Magento install with zero extra infrastructure — no vector database, no embeddings service, and no dependency on a specific AI provider (Anthropic, for one, has no embeddings API). For a bounded, well-structured doc corpus this keyword search is accurate enough, and the assistant compensates for the lack of semantic matching by issuing multiple searches with different terms when the first result set is thin. Semantic/vector retrieval can be added later as an optional backend without changing the skill contract.

Custom docs

The pipeline is source-repo agnostic: point Source repository at any public GitHub repo of Adobe Experience League-flavored (or plain) markdown to ground the assistant on your own documentation. Private repos and non-GitHub sources are on the roadmap.

Extending with Custom Skills

Third-party modules can register tools by implementing ToolInterface and adding them to the ToolRegistry via di.xml. No core modifications needed.

See docs/skills-architecture.md for the full architecture reference, including:

• How the skill/tool system works
• Step-by-step guide for building custom skills
• ACL and permissions model
• Data & privacy details
• MCP compatibility roadmap

Building your own tool? bin/magento mago:tool:create scaffolds the module and bin/magento mago:tool:verify checks it, including every returned field's privacy class. docs/building-a-tool.md walks through it and works as instructions for any coding agent: point your AGENTS.md at it.

Testing

End-to-end tests run with Playwright against Chromium. No test calls a real provider: the chat panel is covered with browser-level SSE stubs, the backend with WireMock standing in for the provider endpoint.

cd Test/End-2-end
npm install && npx playwright install chromium
BASE_URL="https://your-store.test/" npx playwright test

See Test/End-2-end/README.md for configuration, the WireMock setup and how to add scenarios.

Permissions

Each screen asks for its own resource. A role that held MagoAssistant_Mago::config used to reach conversations, statistics and skill permissions too. On upgrade it keeps statistics and skill permissions (data patch GrantSplitScreenResources), but not conversations: grant MagoAssistant_Mago::conversations explicitly to roles that should read other admins' transcripts.

Data & privacy

Mago stores nothing outside your Magento installation. Every request goes directly from your store to the AI provider you configured, using your own API key; what that provider does with the request is governed by its API terms. The only other outbound call the module can make is the add-on feed, which is off unless you switch it on — see New add-ons in the chat panel. With voice input switched on, the spoken audio goes from the administrator's browser to its vendor's speech service. Mago only reads what the current admin's role allows and never writes without an explicit confirmation. Details in docs/skills-architecture.md.

Community

Mago is built in the open with developers, community builders and backers from the Dutch Magento ecosystem. Issues and pull requests are welcome at github.com/mago-assistant; brand assets and press material live at askmago.com/brand.html.

License

MIT