Un agente vale quanto vale il contesto che riesce a portarsi dietro. Le domande di progetto sono due: come recupero il dato giusto, e dove lo tengo — in un indice, in una memoria a lungo termine o dietro uno strumento che lo va a prendere quando serve.

Full-text, vettoriale o ibrida: il criterio di scelta

La ricerca full-text di Azure AI Search usa BM25 e vince quando conta la corrispondenza esatta: codici prodotto, gergo specialistico, date, nomi di persona. La ricerca vettoriale confronta embedding in uno spazio di similarità (coseno, prodotto scalare, distanza euclidea) e trova ciò che è concettualmente vicino anche senza parole in comune, con algoritmo HNSW, approssimato e veloce, oppure exhaustive KNN, esatto e costoso.

La ricerca ibrida è una singola richiesta che porta insieme campo di testo e query vettoriali, le esegue in parallelo e fonde le liste con Reciprocal Rank Fusion. Due conseguenze: il punteggio RRF non è confrontabile con BM25, quindi non ci si costruiscono sopra soglie assolute, e un orderby esplicito sovrascrive il ranking per rilevanza. Sopra l’ibrida si attiva il semantic ranker, un secondo stadio che rilegge i risultati migliori con modelli di linguaggio e aggiunge @search.rerankerScore, caption e answer: la documentazione riporta benefici di rilevanza significativi per l’ibrida con semantic ranker. Infine, i filtri sulle query vettoriali sono in preFilter per default: passare a postFilter cambia risultati e prestazioni.

q = "rimborso spese trasferta estero"
results = search_client.search(
    search_text=q,
    vector_queries=[VectorizableTextQuery(
        text=q, k_nearest_neighbors=50, fields="contentVector")],
    query_type="semantic",
    semantic_configuration_name="default-semantic-config",
)

Indicizzare: chunking, embedding e la pipeline che li produce

L’indicizzazione non è un caricamento, è una pipeline. L’indexer fa da crawler su una data source supportata, riconosce le modifiche e si schedula. Lo skillset arricchisce i documenti durante l’indicizzazione: la skill OCR estrae testo da immagini e PDF scansionati, la skill Text Split spezza il contenuto in chunk con lunghezza massima e sovrapposizione, la skill di embedding di Azure OpenAI trasforma ogni chunk in vettore, l’index projection proietta i chunk come documenti separati in un indice figlio. Messo insieme, questo è l’integrated vectorization; lato query un vectorizer converte la domanda in vettore.

Ed è qui la regola che si sbaglia più spesso: il modello di embedding usato in indicizzazione e quello usato a query time devono coincidere, dimensioni comprese, altrimenti i risultati degradano senza che nulla vada in errore. Sopra questo strato vive l’agentic retrieval, la pipeline multi-query che usa un LLM per scomporre una domanda complessa in sottodomande, le esegue in parallelo, riordina semanticamente e restituisce un contenuto unificato con riferimenti. È il motore di Foundry IQ: una knowledge base combina più knowledge source, indicizzate o remote, sincronizza le ACL e può eseguire le query sotto l’identità Microsoft Entra ID del chiamante, così l’agente non restituisce contenuto che l’utente non potrebbe leggere.

Memoria di conversazione, memoria a lungo termine e conoscenza

Vanno tenute separate tre cose. Il contesto della sessione corrente lo gestisce il runtime dell’agente con conversazioni e risposte. La memoria a lungo termine, in anteprima nel Foundry Agent Service, opera in tre fasi — estrazione, consolidamento con risoluzione dei conflitti, recupero — e conserva tre tipi: profilo utente (preferenze durevoli, da recuperare a inizio conversazione), riassunto di chat (a ogni turno) e memoria procedurale. Si governa con TTL di default a livello di store, CRUD sui singoli item e comandi diretti di ricordare o dimenticare; nelle API di basso livello lo scope va indicato esplicitamente, e i memory store non supportano la rete virtuale.

Il criterio di scelta è quello della documentazione stessa: la memoria per ciò che l’agente impara sull’utente nel tempo, una knowledge base di Foundry IQ per il contenuto aziendale curato, il file search per i documenti che l’utente porta durante l’interazione. Con un avvertimento: la memoria è una superficie di prompt injection, perché ciò che viene estratto oggi condiziona le risposte di domani.

Strumenti: cosa sta dietro un tool e cosa dentro un indice

Il tool file search è la via gestita: il servizio spezza i file, li vettorizza e li indicizza in un vector store, con default noti (chunk da 800 token, sovrapposizione 400, text-embedding-3-large a 256 dimensioni, al massimo 20 chunk in contesto) e limiti noti: 10.000 file per store, un solo vector store per agente e uno per conversazione. Due trappole: attendere lo stato completed prima di rispondere, e la scadenza dopo sette giorni di inattività dei vector store creati dalle conversazioni. Per controllo su chunking e filtri si passa al tool su indice Azure AI Search.

Per le azioni ci sono function calling, il tool OpenAPI per API esterne con autenticazione anonima, a chiave o con identità gestita, il tool MCP per server remoti — con filtro sui tool esposti e gestione delle approvazioni — e il tool A2A per gli agenti remoti. Sul web grounding: Web Search è consigliato e non richiede risorse aggiuntive, Grounding with Bing Search richiede la propria risorsa ma offre più parametri e supporta modelli non OpenAI venduti da Azure, Bing Custom Search resta in anteprima per la restrizione a domini. Attenzione: non rispettano VPN né private endpoint e portano i dati fuori dal confine di conformità di Azure. Il toolbox raggruppa gli strumenti dietro un unico endpoint MCP gestito, con autenticazione, versioning e governance centralizzati; il tool search fa scoprire all’agente solo quelli pertinenti.

Da ricordare per l’esame

  • Full-text per le corrispondenze esatte, vettoriale per la vicinanza concettuale, ibrida con semantic ranker come default; il punteggio RRF non si confronta con BM25.
  • Stesso modello di embedding e stesse dimensioni in indicizzazione e a query time, altrimenti i risultati degradano in silenzio.
  • Memoria per ciò che l’agente impara sull’utente, knowledge base per il contenuto aziendale curato, file search per i documenti della singola interazione.
  • File search significa un solo vector store per agente e uno per conversazione, con stato completed da attendere prima di rispondere.
  • I tool di web grounding ignorano VPN e private endpoint: incompatibili con un progetto isolato in rete.