Anthropic ha pubblicato una guida che vale oro per chiunque stia costruendo agenti AI nel settore ecommerce. Non teoria della domenica: architettura testata su deployments reali che hanno aumentato il valore dei carrelli e reso più efficienti le operazioni dei venditori.
Il punto di partenza è netto. Un agente commerce efficace non è una foresta di subagenti specializzati orchestrati da un router centrale. È Claude in un loop standard equipaggiato con skill, tool e — questo conta più di tutto — una suite di eval solida.
Un agente, non venti subagenti
La tentazione quando progetti un agente commerce è segmentare per dominio: un subagent per la ricerca prodotti, uno per il checkout, uno per i resi, uno per l’inventory management. Sembra pulito sulla lavagna. In produzione collassa.
Il problema è che una conversazione commerce è una sessione strettamente accoppiata attraverso intenti multipli. Ogni handoff tra subagenti è un’operazione lossy: lo stato si perde, il contesto si diluisce, la latenza si moltiplica per due o tre. E i confini tra domini raramente sono così netti come sembravano in fase di design.
Un flusso di reso può aver bisogno dello storico ordini, del carrello corrente e del catalogo prodotti contemporaneamente. Con i subagenti o duplichi l’accesso ovunque o passi la palla a metà task. Nessuna delle due è una buona idea.
Le skill di Claude risolvono questo problema senza il costo dell’handoff. Le istruzioni per dominio vengono caricate nel contesto dell’agente principale, che già possiede l’intera cronologia. Anthropic riporta che nei loro test su deployment enterprise, un singolo agente con skill ha costantemente battuto sia il design monolitico (un prompt per tutto) sia l’architettura a subagenti. Qualità migliore, spesso anche costi e latenza inferiori per task.
I subagenti guadagnano il loro posto solo quando l’orchestrator può chiamarli come tool per un task ristretto e autocontenuto. L’esempio classico è un subagent di ricerca profonda: cerca, legge documenti, scrive codice, attraversa modelli dati, sbatte contro vicoli ciechi. Tutto il lavoro accade dentro il subagent, e solo una risposta compatta torna all’orchestrator.
System prompt o skill? Dipende dalla frequenza
Caricare una skill costa un turno del modello. Quindi la regola è semplice: tutto ciò di cui l’agente ha bisogno in più di un terzo delle conversazioni va nel system prompt. Il resto va nelle skill.
Per un agente shopping, questo significa che la ricerca prodotti sta nel prompt — quasi ogni sessione la tocca. Le skill coprono la long tail: search-discovery, purchase-research, planning-goals, customer-care, memory-personalization.
Per un agente merchant, il prompt tiene grounding e semantica base, mentre le skill si dividono per dominio operativo: performance-insights, catalog-listings, inventory-operations, pricing-promotions, marketing-campaigns.
Le istruzioni critiche — safety, vincoli legali, brand rules, fatti chiave dell’utente come allergie — vanno sempre nel system prompt. Non negoziale.
I componenti UI sono tool
La maggior parte delle risposte di un agente commerce non è prosa. È UI: carousel prodotti, itinerari, mappe dei posti, chart. L’agente deve emettere schema, non testo.
Alcuni team partono prompting il modello a emettere tag custom e parsandoli client-side. Funziona finché la superficie è piccola. Poi crolla: il modello non è addestrato sul tuo markup quanto lo è sulle tool call, quindi l’affidabilità scende. Le definizioni dei tag gonfiano il prompt. Lo storico conversazioni finisce in un formato che solo il tuo parser capisce.
Il pattern che regge è fare di ogni componente UI un tool. Il modello chiama present_products, present_itinerary, present_plan_comparison con argomenti tipizzati. Il server valida ed enrichisce la call, emette un evento, il client lo renderizza. Le tool call sono già nell’array messages in formato nativo, quindi ricaricare una vecchia conversazione non richiede re-parsing.
Il tradeoff è la granularità dello streaming. Ogni argomento top-level di una tool call bufferizza sul server per validazione, quindi i sotto-componenti arrivano a step anche con lo streaming attivo. Per ottenere uno stream token-level, imposti eager_input_streaming: true nella definizione del tool, che salta il buffering e con esso la garanzia schema server-side.
Nelle eval di Anthropic, le violazioni schema sono rarissime su modelli classe Sonnet e superiori. Ma wrappa la call in un retry per i casi in cui una scivola attraverso.
Latenza: attaccala su due fronti
La latenza conta nell’ecommerce, e le superfici consumer sono le meno clementi. Ma quello che Anthropic ha visto muovere metriche come retention, engagement e dimensione del carrello è la qualità dell’outcome. Se la risposta era rilevante e il task effettivamente completato contava più dei guadagni marginali di latenza.
Quindi attacchi la latenza su due fronti: minimizzi la latenza end-to-end attraverso buona ingegneria, e la abbini al drop della latenza percepita — perché il tempo speso a guardare un agente lavorare viene letto come progresso.
Meno turni, tool più veloci, token più veloci
La latenza di completamento task è la somma, su tutti i turni del modello, del tempo all’ultimo token più il processing dei tool. Tre leve: meno turni, tool più veloci, token più veloci. A volte competono, quindi minimizzi la somma, non una sola di esse.
Meno turni: carica il contesto probabile in anticipo. Se l’utente ha aperto l’assistant da una pagina prodotto, metti i dati di quella pagina nel contesto della sessione. La conversazione probabilmente sarà su quello. Aumenta l’intelligenza del modello — modelli più smart possono diminuire i turni totali pianificando meglio le tool call, il che spesso compensa i loro token più lenti. Fai chiamare al modello tool indipendenti in parallelo: query multiple per prodotti, documenti policy, fonti dati sales non devono bruciare turni addizionali.
Tool più veloci: ottimizza il backend del tool stesso. A volte un tool è sovraccaricato con logica di dominio che dovrebbe stare in un sistema upstream. Un availability check che chiama catalog per lo SKU, inventory service per store, fulfillment service per i cutoff, poi applica substitution rules e pickup eligibility nel codice del tool stesso. Quel tool è ora hard to maintain e sta portando logica che dovrebbe stare in un endpoint backend. Dispatcha i tool con avidità: gli argomenti dei tool streamano come altri token, quindi l’harness può eseguire la call di ogni tool appena i suoi argomenti sono completi. Anthropic riporta gap di diversi secondi ridotti a poche centinaia di millisecondi.
Token più veloci: scegli il modello e la sua configurazione facendo uno sweep della tua eval suite. A volte Opus 5 giustifica la differenza di costo rispetto a Sonnet, a volte no. Misura costo per task completato, non per model call, perché un modello più economico che ha bisogno di più turni, o fallisce più spesso, non è più economico.
Latenza percepita: mostra il lavoro
La latenza percepita è il tempo che un utente sente finché lo schermo non fa qualcosa. Due tecniche la accorciano senza toccare il modello:
Streama i componenti mentre si formano. Una risposta commerce renderizzata è tipicamente 500-700 output token, che senza streaming sono cinque o più secondi di spinner. Manda ogni parametro di un presentation tool al client mentre streama e renderizza la pagina progressivamente.
Mostra il lavoro. Mentre l’agente sta raccogliendo contesto, renderizza una breve riga di progresso per ogni step in linguaggio naturale: ‘finding hotels near the water’. Puoi costruirla dagli argomenti esistenti del tool o aggiungere un parametro user_facing_message addizionale che prompta il modello a scrivere la riga.
Prompt caching: il tuo più grande risparmio
Il prompt caching è il tuo più grande candidato alla riduzione dei costi, e il traffico commerce ci si adatta bene. Token input cached costano un decimo di quelli freschi. I migliori deployment commerce che Anthropic ha visto girano a tassi di cache hit del 90-99%, e quello è il range per cui progettare dall’inizio.
Il caching è prefix-based. Una request legge dalla cache fino al primo byte che differisce da una request precedente, quindi conta non solo cosa c’è nel contesto ma l’ordine in cui è. Pensa a una request come tre segmenti, ordinati per quanto spesso cambiano:
Global: la maggior parte del system prompt e delle definizioni tool, identico attraverso ogni sessione. Questo è il tuo cache più caldo e, in scala, probabilmente non scadrà mai.
Session: contesto per-utente e cronologia conversazione, che differiscono tra sessioni ma restano stabili dentro una.
Volatile: qualsiasi cosa cambi dentro una sessione, come il tempo corrente o la pagina corrente. Mettilo alla fine assoluta della request.
L’errore più comune che Anthropic vede è un timestamp o la pagina corrente in cima al system prompt, che rompe silenziosamente la cache su ogni request.
Memory che sopravvive alla sessione
Uno shopper che ha menzionato un’allergia alle noci a marzo non dovrebbe doverla ripetere a giugno. Un merchant che controlla le stesse tre campagne ogni lunedì non dovrebbe doverle nominare ogni volta. La memoria a lungo termine è un sistema che costruisci e ha tre parti: come i fatti sono conservati, come sono scritti, come sono letti.
La memoria appartiene ai tuoi sistemi, non nel modello. Un flat markdown profile funziona quando i profili sono piccoli e l’agente è l’unico lettore. La maggior parte degli agenti commerce in produzione lo superano, e il replacement pratico è il database che già operi. Un fatto è un piccolo record tipizzato: una chiave (shoe_size, default_store, preferred_report_cadence), un valore breve, una categoria, e la sessione da cui viene.
Scrivi la memoria in modo asincrono. Alla fine di ogni turno, o ogni pochi turni in una sessione lunga, un agente in un thread o processo separato legge la conversazione e crea, aggiorna o elimina fatti nello store. Non aggiunge nulla alla latenza della conversazione, e ha ottenuto il 13% in più di fact recall nella eval suite interna di memoria commerce di Anthropic.
L’alternativa ovvia — un tool che l’agente chiama per salvare un fatto — è sbagliata per un agente commerce latency-sensitive. Ogni salvataggio è una tool call dentro un turno user-facing, e mette un’altra decisione davanti all’agente su ogni turno.
Safety: l’enforcement vive nell’harness
Il prompt è dove il comportamento sicuro inizia, ma nel commerce non può essere dove la safety è enforced. I fallimenti sono finanziari e spesso irreversibili, e una prompt rule è a un injection o un bad sample dall’essere skippata.
Il modello propone; una persona o una policy applica. Nessuna tool call del modello muove soldi o cambia il business. Order placement, pagamenti, refund, price change, campaign launch finiscono tutti in un’azione che l’harness controlla invece del modello.
Sul lato consumer questo è strutturale: il checkout tool renderizza il carrello con un bottone per piazzare l’ordine, e l’interfaccia backend che l’agente chiama non ha alcun metodo charge.
Sul lato merchant, ogni write tool produce un staged change con un ID generato dal server, e apply_change ha successo solo per ID che sono stati approvati attraverso una superficie reale: un bottone nel portale dell’operatore, una conferma nella CLI, o il prompt di tool-approval della piattaforma stessa quando l’agente gira su Managed Agents.
Write e render accettano solo ID server-issued. L’harness mantiene un record per-sessione di ogni ID che il server ha dato al modello, e quel record è l’unica chiave che qualsiasi write o render accetterà. Il carrello accetta solo product ID che il server ha restituito a questa sessione. Un ID arrivato in qualsiasi altro modo — allucinato, incollato da un utente, piantato in una review — è rifiutato prima che il backend lo veda.
Il contenuto third-party è sanitizzato. Nel commerce la maggior parte del contesto è scritta da persone che non sei tu — venditori, reviewer, competitor. Ogni backend read è untrusted input e passa attraverso un sanitizer. Ogni tool result authored da terze parti (listing, review, policy, seller message, stored memory) è sanitizzato e wrappato in un fence con un’etichetta fissa prima che il modello lo veda.
Eval: shippare un sistema non-deterministico
Qualsiasi cosa da un piccolo prompt change a un nuovo tool può cambiare il comportamento dell’agente in modi difficili da predire. Le eval sono come lo scopri prima di deployare.
Evalua snapshot, non conversazioni. L’API del modello è stateless, quindi ciò che l’agente produce in output è una funzione del system prompt, dei tool e del messages array. Questo significa che qualsiasi stato una conversazione commerce può raggiungere può essere costruito direttamente. Creare un eval case significa costruire il test state, appendere il test user message, e lasciare che l’agente parta da lì.
Poi grada l’outcome: lo stato finale e la risposta renderizzata, inclusi gli argomenti dell’ultimo write. Anthropic raccomanda contro il grading del path che l’agente ha preso per arrivarci — tali test case sono fragili e restrittivi.
Le eval simulate-user, in cui un secondo modello gioca l’utente e un judge grada l’intera conversazione, sono un tool povero per la misurazione. Due sistemi non-deterministici che interagiscono necessitano sample più grandi, costano di più per trial, sono più difficili da giudicare, e producono failure difficili da attribuire.
Copri i diversi tipi di eval. Per ogni positive case, scrivi la sua controparte negativa: uno ‘should serve’ per ogni ‘should refuse’, uno ‘should just do it’ per ogni ‘should ask’. I negative mancanti sono il gap più comune che Anthropic trova in una suite.
Evalua per: core requests che costituiscono il bulk del tuo traffico; context-dependent requests, come riferimenti a ciò che è sullo schermo; safety e brand cases, dove un fallimento costa soldi o fiducia; interface evaluations, per assicurarti che il componente giusto sia renderizzato; requests che appartengono a multiple capabilities contemporaneamente.
Scrivi eval con SME e usa incident reali. Collabora con gli subject-matter expert che vedono i fallimenti in prima persona: Product, Legal, Merchant Ops, Customer Care, Category Management. I fallimenti reali fanno le migliori eval. 50-100 eval case per user flow è un buon punto di partenza.
Shippare con una grande organizzazione
In una commerce enterprise l’agente è costruito da molti team di ingegneria. Search, checkout, pricing, marketing tech, customer care, catalog platform possiedono ciascuno sistemi da cui l’agente dipende, ciascuno shippa sul proprio cadence, e ciascuno vorrà aggiungere o cambiare un tool, una skill, o una prompt rule.
A differenza di un servizio, un agente non ha strict module boundary che protegge gli altri: un cambiamento fatto dal pricing team condivide una context window con checkout.
Il fix tentante è rompere il sistema in molti subagent, uno per business unit. Come discusso, Anthropic raccomanda contro per ragioni di qualità. Invece, il processo per de-risking la collaborazione multi-team:
Ownership segue i sistemi. Ogni skill e tool ha un singolo owner team. Il shared prompt ha un singolo platform-level owner per le parti comuni e domain owner per la sezione domain-specific.
Un cambiamento shippa con i suoi case e CI gira un set scelto per esso. Un team che contribuisce una skill contribuisce anche i suoi case, inclusi i negative case e i boundary case contro skill vicine. Girare la full suite su ogni pull request è troppo lento e troppo costoso per sopravvivere, quindi costruisci un CI set da essa invece.
L’agente dovrebbe anche essere dentro il release calendar. È una deployment unit, quindi un bad change raggiunge ogni utente in una volta. Rolla prompt e skill change a una canary cohort prima, mantieni uno switch che disattiva una skill senza un deploy, e freezza l’agente prima dei peak period nello stesso modo in cui freezzi altri sistemi.
Anthropic ha rilasciato un’implementazione di riferimento completa con sia l’agente consumer che merchant ed esempi runnable per retail, travel, telecom ed entertainment. Il commerce ha sempre premiato rendere il processo di acquisto il più smooth possibile. Gli agenti lo rendono molto più facile.
