# AI Agent Activity for Magento 2  -  module reference

> See which AI agents visit your Magento 2 store, what they call over UCP, MCP and WebMCP, which bots are fake, and which orders they bring.

Source: https://angeo.dev/docs/modules/agent-activity/
Updated: 2026-10-17

Module reference

# AI Agent Activity for Magento 2  -  module reference

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.

Package`angeo/module-agent-activity`Latest version1.0.0 (released 2026-10-16)Magento2.4.6+PHP8.1 - 8.5LicenseMIT, freeLinks[GitHub](https://github.com/angeo-dev/module-agent-activity) - [Packagist](https://packagist.org/packages/angeo/module-agent-activity) - [Changelog](https://github.com/angeo-dev/module-agent-activity/blob/main/CHANGELOG.md) - [Module page](https://angeo.dev/modules/agent-activity/)

**On this page**

1. What it counts
2. Is that bot real?
3. Requirements
4. Installation
5. The report
6. Command line
7. Configuration reference
8. Cron and stored data
9. Privacy
10. How it works
11. Good to know
12. FAQ
13. Related

## 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](https://angeo.dev/docs/modules/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](https://angeo.dev/docs/modules/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](https://angeo.dev/docs/modules/ucp-checkout/), [MCP Checkout](https://angeo.dev/docs/modules/mcp-checkout/) and [WebMCP](https://angeo.dev/docs/modules/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?

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.

### 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.

### 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.

### 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.

### 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.

## Related

- [AEO Audit](https://angeo.dev/docs/modules/aeo-audit/)  -  score 20 AI-visibility signals from the command line
- [Robots.txt AEO](https://angeo.dev/docs/modules/robots-txt-aeo/)  -  manage AI crawler rules in robots.txt and verify real bots
- [UCP Checkout](https://angeo.dev/docs/modules/ucp-checkout/)  -  UCP checkout sessions over REST; the buyer pays on your own checkout
- [MCP Checkout](https://angeo.dev/docs/modules/mcp-checkout/)  -  guest cart and checkout tools for AI agents, with server-side limits
- [WebMCP](https://angeo.dev/docs/modules/webmcp/)  -  store tools for AI agents in the shopper's browser (Chrome WebMCP)
- [Agent-built order  -  definition](https://angeo.dev/agent-built-order-definition/)
- [Spoofed AI crawler  -  definition](https://angeo.dev/spoofed-ai-crawler-definition/)
- [Measuring AI visibility](https://angeo.dev/measuring-ai-visibility/)
- [All module reference pages](https://angeo.dev/docs/modules/) - [Compatibility matrix](https://angeo.dev/docs/compatibility/)

This page was written from the `README.md`, `composer.json` and `etc/*.xml` files of [tag 1.0.0](https://github.com/angeo-dev/module-agent-activity/tree/1.0.0), read on 16 October 2026. Settings, commands and defaults come straight from that code. If a newer release is out, the README on GitHub wins.