Verwenden des Azure KI-Agentdiensts mit OpenAPI-spezifizierten Tools

Artikel
12/23/2024

Sie können jetzt Ihren Azure AI-Agent mit einer externen API verbinden, indem Sie ein angegebenes OpenAPI 3.0-Tool verwenden, was eine skalierbare Interoperabilität mit verschiedenen Anwendungen ermöglicht. Ermöglichen Sie Ihren benutzerdefinierten Tools die Authentifizierung von Zugriff und Verbindungen mit verwalteten Identitäten (Microsoft Entra ID) für zusätzliche Sicherheit, sodass sie ideal für die Integration in vorhandene Infrastruktur oder Webdienste geeignet ist.

Das OpenAPI-spezifizierte Tool verbessert Ihre Funktionsaufruferfahrung, indem standardisierte, automatisierte und skalierbare API-Integrationen bereitgestellt werden, die die Funktionen und Effizienz Ihres Agents verbessern. OpenAPI-Spezifikationen stellen einen formalen Standard für die Beschreibung von HTTP-APIs bereit. Auf diese Weise können Benutzer verstehen, wie eine API funktioniert, wie eine Sequenz von APIs zusammenarbeiten, Clientcode generieren, Tests erstellen, Designstandards anwenden und vieles mehr. Derzeit unterstützen wir 3 Authentifizierungstypen mit den angegebenen OpenAPI 3.0-Tools: anonymous, API key, managed identity.

Voraussetzungen

Stellen Sie sicher, dass Sie die Voraussetzungen und Setupschritte in der Schnellstartanleitung abgeschlossen haben.
Überprüfen Sie die OpenAPI-Spezifikationen auf folgende Anforderungen für dieses Feature:
1. operationId sollte nur Buchstaben, - und _ enthalten. Sie können ihn ändern, um die Anforderung zu erfüllen. Es wird empfohlen, beschreibende Namen zu verwenden, um Modelle effizient zu entscheiden, welche Funktion verwendet werden soll.

Authentifizieren mit API-Schlüssel

Stellen Sie sicher, dass die OpenAPI-Spezifikation API-Schlüssel unterstützt: Sie verfügt über securitySchemes Abschnitt und weist ein Schema vom Typ „apiKey” auf. Beispiel:
```
    "securitySchemes": {
       "apiKeyHeader": {
                 "type": "apiKey",
                 "name": "x-api-key",
                 "in": "header"
             }
     }
```
Wenn die Sicherheitsschemas mehrere Schemas enthalten, empfehlen wir, nur eines davon beizubehalten.
Entfernen Sie alle Parameter in der OpenAPI-Spezifikation, die API-Schlüssel benötigt, da der API-Schlüssel gespeichert und über eine Verbindung übergeben wird, wie weiter unten in diesem Artikel beschrieben.
Erstellen Sie eine custom keys-Verbindung, um Ihren API-Schlüssel zu speichern.
1. Navigieren Sie zum Azure KI Foundry-Portal, und wählen Sie das KI-Projekt aus. Klicken Sie auf Ressourcen verbinden.
2. Wählen Sie auf der Seite „Einstellungen” + neue Verbindung aus.
  
  Hinweis
  
  Wenn Sie den API-Schlüssel zu einem späteren Zeitpunkt erneut generieren, müssen Sie die Verbindung mit dem neuen Schlüssel aktualisieren.
3. Wählen Sie benutzerdefinierte Schlüssel in andere Ressourcentypen aus.
4. Geben Sie die folgenden Informationen ein
  - Schlüssel: name Ihres Sicherheitsschemas. In diesem Beispiel sollte er x-api-key sein.
```
       "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
```
  - Wert: IHR_API_SCHLÜSSEL
  - Verbindungsname: IHR_VERBINDUNGSNAME (Sie verwenden diesen Verbindungsnamen im folgenden Beispielcode.)
  - Zugriff: Sie können entweder nur dieses Projekt oder für alle Projekte freigegeben auswählen. Stellen Sie einfach im folgenden Beispielcode sicher, dass das Projekt, für das Sie die Verbindungszeichenfolge eingegeben haben, Zugriff auf diese Verbindung hat.

Schritt 1: Erstellen eines Agents mit dem OpenAPI Spec-Tool

