Hur man använder Azure AI Foundry Agent-tjänst med verktyg definierade av OpenAPI

Nu kan du ansluta din Azure AI-agent till ett externt API med ett OpenAPI 3.0-angivet verktyg, vilket möjliggör skalbar samverkan med olika program. Aktivera dina anpassade verktyg för att autentisera åtkomst och anslutningar med hanterade identiteter (Microsoft Entra-ID) för ökad säkerhet, vilket gör det idealiskt för integrering med befintlig infrastruktur eller webbtjänster.

OpenAPI-angivet verktyg förbättrar funktionens samtalsupplevelse genom att tillhandahålla standardiserade, automatiserade och skalbara API-integreringar som förbättrar agentens funktioner och effektivitet. OpenAPI-specifikationer tillhandahåller en formell standard för att beskriva HTTP-API:er. På så sätt kan användarna förstå hur ett API fungerar, hur en sekvens med API:er fungerar tillsammans, generera klientkod, skapa tester, tillämpa designstandarder med mera. För närvarande stöder vi tre autentiseringstyper med de OpenAPI 3.0-angivna verktygen: anonymous, API key, managed identity.

Användningsstöd

Förutsättningar

1. Kontrollera att du har slutfört förberedelserna och installationsstegen i snabbstarten.

2. Kontrollera OpenAPI-specifikationen för följande krav:

   1. Även om det inte krävs av OpenAPI-specifikationen operationId krävs för att varje funktion ska användas med OpenAPI-verktyget.
   2. operationId får endast innehålla bokstäver - och _. Du kan ändra den för att uppfylla kravet. Vi rekommenderar att du använder beskrivande namn för att hjälpa modeller att effektivt bestämma vilken funktion som ska användas.

Autentisera med API-nyckel

Med API-nyckelautentisering kan du autentisera din OpenAPI-specifikation med hjälp av olika metoder, till exempel en API-nyckel eller ägartoken. Endast ett API-nyckelsäkerhetsschema stöds enligt OpenAPI-specifikationen. Om du behöver flera säkerhetsscheman skapar du flera OpenAPI-specifikationsverktyg.

1. Uppdatera säkerhetsscheman för OpenAPI-specifikationen. det har ett securitySchemes avsnitt och ett schema av typen apiKey. Till exempel:

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

   Du behöver vanligtvis bara uppdatera fältet name , vilket motsvarar namnet key på i anslutningen. Om säkerhetsschemana innehåller flera scheman rekommenderar vi att du bara behåller ett av dem.

2. Uppdatera OpenAPI-specifikationen så att den innehåller ett security avsnitt:

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

3. Ta bort alla parametrar i OpenAPI-specifikationen som behöver API-nyckel, eftersom API-nyckeln lagras och skickas via en anslutning, enligt beskrivningen senare i den här artikeln.

4. Skapa en custom keys anslutning för att lagra din API-nyckel.

   1. Gå till Azure AI Foundry-portalen och välj AI-projektet. Välj anslutna resurser.

   2. Välj + ny anslutning på inställningssidan.

      Anmärkning

      Om du återskapar API-nyckeln vid ett senare tillfälle måste du uppdatera anslutningen med den nya nyckeln.

      

   3. Välj anpassade nycklar i andra resurstyper.

      

   4. Ange följande information:

      • nyckel: name fältet i ditt säkerhetsschema. I det här exemplet bör det vara x-api-key

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

      • värde: YOUR_API_KEY
      • Anslutningsnamn: YOUR_CONNECTION_NAME (Du använder det här anslutningsnamnet i exempelkoden nedan.)
      • Åtkomst: du kan välja antingen endast det här projektet eller delas till alla projekt. Se bara till att det projekt som du angav anslutningssträng för i exempelkoden nedan har åtkomst till den här anslutningen.

5. När du har skapat en anslutning kan du använda den via SDK eller REST API. Använd flikarna överst i den här artikeln om du vill se kodexempel.

Autentisera med hanterad identitet (Microsoft Entra-ID)

Microsoft Entra ID är en molnbaserad identitets- och åtkomsthanteringstjänst som dina anställda kan använda för att komma åt externa resurser. Med Microsoft Entra-ID kan du autentisera dina API:er med ytterligare säkerhet utan att behöva skicka in API-nycklar. När du har konfigurerat hanterad identitetsautentisering autentiseras den via den Azure AI-tjänst som din agent använder.

Så här konfigurerar du autentisering med hanterad identitet:

1. Se till att din Azure AI Foundry-resurs har systemtilldelad hanterad identitet aktiverad.

   

2. Skapa en resurs för den tjänst som du vill ansluta till via OpenAPI-specifikationen.

3. Tilldela rätt åtkomst till resursen.

   1. Klicka på Åtkomstkontroll för din resurs

   2. Klicka på Lägg till och lägg sedan till rolltilldelning överst på skärmen.

      

   3. Välj rätt rolltilldelning som behövs, vanligtvis kräver den minst READER-roll . Klicka sedan på Nästa.

   4. Välj Hanterad identitet och klicka sedan på Välj medlemmar.

   5. I listrutan hanterad identitet söker du efter Azure AI-tjänster och väljer sedan AI-tjänsten för din agent.

   6. Klicka på Finish.

4. När installationen är klar kan du fortsätta med verktyget via Azure AI Foundry-portalen, SDK eller REST API. Använd flikarna överst i den här artikeln för att se kodexempel.