AgentConnect — Agenți AI și Comerț Agentic

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ță.