Azure AI Search come knowledge source

Ci sono scenari in cui l’indice esiste già: qualcuno in azienda ha costruito un servizio di ricerca su decine di migliaia di documenti, con il suo chunking, i suoi embedding e la sua sicurezza, e il tuo agente deve solo appoggiarsi a quel lavoro. È il caso di Azure AI Search, che la documentazione di Copilot Studio continua a chiamare così: Copilot Studio supporta l’aggiunta di Azure AI Search come knowledge source.

La prima cosa da fissare è la natura dell’oggetto. Una knowledge source è contenuto che il maker rende disponibile all’agente per fondare le risposte: non è un tool che l’agente invoca con parametri, non è un agent flow e non è un topic. La confusione è facile perché lo stesso connettore Azure AI Search (premium in Copilot Studio) espone anche azioni operative come Search vectors, Semantic Hybrid Search e Agentic Search (Preview), che vivono nel mondo dei tool e dei flussi. Aggiungere un indice come knowledge source è un percorso diverso: nessun parametro da mappare, solo grounding.

Che cosa deve avere l’indice prima di collegarlo

Il lavoro pesante si fa sul lato Azure, prima di aprire Copilot Studio. Serve un account Azure, un servizio di ricerca e soprattutto un indice vettoriale, perché Copilot Studio supporta indici vettorizzati che usano la integrated vectorization. La doc di Copilot Studio è esplicita sul motivo: preparando i dati e scegliendo un modello di embedding, e usando poi Import and vectorize data in Azure AI Search, il sistema può usare lo stesso modello con cui hai vettorizzato i documenti anche per vettorizzare il prompt in arrivo a runtime, riducendo la necessità di scrivere funzioni apposite.

Vale la pena capire come funziona sotto. In fase di indicizzazione la integrated vectorization dipende da un indexer, da un index e da uno skillset che combina una strategia di chunking (per esempio la Text Split skill) con una embedding skill. In fase di query dipende invece da un vectorizer, definito nello schema dell’indice e assegnato a un campo vettoriale, usato automaticamente per convertire la stringa di testo in vettore. La regola d’oro della doc di Azure AI Search è che il vectorizer deve corrispondere al modello di embedding usato per codificare il contenuto: se non corrispondono, la ricerca semantica degenera in rumore. Copilot Studio supporta anche il semantic ranker, ma va configurato in Azure AI Search prima di aggiungere la connessione.

Creare la connessione senza rompersi l’ambiente

Dall’agente si seleziona Add knowledge dalla pagina Overview o Knowledge, oppure dalle Properties di un generative answers node, poi la scheda Featured e Azure AI Search. Con Create new connection si scegle un Authentication type fra Access Key, Client Certificate Auth, Service principal (Microsoft Entra ID application) e Microsoft Entra ID Integrated. Con l’autenticazione a chiave servono Azure AI Search Endpoint URL e Azure AI Search Admin Key. Si indica poi l’indice vettoriale: se ne può aggiungere uno solo. Dopo Add to agent la sorgente compare in tabella con stato In progress e diventa Ready quando l’indicizzazione dei metadati è finita; solo allora la si può usare nel pannello di test.

Attenzione a un avvertimento operativo pesante: Azure AI Search va aggiunto tramite una vera data connection, senza configurare a mano endpoint e chiave API. Una connessione non supportata può lasciare una data connection difettosa che impedisce il caricamento della finestra di dialogo, e poiché le data connection sono gestite a livello di environment il problema può colpire tutti gli agenti. Per recuperare bisogna resettare l’accesso esterno dell’agente oppure eliminarlo e ricrearlo, e ri-aggiungere Azure AI Search da Data sources → Azure AI Search con autenticazione Entra ID invece delle chiavi.

Far tornare le citazioni giuste

Qui sta il punto che in produzione fa la differenza. Per ottenere citazioni, l’indice deve contenere un campo con il link reale al documento. Quando nell’indice è presente il campo metadata_storage_path, Copilot Studio interpreta quel campo come citazione; se il campo non esiste, considera come citazione qualunque campo contenga un link URL completo. Uno schema illustrativo:

"fields": [
  { "name": "id", "key": true },
  { "name": "content", "type": "Edm.String", "searchable": true },
  { "name": "contentVector", "type": "Collection(Edm.Single)" },
  { "name": "metadata_storage_path", "type": "Edm.String", "retrievable": true }
]

Due conseguenze. La prima: gli utenti dell’agente devono avere i permessi per aprire ciò che la citazione indica, altrimenti riceveranno link inutilizzabili. La seconda: le citazioni restituite da una knowledge source non possono essere usate come input di altri tool o azioni.

Retrieval, perimetro e che cosa verifica l’esame

Nel pipeline di retrieval augmented generation di Copilot Studio la domanda viene prima riscritta, poi eseguita su tutte le knowledge source configurate prendendo i primi tre risultati da ciascuna, poi sintetizzata con citazioni e infine validata dai livelli di moderazione. Nella tabella delle sorgenti, Azure AI Search è descritto come ricerca semantica vettoriale su endpoint configurato, e la nota è quella da ricordare: la connessione non è delegata, quindi non c’è security trimming né requisito di autenticazione per l’utente.

È esattamente la confusione che l’esame ama mettere alla prova. Azure AI Search offre di per sé un document-level access control con security filter, ACL e RBAC scope, sensitivity label di Microsoft Purview e ACL di SharePoint, applicati al momento della query confrontando il token Entra del chiamante passato nell’header x-ms-query-source-authorization con i metadati di permesso salvati nell’indice. Ma non dedurne che collegando quell’indice a Copilot Studio il trimming per singolo utente arrivi gratis: qui la sorgente non è delegata, al contrario di SharePoint o Dataverse che usano l’autenticazione delegata dell’utente. Se l’indice contiene documenti riservati, il filtro va progettato di conseguenza. Sul piano di rete, invece, Copilot Studio supporta indici configurati per virtual network tramite private endpoint, con il supporto Virtual Network abilitato nell’ambiente Power Platform.

Ultima trappola di lessico: la connessione è una credenziale, quindi in una solution viaggia come connection reference e non come environment variable, e non ha nulla a che vedere con le variabili globali di conversazione.