AI Assistant for Magento 2: User Guide

An AI chat in the Magento admin for the admin users you choose. They ask about orders, shipments, stock, errors and settings in plain language; the assistant reads the store database (read-only, personal data masked), configuration, logs and code, and answers in the user's language. This guide covers installation, setup, every setting, the admin pages, the command line and permissions.

• Admin demo: https://demo.commercegears.com/try-admin/ai-assistant
• Changelog: Release notes · Questions: FAQ

1. What you need

About the API key and costs. Questions go to the AI provider you choose with your own API key, and the provider bills you for that usage. The module records the cost of every request (section 6) and lets you set limits. Ready Reports do not use the provider.

2. Installation

Install with Composer using the access keys from your account (see https://commercegears.com/composer-access/):

composer config repositories.commercegears composer https://repo.commercegears.com
composer config --auth http-basic.repo.commercegears.com PUBLIC_KEY PRIVATE_KEY
composer require commercegears/module-ai-assistant
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

To update later: composer update commercegears/module-ai-assistant, then the same bin/magento commands.

3. Quick start

1. Stores > Configuration > CommerceGears > AI > AI Providers & Costs (shared by all CommerceGears AI modules): paste your Anthropic API Key (and the OpenAI key if you use OpenAI or generated images), click Save Config, then Refresh Models.
2. Stores > Configuration > CommerceGears > AI > AI Assistant (also AI Assistant > Settings in the admin menu), General: set Enabled = Yes, keep Provider = Anthropic (or choose OpenAI, see 4.3).
3. Choose the Anthropic Model and click Save Config.
4. System > Permissions > User Roles: give the roles that may use the chat AI Assistant > Chat and, as needed, the other AI Assistant permissions (section 8).
5. Check AI Providers & Costs > Costs > Model Prices against your provider's pricing page and, if you like, set the Monthly Budget there (all AI modules) or AI Assistant > Limits > AI Assistant Monthly Limit (USD).
6. Open AI Assistant > Chat and ask a question, for example "How many orders did we get yesterday?".

4. Settings

The assistant's settings are in Stores > Configuration > CommerceGears > AI > AI Assistant at default scope. Since 2.1.0 the API keys, model lists, model prices and the monthly budget for all AI modules are in Stores > Configuration > CommerceGears > AI Providers & Costs (CommerceGears AI Core). API keys and tokens are stored encrypted and are never shown to the assistant or written to the log.

4.1 General

4.2 Anthropic

4.3 OpenAI

4.4 Capabilities

Each optional feature can be switched on or off on its own.

4.5 Limits

4.6 Database Access (Always Read-Only)

Database Connection (Read-only) chooses a connection from app/etc/env.php. The default uses a connection named commercegears_ai_readonly when it exists, otherwise the main connection; on production you can choose a replica. Whichever connection is chosen, every statement runs in a read-only transaction, so the database rejects writes. Check read-only access tests the saved connection.

Query Timeout (Seconds) (default 30) is one limit for every query of the assistant, including CSV reports and saved report downloads: when it is reached the database stops the query, so a heavy question cannot slow down the store. Lower it on a busy store.

For extra safety create a database user with SELECT grants only. The module prints the SQL; review it, replace CHANGE_ME with a strong password and run it as a database administrator, then add the connection it prints to env.php as commercegears_ai_readonly:

bin/magento commercegears:ai-assistant:db-grants > ai_assistant_grants.sql
bin/magento commercegears:ai-assistant:db-status

Run db-grants again after deployments that add tables.

4.7 Store Knowledge

4.8 New Relic (Optional) and Costs

New Relic: Enabled, a User API key (NRAK-...) of a user with a read-only role, the Account ID, the Data Center (US or EU) and optionally the APM application name. Test connection checks the saved settings.

Model prices are in AI Providers & Costs > Costs > Model Prices (USD per million tokens). Current Claude and OpenAI models have built-in prices; add a row for any other model you use.

5. Using the assistant

Chat. Open AI Assistant > Chat or the floating chat button. The start page offers six ready requests to click: a weekend promotion created as an inactive cart price rule draft, a landing page draft for it, a monthly sales trend with month-over-month change (chart and CSV), best sellers against slow movers with days of stock left, the most valuable repeat customers and a store health check (stuck orders, unshipped invoiced orders, today's log errors). Clicking one puts the full request in the question box, so it can be adjusted before sending (the drafts need the matching Assistant Actions permissions). The floating chat suggests requests about the order, product or customer on the page. While working, the status line shows what the assistant is looking at. Answers can contain links to admin pages (only index, view and edit pages), charts and CSV reports with a download button. Conversations can be renamed, pinned, archived and shared from their menu.

What it reads. The store database (one SELECT-like statement at a time, sensitive tables denied), the configuration, the logs, the code in app/code, app/design and vendor/magento (credential files such as env.php are refused), the chosen knowledge base pages and, when set up, New Relic. Personal data and secrets are masked before anything is sent to the provider.

What it can create. Only through six write tools defined in the module's code, each with its own permission:

The first call shows the user a summary written by the server with Yes and No; the item is created only after the Yes button and only with exactly the content shown. The tools never change or delete existing data (a store note can replace the text of an earlier note, again only after Yes). The daily summary, scheduled questions and test runs never get a write tool. List everything that was created with bin/magento commercegears:ai-assistant:write-log.

CMS page drafts. Ask, for example, "Make a landing page for our autumn sale with a hero, three feature blocks and an FAQ". The page is built from sections with inline styles only, cleaned on the server, and created inactive. The chat shows a link to the page and a preview link valid for one hour.

Cart price rule drafts. Ask, for example, "10% off bags over £50 for logged-in customers next weekend, coupon AUTUMN10". Percent, fixed and buy X get Y discounts, dates, groups, coupons and conditions are supported. When something is unclear, the assistant asks instead of guessing.

Issue tickets. When the assistant finds a problem or a missing feature it proposes a ticket. In AI Assistant > Issue Tickets users with Update Tickets change the status, priority and resolution note, and can export a ticket to GitHub.

Inbox and scheduled questions. AI Assistant > Inbox shows the daily summaries and the answers to scheduled questions. Scheduled questions are added from the chat ("send me yesterday's orders every morning at 8") or with the form on the Inbox page, and can be paused or deleted there.

Ready Reports. When the assistant made a CSV report for you in the chat, it offers to save it under Ready Reports. After Yes the report appears on the AI Assistant > Ready Reports page, under Sales, Products and stock, Customers and carts, Tax, refunds and discounts, or Other. A report over a period has a Start date and an End date: choose other dates and click Download CSV to get it again, without the assistant and at no cost. Some reports have another filter (for example a stock threshold); a report without filters has only the download button. Only you see a report until you tick Share with everyone who may open Ready Reports; only you can delete it. Names, e-mail addresses, phone numbers and addresses are masked unless your role has Show Personal Data in Saved Reports.

Store Notes. When the assistant had to work something out about how your store is built, for example which table holds the carrier statuses and what status 3 means, it offers to remember it: "Remember for later" with the fact and where it found it. After Yes it checks this note in later conversations before it looks again, which makes such answers faster and cheaper. AI Assistant > Store Notes lists every note with its source, the date it was confirmed and who saved it; Correct this note changes the text, Turn off stops the assistant from using it, Delete removes it. The assistant still checks a note in the data when the answer depends on it, and never remembers figures that change, personal data or passwords.

Feedback and Test Set. Key answers ask "Was this helpful?". Answers rated down in AI Assistant > Feedback can be added to the Test Set and run again after a change of model or settings. Each run is sent to the provider again and costs money.

6. Cost Analytics

AI Assistant > Cost Analytics shows the cost of every request by day, user, model, provider and conversation, for quick ranges or a custom range. With a monthly budget (all AI modules) or an AI Assistant limit set, it shows how much of each is used. AI Services > Usage & Costs shows the costs of all AI modules together. Requests of the daily summary and scheduled questions are listed too.

7. Command line

8. Permissions (ACL)

System > Permissions > User Roles > Role Resources > AI Assistant:

• Chat (CSV reports contain unmasked personal data): the chat, floating chat and Inbox. CSV reports made in the chat contain real customer data (names, e-mail addresses, phone numbers, addresses), so give this permission only to roles that may see that data.
• Tickets, with Update Tickets
• Cost Analytics
• Ready Reports, with Show Personal Data in Saved Reports
• Store Notes (view, correct and delete)
• Feedback and Test Set
• Assistant Actions (created after confirmation): Record Issue Tickets, Schedule Questions, Create Inactive CMS Page Drafts, Create Inactive Cart Price Rule Drafts, Save Reports, Save Store Notes

The settings page is under Stores > Settings > Configuration > AI Assistant Configuration. On installation, roles with Chat get Record Issue Tickets and Schedule Questions; the draft permissions, Save Reports and Show Personal Data in Saved Reports are given to nobody except full administrators.

9. Troubleshooting

• "The assistant is not available for you yet": the module is off, the API key is missing or the role lacks Chat. The message says which. Users kept away by a store module (for example a list of allowed users) do not see the AI Assistant at all.
• API key errors or "Refresh Models" rejected: save AI Providers & Costs with the key first; the button uses the saved key.
• "This month's AI budget ... for all AI modules is used up" or "AI Assistant limit ... is used up": raise or empty the Monthly Budget in AI Providers & Costs or the AI Assistant Monthly Limit, or wait for next month.
• A cost of $0 with "no price": the model has no row in AI Providers & Costs > Costs > Model Prices and no built-in price. Add it; earlier costs are not recalculated.
• "SELECT command denied": the read-only database user lacks grants for a new table; run db-grants again.
• No offer to create a page or promotion: the capability must be Yes and the role needs both permissions.
• No daily summary or scheduled answers: the cron group commercegears_ai_assistant must run; check var/log/ai_assistant.log.
• A preview link shows 404: it is valid for one hour and for one store view; open it again from the chat.
• var/log/ai_assistant.log logs model and tool calls without questions, answers or data.

10. Uninstall

bin/magento module:disable CommerceGears_AiAssistant
composer remove commercegears/module-ai-assistant
bin/magento setup:upgrade
bin/magento cache:flush

The module's tables (commercegears_ai_assistant_*), its settings (commercegears_ai_assistant/* in core_config_data), the files under var/commercegears_ai_assistant/ and generated images in pub/media/wysiwyg/commercegears-ai/ are not removed automatically. CMS pages and cart price rules the assistant created are normal Magento entities and stay. Remove the commercegears_ai_readonly database user and connection if you created them.