Module reference

AI Agent Activity for Magento 2 — module reference

Q: Does it store IP addresses?

No. The IP address is used for the bot check and then dropped. It also stores no full user agent, no request body, no query string and no customer data.

Q: Why are my page numbers lower than in my CDN?

Pages served from Varnish, LiteSpeed or a CDN never reach Magento, so they are not counted. Treat web page numbers as a lower bound. UCP, MCP and WebMCP calls are always counted.

Q: How does it know an order came from an agent?

When an order is placed, it checks if the cart was built through a UCP checkout session, an MCP cart or a WebMCP add to cart. Those orders appear with their revenue.

Q: Why do I see no numbers after install?

The totals are built by cron every hour. Press Refresh now in the report, or run angeo:agents:aggregate.

Q: Does it need the other angeo modules?

No. It works alone. With UCP Checkout, MCP Checkout and WebMCP installed it can also link orders to agents.

Covers angeo/module-agent-activity 1.0.0 · Checked 16 October 2026 · MIT licensed

AI Agent Activity shows what AI agents do in your store — and what they bring. Which agents come, what they fetch, which calls fail, which “bots” are fake, and how many carts built by an agent turn into orders.

You get one report with charts and one event log. No IP addresses are stored.

What it counts

Channel	What is counted
UCP	`/.well-known/ucp`, UCP catalog, checkout and order calls, `continue_url` opens
MCP	Calls to the store MCP endpoint `/mcp`, by JSON-RPC method and tool
WebMCP	Tool calls from an agent in the shopper’s browser (WebMCP 1.0.1+ tags them by tool)
Web pages	Storefront pages fetched by known AI crawlers and agents
Orders	Orders whose cart an agent built — through UCP checkout, an MCP cart or WebMCP add to cart — with revenue

Every agent has a type, so you can see why it came:

Type	Examples
Agent platform	A UCP platform (named by its profile host), an MCP client, a browser agent using WebMCP
Browsing agent	Google-Agent, ChatGPT agent (Web Bot Auth), GrokAgent
User-triggered fetch	ChatGPT-User, Claude-User, Perplexity-User, MistralAI-User, DuckAssistBot
AI search	OAI-SearchBot, Claude-SearchBot, PerplexityBot, Applebot, Amzn-SearchBot
Training crawler	GPTBot, ClaudeBot, Meta-ExternalAgent, Amazonbot, CCBot, Bytespider
Search engine	Googlebot, Bingbot — off by default

Is that bot real?

Anyone can send User-Agent: GPTBot. With the setting on, the module checks requests from OpenAI, Anthropic, Perplexity and Google-Agent against the IP ranges these vendors publish, and marks them verified or spoofed. The lists are downloaded once a day by cron. The client IP is used for the check and never stored.

Requests signed with Web Bot Auth (Signature-Agent + tag="web-bot-auth") are marked as signed. Agents that browse with a normal Chrome user agent (ChatGPT agent, Google-Agent) are named by their signer. The signature itself is not verified here — do that at your CDN, or with Robots.txt AEO.

Requirements

Magento	2.4.6+ (Open Source, Mage-OS or Adobe Commerce) — `magento/framework >=103.0.6 <104`
PHP	8.1 – 8.5 — `~8.1.0\|\|~8.2.0\|\|~8.3.0\|\|~8.4.0\|\|~8.5.0`
PHP extensions	`json`

The module works without the other angeo modules. With UCP Checkout, MCP Checkout and WebMCP it also links orders to agents and shows the UCP funnel.

Installation

composer require angeo/module-agent-activity
bin/magento module:enable Angeo_AgentActivity
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

Logging starts right away. Make sure Magento cron runs: it builds the totals every hour and downloads the IP lists once a day. To see numbers right after install, press Refresh now in the report.

The report

Reports → Marketing → AI Agent Activity

Period: the last 7, 30 or 90 days, or your own range. One store view or all.
Summary: agent calls, distinct agents, agent-built orders and revenue, error rate, spoofed bot calls — each compared with the period before.
Charts: calls per day by channel, calls by agent type, top 10 agents, responses by status, the UCP checkout funnel.
Tables: agents (company, type, errors, IP check, last seen), agent-built orders with links, operations (errors, average time), and the most fetched pages by agent type.
Export CSV of the whole report, and Refresh now to rebuild the totals.

