AgentConnect — Agents IA & Commerce Agentique — Guide d'installation et de configuration

1. Requirements & concepts#

• OpenMage LTS 19.x/20.x or Magento CE 1.9.x · PHP 7.4–8.3 with the ionCube Loader enabled · HTTPS on your storefront (required by claude.ai / ChatGPT connectors).
• Concepts: the discovery surfaces (llms.txt, agents.md, the UCP profile at /.well-known/ucp) tell agents what your store is; the JSON read API and the MCP server let them browse it; agent carts let them prepare a purchase that a human finishes in your normal checkout; the optional AI Copilot helps you write content in the admin.
• The agentic side needs no LLM key and costs no tokens — agents bring their own model. Only the optional Copilot uses your Anthropic/OpenAI key.

2. Installation#

1. Download the package from your Imavio account (Downloads) after purchase.
2. Unzip it and upload the contents over your Magento root — it merges into app/code/local/Imavio/AgentConnect and app/etc/modules/Imavio_AgentConnect.xml. No core files are overwritten.
3. Flush the cache: System → Cache Management → Flush Magento Cache. Setup scripts create the telemetry tables automatically.
4. The extension ships disabled by default — nothing is exposed until you enable it.

3. License activation#

1. Go to System → Configuration → Imavio Extensions → AgentConnect → License.
2. Paste the license key from your Imavio account and save — activation is instant.
3. The agentic surfaces are never gated by license state: an expired license only shows admin notices and pauses updates.

4. Quick start — enable discovery#

1. In System → Configuration → Imavio Extensions → AgentConnect, set Enabled to Yes and turn on Discovery.
2. Open https://your-store.example/llms.txt in a browser — you should see the generated store description. Same for /agents.md and /.well-known/ucp.
3. Review the generated texts in the admin and adjust tone, highlights and policies — this is what agents will quote about you. (The Copilot's llms.txt copywriter can draft them for you.)

5. The JSON read API#

Once enabled, the store answers read-only JSON on the agent endpoints. Search example:

curl -s "https://your-store.example/agent/products.json?q=backpack"

Responses include name, SKU, price with currency, stock state, image and product URL for each match. The category and product-detail endpoints are announced in the UCP profile (/.well-known/ucp), so agents find them without guessing. Everything is cached and rate-limited; there is no write access and no customer data.

6. Connecting Claude & ChatGPT (MCP)#

Your MCP endpoint is https://your-store.example/agent/mcp (public HTTPS required).

1. claude.ai: Settings → Connectors → Add custom connector, paste the MCP URL and save. In a new chat, enable the connector and ask: "What can you find in this store for under 50 EUR?"
2. ChatGPT: enable developer mode in the settings, then add a connector with the same MCP URL.

The server exposes six tools — search_catalog, lookup_catalog, get_product, create_cart, update_cart and get_cart. The assistant picks the right ones on its own. Note that update_cart has replace semantics: the list you send becomes the cart. Category browsing lives in the JSON API (/agent/collections/{handle}/products.json), not in MCP.

7. Agent carts & human checkout#

When an agent builds a cart, the reply always carries a continue_url. Opening it in a browser loads your regular checkout with the cart preloaded — the human reviews, chooses shipping and payment, and pays as usual. Agents can never trigger payment, place orders or touch customer accounts; agent carts expire like any other quote in your store.

8. Telemetry & revenue attribution#

Open Imavio → AgentConnect in the admin:

• The dashboard shows agent traffic, MCP sessions, top requested products and attributed revenue.
• The activity grid lists every agentic request with source, endpoint and timing.
• Orders that started as agent carts wear an agentic badge in the order grid, so attribution survives into your normal reporting.

9. AI Copilot setup (BYO key)#

1. In the configuration, open the AI Copilot section, choose your provider (Anthropic or OpenAI), paste your own API key and pick a model.
2. The Copilot unlocks the Content Studio on products (descriptions, feature bullets), one-click translations, the llms.txt copywriter and plain-language insights over your telemetry.
3. Costs go directly to your provider at their rates. The key is used server-side only, exclusively against the provider you selected — the agentic surfaces never use it.

10. Security & rate limits#

• All agentic endpoints are read-only and expose no customer data or PII.
• Per-IP rate limiting with sensible defaults; the thresholds are configurable if you want them stricter or looser.
• Responses are cached, keeping agent traffic away from your database and your shoppers' experience.

11. Agent-ready verification checklist#

Run these from any machine, replacing your-store.example with your domain:

# 1. UCP profile — should return JSON with your store profile and endpoints
curl -s https://your-store.example/.well-known/ucp

# 2. llms.txt — should return the plain-text store description
curl -s https://your-store.example/llms.txt

# 3. JSON API — should return matching products as JSON
curl -s "https://your-store.example/agent/products.json?q=test"

# 4. MCP server — should list the six tools
curl -s -X POST https://your-store.example/agent/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

If all four answer correctly, your store is agent-ready.

12. Troubleshooting#

• 404 on /llms.txt or /.well-known/ucp — flush the configuration cache; if your web server blocks dotfiles or .well-known, allow that path in the vhost.
• HTTP 429 answers — the rate limiter at work; raise the limits in the configuration if legitimate agents hit them.
• claude.ai / ChatGPT cannot connect — the MCP endpoint must be public HTTPS with a valid certificate; test it with the tools/list curl above.
• Products missing from results — only enabled, visible, in-stock products are exposed; check status and visibility.
• Copilot errors — verify the API key, the selected model and your provider account's credit.

13. Updates#

New versions appear under Downloads in your Imavio account while your update window is active, and the extension shows an update notice in the admin when one is available. An expired license never turns off the agentic surfaces — it only pauses updates and support. Need help? Open a ticket from your Imavio account — support is included with your license.