Verwenden des Foundry-Agent-Diensts mit den angegebenen OpenAPI-Tools

Sie können jetzt Ihren Azure AI-Agent mit einer externen API verbinden, indem Sie ein angegebenes OpenAPI 3.0-Tool verwenden und so eine skalierbare Interoperabilität mit verschiedenen Anwendungen ermöglichen. Mithilfe von verwalteten Identitäten (Microsoft Entra ID) für die Authentifizierung können Sie Ihre benutzerdefinierten Tools sicher aktivieren, um Den Zugriff und Verbindungen zu authentifizieren. Dieser Ansatz eignet sich ideal für die Integration in vorhandene Infrastruktur oder Webdienste.

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. Dieser Standard hilft Benutzern zu verstehen, wie eine API funktioniert, wie eine Sequenz von APIs zusammenarbeitet und unterstützt das Generieren von Clientcode, das Erstellen von Tests, das Anwenden von Designstandards und vieles mehr. Derzeit unterstützen die angegebenen OpenAPI 3.0-Tools drei Authentifizierungstypen: anonymous, , API keyund managed identity.

Nutzungssupport

Voraussetzungen

1. Stellen Sie sicher, dass Sie die erforderlichen Voraussetzungen und Setup-Schritte in der Schnellstartanleitung ausführen.
2. Überprüfen Sie die OpenAPI-Spezifikation auf die folgenden Anforderungen:
   1. Obwohl für die OpenAPI-Spezifikation nicht erforderlich, muss jede Funktion über eine operationId Funktion verfügen, um mit dem OpenAPI-Tool zu arbeiten.
   2. Dies operationId sollte nur Buchstaben, - und _ enthalten. Sie können sie ändern, um diese Anforderung zu erfüllen. Verwenden Sie einen beschreibenden Namen, damit Modelle effizient entscheiden können, welche Funktion verwendet werden soll.

Authentifizieren mit einem API-Schlüssel

Mithilfe der API-Schlüsselauthentifizierung können Sie Ihre OpenAPI-Spezifikation über verschiedene Methoden wie einen API-Schlüssel oder Bearertoken authentifizieren. Jede OpenAPI-Spezifikation unterstützt nur ein API-Schlüsselsicherheitsschema. Wenn Sie mehrere Sicherheitsschemas benötigen, erstellen Sie mehrere OpenAPI-Spezifikationstools.

1. Aktualisieren Sie Ihre OpenAPI-Spezifikationssicherheitsschemas. Es verfügt über einen securitySchemes Abschnitt und ein Schema vom Typ apiKey. Beispiel:

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

   Normalerweise müssen Sie das name Feld nur aktualisieren, das dem Namen der key Verbindung entspricht. Wenn die Sicherheitsschemas mehrere Schemas enthalten, behalten Sie nur eines davon bei.

2. Aktualisieren Sie Ihre OpenAPI-Spezifikation so, dass sie einen security Abschnitt enthält:

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

3. 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.

4. Erstellen Sie eine custom keys-Verbindung, um Ihren API-Schlüssel zu speichern.

   1. Wechseln Sie zum Microsoft Foundry-Portal , und wählen Sie im linken Navigationsbereich das Verwaltungscenter aus.

      

   2. Wählen Sie verbundene Ressourcen unter dem KI-Projekt im linken Navigationsbereich aus.

   3. 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.

      

   4. Wählen Sie benutzerdefinierte Schlüssel in andere Ressourcentypen aus.

      

   5. Geben Sie die folgenden Informationen ein:

      • Schlüssel: name Feld 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: YOUR_CONNECTION_NAME (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.

5. Nachdem Sie eine Verbindung erstellt haben, verwenden Sie sie über das SDK oder die REST-API. Verwenden Sie die Registerkarten oben in diesem Artikel, um Codebeispiele anzuzeigen.

Authentifizieren mit verwalteter Identität (Microsoft Entra-ID)

Microsoft Entra ID ist ein cloudbasierter Identitäts- und Zugriffsverwaltungsdienst, den Ihre Mitarbeiter für den Zugriff auf externe Ressourcen verwenden können. Mithilfe der Microsoft Entra-ID können Sie zusätzliche Sicherheit hinzufügen, wenn Sie Ihre APIs authentifizieren, ohne API-Schlüssel verwenden zu müssen. Nachdem Sie die verwaltete Identitätsauthentifizierung eingerichtet haben, übernimmt das Foundry Tool, das Ihr Agent verwendet, die Authentifizierung.

Beim Konfigurieren der verwalteten Identitätsauthentifizierung müssen Sie einen Zielgruppenwert angeben. Die Zielgruppe ist der OAuth2-Ressourcenbezeichner (auch als Bereichs- oder Anwendungs-ID-URI bezeichnet), der angibt, auf welche API oder welchen Dienst die verwaltete Identität zugreifen kann.

Allgemeine Benutzergruppenwerte:

• Foundry Tools (ehemals Azure AI-Dienste oder Cognitive Services): https://cognitiveservices.azure.com/
• Azure Resource Manager-APIs: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• Benutzerdefinierte APIs, die in der Microsoft Entra-ID registriert sind: Verwenden Sie den Anwendungs-ID-URI , der in der App-Registrierung der API gefunden wurde.

So richten Sie die Authentifizierung mithilfe von verwalteter Identität ein:

1. Stellen Sie sicher, dass ihre Foundry-Ressource eine vom System zugewiesene verwaltete Identität aktiviert hat.

   

2. Erstellen Sie eine Ressource für den Dienst, mit dem Sie über die OpenAPI-Spezifikation eine Verbindung herstellen möchten.

3. Weisen Sie den richtigen Zugriff auf die Ressource zu.

   1. Wählen Sie die Zugriffssteuerung für Ihre Ressource aus.

   2. Wählen Sie "Hinzufügen" aus, und fügen Sie dann die Rollenzuweisung am oberen Rand des Bildschirms hinzu.

      

   3. Wählen Sie die richtige Rollenzuweisung aus. In der Regel ist mindestens die READER-Rolle erforderlich. Wählen Sie dann Weiter aus.

   4. Wählen Sie verwaltete Identität und dann Mitglieder auswählen.

   5. Suchen Sie im Dropdownmenü verwalteter Identität nach Foundry Tools , und wählen Sie dann das Foundry Tool Ihres Agents aus.

   6. Wählen Sie "Fertig stellen" aus.

4. Nachdem Sie das Setup abgeschlossen haben, können Sie das Tool über das Foundry-Portal, das SDK oder die REST-API verwenden. Verwenden Sie die Registerkarten oben in diesem Artikel, um Codebeispiele anzuzeigen.