Richiamare un'app Web del Servizio App dal Servizio Agente di Azure AI Foundry

Il servizio Azure AI Foundry Agent consente di creare agenti di intelligenza artificiale personalizzati in base alle proprie esigenze tramite istruzioni personalizzate e aumentata da strumenti avanzati come l'interprete del codice e le funzioni personalizzate. È ora possibile connettere l'agente di Intelligenza artificiale di Azure a un'API esterna usando uno strumento specificato OpenAPI 3.0 , consentendo l'interoperabilità scalabile con varie applicazioni.

Servizio app di Azure è una piattaforma completamente gestita per la creazione, la distribuzione e il ridimensionamento di api e app Web. Se l'API è ospitata nel servizio app di Azure, è possibile connettere l'agente di intelligenza artificiale all'API usando la specifica OpenAPI. La specifica OpenAPI definisce l'API e come interagire con essa. È quindi possibile usare il linguaggio naturale per richiamare l'API tramite l'agente di intelligenza artificiale. Questo strumento è potente perché consente di aggiungere funzionalità dell'agente di intelligenza artificiale alle app esistenti con modifiche minime al codice. Inoltre, questo agente ha la possibilità di interagire direttamente con l'app. Non è necessario apportare modifiche significative al codice o lavorare sull'implementazione altri aggiornamenti secondari per interagire con l'agente usando gli SDK disponibili.

In questa esercitazione si usa un agente di Azure AI Foundry per richiamare un'API esistente ospitata nel servizio app di Azure. Al termine di questo tutorial, avrai un'applicazione di chat assistente di moda in esecuzione su App Service, utilizzando un agente di intelligenza artificiale del servizio Azure AI Foundry Agent.

Prerequisiti

1. Un account GitHub. È anche possibile ottenerne uno gratuitamente.
2. Un account Azure con una sottoscrizione attiva. Se non si ha un account Azure, è possibile crearne uno gratuitamente.

1. Esaminare l'esempio in GitHub Codespaces

1. Accedere all'account GitHub e passare a https://github.com/Azure-Samples/ai-agent-openai-web-app/fork.
2. Seleziona Crea fork.
3. Selezionare Codice>Crea codespace nel file main. La configurazione del codespace richiede alcuni minuti.

Il repository di esempio include il contenuto seguente:

Contenuto	Descrizione
src/webapp	Un'applicazione .NET Blazor front-end.
infra	Infrastruttura distribuita come codice per la distribuzione di un'app Web .NET in Azure e risorse di Azure AI Foundry per l'agente di intelligenza artificiale. Vedere Creare modelli dell'interfaccia della riga di comando per sviluppatori di Azure.
azure.yaml	Configurazione dell'interfaccia della riga di comando per sviluppatori di Azure che distribuisce l'applicazione Blazor in servizio app. Vedere Creare modelli dell'interfaccia della riga di comando per sviluppatori di Azure.

2. Distribuire l'infrastruttura e l'applicazione di Azure

1. Accedere all'account Azure usando il comando azd auth login e seguendo il prompt:

   azd auth login
   

2. Creare l'app servizio app e distribuire il codice usando il azd up comando :

   azd up
   

   Il completamento del comando azd up potrebbe richiedere alcuni minuti. azd up utilizza i file Bicep nei tuoi progetti per creare un'app di Servizio app nel piano tariffario P0v3 e distribuisce l'app .NET in src/webapp. Il comando crea anche Azure AI Foundry e le risorse di supporto per l'agente.

3. Creare l'agente di intelligenza artificiale

1. Nel portale di Azure passare al gruppo di risorse creato dal modello azd. Il nome del gruppo di risorse è nell'output del comando azd eseguito.

2. Selezionare la risorsa del progetto di intelligenza artificiale di Azure . Il nome deve essere nel formato ai-aiproject-<identifier>. Assicurarsi di selezionare la risorsa del progetto e non le risorse dei servizi hub o di intelligenza artificiale. Gli agenti vengono creati dalla risorsa del progetto di intelligenza artificiale di Azure.

3. Selezionare Avvia studio per aprire Azure AI Foundry Studio.

4. Nel menu a sinistra sotto Crea e personalizza, selezionare Agenti.

5. Quando la pagina viene caricata, nell'elenco a discesa selezionare la risorsa del servizio Azure OpenAI generata automaticamente e quindi selezionare Andiamo.

6. Selezionare + Nuovo agente per creare un nuovo agente o usarne uno predefinito se ne è già stato creato uno.

