Migliorare il pagamento dell'e-commerce con le funzionalità di AI del browser

1. Introduzione

Lo sviluppo web moderno offre un'alternativa ai round trip basati sul cloud per l'utilizzo dell'AI. Chrome ha iniziato a distribuire API AI integrate che ti consentono di utilizzare qualsiasi cosa, dai piccoli modelli esperti per la traduzione a modelli di linguaggio completi distillati, il tutto senza costi per i token per te o per i tuoi utenti, eseguiti in privato sul loro dispositivo.

Allo stesso tempo, gli agenti AI offrono agli utenti un nuovo modo di interagire con le applicazioni web e rendere la tua esperienza web pronta per gli agenti con WebMCP può contribuire a ridurre l'utilizzo dei token, fornendo risultati più accurati rispetto all'attivazione tradizionale che richiede screenshot e scraping del DOM.

In questo codelab lavorerai su Mont-Royal Plein Air, un sito di e-commerce di attrezzature per attività all'aperto. Imparerai a creare e integrare le API AI integrate e WebMCP per:

1. Deduci l'intento del cliente dalla cronologia di navigazione e crea dinamicamente consigli per lui utilizzando modelli on-device.
2. Espone gli strumenti che gli agenti e gli assistenti del browser possono utilizzare per navigare nel sito, esaminare i prodotti e i consigli e gestire il carrello degli acquisti di un utente.
3. (Facoltativo) Traduci il tuo sito al volo utilizzando modelli specializzati di piccole dimensioni sul dispositivo.
4. (Facoltativo) Trasforma la ricerca di base sul sito in un agente sul sito utilizzando gli stessi strumenti utilizzati dagli agenti esterni.

Obiettivi didattici

• Come utilizzare l'API Prompt e applicare l'output JSON strutturato.
• Come registrare gli strumenti WebMCP e strategie per pensare alla composizione e alla granularità degli strumenti.
• (Facoltativo) Come utilizzare l'API Translator per tradurre rapidamente i contenuti utilizzando un modello esperto sul dispositivo.
• (Facoltativo) Come chiamare autonomamente gli strumenti WebMCP.

Prerequisiti

• Un Account Google personale e Google Cloud.
• Google Chrome versione 150 o successive oppure canali Canary, Dev o beta, con i flag #enable-webmcp-testing e #devtools-webmcp-support attivati.
• Familiarità con HTML, CSS, JavaScript e TypeScript.
• Familiarità con JSON Schema.

2. Configurazione del progetto

Account Google

Se non hai ancora un Account Google personale, devi crearne uno.

accedi alla console Google Cloud

Accedi alla console Google Cloud utilizzando un Account Google personale.

Abilita fatturazione

Suggerimento:se configuri la fatturazione utilizzando i crediti Google Cloud, puoi saltare questo passaggio.

Per configurare un account di fatturazione personale, attiva la fatturazione nella console Cloud.

Creare un progetto (facoltativo)

Se non hai un progetto attuale che vuoi utilizzare per questo lab, creane uno nuovo qui.

Apri l'editor di Cloud Shell

1. Fai clic su questo link per passare direttamente all'editor di Cloud Shell.
2. Se ti viene chiesto di autorizzare in qualsiasi momento della giornata, fai clic su Autorizza per continuare.
3. Se il terminale non viene visualizzato nella parte inferiore dello schermo, aprilo:
   • Fai clic su Visualizza.
   • Fai clic su Terminale.

Configurare il progetto

1. Nel terminale, imposta il progetto utilizzando questo comando:

   gcloud config set project [PROJECT_ID]
   

   Esempio: gcloud config set project lab-project-id-example

   Se non ricordi l'ID progetto, puoi elencare tutti gli ID progetto utilizzando gcloud projects list.

   