Erstellen Sie ein Clientobjekt, das die Verbindungszeichenfolge zum Herstellen einer Verbindung mit Ihrem KI-Projekt und anderen Ressourcen enthält.

Python
C#

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"],
)

using System;
using System.Collections.Generic;
using System.IO;
using System.Runtime.CompilerServices;
using System.Text.Json.Serialization;
using System.Text.Json;
using System.Threading.Tasks;
using Azure.Core.TestFramework;
using NUnit.Framework;
using Newtonsoft.Json.Linq;

namespace Azure.AI.Projects.Tests;

public partial class Sample_Agent_OpenAPI : SamplesBase<AIProjectsTestEnvironment>
{
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "weather_openapi.json");
    }

    [Test]
    public async Task OpenAPICallingExample()
    {
        var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
        var storageQueueUri = TestEnvironment.STORAGE_QUEUE_URI;
        AgentsClient client = new(connectionString, new DefaultAzureCredential());
        var file_path = GetFile();

Schritt 2: Aktivieren des OpenAPI Spec-Tools

Möglicherweise möchten Sie die OpenAPI-Spezifikation in einer anderen Datei speichern und den Inhalt importieren, um das Tool zu initialisieren. Bitte beachten Sie, dass der Beispielcode anonymous als Authentifizierungstyp verwendet.

Python
C#

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)

Wenn Sie eine Verbindung verwenden möchten, die den API-Schlüssel für die Authentifizierung speichert, ersetzen Sie die Zeile durch

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

Ihre Verbindungs-ID sieht wie /subscriptions/{subscription ID}/resourceGroups/{resource group name}/providers/Microsoft.MachineLearningServices/workspaces/{project name}/connections/{connection name} aus.

Wenn Sie verwaltete Identität für die Authentifizierung verwenden möchten, ersetzen Sie die Zeile durch

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

Ein Beispiel für die Zielgruppe wäre https://cognitiveservices.azure.com/.

    #region Snippet:OpenAPIDefineFunctionTools
    OpenApiAnonymousAuthDetails oaiAuth = new();
    OpenApiToolDefinition openapiTool = new(
        name: "get_weather",
        description: "Retrieve weather information for a location",
        spec: BinaryData.FromBytes(File.ReadAllBytes(file_path)),
        auth: oaiAuth
    );

# Create agent with OpenAPI tool and process assistant run
with project_client:
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        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}")

Response<Agent> agentResponse = await client.CreateAgentAsync(
            model: "gpt-4",
            name: "azure-function-agent-foo",
            instructions: "You are a helpful assistant.",
            tools: new List<ToolDefinition> { openapiTool }
            );
Agent agent = agentResponse.Value;
#endregion
Response<AgentThread> threadResponse = await client.CreateThreadAsync();
AgentThread thread = threadResponse.Value;

Schritt 4: Erstellen einer Ausführung und Überprüfen der Ausgabe

Wenn Sie eine Ausführung erstellen, können Sie beobachten, dass das Modell das OpenAPI Spec-Tool verwendet, um eine Antwort auf die Frage des Benutzers bereitzustellen.

Python
C#

# 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}")

        #region Snippet:OpenAPIHandlePollingWithRequiredAction
        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
            thread.Id,
            MessageRole.User,
            "What's the weather in Seattle?");
        ThreadMessage message = messageResponse.Value;

        Response<ThreadRun> runResponse = await client.CreateRunAsync(thread, agent);

        do
        {
            await Task.Delay(TimeSpan.FromMilliseconds(500));
            runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
        }
        while (runResponse.Value.Status == RunStatus.Queued
            || runResponse.Value.Status == RunStatus.InProgress
            || runResponse.Value.Status == RunStatus.RequiresAction);
        #endregion

        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
            = await client.GetMessagesAsync(thread.Id);
        IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

        // Note: messages iterate from newest to oldest, with the messages[0] being the most recent
        foreach (ThreadMessage threadMessage in messages)
        {
            Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
            foreach (MessageContent contentItem in threadMessage.ContentItems)
            {
                if (contentItem is MessageTextContent textItem)
                {
                    Console.Write(textItem.Text);
                }
                else if (contentItem is MessageImageFileContent imageFileItem)
                {
                    Console.Write($"<image from ID: {imageFileItem.FileId}");
                }
                Console.WriteLine();
            }
        }

Freigeben über