7. Quando viene creato l'agente, aggiungere le istruzioni seguenti nel menu a destra. Queste istruzioni assicurano che l'agente risponda solo alle domande e completi le attività correlate all'app fashion store.

    You are an agent for a fashion store that sells clothing. You have the ability to view inventory, update the customer's shopping cart, and answer questions about the clothing items that are in the inventory. You should not answer questions about topics that are unrelated to the fashion store. If a user asks an unrelated question, please respond by telling them that you can only talk about things that are related to the fashion store.
    

4. Aggiungere lo strumento specificato OpenAPI all'agente di intelligenza artificiale

Per indicazioni dettagliate con screenshot e altre informazioni, vedere Aggiungere lo strumento di specifica OpenAPI nel portale di Azure AI Foundry. I passaggi sono riepilogati nelle istruzioni seguenti.

1. Selezionare + Aggiungi accanto a Azione.

2. Selezionare Lo strumento specificato OpenAPI 3.0.

3. Assegnare un nome allo strumento e la descrizione seguente. La descrizione viene usata dal modello per decidere quando e come usare lo strumento.

    This tool is used to interact with and manage an online fashion store. The tool can add or remove items from a shopping cart as well as view inventory.
    

4. Lasciare anonimo il metodo di autenticazione. Non è presente alcuna autenticazione nell'app Web. Se l'app richiede una chiave API o un'identità gestita per accedervi, questa posizione è la posizione in cui specificare queste informazioni.

5. Copiare e incollare la specifica OpenAPI nella casella di testo. La specifica OpenAPI viene fornita in Codespace nella src/webapp directory e viene chiamata swagger.json.

6. Prima di completare la creazione dello strumento, devi copiare e incollare l'URL dell'app nella specifica OpenAPI. Sostituire il segnaposto <APP-SERVICE-URL> nella riga 10 della specifica OpenAPI con l'URL dell'app. che presenta il formato https://<app-name>.azurewebsites.net.

   • Per trovare l'URL dell'app, tornare al gruppo di risorse e passare al servizio app. L'URL si trova nella pagina Panoramica del servizio app.

7. Selezionare Avanti, esaminare i dettagli forniti e quindi selezionare Crea strumento.

5. Connettere il servizio app all'agente di intelligenza artificiale

Dopo aver configurato l'agente di intelligenza artificiale e aver aggiunto lo strumento specificato OpenAPI, è necessario configurare il servizio app con le variabili di ambiente appropriate in modo che l'app conosca l'agente a cui connettersi. L'app ha già un'identità gestita assegnata che consente l'accesso al servizio agente di intelligenza artificiale. Questa identità gestita è necessaria per l'app per raggiungere l'agente e viene creata con il modello azd.

1. Dal Dashboard Agenti, dove è stato aggiunto lo strumento OpenAPI, annotare l'ID dell'agente agent ID. che presenta il formato asst_<unique-identifier>.
2. Seleziona Panoramica nel menu e nota la stringa di connessione del progetto. che presenta il formato <region>.api.azureml.ms;<subscription-id>;<resource-group-name>;<project-name>.
3. Accedi al Servizio app nel portale di Azure.
4. Selezionare Variabili di ambiente nel menu a sinistra.
5. Nella scheda Impostazioni app selezionare + Aggiungi e aggiungere l'impostazione seguente:
   • Nome: AzureAIAgent__ConnectionString
   • Valore: la stringa di connessione che hai annotato dal Servizio Agente di Intelligenza Artificiale
6. Aggiungere un'altra impostazione dell'app:
   • Nome: AzureAIAgent__AgentId
   • Valore: ID agente che hai annotato durante la creazione dell'agente
7. Selezionare Applica nella parte inferiore della pagina e confermare quando richiesto. L'app viene riavviata con le nuove impostazioni applicate.

6. Verificare l'app in esecuzione

Nell'output AZD trovare l'URL dell'app e passarvi nel browser. L'URL è simile al seguente nell'output azd:

Deploying services (azd deploy)

    (✓) Done: Deploying service web
    - Endpoint: https://<app-name>.azurewebsites.net/

Nella finestra di chat porre le domande dell'agente, ad esempio:

• Cosa c'è nel mio carrello?
• Aggiungi una piccola giacca denim al mio carrello
• Abbiamo qualche blazer in magazzino? È anche possibile porre domande generali sugli elementi e l'agente deve essere in grado di fornire informazioni.
• Raccontami della camicia a quadretti casual Red Slim Fit
• Il blazer è caldo?

Pulizia

Al termine di questa app, eseguire quanto segue per eliminare il gruppo di risorse con tutte le risorse create durante questa esercitazione.

azd down

Risoluzione dei problemi

Problemi comuni