2. Verrà visualizzato il seguente messaggio: Updated property [core/project].

   Se vedi un WARNING e ti viene chiesto Do you want to continue (Y/n)?, probabilmente hai inserito l'ID progetto in modo errato. Premi n, premi Enter e prova a eseguire di nuovo il comando gcloud config set project.

Configurazione locale e dello spazio di lavoro

1. Nel terminale (o nel terminale Cloud Shell), clona il repository del progetto e vai alla directory del progetto:

   git clone https://github.com/GoogleChromeLabs/codelabs mont-royal
   cd mont-royal
   

2. Vai alla cartella ecommerce-ai-enhancements/starter:

   cd ecommerce-ai-enhancements/starter
   

3. Installa le dipendenze utilizzando pnpm:

   pnpm install
   

4. Avvia il server di sviluppo locale:

   pnpm dev
   

   Apri il browser all'indirizzo http://localhost:5173 per visualizzare il negozio Mont-Royal Plein Air.

(Facoltativo) Installa l'estensione WebMCP Inspector

Per semplificare l'utilizzo di WebMCP, puoi installare lo strumento di controllo del contesto del modello WebMCP. Una volta installato, devi ottenere una chiave API Gemini per utilizzarlo:

• Vai ad AI Studio.
• Fai clic sul pulsante Crea chiave API per generare una nuova chiave API Gemini collegata al progetto che hai configurato in precedenza in questo passaggio.
• Apri lo strumento di ispezione del contesto del modello WebMCP (si apre nel riquadro laterale) e fai clic sul pulsante Aggiorna chiave API Gemini.
• Incolla la chiave API nel popup e salva.

Questa estensione ha un agente di base che può utilizzare WebMCP, consentendoti di provare il tuo sito web tramite l'estensione anziché chiamare direttamente gli strumenti WebMCP tramite DevTools.

3. Modelli di AI integrati sul web

Che cos'è l'API Prompt?

L'API Prompt offre alle applicazioni web l'accesso diretto a un modello linguistico multimodale di piccole dimensioni in esecuzione interamente sul dispositivo dell'utente. Poiché l'inferenza viene eseguita localmente:

• Latenza cloud pari a zero: nessun round trip di rete o accodamento del server di backend.
• Privato per impostazione predefinita: i prompt e qualsiasi contesto passato non vengono mai trasferiti dal dispositivo
• Costo zero: l'inferenza viene eseguita sull'hardware client senza fatturazione dei token o spese di hosting cloud.
• Funziona offline: funziona in modo affidabile anche senza una connessione a internet attiva.

In Chrome, l'API Prompt è accessibile tramite l'interfaccia globale LanguageModel.

// 1. Set your expected inputs and outputs. This is multimodal, so you can
// include other types here, too
const languages = {
   expectedInputs: [{type: "text", languages: ["en"]}],
   expectedOutputs: [{type: "text", languages: ["en"]}],
}

// 2. Check availability. Always pass in your expected inputs and outputs,
// as some models may only support some inputs and outputs
const availability = await LanguageModel.availability(languages);
// 'available', 'downloading', or 'unavailable'

// 3. Create an isolated session with system prompt and language constraints
const session = await LanguageModel.create({
  ...languages,
  // Optional: add initial context to your session, like a system prompt
  initialPrompts: [
   {
      role: 'system',
      content: 'You are an expert outdoors sales assistant...'
   }
  ]
});

// 4. Define your expected output as JSON Schema
const schema = {
   //...
}

// 5. Prompt the model (supports plain text or structured models)
const result = await session.prompt('Recommend a 3-season tent footprint.', {
  responseConstraint: schema,
});

Best practice di gestione della memoria:

• Puoi clone() una sessione, copiando l'intero stato della finestra contestuale, e utilizzare i cloni in modo indipendente, riducendo il tempo necessario per avviare una nuova sessione.
• Quando hai finito di utilizzare una sessione, destroy() per liberare risorse.

Esercizio 1: consigli basati sul percorso

