Jak korzystać z usługi Foundry Agent z narzędziami określonymi w specyfikacji OpenAPI

Teraz możesz połączyć agenta usługi Azure AI z zewnętrznym interfejsem API przy użyciu określonego narzędzia OpenAPI 3.0, co umożliwia skalowalną współdziałanie z różnymi aplikacjami. Korzystając z tożsamości zarządzanych (Microsoft Entra ID) do uwierzytelniania, można bezpiecznie włączyć niestandardowe narzędzia do uwierzytelniania dostępu i połączeń. Takie podejście jest idealne do integracji z istniejącą infrastrukturą lub usługami internetowymi.

Narzędzie OpenAPI poprawia Twoje doświadczenie w wywoływaniu funkcji, zapewniając ustandaryzowane, zautomatyzowane i skalowalne integracje API, które zwiększają możliwości i wydajność Twojego agenta. Specyfikacje interfejsu OpenAPI zapewniają formalny standard opisujący interfejsy API HTTP. Ten standard pomaga ludziom zrozumieć, jak działa interfejs API, jak działa sekwencja interfejsów API i obsługuje generowanie kodu klienta, tworzenie testów, stosowanie standardów projektowych i nie tylko. Obecnie określone narzędzia openAPI 3.0 obsługują trzy typy uwierzytelniania: anonymous, API keyi managed identity.

Wsparcie użytkowania

Wymagania wstępne

1. Upewnij się, że spełnisz wymagania wstępne i kroki konfiguracji w przewodniku Szybki start.
2. Sprawdź specyfikację interfejsu OpenAPI pod kątem następujących wymogów.
   1. Chociaż specyfikacja OpenAPI tego nie wymaga, każda funkcja musi mieć operationId, aby działać z narzędziem OpenAPI.
   2. Element operationId powinien zawierać tylko litery, -i _. Można go zmodyfikować, aby spełnić to wymaganie. Użyj nazwy opisowej, aby ułatwić modelom efektywne decydowanie o tym, która funkcja ma być używana.

Uwierzytelnij za pomocą klucza API

Za pomocą uwierzytelniania klucza API można uwierzytelniać specyfikację OpenAPI różnymi metodami, takimi jak klucz API lub token dostępu. Każda specyfikacja interfejsu OpenAPI obsługuje tylko jeden schemat zabezpieczeń klucza interfejsu API. Jeśli potrzebujesz wielu schematów zabezpieczeń, utwórz wiele narzędzi specyfikacji interfejsu OpenAPI.

1. Zaktualizuj schematy zabezpieczeń specyfikacji interfejsu OpenAPI. Ma on sekcję securitySchemes i jeden schemat typu apiKey. Przykład:

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

   Zazwyczaj wystarczy zaktualizować name pole, które odpowiada nazwie key w połączeniu. Jeśli schematy zabezpieczeń zawierają wiele schematów, zachowaj tylko jeden z nich.

2. Zaktualizuj specyfikację interfejsu OpenAPI, aby uwzględnić sekcję security :

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

3. Usuń dowolny parametr w specyfikacji interfejsu OpenAPI, który wymaga klucza interfejsu API, ponieważ klucz interfejsu API jest przechowywany i przekazywany przez połączenie, zgodnie z opisem w dalszej części tego artykułu.

4. Utwórz połączenie custom keys, aby przechować klucz API.

   1. Przejdź do portalu Microsoft Foundry i wybierz pozycję Centrum zarządzania w okienku nawigacji po lewej stronie.

      

   2. Wybierz pozycję Połączone zasoby w obszarze projektu sztucznej inteligencji w okienku nawigacji po lewej stronie.

   3. Wybierz pozycję + nowe połączenie na stronie ustawień.

      Uwaga / Notatka

      W przypadku ponownego wygenerowania klucza interfejsu API w późniejszym terminie należy zaktualizować połączenie przy użyciu nowego klucza.

      

   4. Wybierz niestandardowe klucze w innych typach zasobów.

      

   5. Wprowadź następujące informacje

      • key: name pole schematu zabezpieczeń. W tym przykładzie powinno to być x-api-key

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

      • wartość: YOUR_API_KEY

      • Nazwa połączenia: YOUR_CONNECTION_NAME (użyj tej nazwy połączenia w poniższym przykładowym kodzie).

      • Dostęp: możesz wybrać tylko ten projekt lub udostępnić go wszystkim projektom. Upewnij się, że w poniższym przykładowym kodzie projekt, dla którego wprowadzono łańcuch połączenia, ma dostęp do tego połączenia.

5. Po utworzeniu połączenia użyj go za pomocą zestawu SDK lub interfejsu API REST. Użyj kart w górnej części tego artykułu, aby wyświetlić przykłady kodu.

Uwierzytelnianie przy użyciu tożsamości zarządzanej (Microsoft Entra ID)

Microsoft Entra ID to oparta na chmurze usługa zarządzania tożsamościami i dostępem, która umożliwia pracownikom uzyskiwanie dostępu do zasobów zewnętrznych. Korzystając z identyfikatora Entra firmy Microsoft, możesz dodać dodatkowe zabezpieczenia podczas uwierzytelniania interfejsów API bez konieczności używania kluczy interfejsu API. Po skonfigurowaniu uwierzytelniania tożsamości zarządzanej narzędzie Foundry używane przez agenta zarządza uwierzytelnianiem.

Podczas konfigurowania uwierzytelniania tożsamości zarządzanej należy podać wartość Audience. Publiczność to identyfikator zasobów OAuth2 (nazywany również identyfikatorem URI zakresu lub identyfikatora aplikacji), który określa, do którego interfejsu API lub której usługi zarządzana tożsamość może uzyskać dostęp.

Typowe wartości odbiorców:

• Foundry Tools (dawniej Azure AI Services lub Cognitive Services): https://cognitiveservices.azure.com/
• Interfejsy API usługi Azure Resource Manager: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• Niestandardowe interfejsy API zarejestrowane w Microsoft Entra ID: użyj identyfikatora URI aplikacji znalezionego w rejestracji tej aplikacji.

Aby skonfigurować uwierzytelnianie przy użyciu tożsamości zarządzanej:

1. Upewnij się, że zasób usługi Foundry ma włączoną tożsamość zarządzaną przypisaną przez system.

   

2. Utwórz zasób dla usługi, do której chcesz się podłączyć za pomocą specyfikacji OpenAPI.

3. Przypisz odpowiedni dostęp do zasobu.

   1. Wybierz pozycję Kontrola dostępu dla zasobu.

   2. Wybierz pozycję Dodaj , a następnie dodaj przypisanie roli w górnej części ekranu.

      

   3. Wybierz wymagane odpowiednie przypisanie roli. Zazwyczaj wymaga co najmniej roli CZYTELNIK. Następnie wybierz Dalej.

   4. Wybierz pozycję Tożsamość zarządzana , a następnie wybierz pozycję Członkowie.

   5. W menu rozwijanym tożsamości zarządzanej wyszukaj pozycję Narzędzia Foundry a następnie wybierz narzędzie Foundry agenta.

   6. Wybierz Zakończ

4. Po zakończeniu instalacji możesz użyć narzędzia za pomocą portalu Foundry, zestawu SDK lub interfejsu API REST. Użyj zakładek w górnej części tego artykułu, aby wyświetlić przykłady kodu.