1. Chat non funzionante
   • Verificare che le variabili di ambiente (AzureAIAgent__ConnectionString e AzureAIAgent__AgentId) siano impostate correttamente nelle variabili di ambiente del servizio app.
   • Verificare che l'agente di intelligenza artificiale sia stato creato correttamente e configurato con lo strumento OpenAPI corretto.
   • Verificare che l'URL della specifica OpenAPI sia accessibile dal servizio agente di Azure AI Foundry.
   • Assicurarsi che l'URL del servizio App sia aggiornato nel swagger.json fornito allo strumento specificato OpenAPI.
2. Problemi di autorizzazione
   • Se si verificano errori di autenticazione, assicurarsi che l'identità gestita del servizio app disponga delle autorizzazioni appropriate per accedere al servizio agente di Azure AI Foundry. L'identità gestita richiede almeno l'autorizzazione Microsoft.MachineLearningServices/workspaces/agents/action per interagire con l'agente. Il "ruolo sviluppatore di Intelligenza artificiale di Azure" fornito ha questa autorizzazione e deve essere sufficiente. Se si decide di modificare questo ruolo, assicurarsi che disponga dell'autorizzazione necessaria.
3. Problemi relativi all'API
   • Se l'agente non è in grado di eseguire azioni nell'inventario o nel carrello, verificare i percorsi API nella specifica OpenAPI.
   • Verificare che gli endpoint API rispondano correttamente testandoli direttamente nell'interfaccia utente di Swagger all'indirizzo /api/docs.

Visualizzazione dei log

Per visualizzare i log per il servizio app:

1. Accedi al Servizio app nel portale di Azure.
2. Nel menu a sinistra selezionare Monitoraggio>del flusso di log per visualizzare i log in tempo reale.
3. Questi log rivelano eventuali problemi dell'applicazione che potrebbero essere necessari per risolvere.

Informazioni sulle funzionalità API

La specifica OpenAPI fornisce all'agente di intelligenza artificiale informazioni sugli endpoint disponibili:

Endpoint dell'API del carrello

• GET /api/Cart: recupera il contenuto corrente del carrello acquisti e il costo totale
• DELETE /api/Cart: cancella tutti gli elementi dal carrello
• POST /api/Cart/add: aggiunge un articolo al carrello acquisti
• PUT /api/Cart/{productId}/size/{size}: aggiorna la quantità di un articolo specifico
• DELETE /api/Cart/{productId}/size/{size}: rimuove un elemento specifico dal carrello

Endpoint dell'API di Inventario

• GET /api/Inventory: elenca tutti gli articoli di inventario disponibili
• GET /api/Inventory/{id}: Ottiene i dettagli su un prodotto specifico
• GET /api/Inventory/{id}/size/{size}: Controlla l'inventario per una dimensione specifica del prodotto
• GET /api/Inventory/sizes: ottiene tutte le dimensioni disponibili nell'inventario

Interazioni con agenti avanzati

Oltre alle interazioni di base, l'agente di intelligenza artificiale può gestire scenari più complessi:

• Raccomandazioni personalizzate: "Ho bisogno di un outfit casual aziendale per una riunione"
• Indicazioni sulle dimensioni: "Che dimensione blazer sarebbe adatto a qualcuno che ha 6'2" e 180 libbre?"
• Coordinamento outfit: "Cosa si abbina con la giacca denim nera?"
• Gestione carrello acquisti: "Rimuovere la maglia grande e aggiungere una media"
• Controlli inventario: "Hai delle magliette rosse di taglia media?"
• Richieste di prezzo: "Qual è l'intervallo di prezzo per blazer?"

Considerazioni sulla sicurezza

• L'applicazione usa le identità gestite di Azure per l'autenticazione sicura al servizio agente di Azure AI Foundry negli ambienti di produzione.
• È possibile proteggere ulteriormente l'app e l'agente usando una delle procedure standard e delle risorse di Azure. Per i modelli di infrastruttura dell'agente di intelligenza artificiale di Azure sicuri, vedere il repository azureai-samples.

Passaggi successivi

Dopo aver appreso come connettere l'agente di intelligenza artificiale a un'API nel servizio app di Azure, è possibile esplorare le altre integrazioni di intelligenza artificiale disponibili con il servizio app:

Esercitazione: Creare un chatbot con il servizio app di Azure e Azure OpenAI (.NET)

Esercitazione: Eseguire il chatbot in App Service con un'estensione Phi-4 sidecar (ASP.NET Core)

Distribuire un'app Blazor .NET connessa a SQL di Azure e Azure OpenAI su Azure App Service