I siti di e-commerce in genere hanno caroselli o upsell di articoli "acquistati spesso insieme". Per un sito all'aperto, potrebbe essere più utile creare questi consigli in base alla cronologia di navigazione.

Per farlo, creerai una pipeline di suggerimenti in tre fasi:

1. Profilatore del percorso: utilizzando l'API Prompt, analizzerai la cronologia di navigazione cronologica del cliente per tentare di dedurre la sua vera intenzione di avventura.
2. Query sul prodotto: da questo intent, invierai una richiesta API a un backend di prodotto fittizio per ottenere elementi correlati.
3. Consigli sui prodotti: restituirai questi prodotti all'API Product per classificarli, restituendo i cinque complementi più coerenti con ciò che l'utente sta visualizzando.

Attività 1.1: inizializzazione dell'API Prompt

Anziché inizializzare l'API Prompt singolarmente ogni volta che vuoi utilizzarla, centralizzi le chiamate in un unico file, memorizzando la creazione tramite il prompt di sistema per ridurre il tempo di avvio per più chiamate allo stesso agente.

Vai al file src/ai/prompt-api.ts e controlla getPromptSession() nelle righe 27-58:

export async function getPromptSession(
  systemPrompt: string = '',
  options: { signal?: AbortSignal } = {}
): Promise<LanguageModel>

1. Riutilizzare una sessione base memorizzata nella cache. Esiste già una mappa della cache alla riga 21, baseSessions, con chiave di sistema. Il riutilizzo dei modelli di base anziché la clone()zione di nuovi modelli riduce il tempo di avvio e eredita la configurazione di base senza che le sessioni interferiscano tra loro. Restituisci il clone: i chiamanti possono interagire con lui, ad esempio destroy(), liberamente senza eliminare la base memorizzata nella cache.
2. Rileva le funzionalità dell'API. Rileva se l'API esiste e genera un errore in caso contrario.
3. Dichiara le tue modalità e lingue. I modelli integrati possono supportare l'input multimodale. Devi dichiarare le modalità di cui hai bisogno e le lingue che vuoi supportare. Tutti i contenuti che invii al LLM sono in inglese.
4. Controlla la disponibilità prima di creare qualsiasi cosa. Anche se l'API esiste, un modello che supporti i tuoi requisiti potrebbe non esistere. Controlla se ne esiste uno. In caso contrario, genera un errore. Se non è ancora stato scaricato, visualizza lo stato di avanzamento del download del report.
5. Crea la sessione. Configura le opzioni per creare una nuova sessione dell'API Prompt e il prompt di sistema, se incluso

Attività 1.2: implementa Profiler del percorso

Vai al file src/ai/journey-profiler.ts e ispeziona la funzione di destinazione nelle righe 42-100:

export async function inferJourneyProfile(
  context: ProfilerInputContext,
  catalogMap: ReadonlyMap<string, Product>
): Promise<JourneyProfile>

1. Utilizza la funzione dell'attività 1 per generare una nuova sessione di prompt da utilizzare.
2. Chiedi al modello di utilizzare il testo del prompt fornito, utilizzando journeyProfileSchema come schema JSON per il ritorno strutturato.
3. Analizza l'output del prompt ed elimina i duplicati delle categorie target.
4. Sostituisci i ritorni di stringhe codificate con i risultati effettivi del prompt.
5. Distruggi la sessione al termine per liberare memoria.

Leggi src/utils/journey-helpers.ts per scoprire come la raccolta del contesto viene trasformata in un prompt.

Attività 1.3: implementa il re-ranker di sinergia

Vai al file src/ai/synergy-reranker.ts e ispeziona la funzione di destinazione nelle righe 30-71:

export async function rankComplementaryGear(
  profile: JourneyProfile,
  candidates: readonly Product[],
  currentProduct?: Product | null,
  cartProducts?: readonly Product[],
  limit: number = 5
): Promise<readonly RecommendedItem[]>

