MageAgent Assistant

An AI store operator for Magento 2 / Mage-OS, reachable over Telegram and from a chat window inside the Magento admin (MageAgent > Chat). Chat with your store: look up orders, products, customers (including free-text search), sales data, best sellers, coupon usage, and abandoned carts, and ask it to make changes - price updates, stock changes, order status and comments, cache flushes, reindexing, creating customers, products, categories, and orders, moving products between categories, managing cart price rules and discount coupons, and handling fulfillment end to end: invoices, shipments with tracking numbers (added at creation or after the fact), and full or partial refunds (credit memos). Every write is a two-step confirmation: the agent queues the action and you tap Confirm/Cancel (in Telegram or in the admin chat card) before anything happens.

Works with Anthropic, OpenAI, DeepSeek, or any OpenAI-compatible LLM API.

This repository is a read-only subtree split of ZhenIT/magento2-agent, which also contains a full docker-compose development sandbox. Please open issues and pull requests there.

Requirements

• Magento 2.4.6+ or Mage-OS equivalent
• PHP 8.1 - 8.4

Installation

composer require mageagent/module-assistant
bin/magento module:enable MageAgent_Assistant
bin/magento setup:upgrade
bin/magento cache:flush

Configuration

Everything lives under Stores > Configuration > MageAgent > MageAgent Assistant:

• LLM: provider (Anthropic / OpenAI / DeepSeek / Custom), API key, model.
• Telegram: bot token (from @BotFather) and a user-id allowlist. The allowlist is deny-by-default - an empty list means nobody can use the bot.
• Agent: enable write tools (off by default), a per-tool disabled-tools list (trims the schema resent on every LLM call), history length, pending-action TTL.

The Telegram channel needs the long-polling daemon running:

bin/magento mageagent:daemon

Run it under your process supervisor of choice (systemd, supervisord, or a dedicated container). The admin chat window works without the daemon.

Trying it from the CLI

bin/magento mageagent:tool get_store_info '{}'         # run a single tool, no LLM
bin/magento mageagent:chat "how many orders today?"    # full agent loop, no Telegram
bin/magento mageagent:eval                             # regression smoke suite

See Testing without Telegram in the monorepo for the full CLI reference (--force, --yes, --reset, eval case format, and more).

Security model

• The Telegram user allowlist is deny-by-default - an empty list means nobody can use the bot.
• The bot token and LLM API key are stored encrypted (Magento Encrypted config backend).
• Destructive tools are gated by an admin on/off switch and a per-call confirmation that only the requester who queued the action can resolve.
• Every tool execution attempt (success, error, denied, or pending) is written to the mageagent_audit_log table.

See Security notes in the monorepo for the full picture.

License

MIT - see LICENSE.