Perché l’orchestrazione IA deve avvenire nel browser

Nel primo capitolo abbiamo mostrato che l’orchestrazione dell’intelligenza artificiale deve risiedere nel browser, vicino alla mappa e al suo stato applicativo in tempo reale. Questa vicinanza consente all’agente di accedere immediatamente a layer, estensione della vista e altri elementi dinamici, garantendo risposte coerenti con quello che l’utente sta visualizzando.

Per illustrare il meccanismo, riprendiamo l’esempio dei “nursing homes” (case di riposo) con la richiesta più specifica: “Mostra le case di riposo non profit in Texas e indica quale percentuale rappresentano rispetto al totale delle case di riposo in Texas.” Sebbene la frase sembri semplice, una mappa web può contenere decine di layer e centinaia di campi i cui nomi e valori non corrispondono esattamente al linguaggio dell’utente.

L’agente deve quindi identificare il layer United States Nursing Homes, scoprire che lo stato è memorizzato con codici a due lettere nel campo USERState e riconoscere che le strutture non profit non sono etichettate semplicemente “nonprofit”, ma hanno valori multipli nel campo USEROwnership_Type che iniziano con “Non profit -”. Solo dopo aver scoperto lo schema corretto, calcolare la percentuale e evidenziare le strutture sulla mappa, l’agente può fornire la risposta richiesta.

Strumenti dell’agente e interazione con la mappa

Gli strumenti dell’agente accedono alla mappa live attraverso il componente arcgis-map, leggendo layer, estensione e altri stati della vista al momento dell’esecuzione. Per una domanda come “Cosa c’è nella mia vista attuale?”, lo strumento di query utilizza l’estensione corrente anche se l’utente ha appena spostato la mappa.

L’ArcGIS Maps SDK for JavaScript fornisce le operazioni di base:

    • interrogazione delle feature
    • applicazione di filtri
    • calcolo della geometria
    • controllo della viewport
. L’orchestrazione avviene nel browser; le singole operazioni possono usare dati client‑side o chiamare servizi esterni secondo necessità.

Questi agenti sono disponibili tramite i componenti AI dell’Sdk. Il componente arcgis-assistant gestisce l’interfaccia conversazionale e orchestra le richieste tra gli agenti registrati.

Dalla definizione di workflow predefiniti alle skill

All’inizio del 2025 abbiamo progettato gli agenti con un approccio semplice: inserire i metadati dei layer e dei campi nel prompt e lasciare che il modello decidesse cosa usare. Per mappe piccole questo funzionava, ma con l’aumento dei layer e dei campi il modello iniziava a scegliere campi errati o a generare query su campi inesistenti.

Il primo miglioramento significativo è stato l’uso di embedding combinati con workflow costruiti in LangGraph. Gli embedding hanno permesso di recuperare i layer e i campi più rilevanti per una richiesta, mentre il grafo ha organizzato i passaggi per recuperare il contesto, generare le query e chiamare gli strumenti. Un contesto focalizzato e un percorso di esecuzione esplicito hanno aumentato l’affidabilità degli agenti.

Tuttavia, i percorsi predefiniti limitavano la capacità di recupero. Se un agente sceglieva il layer sbagliato o necessitava di più contesto, il workflow non sempre consentiva di tornare indietro e correggere la decisione.

Introduzione delle skill guidate

Abbiamo quindi introdotto le skill nell’architettura: istruzioni che descrivono come svolgere un compito usando gli strumenti disponibili. Invece di codificare ogni decisione come un ramo del grafo, lasciamo che l’agente scelga gli strumenti, ne esamini i risultati e decida il passo successivo. Con i modelli più recenti, questo approccio ha semplificato i workflow, offrendo allo stesso tempo più flessibilità quando il primo tentativo non riesce.

Trasferire la logica decisionale specifica del compito dalle branche del grafo alle istruzioni delle skill ha anche ridotto notevolmente la quantità di codice di workflow da mantenere.

Rappresentazione semplificata di un workflow predefinito vs. un loop guidato da skill

Un workflow predefinito segue un percorso fisso: recupera contesto → genera query → chiama strumento → restituisce risultato. Un loop guidato da skill, invece, permette all’agente di ciclare tra strumenti finché non ottiene le informazioni necessarie, adattandosi in tempo reale.

Caricamento dinamico delle skill

Un agente può utilizzare più skill, ognuna focalizzata su un compito specifico. Attraverso la progressive disclosure, il modello vede inizialmente solo i nomi e le descrizioni delle skill. Quando una skill viene caricata, le sue istruzioni dettagliate vengono aggiunte al contesto, e solo gli strumenti elencati nella proprietà allowed-tools sono messi a disposizione del modello. Questo mantiene istruzioni e disponibilità degli strumenti concentrate sul compito corrente.

Di seguito un estratto della skill query che mostra come le istruzioni guidano l’agente a trovare layer e campi rilevanti, interrogare i dati e rispondere all’utente.

---

name: query

description: Use to find, query, and summarize feature-layer data.

allowed-tools: >-

listSharedResources findRelevantLayers findRelevantFields

getAttribute getStatistics getTopFeatures queryFeatures

---

Indicazioni della skill “query”

    • Trova i layer pertinenti con findRelevantLayers.
    • Scopri campi e valori con findRelevantFields; non inventare campi.
    • Usa queryFeatures per contare o recuperare le feature corrispondenti.
    • Rispondi solo con i risultati degli strumenti; segnala direttamente eventuali errori.