1. Utilizza la funzione dell'attività 1 per generare una nuova sessione di prompt da utilizzare.
2. Chiedi al modello di utilizzare il testo del prompt fornito e lo schema generato.
3. Analizza l'output del prompt.
4. Restituisci l'elenco dei consigli assemblato utilizzando assembleRecommendations.
5. Distruggi la sessione al termine per liberare memoria.

Leggi src/utils/reranker-helpers.ts e src/utils/recommendation-schemas.ts per scoprire come vengono generati il prompt e lo schema e come vengono assemblati i suggerimenti dai risultati del prompt

Verificare la pipeline dei consigli

1. Apri Chrome per http://localhost:5173/catalog/tent-mont-tremblant-3p.
2. Scorri verso il basso fino alla sezione Per te.
3. Osserva come le 5 schede correlate si aggiornano per riflettere gli accoppiamenti di kit intelligenti (come impronte a terra, materassini e picchetti leggeri) anziché prodotti casuali.
4. Apri la console Chrome DevTools per esaminare la durata di esecuzione in tempo reale di entrambi i passaggi di inferenza.

(Facoltativo) Attività 1.4: esplora altri modelli di AI integrati

Sono disponibili diversi altri modelli di AI integrati, tra cui il modello esperto dell'API Translator. I componenti di questo codebase sono già collegati a un servizio che rileva le modifiche nella lingua corrente e chiede la traduzione. Il tuo compito è collegare il tutto.

Vai al file: src/ai/translator.ts

Ispeziona la funzione di destinazione createTranslator nelle righe 29-45:

export async function createTranslator(
  targetLang: SupportedLanguage
): Promise<Translator | null>

1. Verifica il supporto dell'API Translator e assicurati che la lingua di destinazione non sia l'inglese (i contenuti sono in inglese per impostazione predefinita).
2. Crea una coppia linguistica, dall'inglese alla lingua di destinazione, e verifica se è disponibile.
3. Crea opzioni per il traduttore e collega un monitor che mostri l'avanzamento del download del modello.
4. Restituisce il traduttore inizializzato.

Successivamente, esamina la funzione di destinazione translate nelle righe 50-58:

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

5. Controlla se è disponibile un traduttore con getCachedTranslator che passa in targetLang. In caso contrario, restituisci il testo pulito.
6. In caso affermativo, utilizza il traduttore per tradurre il testo pulito.

Vai al file: src/ai/translator.ts

Esamina la funzione di destinazione render nelle righe 204:

export async function translate(
  text: string,
  targetLang: SupportedLanguage
): Promise<string>

7. Attivare il componente Selettore lingua

Leggi src/utils/translator-helpers.ts per scoprire come funzionano la cache di traduzione e l'abbonamento.

4. Utilizzo di WebMCP per migliorare l'esperienza dell'agente

Che cos'è WebMCP?

Man mano che gli utenti iniziano a utilizzare agenti autonomi e di co-browsing, per i siti web è diventato importante adattarsi. Gli agenti si basano tradizionalmente sull'attivazione, ovvero sull'acquisizione di screenshot e sullo scraping del DOM e degli alberi di accessibilità, per determinare come interagire con un sito. Questo processo è lento, fragile e soggetto a errori e spreca i token utente.

WebMCP aiuta a risolvere questo problema consentendo agli sviluppatori di fornire strumenti direttamente agli agenti per interagire con la pagina in cui si trovano. Gli agenti che li supportano possono utilizzare questi strumenti proprio come uno strumento nel tuo harness di codifica, con input e valori restituiti chiari e strutturati dettati da te.

// Register a tool directly on document.modelContext
document.modelContext.registerTool({
  name: 'get_product_specs',
  title: 'Get Product Specs',
  description: 'Retrieve technical specifications for the active product.',
  inputSchema: {
    type: 'object',
    properties: {
      // ...
    },
  },
  annotations: {
    readOnlyHint: true, // Informs the agent this tool causes no side-effects
  },
  execute: async (input) => {
    return {
      weight: '1.8 kg',
      capacity: '3 persons',
      seasons: '3-season',
    };
  },
});

