Come usare il servizio agente Foundry con gli strumenti specificati OpenAPI (versione classica)

È 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. Usando le identità gestite (Microsoft Entra ID) per l'autenticazione, è possibile abilitare in modo sicuro gli strumenti personalizzati per autenticare l'accesso e le connessioni. Questo approccio è ideale per l'integrazione con l'infrastruttura o i servizi Web esistenti.

Lo strumento OpenAPI specificato migliora l'esperienza di chiamata delle funzioni fornendo integrazioni API standardizzate, automatizzate e scalabili che migliorano le funzionalità e l'efficienza dell'agente. Le specifiche OpenAPI forniscono uno standard formale per descrivere le API HTTP. Questo standard consente agli utenti di comprendere il funzionamento di un'API, il funzionamento di una sequenza di API e supporta la generazione di codice client, la creazione di test, l'applicazione di standard di progettazione e altro ancora. Attualmente, gli strumenti specificati OpenAPI 3.0 supportano tre tipi di autenticazione: anonymous, API keye managed identity.

Supporto per l'utilizzo

Prerequisiti

1. Assicurarsi di completare i prerequisiti e i passaggi di installazione nella guida introduttiva.
2. Controllare la specifica OpenAPI per i requisiti seguenti:
   1. Anche se non richiesto dalla specifica OpenAPI, ogni funzione deve avere un operationId oggetto per lavorare con lo strumento OpenAPI.
   2. Deve operationId contenere solo lettere, -e _. È possibile modificarlo per soddisfare questo requisito. Usare un nome descrittivo per consentire ai modelli di decidere in modo efficiente quale funzione usare.

Eseguire l'autenticazione con la chiave API

Usando l'autenticazione della chiave API, è possibile autenticare la specifica OpenAPI tramite metodi diversi, ad esempio una chiave API o un token di connessione. Ogni specifica OpenAPI supporta un solo schema di sicurezza della chiave API. Se sono necessari più schemi di sicurezza, creare più strumenti per specifiche OpenAPI.

1. Aggiornare gli schemi di sicurezza delle specifiche OpenAPI. Ha una securitySchemes sezione e uno schema di tipo apiKey. Per esempio:

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   In genere è sufficiente aggiornare il name campo, che corrisponde al nome di key nella connessione. Se gli schemi di sicurezza includono più schemi, mantenerli solo uno di essi.

2. Aggiornare la specifica OpenAPI per includere una security sezione:

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. Rimuovere qualsiasi parametro nella specifica OpenAPI che richiede la chiave API, perché la chiave API viene archiviata e passata tramite una connessione, come descritto più avanti in questo articolo.

4. Creare una custom keys connessione per archiviare la chiave API.

   1. Passare al portale Microsoft Foundry e selezionare Management center dal riquadro di spostamento a sinistra.

      

   2. Selezionare Risorse connesse nel progetto di intelligenza artificiale nel riquadro di spostamento a sinistra.

   3. Selezionare + nuova connessione nella pagina delle impostazioni.

      Nota

      Se si rigenera la chiave API in un secondo momento, è necessario aggiornare la connessione con la nuova chiave.

      

   4. Selezionare chiavi personalizzate in altri tipi di risorse.

      

   5. Immettere le informazioni seguenti

      • key: name campo del tuo schema di sicurezza. In questo esempio deve essere x-api-key

        "securitySchemes": {
            "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
        

      • value: YOUR_API_KEY

      • Nome connessione: YOUR_CONNECTION_NAME (usare questo nome di connessione nel codice di esempio seguente).

      • Accesso: è possibile scegliere questo progetto solo o condiviso a tutti i progetti. Assicurati che il progetto per il quale hai inserito la stringa di connessione nel codice di esempio seguente abbia accesso a questa connessione.

5. Dopo aver creato una connessione, usarla tramite l'SDK o l'API REST. Usare le schede nella parte superiore di questo articolo per visualizzare esempi di codice.

Eseguire l'autenticazione con l'identità gestita (Microsoft Entra ID)

Microsoft Entra ID è un servizio di gestione delle identità e degli accessi basato sul cloud che i dipendenti possono usare per accedere alle risorse esterne. Usando Microsoft Entra ID, è possibile aggiungere sicurezza aggiuntiva quando si autenticano le API senza dover usare le chiavi API. Dopo aver configurato l'autenticazione dell'identità gestita, lo strumento Foundry usato dall'agente gestisce l'autenticazione.

Quando si configura l'autenticazione dell'identità gestita, è necessario fornire un valore Audience. L'audience è l'identificatore di risorsa OAuth2 (detto anche URI dell'ambito o ID applicazione) che identifica l'API o servizio a cui l'identità gestita può accedere.

Valori comuni dei destinatari:

• Strumenti Foundry (in precedenza servizi Azure AI o Servizi cognitivi): https://cognitiveservices.azure.com/
• Azure Resource Manager API: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• API personalizzate registrate in Microsoft Entra ID: Utilizzare l'URI ID dell'applicazione disponibile nella registrazione dell'app dell'API

Per configurare l'autenticazione usando l'identità gestita:

1. Assicurati che la tua risorsa Foundry abbia attivata un'identità gestita assegnata dal sistema.

   Screenshot che mostra il selettore di identità gestita nel portale di Azure.

2. Creare una risorsa per il servizio a cui connettersi tramite la specifica OpenAPI.

3. Assegnare l'accesso appropriato alla risorsa.

   1. Selezionare Controllo di accesso per la risorsa.

   2. Selezionare Aggiungi e quindi aggiungere un'assegnazione di ruolo nella parte superiore della schermata.

      Un screenshot che mostra il selettore di assegnazione di ruolo nel Portale di Azure.

   3. Selezionare l'assegnazione di ruolo appropriata necessaria. In genere, richiede almeno il ruolo READER . Quindi selezionare Avanti.

   4. Selezionare Identità gestita e quindi selezionare membri.

   5. Nel menu a discesa dell'Identità gestita, cercare Foundry Tools e quindi selezionare il Foundry Tool dell'agente.

   6. Selezionare Fine.

4. Dopo aver completato la configurazione, è possibile usare lo strumento tramite il portale foundry, l'SDK o l'API REST. Usare le schede nella parte superiore di questo articolo per visualizzare gli esempi di codice.