Nei test, l’approccio guidato da skill ha migliorato accuratezza e flessibilità, ma ha richiesto più chiamate al modello e più token, aumentando il costo di esecuzione. I workflow predefiniti rimangono più efficienti per compiti prevedibili, mentre le skill guidate risultano utili quando l’agente deve adattarsi a risultati intermedi. Entrambi i metodi sono supportati e possono essere combinati.

Ricerca vettoriale nel browser

Abbiamo introdotto la ricerca basata su embedding per recuperare metadati di layer e campi prima della generazione della query. I layer di feature sono analoghi a tabelle di database e i loro campi a colonne: l’agente ha bisogno solo dello schema rilevante, non di tutti gli schemi disponibili.

Gli embedding trasformano il testo in vettori numerici, consentendo di cercare layer e campi per significato anziché per corrispondenza esatta. La generazione degli embedding è una fase di preparazione della mappa web: gli embedding vengono creati a partire dai titoli dei layer e dai metadati dei campi e salvati come risorsa dell’item della mappa. Al caricamento dell’applicazione, la mappa scarica gli embedding per il recupero lato browser.

Nel loop guidato da skill, il modello decide quando recuperare il contesto e quale query di ricerca utilizzare. Lo strumento di recupero converte la query in embedding, ricerca tra gli embedding dei layer e dei campi, e restituisce i candidati più pertinenti. L’agente può quindi ispezionare i risultati e ripetere la ricerca se serve più contesto. Nell’esempio delle case di riposo, questo aiuta a identificare il layer corretto e i campi di stato e proprietà prima di costruire la query.

Migliorare rilevanza e reattività

Inizialmente la ricerca ordinava i candidati per similarità coseno rispetto alla richiesta dell’utente. Questo funzionava bene nella maggior parte dei casi, ma mappe con molti campi simili – ad esempio population1990, population1991 e così via – producevano una short‑list dominata da campi strettamente correlati, escludendo altri contesti utili.

Per bilanciare rilevanza e diversità, abbiamo aggiunto la Massimal Marginal Relevance (MMR). MMR seleziona risultati che sono sia pertinenti alla richiesta sia diversi tra loro, riducendo la ridondanza nel contesto passato al modello. Poiché il confronto aggiuntivo aumenta il carico di lavoro, la ricerca è stata spostata in un web worker per mantenerla fuori dal thread principale.

Evoluzione della generazione degli embedding

Le prime versioni generavano embedding nel browser usando all-MiniLM-L6-v2. Successivamente abbiamo sperimentato modelli di embedding ospitati su server, come text-embedding-ada-002, ottenendo una qualità di recupero superiore. In fase di runtime, lo strumento di recupero chiama il server per embedizzare la query, mentre i confronti vettoriali e il ranking MMR avvengono localmente nel web worker.

Gli agenti attuali utilizzano la ricerca basata su embedding, che richiede la generazione, l’archiviazione e l’aggiornamento degli embedding man mano che il contenuto e i metadati della mappa cambiano. Stiamo inoltre esplorando alternative come Jev e l’OpenAI Decisions API per selezionare layer e campi rilevanti senza mantenere l’intera pipeline di embedding.

L’agente di esplorazione dati

Il Data Exploration Agent risponde a domande sui dati nei layer della mappa, fornendo conteggi, statistiche riepilogative, classifiche di feature e query spaziali.

Tracciare la richiesta delle case di riposo

Durante una sessione registrata, l’agente ha seguito questi passaggi:

    • Ha riconosciuto la necessità di trovare il layer “United States Nursing Homes”.
    • Ha usato findRelevantLayers per filtrare i layer contenenti la parola “Nursing”.
    • Ha identificato il campo USER_State come quello che contiene i codici di stato.
    • Ha individuato il campo USEROwnershipType e ha filtrato i valori che iniziano con “Non profit -”.
    • Ha costruito una query spaziale limitata all’estensione del Texas.
    • Ha eseguito queryFeatures per contare le strutture non profit e il totale delle strutture in Texas.
    • Ha calcolato la percentuale e ha inviato al componente arcgis-map le istruzioni per evidenziare le feature corrispondenti.
    • Infine, ha formulato la risposta all’utente includendo il conteggio, la percentuale e la visualizzazione sulla mappa.

Ogni passo è stato guidato dalle skill, con il modello che ha scelto gli strumenti appropriati, valutato i risultati e deciso se fosse necessario un ulteriore recupero di contesto.

Conclusioni e prospettive future

L’integrazione di agenti IA nativi del browser nella piattaforma Esri dimostra come l’orchestrazione locale possa migliorare l’interattività, la velocità e la pertinenza delle risposte. L’uso combinato di embedding, skill guidate e workflow ibridi fornisce un equilibrio tra efficienza e flessibilità, permettendo agli agenti di gestire mappe complesse con numerosi layer e campi.

Le sfide rimangono nella gestione dei costi di token, nella manutenzione degli embedding e nella garanzia di coerenza quando i dati della mappa cambiano. Tuttavia, le sperimentazioni con API decisionali esterne e modelli di embedding più leggeri promettono di semplificare ulteriormente il flusso di lavoro.

In futuro, ci aspettiamo una maggiore integrazione di capacità multimodali (ad esempio, analisi di immagini satellitari) e una più profonda personalizzazione delle skill per settori specifici, come la pianificazione urbana, la gestione delle risorse naturali e la risposta alle emergenze.