Quando un agente si connette alla pagina web, esegue una query su document.modelContext.getTools(). Ogni strumento registrato espone:

• name: identificatore dello strumento programmatico utilizzato dagli agenti durante l'esecuzione degli strumenti (ad es. 'get_product_specs').
• title: etichetta di visualizzazione leggibile utilizzata dagli ispettori e dalle interfacce degli agenti (ad es. 'Get Product Specs').
• description: descrizione in testo normale che informa il modello su cosa fa lo strumento e quando chiamarlo. In questo modo, l'agente determina se deve chiamare lo strumento, quindi sii descrittivo.
• inputSchema: schema JSON che definisce gli argomenti accettati.
• annotations: suggerimenti sul comportamento, ad esempio { readOnlyHint: true } per gli strumenti di sola lettura che non causano effetti collaterali sullo stato.
• execute: funzione asincrona eseguita quando viene richiamato lo strumento.

Best practice: le best practice per la granularità degli strumenti sono ancora in evoluzione. Gli strumenti più granulari con cui gli agenti possono creare i propri percorsi utente sembrano emergere come best practice anziché strumenti omnibus, quindi è ciò che viene presentato qui.

Attività 2.1: strumenti per consigli e prodotti

Inizia registrando uno strumento per consentire agli agenti di recuperare i consigli che hai appena creato nell'esercizio precedente.

Vai al file: src/components/product/ForYouSection.ts

Ispeziona registerWebMCPTools() nelle righe 71-94:

private registerWebMCPTools(): void

1. Controlla se WebMCP è supportato.
2. Se sì, registra lo strumento.

• Scegli un titolo e una descrizione che invoglino un agente a scegliere lo strumento. In questo caso, pensa all'ingegneria dei prompt.
• Non è presente alcun input, quindi includi solo uno schema JSON dell'oggetto vuoto.
• Questo è uno strumento di sola lettura.
• Nella funzione di esecuzione, utilizza recommendationStore per ottenere l'insieme corrente di consigli, quindi restituisci l'ID prodotto corrente e l'insieme di consigli sui prodotti.
• Aggiungi un segnale di interruzione e intercettalo in modo che non generi un errore. In questo modo, lo strumento viene rimosso correttamente quando il componente viene smontato.

Vai al file: src/views/ProductView.ts

3. Ripeti la stessa procedura per registrare uno strumento get_current_product, questa volta restituendo l'intero prodotto e i consigli

Suggerimento:la registrazione degli strumenti avviene a livello di componente, quindi quando i componenti vengono combinati per creare una pagina, gli strumenti vengono inclusi.

Attività 2.2: strumenti del riquadro a scomparsa del carrello

Vai al file: src/components/cart/CartDrawer.ts

Ispeziona registerWebMCPTools() nelle righe 83-114:

private registerWebMCPTools(): void

1. Registra lo strumento view_cart:

• Il relativo inputSchema deve essere un oggetto con una singola opzione booleana, openDrawer.
• Deve essere di sola lettura.
• Legge l'input come parte della sua funzione execute, decide se mostrare o nascondere il carrello, aggiorna recommendationStore e poi restituisce il riepilogo del carrello

2. Registra lo strumento manage_cart:

• Il relativo inputSchema deve essere un oggetto con items, che è un array di oggetti con l'enumerazione productID, add, remove e update action e l'intero quantity.
• La funzione execute deve passare gli elementi a this.updateCart

Attività 2.3: strumento di cambio lingua

Porta WebMCP a un livello superiore esponendo uno strumento linguistico ad agenti esterni.

Vai al file: src/components/navigation/LanguagePicker.ts

Ispeziona registerWebMCPTools() nelle righe 61-63:

private registerWebMCPTools(): void

