AgentConnect — Agenți AI și Comerț Agentic — Ghid de instalare & configurare

1. Cerințe și concepte#

• OpenMage LTS 19.x/20.x sau Magento CE 1.9.x · PHP 7.4–8.3 cu ionCube Loader activat · HTTPS pe magazin (cerut de conectorii claude.ai / ChatGPT).
• Concepte: suprafețele de descoperire (llms.txt, agents.md, profilul UCP din /.well-known/ucp) le spun agenților ce este magazinul tău; API-ul JSON de citire și serverul MCP îi lasă să-l răsfoiască; coșurile de agent le permit să pregătească o cumpărătură pe care o finalizează un om în checkout-ul obișnuit; Copilotul AI opțional te ajută la conținut în admin.
• Partea agentică nu are nevoie de nicio cheie LLM și nu costă tokeni — agenții vin cu propriul model. Doar Copilotul opțional folosește cheia ta Anthropic/OpenAI.

2. Instalare#

1. Descarcă pachetul din contul Imavio (Descărcări) după cumpărare.
2. Dezarhivează și urcă conținutul peste rădăcina Magento — se îmbină în app/code/local/Imavio/AgentConnect și app/etc/modules/Imavio_AgentConnect.xml. Niciun fișier de core nu e suprascris.
3. Golește cache-ul: System → Cache Management → Flush Magento Cache. Scripturile de setup creează automat tabelele de telemetrie.
4. Extensia vine dezactivată implicit — nimic nu e expus până nu o pornești.

3. Activarea licenței#

1. Mergi la System → Configuration → Imavio Extensions → AgentConnect → License.
2. Lipește cheia de licență din contul Imavio și salvează — activarea e instantă.
3. Suprafețele agentice nu sunt niciodată condiționate de starea licenței: o licență expirată doar afișează notificări în admin și pune actualizările pe pauză.

4. Pornire rapidă — activează descoperirea#

1. În System → Configuration → Imavio Extensions → AgentConnect, setează Enabled pe Yes și pornește Discovery.
2. Deschide https://magazinul-tau.exemplu/llms.txt în browser — ar trebui să vezi descrierea generată a magazinului. La fel pentru /agents.md și /.well-known/ucp.
3. Revizuiește textele generate din admin și ajustează tonul, punctele forte și politicile — asta vor cita agenții despre tine. (Copywriter-ul de llms.txt din Copilot ți le poate redacta.)

5. API-ul JSON de citire#

Odată activat, magazinul răspunde cu JSON read-only pe endpoint-urile de agent. Exemplu de căutare:

curl -s "https://magazinul-tau.exemplu/agent/products.json?q=rucsac"

Răspunsurile includ nume, SKU, preț cu valută, stare de stoc, imagine și URL-ul produsului pentru fiecare potrivire. Endpoint-urile de categorii și de detaliu de produs sunt anunțate în profilul UCP (/.well-known/ucp), ca agenții să le găsească fără să ghicească. Totul e cache-uit și limitat la rată; nu există acces de scriere și nici date de clienți.

6. Conectarea Claude și ChatGPT (MCP)#

Endpoint-ul tău MCP este https://magazinul-tau.exemplu/agent/mcp (HTTPS public obligatoriu).

1. claude.ai: Settings → Connectors → Add custom connector, lipește URL-ul MCP și salvează. Într-un chat nou, activează conectorul și întreabă: „Ce găsești în magazinul ăsta sub 250 de lei?"
2. ChatGPT: activează developer mode din setări, apoi adaugă un conector cu același URL MCP.

Serverul expune șase unelte — search_catalog, lookup_catalog, get_product, create_cart, update_cart și get_cart. Asistentul le alege singur pe cele potrivite. Atenție: update_cart are semantică de înlocuire — lista trimisă devine coșul. Navigarea pe categorii stă în API-ul JSON (/agent/collections/{handle}/products.json), nu în MCP.

