Avvio rapido: Aggiungere una knowledge base di Foundry IQ a un agente ospitato con una casella degli strumenti

In questa guida rapida, si collega un agente ospitato a una knowledge base di Foundry IQ in Foundry Tools e si accede a tale knowledge base tramite una toolbox. Una base di conoscenza in Foundry IQ usa il recupero agentico di Azure AI Search per pianificare una query, cercare nei tuoi dati, riordinare i risultati e generare una risposta con citazioni. La casella degli strumenti espone l'endpoint MCP (Model Context Protocol) della Knowledge Base come singolo strumento e l'agente chiama tale strumento con la propria identità gestita per l'autenticazione senza chiave.

Completa tre parti:

• Eseguire il provisioning di una knowledge base una sola volta con uno script Python che crea un indice di ricerca, vi carica documenti di esempio e crea la fonte delle informazioni e la knowledge base.
• Creare una connessione alla casella degli strumenti che punti all'endpoint MCP della knowledge base e si autentichi con l'identità gestita dell'agente.
• Distribuisci un agente ospitato che rileva lo strumento knowledge_base_retrieve tramite la Toolbox e basa le sue risposte sulle fonti recuperate.

Il codice dell'agente, lo script di provisioning della Knowledge Base, la definizione della casella degli strumenti e un hook di automazione provengono dall'esempio di IQ Foundry, in modo da concentrarsi sul flusso di lavoro anziché sull'implementazione.

Prerequisiti

Questo argomento di avvio rapido si basa sulla toolchain dell'agente ospitato. Completare prima i prerequisiti nell'Avvio rapido dell'agente ospitato, che illustrano la sottoscrizione Azure, i ruoli del progetto, Python, Azure Developer CLI (azd) e l'estensione microsoft.foundry.

Altri elementi necessari:

• Un servizio Azure AI Search che supporta il recupero agentico. Abilitare un'identità gestita assegnata dal sistema nel servizio e abilitare il controllo degli accessi in base al ruolo. Nel portale di Azure, nel servizio di ricerca, vai a Impostazioni>Chiavi e imposta Controllo dell'accesso API su Entrambi o Controllo dell'accesso in base al ruolo.
• Distribuzione di un modello di chat nel progetto Foundry, ad esempio gpt-5.4-mini. La Knowledge Base usa lo stesso modello per sintetizzare le risposte.

Ruoli richiesti

Assegnare i ruoli seguenti prima di eseguire il provisioning. La knowledge base richiama il modello con l'identità gestita del servizio di ricerca, quindi tale identità deve avere accesso al tuo account Foundry.

L'identità gestita dell'agente esiste solo dopo la distribuzione dell'agente, quindi si assegna il lettore dati dell'indice di ricerca nel passaggio 6.

Passaggio 1: Inizializzare l'agente ospitato

Inizializzare un agente ospitato dall'esempio di Foundry IQ. L'esempio include il codice dell'agente, lo provision_kb.py script, la toolbox.yaml definizione e gli hook di automazione. Eseguire questi comandi in una directory vuota.

mkdir my-foundry-iq-agent
cd my-foundry-iq-agent
azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/17-foundry-iq-toolbox/azure.yaml"

Segui le istruzioni per selezionare l'abbonamento, il progetto Foundry e la distribuzione di un modello di chat, ad esempio gpt-5.4-mini. Se non si ha un progetto, il flusso ne guida la creazione. L'inizializzazione imposta il progetto selezionato come progetto attivo e copia i file di esempio in una nuova directory del servizio, src/agent-framework-foundry-iq-knowledge-base-responses/.

Passaggio 2: Abilitare il provisioning con un solo comando

L'esempio include un hook postprovision che esegue lo script della knowledge base, crea la connessione della casella degli strumenti, crea la casella degli strumenti e imposta la variabile di ambiente TOOLBOX_ENDPOINT ogni volta che si esegue il provisioning. Collegare l'hook al file azure.yaml generato da azd ai agent init .

Aprire azure.yaml e aggiungere questo blocco di primo livello. L'hook postprovision deve essere al livello superiore perché gli hook con ambito di servizio supportano solo il pacchetto e il ciclo di vita della distribuzione.

hooks:
  postprovision:
    posix:
      shell: sh
      run: ./src/agent-framework-foundry-iq-knowledge-base-responses/hooks/postprovision.sh
    windows:
      shell: pwsh
      run: ./src/agent-framework-foundry-iq-knowledge-base-responses/hooks/postprovision.ps1

L'hook individua la propria directory, quindi funziona indipendentemente dalla directory azd da cui viene eseguita.

Passaggio 3: Effettuare il provisioning delle risorse Azure e della Knowledge Base

1. Indirizza l'hook al tuo servizio di ricerca esistente:

   azd env set AZURE_SEARCH_ENDPOINT "https://<your-search>.search.windows.net"
   

   L'hook ricava l'endpoint del modello per la sintesi delle risposte dall'endpoint del progetto. Per usare un'altra risorsa Azure OpenAI, impostarla prima con azd env set AZURE_OPENAI_ENDPOINT "https://<account>.openai.azure.com".