1. Registra lo strumento switch_language:
   • inputSchema deve avere una proprietà language che sia un enum di SUPPORTED_LANGUAGE_CODES.
   • La funzione execute deve chiamare this.switchLanguage con la lingua fornita.

Attività 2.4: strumenti di navigazione dello store

Consenti agli agenti autonomi di navigare nello store, passare alle pagine di prodotto, sfogliare le categorie o avviare ricerche.

Vai al file: src/components/navigation/SiteHeader.ts

Ispeziona registerWebMCPTools() nelle righe 155-171:

private registerWebMCPTools(): void

1. Controlla se WebMCP è supportato.
2. Registra lo strumento search:
   • Lo schema di input accetta una stringa query.
   • In execute, chiama this.search(input?.query).
3. Registra lo strumento go_to_catalog:
   • Lo schema di input accetta activity (enum di ACTIVITIES) e category (enum di PRODUCT_CATEGORIES) facoltativi.
   • In execute, chiama this.goToCatalog(input?.activity, input?.category).
4. Registra lo strumento get_categories_and_activities:
   • Strumento di sola lettura senza parametri di input.
   • In execute, chiama this.getCategoriesAndActivities().
5. Registra lo strumento go_to_product:
   • Lo schema di input richiede una stringa productId.
   • In execute, chiama this.goToProduct(input?.productId).

Verifica con lo strumento di controllo WebMCP

1. Ricarica http://localhost:5173/catalog/tent-mont-tremblant-3p in Chrome e vai a una pagina di prodotto.
2. Apri Chrome DevTools > Application > WebMCP.
3. Dovresti visualizzare gli strumenti WebMCP: get_recommendations, get_current_product, view_cart, manage_cart, switch_language, search, go_to_catalog, get_categories_and_activities e go_to_product.
4. Fai clic su uno di questi per visualizzarne i dettagli e i parametri.
5. Scegli una con parametri, seleziona alcune opzioni e fai clic su Esegui strumento per vederla in azione.
6. (Facoltativo) Se hai installato e configurato WebMCP Model Context Tool Inspector, aprilo: si apre nel riquadro laterale di Chrome. Utilizza l'interfaccia di chat per chiedere all'agente di eseguire un'azione che ritieni debba richiamare uno dei tuoi strumenti per vedere come risponde.

5. (Facoltativo) Creare un agente in loco

Chiamare gli strumenti WebMCP in-page

Gli strumenti WebMCP non sono solo per le estensioni del browser esterni o i bot di terze parti: la tua applicazione può chiamarli direttamente. Eseguendo query su document.modelContext.getTools(), il codice lato client può rilevare ed eseguire gli strumenti in modo dinamico.

Puoi utilizzarlo per creare un assistente allo shopping AI in loco, trasformando la barra di ricerca in uno strumento di rilevamento dei prodotti basato sull'input in linguaggio naturale. Anziché scrivere codice imperativo personalizzato per coordinare numerosi filtri per sfaccettatura, la barra di ricerca può inviare query in linguaggio naturale all'API Prompt, che decide quali strumenti WebMCP in-page richiamare.

Best practice:anche se l'agente che stai creando sostituisce la barra di ricerca, non devi utilizzare un LLM per la ricerca nel sito. Esistono pattern e algoritmi molto più efficienti, accurati e consolidati per questo scopo. Questo esempio ha solo lo scopo di dimostrare la chiamata non deterministica degli strumenti WebMCP del tuo sito.

Per scoprire e richiamare uno strumento WebMCP da JavaScript:

// getTools() returns a Promise — it must be awaited.
const tools = await document.modelContext.getTools();
const tool = tools.find(t => t.name === 'list_items');

const json = await document.modelContext.executeTool(tool, args);
const result = JSON.parse(json); // executeTool resolves with a DOMString

Attività 3.1: strumenti delle sfaccettature della barra laterale