The charts use the Chart.js that ships with Magento. No CDN and no inline JavaScript. Every chart also has a table with the same numbers.

Reports → Marketing → AI Agent Events is the event log: a normal admin grid with filters, column controls and CSV or XML export.

Command line

bin/magento angeo:agents:report --days=30
bin/magento angeo:agents:report --from=2026-10-01 --to=2026-10-15
bin/magento angeo:agents:report --store=1 --format=json
bin/magento angeo:agents:aggregate --days=2      # rebuild the totals now
bin/magento angeo:agents:refresh-ranges          # download the bot IP lists now

Command	What it does
`bin/magento angeo:agents:aggregate`	Rebuild the AI agent activity daily totals (the report reads these).
`bin/magento angeo:agents:refresh-ranges`	Download the published IP ranges of OpenAI, Anthropic, Perplexity and Google-Agent.
`bin/magento angeo:agents:report`	Show what AI agents did in the store (UCP, MCP, WebMCP, AI crawlers and agents).

Configuration reference

All settings are under Stores → Configuration → Angeo → AI Agent Activity. The table shows each field, its config path (for bin/magento config:set) and its default value.

General (4)

Setting	Config path	Default
Log Agent Activity	`angeo_agent_activity/general/enabled`	Yes
Log AI Crawler and Agent Page Visits	`angeo_agent_activity/general/log_crawlers`	Yes
Also Log Googlebot and Bingbot	`angeo_agent_activity/general/log_search_engines`	No
Check Bots Against Published IP Ranges	`angeo_agent_activity/general/verify_ip`	Yes

Data Retention (2)

Setting	Config path	Default
Keep Single Events (days)	`angeo_agent_activity/retention/raw_days`	`90`
Keep Daily Totals (days)	`angeo_agent_activity/retention/daily_days`	`730`

Cron and stored data

Job	Cron group	Schedule
`angeo_agent_activity_aggregate`	`default`	`7 * * * *`
`angeo_agent_activity_refresh_ranges`	`default`	`23 4 * * *`
`angeo_agent_activity_cleanup`	`default`	`41 3 * * *`

Table	What it holds	Columns
`angeo_agent_event`	Angeo AI agent activity: events	`event_id, created_at, store_id, channel, category, agent, operator, operation, status, verified, signed, duration_ms, path, ref, order_id, value, currency`
`angeo_agent_event_daily`	Angeo AI agent activity: daily totals	`row_id, day, store_id, channel, category, agent, operator, operation, verified_state, calls, status_2xx, status_3xx, status_4xx, status_5xx, signed, duration_sum, duration_count, orders, revenue, currency`
`angeo_agent_path_daily`	Angeo AI agent activity: daily pages	`row_id, day, store_id, category, path, calls, agents`
`angeo_agent_quote`	Angeo AI agent activity: agent carts	`quote_id, channel, agent, created_at`

Privacy

The module stores no IP address, no full user agent, no request body, no query string and no customer data. An agent is a short name (such as chatgpt-user) or the host of its UCP platform profile. SECURITY.md in the repository lists exactly what is stored.

How it works

storefront request ──▶ controller_front_send_response_before
                         ├─ AgentDetector: UCP-Agent → Signature-Agent → user agent
                         ├─ RequestClassifier: ucp / mcp / webmcp / web page, or ignore
                         ├─ IpVerifier: local copy of vendor IP lists → verified / spoofed
                         └─ one INSERT into angeo_agent_event
order placed ──▶ checkout_submit_all_after → UCP session / MCP cart / WebMCP cart?
cron hourly  ──▶ Aggregator → angeo_agent_event_daily, angeo_agent_path_daily
admin report ──▶ reads the daily totals

Normal shoppers cost a few header reads. Each agent request costs one INSERT. The report never scans the event log.

Good to know

Only requests that reach Magento are counted. Pages served from Varnish, LiteSpeed cache or a CDN are not, so web page numbers are a lower bound. UCP, MCP and WebMCP endpoints are not cached, so they are always counted.
Behind a load balancer or CDN, set up Magento’s trusted proxy headers, so the IP check sees the real client address. If Magento only sees a private address, the check gives no verdict.
Days and the report range are in UTC.

FAQ

Does it store IP addresses?