7. Coșurile de agent și checkout-ul uman#

Când un agent construiește un coș, răspunsul poartă mereu un continue_url. Deschis în browser, acesta încarcă checkout-ul tău obișnuit cu coșul preîncărcat — omul verifică, alege livrarea și plata și plătește ca de obicei. Agenții nu pot declanșa plăți, nu pot plasa comenzi și nu ating conturile clienților; coșurile de agent expiră ca orice alt quote din magazin.

8. Telemetrie și atribuire de venit#

Deschide Imavio → AgentConnect în admin:

• Dashboard-ul arată traficul agenților, sesiunile MCP, produsele cele mai cerute și venitul atribuit.
• Grila de activitate listează fiecare cerere agentică, cu sursă, endpoint și timp.
• Comenzile pornite din coșuri de agent poartă un badge agentic în grila de comenzi, deci atribuirea supraviețuiește în raportarea ta obișnuită.

9. Configurarea Copilotului AI (cheia ta)#

1. În configurare, deschide secțiunea AI Copilot, alege providerul (Anthropic sau OpenAI), lipește propria cheie API și alege modelul.
2. Copilotul deblochează Content Studio pe produse (descrieri, bullet-uri de caracteristici), traduceri dintr-un clic, copywriter-ul de llms.txt și insights pe limba ta peste telemetrie.
3. Costurile merg direct la providerul tău, la tarifele lui. Cheia e folosită doar pe server, exclusiv către providerul ales — suprafețele agentice nu o folosesc niciodată.

10. Securitate și limite de rată#

• Toate endpoint-urile agentice sunt read-only și nu expun date de clienți sau PII.
• Rate limiting per IP cu valori implicite rezonabile; pragurile sunt configurabile dacă le vrei mai stricte sau mai relaxate.
• Răspunsurile sunt cache-uite, ținând traficul agenților departe de baza de date și de experiența cumpărătorilor.

11. Checklist de verificare „agent-ready"#

Rulează comenzile de mai jos de pe orice mașină, înlocuind magazinul-tau.exemplu cu domeniul tău:

# 1. Profilul UCP — trebuie să întoarcă JSON cu profilul și endpoint-urile
curl -s https://magazinul-tau.exemplu/.well-known/ucp

# 2. llms.txt — trebuie să întoarcă descrierea text a magazinului
curl -s https://magazinul-tau.exemplu/llms.txt

# 3. API-ul JSON — trebuie să întoarcă produse potrivite, ca JSON
curl -s "https://magazinul-tau.exemplu/agent/products.json?q=test"

# 4. Serverul MCP — trebuie să listeze cele șase unelte
curl -s -X POST https://magazinul-tau.exemplu/agent/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Dacă toate patru răspund corect, magazinul tău e pregătit pentru agenți.

12. Depanare#

• 404 pe /llms.txt sau /.well-known/ucp — golește cache-ul de configurare; dacă serverul web blochează dotfiles sau .well-known, permite calea respectivă în vhost.
• Răspunsuri HTTP 429 — limitatorul de rată la lucru; mărește limitele din configurare dacă agenți legitimi le ating.
• claude.ai / ChatGPT nu se conectează — endpoint-ul MCP trebuie să fie HTTPS public cu certificat valid; testează-l cu curl-ul tools/list de mai sus.
• Lipsesc produse din rezultate — se expun doar produsele active, vizibile și pe stoc; verifică statusul și vizibilitatea.
• Erori la Copilot — verifică cheia API, modelul selectat și creditul contului la provider.

13. Actualizări#

Versiunile noi apar în Descărcări în contul tău Imavio cât timp fereastra de actualizări e activă, iar extensia afișează un notice de update în admin când există una. O licență expirată nu închide niciodată suprafețele agentice — doar pune pe pauză actualizările și suportul. Ai nevoie de ajutor? Deschide un tichet din contul Imavio — suportul e inclus în licență.