Esporre ogni sfaccettatura della barra laterale del catalogo a WebMCP in modo che gli agenti (e l'assistente di ricerca nella pagina) possano attivare/disattivare i filtri in modo programmatico.

Ogni componente sfaccettatura in src/components/facets/ fornisce già un metodo helper nella relativa classe e uno schema di input esportato in src/utils/filter-schemas.ts:

1. In src/components/facets/ActivityFacet.ts:
   • Registra activity_filter utilizzando activityFilterSchema.
   • In execute, chiama this.filterActivity(input?.activity, input?.selected).
2. In src/components/facets/CategoryFacet.ts:
   • Registra category_filter utilizzando categoryFilterSchema.
   • In execute, chiama this.filterCategory(input?.category, input?.selected).
3. In src/components/facets/ConditionFacet.ts:
   • Registra condition_filter utilizzando conditionFilterSchema.
   • In execute, chiama this.filterCondition(input?.condition, input?.selected).
4. In src/components/facets/PriceFacet.ts:
   • Registra price_filter utilizzando priceFilterSchema.
   • In execute, chiama this.filterPrice(input?.priceRange || input?.bracket, input?.selected).
5. In src/components/facets/WeightFacet.ts:
   • Registra weight_filter utilizzando weightFilterSchema.
   • In execute, chiama this.filterWeight(input?.weightRange || input?.bracket, input?.selected).
6. In src/components/facets/RatingFacet.ts:
   • Registra rating_filter utilizzando ratingFilterSchema.
   • In execute, chiama this.filterRating(input?.minRating || input?.rating, input?.selected).
7. In src/components/facets/SearchFacet.ts:
   • Registra keyword_filter utilizzando keywordFilterSchema.
   • In execute, chiama this.updateKeyword(input?.keyword).

Ricorda di verificare il supporto di WebMCP e di trasmettere { signal: this.signal } con .catch(() => {}) come hai imparato nel passaggio 2.

Attività 3.2: strumenti di visualizzazione del catalogo

Ora registra gli strumenti di elenco a livello di catalogo, reimpostazione dei filtri e strumenti di ricerca semantica su document.modelContext.

Vai al file: src/views/CatalogView.ts

Ispeziona registerWebMCPTools() nelle righe 125-140:

private registerWebMCPTools(): void

1. Controlla se WebMCP è supportato.
2. Registra lo strumento list_items:
   • Non accetta parametri di input ed è di sola lettura.
   • La sua funzione execute deve chiamare this.getItemsSummary().
3. Registra lo strumento reset_filters:
   • Non accetta parametri di input.
   • La sua funzione execute deve chiamare this.resetFilters().
4. Registra lo strumento semantic_catalog_filter:
   • Utilizza semanticCatalogFilterSchema.
   • La sua funzione execute deve chiamare interpretAndApplySemanticFilter(input.query).

Attività 3.3: orchestra l'agente di filtro semantico

Ora è il momento di collegare tutto. Questa attività trasforma la ricerca in una pipeline semantica che alimenta lo strumento semantic_catalog_filter:

Vai al file: src/ai/catalog-semantic-filter.ts

Ispeziona prewarmSemanticFilterSession() nelle righe 84-88:

export async function prewarmSemanticFilterSession(): Promise<void>

1. Controlla se warmSession esiste già; in caso affermativo, restituisci il risultato in anticipo.
2. Prepara una sessione dell'API Prompt con SEMANTIC_FILTER_SYSTEM_PROMPT utilizzando getPromptSession() e archiviala in warmSession. Esegui il wrapping in un blocco try/catch in modo che la creazione della ricerca possa comunque eseguire il fallback in modo controllato in caso di errore di pre-riscaldamento.

Ispeziona inferSearchFacets() nelle righe 93-134:

async function inferSearchFacets(
  searchTerm: string,
  cachedJourney: JourneyProfile | null
): Promise<{ parsed: SemanticFilterResponse; cacheHit: boolean }>

3. Richiedi la sessione pre-riscaldata da warmSession, se disponibile (e reimposta warmSession su null), oppure crea una nuova sessione utilizzando getPromptSession(SEMANTIC_FILTER_SYSTEM_PROMPT).
4. Richiedi al modello di utilizzare promptText, usando semanticFilterSchema come responseConstraint.
5. Analizza il JSON restituito, memorizza il risultato analizzato nella cache persistente con cacheKey e distrugge la sessione in un blocco finally.

Ispeziona applyFacetsViaWebMCP() nelle righe 139-270:

async function applyFacetsViaWebMCP(
  searchTerm: string,
  parsed: SemanticFilterResponse
): Promise<{ appliedFilters: SemanticFilterResult['appliedFilters']; toolsExecuted: string[] }>

6. Scopri gli strumenti registrati su document.modelContext utilizzando await document.modelContext.getTools().
7. Reimposta i filtri per iniziare da zero chiamando il numero await executeFacet('reset_filters', {}).
8. Applica contemporaneamente le sfaccettature attive utilizzando await Promise.all(facetTasks).

Ispeziona interpretAndApplySemanticFilter() nelle righe 272-316:

export async function interpretAndApplySemanticFilter(
  searchTerm: string
): Promise<SemanticFilterResult>

9. Deduci i facet di ricerca chiamando inferSearchFacets(searchTerm, cachedJourney).
10. Applica le sfaccettature dedotte al catalogo utilizzando applyFacetsViaWebMCP(searchTerm, parsed).

Verifica l'agente in-page

1. Vai a http://localhost:5173/catalog.
2. Nella barra di ricerca in alto, inserisci: "lightweight 3 season tent for wet hikes"
3. Guarda l'API Prompt analizzare la richiesta, richiamare activity_filter (Escursionismo), category_filter (Tende) e condition_filter (Bagnato), restringendo immediatamente il catalogo all'attrezzatura corrispondente senza alcun clic manuale sulle caselle di controllo.

6. Che cosa hai imparato

Complimenti. Hai trasformato un'applicazione e-commerce in un'esperienza intelligente e orientata all'agente, basata interamente sull'AI on-device e sulle API della piattaforma web standard.

Cosa hai creato:

• API Prompt on-device: sintetizza le sequenze temporali di navigazione degli utenti con LanguageModel per generare contesto JourneyProfile in tempo reale e ha creato un motore di sinergia rankComplementaryGear utilizzando schemi JSON strutturati (responseConstraint).
• Strumenti dei componenti WebMCP: strumenti modulari e incapsulati registrati nei componenti UI (get_recommendations, get_current_product, view_cart, manage_cart) tramite document.modelContext.
• Architettura di inoltro dell'agente: esecuzione dello strumento testata e verificata utilizzando l'estensione Chrome WebMCP Inspector.
• Agente in pagina on-site: strumenti lato client orchestrati direttamente nel browser per consentire la ricerca nel catalogo in linguaggio naturale con più sfaccettature dalla barra di ricerca dell'intestazione del sito.
• Modelli AI on-device specializzati: è stata esplorata la traduzione dinamica on-device utilizzando Translator.

Conclusioni importanti:

1. Latenza zero e privacy elevata: i modelli on-device come Gemini Nano eliminano le chiavi API cloud, la latenza di rete e i problemi di esfiltrazione dei dati.
2. Gli output strutturati sono essenziali: l'utilizzo di schemi JSON con responseConstraint trasforma la generazione di testo creativo in una logica applicativa affidabile e sicura.
3. WebMCP prepara il web per gli agenti AI: la registrazione degli strumenti direttamente nel DOM consente sia alle funzionalità assistive interne sia agli agenti browser autonomi esterni di eseguire azioni verificate e deterministiche.
4. Lascia che il modello proponga, non esegua: limitare il modello a un enum dei tuoi strumenti registrati e inviare il risultato personalmente rende il comportamento dell'agente verificabile e impedisce che inventi azioni.