2. Effettuare il provisioning delle risorse e della knowledge base:

   azd provision
   

   azd provision crea o riutilizza il progetto Foundry e la distribuzione del modello. Quindi, l'hook postprovision:

   1. Esegue provision_kb.py per creare l'indice di ricerca foundry-iq-index, effettua il seeding dei documenti Earth at night e crea la fonte delle informazioni foundry-iq-ks e la knowledge base foundry-iq-kb. Lo script archivia l'endpoint MCP della Knowledge Base come KB_MCP_ENDPOINT.
   2. Crea la connessione knowledge-base-mcp. Questa connessione è destinata all'endpoint MCP della Knowledge Base e usa l'identità agente, in modo che l'identità gestita dell'agente esegua l'autenticazione senza segreti archiviati.
   3. Crea la casella degli strumenti knowledge-base da toolbox.yaml, che espone lo strumento knowledge_base_retrieve.
   4. Imposta TOOLBOX_ENDPOINT in modo che l'agente si connetta alla casella degli strumenti.

Passaggio 4: Eseguire l'agente a livello locale

1. Avvia l'agente:

   azd ai agent run
   

   Questo comando crea un ambiente virtuale, installa le dipendenze e gestisce l'agente in http://localhost:8088. I pacchetti di anteprima possono generare avvisi pip durante l'installazione. Questi avvisi non sono bloccanti.

2. In un terminale separato, porre all'agente una domanda a cui la Knowledge Base può rispondere:

   azd ai agent invoke --local "What can you tell me about the Earth at night?"
   

   L'agente locale si connette alla casella degli strumenti, ma il recupero dalla Knowledge Base richiede l'identità dell'agente distribuito. Usare l'esecuzione locale per confermare che l'agente venga avviato e raggiunga la casella degli strumenti. Dopo la distribuzione, verificare le risposte con grounding.

Passaggio 5. Eseguire la distribuzione in Servizio Agente Fonderia

Distribuire il codice sorgente dell'agente. azd crea un pacchetto dell'origine come file ZIP e lo carica in Foundry, che risolve le dipendenze e compila l'agente ospitato in remoto:

azd deploy

Al termine dell'esecuzione del comando, l'output mostra i collegamenti al playground dell'agente e all'endpoint dell'agente.

Passaggio 6: Concedere all'agente l'accesso alla Knowledge Base

L'agente distribuito recupera dalla base di conoscenza con la propria identità gestita. Assegnare a tale identità il ruolo Search Index Data Reader nel servizio di ricerca.

1. Trova l'ID oggetto dell'identità dell'agente nel portale Foundry. Passare ad Agenti, selezionare l'agente e quindi selezionare Identità.

2. Assegnare il ruolo nel servizio di ricerca:

   searchId=$(az search service show -n <search-name> -g <resource-group> --query id -o tsv)
   az role assignment create --assignee-object-id <agent-identity-object-id> \
     --assignee-principal-type ServicePrincipal \
     --role "Search Index Data Reader" --scope $searchId
   

   In PowerShell, usare un backtick di continuazione di riga (`) anziché \.

Passaggio 7: Richiamare l'agente distribuito

Inviare una domanda all'agente distribuito e confermare le risposte dalla Knowledge Base:

azd ai agent invoke "What can you tell me about the Earth at night?"

L'agente restituisce una risposta fondata con citazioni dei documenti di esempio. Provate ancora qualche domanda per vedere come funziona il recupero delle informazioni nel corpus di esempio:

azd ai agent invoke "Why do some lights appear over the open ocean?"
azd ai agent invoke "How is nighttime imagery used to study light pollution?"

Pulire le risorse

Elimina le risorse quando hai finito, per evitare ulteriori addebiti.

1. Eliminare la knowledge base, l'origine della knowledge base e l'indice dal servizio di ricerca. Nel portale di Azure, nel servizio di ricerca eliminare foundry-iq-kb, foundry-iq-kse l'indicefoundry-iq-index. È possibile mantenere il servizio di ricerca per altri progetti.

2. Eliminare l'agente e le relative risorse Azure:

   Warning

   Se l'ambiente corrente azd ha creato il progetto Foundry, azd down elimina definitivamente il gruppo di risorse del progetto e tutti gli elementi in esso contenuti. Se è stato selezionato un progetto esistente durante l'inizializzazione, azd down lascia il progetto, il relativo gruppo di risorse, l'agente ospitato e altre risorse di avvio rapido sul posto. Per eliminare le risorse non più necessarie dal progetto esistente, eliminarle separatamente.

   azd down
   

Risoluzione dei problemi

Cosa si è appreso

Questo avvio rapido spiega come:

• È stata creata una Knowledge Base di IQ Foundry con un indice di ricerca, un'origine della knowledge base e documenti di esempio.
• È stata esposta la base di conoscenza tramite una connessione alla casella degli strumenti che usa l'identità gestita dell'agente.
• È stato distribuito un agente ospitato che giustifica le risposte nella Knowledge Base con citazioni.

Passo successivo

Contenuti correlati

• Che cos'è Foundry IQ?
• Connettere una knowledge base Foundry IQ al servizio Foundry Agent
• Creare una cassetta degli strumenti basata sugli intenti in Foundry
• Guida introduttiva: Implementare il primo agente ospitato