Udostępnij za pośrednictwem

Jak używać usługi Azure AI Agent z określonymi narzędziami OpenAPI

  • Artykuł

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 skalowalne współdziałanie z różnymi aplikacjami. Umożliwianie niestandardowym narzędziom uwierzytelniania dostępu i połączeń za pomocą tożsamości zarządzanych (Microsoft Entra ID) w celu zwiększenia bezpieczeństwa, dzięki czemu jest idealnym rozwiązaniem do integracji z istniejącą infrastrukturą lub usługami internetowymi.

Narzędzie openAPI Określone narzędzie ulepsza środowisko wywoływania funkcji, zapewniając ustandaryzowane, zautomatyzowane i skalowalne integracje interfejsu API, które zwiększają możliwości i wydajność agenta. Specyfikacje interfejsu OpenAPI zapewniają formalny standard opisujący interfejsy API HTTP. Dzięki temu użytkownicy mogą zrozumieć, jak działa interfejs API, jak działa sekwencja interfejsów API, generować kod klienta, tworzyć testy, stosować standardy projektowania i nie tylko. Obecnie obsługujemy 3 typy uwierzytelniania z określonymi narzędziami interfejsu OpenAPI 3.0: anonymous, , API keymanaged identity.

Obsługa użycia

Pomoc techniczna dotycząca znajdowania sztucznej inteligencji platformy Azure Zestaw SDK dla języka Python Zestaw SDK języka C# Interfejs API REST Konfiguracja agenta podstawowego Konfiguracja agenta standardowego
✔️ ✔️ ✔️ ✔️ ✔️

Wymagania wstępne

  1. Upewnij się, że zostały spełnione wymagania wstępne i kroki konfiguracji w przewodniku Szybki start.

  2. Sprawdź specyfikację interfejsu OpenAPI, aby uzyskać następujące wymagania:

    1. operationId powinna zawierać tylko litery - i _. Można go zmodyfikować w celu spełnienia wymagań. Zalecamy użycie nazwy opisowej, aby ułatwić modelom efektywne decydowanie o tym, która funkcja ma być używana.

Uwierzytelnianie przy użyciu klucza interfejsu API

  1. Sprawdź, czy specyfikacja interfejsu OpenAPI obsługuje klucze interfejsu API: zawiera securitySchemes sekcję i ma jeden schemat typu apiKey. Na przykład:

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

    Jeśli schematy zabezpieczeń zawierają wiele schematów, zalecamy przechowywanie tylko jednego z nich.

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

  3. Utwórz połączenie do custom keys przechowywania klucza interfejsu API.

    1. Przejdź do portalu usługi Azure AI Foundry i wybierz projekt sztucznej inteligencji. Kliknij pozycję Połączone zasoby. Zrzut ekranu przedstawiający przycisk ustawień projektu sztucznej inteligencji.

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

      Uwaga

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

      Zrzut ekranu przedstawiający ekran połączeń dla projektu sztucznej inteligencji.

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

      Zrzut ekranu przedstawiający wybór kluczy niestandardowych dla projektu sztucznej inteligencji.

    4. Wprowadź następujące informacje

      • klucz: name schemat 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żyjesz 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 wprowadzony parametry połączenia ma dostęp do tego połączenia.

Krok 1. Tworzenie klienta projektu

Utwórz obiekt klienta, który będzie zawierać parametry połączenia na potrzeby nawiązywania połączenia z projektem sztucznej inteligencji i innymi zasobami.

import os
import jsonref
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails


# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

Krok 2. Tworzenie definicji narzędzia Specyfikacji interfejsu OpenAPI

Możesz zapisać specyfikację interfejsu OpenAPI w innym pliku i zaimportować zawartość w celu zainicjowania narzędzia. Zwróć uwagę, że przykładowy kod jest używany anonymous jako typ uwierzytelniania.

with open('./weather_openapi.json', 'r') as f:
    openapi_spec = jsonref.loads(f.read())

# Create Auth object for the OpenApiTool (note that connection or managed identity auth setup requires additional setup in Azure)
auth = OpenApiAnonymousAuthDetails()

# Initialize agent OpenAPI tool using the read in OpenAPI spec
openapi = OpenApiTool(name="get_weather", spec=openapi_spec, description="Retrieve weather information for a location", auth=auth)

Jeśli chcesz użyć połączenia, które przechowuje klucz interfejsu API, na potrzeby uwierzytelniania zastąp wiersz ciągiem

auth = OpenApiConnectionAuthDetails(security_scheme=OpenApiConnectionSecurityScheme(connection_id="your_connection_id"))

Identyfikator połączenia wygląda następująco: /subscriptions/{subscription ID}/resourceGroups/{resource group name}/providers/Microsoft.MachineLearningServices/workspaces/{project name}/connections/{connection name}.

Jeśli chcesz użyć tożsamości zarządzanej do uwierzytelniania, zastąp wiersz ciągiem

auth = OpenApiManagedAuthDetails(security_scheme=OpenApiManagedSecurityScheme(audience="https://your_identity_scope.com"))

Przykładem odbiorców będzie https://cognitiveservices.azure.com/.

Krok 3. Tworzenie agenta i wątku

# Create agent with OpenAPI tool and process assistant run
with project_client:
    agent = project_client.agents.create_agent(
        model="gpt-4o",
        name="my-assistant",
        instructions="You are a helpful assistant",
        tools=openapi.definitions
    )
    print(f"Created agent, ID: {agent.id}")

    # Create thread for communication
    thread = project_client.agents.create_thread()
    print(f"Created thread, ID: {thread.id}")

Krok 4. Tworzenie przebiegu i sprawdzanie danych wyjściowych

Utwórz przebieg i zwróć uwagę, że model używa narzędzia Specyfikacji interfejsu OpenAPI w celu udzielenia odpowiedzi na pytanie użytkownika.

# Create message to thread
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="What's the weather in Seattle?",
    )
    print(f"Created message, ID: {message.id}")

    # Create and process agent run in thread with tools
    run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
    print(f"Run finished with status: {run.status}")

    if run.status == "failed":
        print(f"Run failed: {run.last_error}")

    # Delete the assistant when done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

    # Fetch and log all messages
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")