Freigeben über

Verbinden von Agents mit OpenAPI-Tools

Verbinden Sie Ihre Microsoft Foundry-Agents mit externen APIs mithilfe von OpenAPI 3.0-Spezifikationen. Agents, die eine Verbindung mit OpenAPI-Tools herstellen, können externe Dienste aufrufen, Echtzeitdaten abrufen und ihre Funktionen über integrierte Funktionen hinaus erweitern.

OpenAPI-Spezifikationen definieren eine Standardmethode zum Beschreiben von HTTP-APIs, damit Sie vorhandene Dienste in Ihre Agents integrieren können. Microsoft Foundry unterstützt drei Authentifizierungsmethoden: anonymous, , API keyund managed identity. Hilfe zum Auswählen einer Authentifizierungsmethode finden Sie unter Auswählen einer Authentifizierungsmethode.

Nutzungssupport

✔️ (GA) gibt die allgemeine Verfügbarkeit an, ✔️ (Vorschau) gibt die öffentliche Vorschau an, und ein Gedankenstrich (-) gibt an, dass das Feature nicht verfügbar ist.

Microsoft Foundry-Support Python SDK C# SDK JavaScript SDK Java-SDK REST API Basic-Agent-Setup Standard-Agent-Setup
✔️ ✔️ (Vorschau) ✔️ (Vorschau) ✔️ (Vorschau) ✔️ (Vorschau) ✔️ (GA) ✔️ ✔️

Hinweis

Verwenden Sie für Java das com.azure:azure-ai-agents Paket für OpenAPI-Agenttools. Das com.azure:azure-ai-projects Paket macht derzeit keine OpenAPI-Agent-Tooltypen verfügbar.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie folgendes haben:

  • Ein Azure-Abonnement mit den richtigen Berechtigungen.
  • Azure RBAC-Rolle: Mitwirkender oder Besitzer im Foundry-Projekt.
  • Ein Foundry-Projekt, das mit einem konfigurierten Endpunkt erstellt wurde.
  • Ein KI-Modell, das in Ihrem Projekt bereitgestellt wird.
  • Eine grundlegende oder Standard-Agent-Umgebung.
  • SDK für Ihre bevorzugte Sprache installiert:
    • Python: azure-ai-projects (neueste Vorabversion)
    • C#: Azure.AI.Projects.OpenAI
    • TypeScript/JavaScript: @azure/ai-projects
    • Java: com.azure:azure-ai-agents

Umgebungsvariablen

Variable Description
FOUNDRY_PROJECT_ENDPOINT Die URL des Foundry-Projekt-Endpunkts (nicht des externen OpenAPI-Dienstendpunkts).
FOUNDRY_MODEL_DEPLOYMENT_NAME Der Name des bereitgestellten Modells.
OPENAPI_PROJECT_CONNECTION_NAME (Für API-Schlüsselauthentifizierung) Der Projektverbindungsname für den OpenAPI-Dienst.
  • OpenAPI 3.0-Spezifikationsdatei, die diese Anforderungen erfüllt:
    • Jede Funktion muss ein operationId enthalten (erforderlich für das OpenAPI-Tool).
    • operationId darf nur Buchstaben, - und _ enthalten.
    • Verwenden Sie beschreibende Namen, um Modelle effizient zu bestimmen, welche Funktion sie verwenden sollen.
    • Unterstützter Inhaltstyp: "application/json", "application/json-patch+json"
  • Für die verwaltete Identitätsauthentifizierung: Leserolle oder höher für Zieldienstressourcen.
  • Für die API-Schlüssel-/Tokenauthentifizierung: eine Projektverbindung, die mit Ihrem API-Schlüssel oder -Token konfiguriert ist. Siehe Hinzufügen einer neuen Verbindung zu Ihrem Projekt.

Hinweis

Der FOUNDRY_PROJECT_ENDPOINT Wert bezieht sich auf Ihren Microsoft Foundry-Projektendpunkt, nicht auf den externen OpenAPI-Dienstendpunkt. Sie finden diesen Endpunkt im Microsoft Foundry-Portal auf der Seite "Übersicht" Ihres Projekts. Dieser Endpunkt ist erforderlich, um den Agentdienst zu authentifizieren und ist von allen openAPI-Endpunkten getrennt, die in Ihrer Spezifikationsdatei definiert sind.

Verstehen Sie die Einschränkungen

  • Ihre OpenAPI-Spezifikation muss operationId für jede Operation enthalten, und operationId darf nur Buchstaben, - und _ enthalten.
  • Unterstützte Inhaltstypen: application/json, application/json-patch+json.
  • Verwenden Sie für die API-Schlüsselauthentifizierung ein API-Schlüsselsicherheitsschema pro OpenAPI-Tool. Wenn Sie mehrere Sicherheitsschemas benötigen, erstellen Sie mehrere OpenAPI-Tools.

Code-Beispiel

Hinweis

  • Sie benötigen das neueste Vorabpaket. Details finden Sie in der Schnellstartanleitung .
  • Wenn Sie den API-Schlüssel für die Authentifizierung verwenden, sollte Ihre Verbindungs-ID im Format /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}} sein.

Von Bedeutung

Damit die API-Schlüsselauthentifizierung funktioniert, muss Ihre OpenAPI-Spezifikationsdatei Folgendes enthalten:

  1. Ein securitySchemes Abschnitt mit Ihrer API-Schlüsselkonfiguration, z. B. den Headernamen und den Parameternamen.
  2. Ein security Abschnitt, der auf das Sicherheitsschema verweist.
  3. Eine Projektverbindung, die mit dem übereinstimmenden Schlüsselnamen und -wert konfiguriert ist.

Ohne diese Konfigurationen ist der API-Schlüssel nicht in Anforderungen enthalten. Ausführliche Einrichtungsanweisungen finden Sie im Abschnitt " Authentifizieren mit API-Schlüssel ".

Sie können auch die tokenbasierte Authentifizierung (z. B. ein Bearertoken) verwenden, indem Sie das Token in einer Projektverbindung speichern. Erstellen Sie für die Bearer-Tokenauthentifizierung eine Verbindung mit benutzerdefinierten Schlüsseln, wobei der Schlüssel auf Authorization und der Wert auf Bearer <token> festgelegt sind (ersetzen Sie <token> durch das tatsächliche Token). Das Wort Bearer gefolgt von einem Leerzeichen muss in den Wert eingeschlossen werden. Ausführliche Informationen finden Sie unter Einrichten einer Bearer-Tokenverbindung.

Schnelle Überprüfung

Überprüfen Sie zunächst, ob Ihre Umgebung ordnungsgemäß konfiguriert ist:

# Verify authentication and project connection
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with DefaultAzureCredential() as credential, \
     AIProjectClient(endpoint=endpoint, credential=credential) as project_client:
    print(f"Successfully connected to project")

Wenn dieser Befehl ohne Fehler ausgeführt wird, können Sie einen Agent mit OpenAPI-Tools erstellen.

Vollständiges Beispiel

# Import required libraries
import os
import jsonref
from dotenv import load_dotenv
from typing import Any, cast
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):

    weather_asset_file_path = os.path.abspath(os.path.join(os.path.dirname(__file__), "../assets/weather_openapi.json"))

    with open(weather_asset_file_path, "r") as f:
        openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))

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

    # If you want to use key-based authentication
    # IMPORTANT: Your OpenAPI spec must include securitySchemes and security sections
    # Example spec structure for API key auth:
    # {
    #   "components": {
    #     "securitySchemes": {
    #       "apiKeyHeader": {
    #         "type": "apiKey",
    #         "name": "x-api-key",  # This must match the key name in your project connection
    #         "in": "header"
    #       }
    #     }
    #   },
    #   "security": [{"apiKeyHeader": []}]
    # }
    #
    # For Bearer token authentication, use this securitySchemes structure instead:
    # {
    #   "components": {
    #     "securitySchemes": {
    #       "bearerAuth": {
    #         "type": "apiKey",
    #         "name": "Authorization",
    #         "in": "header"
    #       }
    #     }
    #   },
    #   "security": [{"bearerAuth": []}]
    # }
    # Then set connection key = "Authorization" and value = "Bearer <token>"
    # The word "Bearer" followed by a space MUST be included in the value.

    openapi_connection = project_client.connections.get(os.environ["OPENAPI_PROJECT_CONNECTION_NAME"])
    connection_id = openapi_connection.id
    print(f"OpenAPI connection ID: {connection_id}")

    openapi_key_auth_tool={
        "type": "openapi",
        "openapi":{
            "name": "TOOL_NAME",
            "spec": SPEC_NAME,  # Must include securitySchemes and security sections
            "auth": {
                "type": "project_connection",
                "security_scheme": {
                    "project_connection_id": connection_id
                }
            },
        }
    }

    # If you want to use Managed Identity authentication
    openapi_mi_auth_tool={
        "type": "openapi",
        "openapi":{
            "name": "TOOL_NAME",
            "description": "",
            "spec": SPEC_NAME,
            "auth": {
                "type": "managed_identity",
                "security_scheme": {
                    "audience": ""  #audience to the service, such as https://ai.azure.com
                }
            },
        }
    }

    agent = project_client.agents.create_version(
        agent_name="MyAgent",
        definition=PromptAgentDefinition(
            model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
            instructions="You are a helpful assistant.",
            tools=[weather_tool],
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    response = openai_client.responses.create(
        input="What's the weather in Seattle?",
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    )
    print(f"Agent response: {response.output_text}")

    print("\nCleaning up...")
    project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

Funktionsweise dieses Codes

In diesem Beispiel wird ein Agent mit einem OpenAPI-Tool erstellt, das die wttr.in Wetter-API mithilfe der anonymen Authentifizierung aufruft. Wenn Sie den Code ausführen:

  1. Sie lädt die Wetter-OpenAPI-Spezifikation aus einer lokalen JSON-Datei.
  2. Erstellt einen Agent mit dem Wettertool, das für anonymen Zugriff konfiguriert ist.
  3. Sendet eine Abfrage, die nach Seattles Wetter fragt.
  4. Der Agent verwendet das OpenAPI-Tool, um die Wetter-API aufzurufen und formatierte Ergebnisse zurückgibt.
  5. Bereinigt durch Löschen der Agentversion.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • Lokale Datei: weather_openapi.json (OpenAPI-Spezifikation)

Erwartete Ausgabe

Agent created (id: asst_abc123, name: MyAgent23, version: 1)
Response created: The weather in Seattle is currently cloudy with a temperature of 52°F (11°C)...

Cleaning up...
Agent deleted

Häufige Fehler

  • FileNotFoundError: Die OpenAPI-Spezifikationsdatei wurde im angegebenen Pfad nicht gefunden.
  • KeyError: Fehlende erforderliche Umgebungsvariablen
  • AuthenticationError: Ungültige Anmeldeinformationen oder unzureichende Berechtigungen oder fehlende securitySchemes OpenAPI-Spezifikation für die API-Schlüsselauthentifizierung
  • Ungültiges operationId Format in der OpenAPI-Spezifikation verursacht Fehler bei der Toolregistrierung
  • API-Schlüssel nicht eingefügt: Überprüfen Sie, ob ihre OpenAPI-Spezifikation sowohl als securitySchemes auch security Abschnitte enthält und dass der Schlüsselname Ihrer Projektverbindung entspricht.

Beispiel für die Verwendung von Agents mit dem OpenAPI-Tool

In diesem Beispiel wird die Verwendung von Diensten veranschaulicht, die durch eine OpenAPI-Spezifikation mithilfe eines Agents beschrieben werden. Es verwendet den wttr.in-Dienst , um Wetter und seine Spezifikationsdatei weather_openapi.jsonzu erhalten. In diesem Beispiel werden synchrone Methoden der Azure AI Projects-Clientbibliothek verwendet. Ein Beispiel, das asynchrone Methoden verwendet, finden Sie im Beispiel im Azure SDK für .NET-Repository auf GitHub.

class OpenAPIDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "weather_openapi.json");
    }

    public static void Main()
    {
        // First, create an agent client and read the environment variables, which will be used in the next steps.
        var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
        var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

        // Create an Agent with `OpenAPIAgentTool` and anonymous authentication.
        string filePath = GetFile();
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "get_weather",
            spec: BinaryData.FromBytes(BinaryData.FromBytes(File.ReadAllBytes(filePath))),
            auth: new OpenAPIAnonymousAuthenticationDetails()
        );
        toolDefinition.Description = "Retrieve weather information for a location.";
        OpenAPITool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the weather in Seattle, WA.
        ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
        ResponseResult response = responseClient.CreateResponse(
                userInputText: "Use the OpenAPI tool to print out, what is the weather in Seattle, WA today."
            );
        Console.WriteLine(response.GetOutputText());

        // Finally, delete all the resources created in this sample.
        projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Funktionsweise dieses Codes

In diesem C#-Beispiel wird ein Agent mit einem OpenAPI-Tool erstellt, das Wetterinformationen aus wttr.in mithilfe der anonymen Authentifizierung abruft. Wenn Sie den Code ausführen:

  1. Sie liest die Wetter-OpenAPI-Spezifikation aus einer lokalen JSON-Datei.
  2. Erstellt einen Agent mit dem konfigurierten Wettertool.
  3. Sendet eine Anforderung, die über das OpenAPI-Tool nach Seattles Wetter fragt.
  4. Der Agent ruft die Wetter-API auf und gibt die Ergebnisse zurück.
  5. Wird bereinigt durch das Löschen des Agents.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • Lokale Datei: Assets/weather_openapi.json (OpenAPI-Spezifikation)

Erwartete Ausgabe

The weather in Seattle, WA today is cloudy with temperatures around 52°F...

Häufige Fehler

  • FileNotFoundException: OpenAPI-Spezifikationsdatei im Ordner "Assets" nicht gefunden
  • ArgumentNullException: Fehlende erforderliche Umgebungsvariablen
  • UnauthorizedAccessException: Ungültige Anmeldeinformationen oder unzureichende RBAC-Berechtigungen
  • API-Schlüssel nicht eingefügt: Überprüfen Sie, ob Ihre OpenAPI-Spezifikation sowohl securitySchemes (in components) als auch security Abschnitte mit übereinstimmenden Schemanamen enthält.

Beispiel für die Verwendung von Agents mit dem OpenAPI-Tool im Webdienst, für die Authentifizierung erforderlich ist

In diesem Beispiel verwenden Sie Dienste mit einer OpenAPI-Spezifikation, indem Sie den Agent in einem Szenario verwenden, das eine Authentifizierung erfordert. Sie verwenden die TripAdvisor-Spezifikation.

Der TripAdvisor-Dienst erfordert eine schlüsselbasierte Authentifizierung. Um eine Verbindung im Azure-Portal zu erstellen, öffnen Sie Microsoft Foundry, und wählen Sie im linken Bereich das Verwaltungscenter und dann "Verbundene Ressourcen" aus. Erstellen Sie schließlich eine neue Verbindung des Typs "Benutzerdefinierte Schlüssel" . Benennen Sie es tripadvisor , und fügen Sie ein Schlüsselwertpaar hinzu. Fügen Sie einen Schlüssel mit dem Namen key hinzu, und geben Sie den Wert Ihres TripAdvisor-Schlüssels ein.

class OpenAPIConnectedDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "tripadvisor_openapi.json");
    }

    public static void Main()
    {
        // First, we need to create agent client and read the environment variables, which will be used in the next steps.
        var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
        var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

        // Create an Agent with `OpenAPIAgentTool` and authentication by project connection security scheme.
        string filePath = GetFile();
        AIProjectConnection tripadvisorConnection = projectClient.Connections.GetConnection("tripadvisor");
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            spec: BinaryData.FromBytes(BinaryData.FromBytes(File.ReadAllBytes(filePath))),
            auth: new OpenAPIProjectConnectionAuthenticationDetails(new OpenAPIProjectConnectionSecurityScheme(
                projectConnectionId: tripadvisorConnection.Id
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        OpenAPITool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the hotels in France.
        // Test the Web service access before you run production scenarios.
        // It can be done by setting:
        // ToolChoice = ResponseToolChoice.CreateRequiredChoice()`
        // in the ResponseCreationOptions. This setting will
        // force Agent to use tool and will trigger the error if it is not accessible.
        ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
        CreateResponseOptions responseOptions = new()
        {
            ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
            InputItems =
            {
                ResponseItem.CreateUserMessageItem("Recommend me 5 top hotels in paris, France."),
            }
        };
        ResponseResult response = responseClient.CreateResponse(
            options: responseOptions
        );
        Console.WriteLine(response.GetOutputText());

        // Finally, delete all the resources we have created in this sample.
        projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
    }
}

Funktionsweise dieses Codes

In diesem C#-Beispiel wird die Verwendung eines OpenAPI-Tools mit API-Schlüsselauthentifizierung über eine Projektverbindung veranschaulicht. Wenn Sie den Code ausführen:

  1. Sie lädt die TripAdvisor OpenAPI-Spezifikation aus einer lokalen Datei.
  2. Ruft die tripadvisor Projektverbindung ab, die Ihren API-Schlüssel enthält.
  3. Erstellt einen Agenten mit dem TripAdvisor-Tool, der so konfiguriert ist, dass er die Verbindung für die Authentifizierung verwendet.
  4. Sendet eine Anfrage nach Hotelempfehlungen in Paris.
  5. Der Agent ruft die TripAdvisor-API mit Ihrem gespeicherten API-Schlüssel auf und gibt Ergebnisse zurück.
  6. Wird bereinigt durch das Löschen des Agents.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • Lokale Datei: Assets/tripadvisor_openapi.json
  • Projektverbindung: tripadvisor mit gültigem API-Schlüssel konfiguriert

Erwartete Ausgabe

Here are 5 top hotels in Paris, France:
1. Hotel Name - Rating: 4.5/5, Location: ...
2. Hotel Name - Rating: 4.4/5, Location: ...
...

Häufige Fehler

  • ConnectionNotFoundException: Es wurde keine Projektverbindung mit dem Namen tripadvisor gefunden.
  • AuthenticationException: Ungültiger API-Schlüssel in der Projektverbindung oder fehlende/falsche securitySchemes Konfiguration in openAPI-Spezifikation.
  • Tool nicht verwendet: Überprüfen Sie, ob ToolChoice = ResponseToolChoice.CreateRequiredChoice() die Verwendung des Tools erzwingt.
  • API-Schlüssel wird nicht an die API übergeben: Stellen Sie sicher, dass die OpenAPI-Spezifikation die richtigen Abschnitte konfiguriert hat.

Erstellen eines Java-Agents mit OpenAPI-Toolfunktionen

In diesem Java-Beispiel wird ein Agent mithilfe eines OpenAPI-Tools und einer lokalen OpenAPI 3.0-Spezifikationsdatei erstellt. Im Beispiel wird die anonyme Authentifizierung verwendet und ein öffentlicher API-Endpunkt aufgerufen.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.AgentsServiceVersion;
import com.azure.ai.agents.ConversationsClient;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.OpenApiAgentTool;
import com.azure.ai.agents.models.OpenApiAnonymousAuthDetails;
import com.azure.ai.agents.models.OpenApiFunctionDefinition;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.json.JsonProviders;
import com.azure.json.JsonReader;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;

public class OpenApiAgentJavaSample {
    public static void main(String[] args) throws Exception {
        String endpoint = System.getenv("FOUNDRY_PROJECT_ENDPOINT");
        if (endpoint == null || endpoint.isBlank()) {
            endpoint = System.getenv("PROJECT_ENDPOINT");
        }

        String model = System.getenv("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        if (model == null || model.isBlank()) {
            model = System.getenv("MODEL_DEPLOYMENT_NAME");
        }

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .endpoint(endpoint)
            .credential(new DefaultAzureCredentialBuilder().build())
            .serviceVersion(AgentsServiceVersion.V2025_11_15_PREVIEW);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();
        ConversationsClient conversationsClient = builder.buildConversationsClient();

        JsonReader reader = JsonProviders.createReader(Files.readAllBytes(Path.of("openapi_spec.json")));
        BinaryData spec = reader.getNullable(nonNullReader -> BinaryData.fromObject(nonNullReader.readUntyped()));

        OpenApiFunctionDefinition toolDefinition = new OpenApiFunctionDefinition(
            "httpbin_get",
            spec,
            new OpenApiAnonymousAuthDetails())
            .setDescription("Get request metadata from an OpenAPI endpoint.");

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition(model)
            .setInstructions("Use the OpenAPI tool for HTTP request metadata.")
            .setTools(Arrays.asList(new OpenApiAgentTool(toolDefinition)));

        AgentVersionDetails agentVersion = agentsClient.createAgentVersion("openapiValidationAgentJava", agentDefinition);
        System.out.println("Agent: " + agentVersion.getName() + ", version: " + agentVersion.getVersion());

        Conversation conversation = conversationsClient.getConversationService().create();
        conversationsClient.getConversationService().items().create(
            ItemCreateParams.builder()
                .conversationId(conversation.id())
                .addItem(EasyInputMessage.builder()
                    .role(EasyInputMessage.Role.USER)
                    .content("Use the OpenAPI tool and summarize the returned URL and origin in one sentence.")
                    .build())
                .build());

        try {
            AgentReference agentReference = new AgentReference(agentVersion.getName()).setVersion(agentVersion.getVersion());
            ResponseCreateParams.Builder options = ResponseCreateParams.builder().maxOutputTokens(300L);
            Response response = responsesClient.createWithAgentConversation(agentReference, conversation.id(), options);

            String text = response.output().stream()
                .filter(item -> item.isMessage())
                .map(item -> item.asMessage().content()
                    .get(item.asMessage().content().size() - 1)
                    .asOutputText()
                    .text())
                .reduce((first, second) -> second)
                .orElse("<no message output>");

            System.out.println("Status: " + response.status().map(Object::toString).orElse("unknown"));
            System.out.println("Response: " + text);
        } finally {
            agentsClient.deleteAgentVersion(agentVersion.getName(), agentVersion.getVersion());
            System.out.println("Agent deleted");
        }
    }
}

Funktionsweise dieses Codes

In diesem Java-Beispiel wird ein Agent mit einem OpenAPI-Werkzeug erstellt und eine Antwort im Gesprächsbereich ausgeführt.

  1. Lädt die OpenAPI-Spezifikation von openapi_spec.json.
  2. Erstellt eine Agent-Version mit OpenApiAgentTool.
  3. Erstellt eine Unterhaltung und fügt eine Benutzernachricht hinzu.
  4. Erstellt eine Antwort durch Übergeben von AgentReference und Konversations-ID.
  5. Bereinigt durch Löschen der Agentversion.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT (oder PROJECT_ENDPOINT) und FOUNDRY_MODEL_DEPLOYMENT_NAME (oder MODEL_DEPLOYMENT_NAME)
  • Lokale Datei: openapi_spec.json (OpenAPI 3.0-Spezifikation)

Erwartete Ausgabe

Agent: openapiValidationAgentJava, version: 1
Status: completed
Response: The API response reports URL ... and origin ...
Agent deleted

Häufige Fehler

  • Invalid OpenAPI specification: Analysieren Sie den OpenAPI-JSON in ein Objekt, bevor Sie es an OpenApiFunctionDefinition weitergeben.
  • Invalid conversation id: Erstellt eine Unterhaltung, und übergibt conversation.id() an createWithAgentConversation.
  • AuthenticationFailedException: Überprüfen, ob DefaultAzureCredential ein Token für Ihr angemeldetes Konto erhalten kann.

Die folgenden Beispiele zeigen, wie Sie ein OpenAPI-Tool mithilfe der REST-API aufrufen.

Anonyme Authentifizierung

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": { "type": "anonymous" },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

API-Schlüsselauthentifizierung (Projektverbindung)

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "project_connection",
            "security_scheme": {
              "project_connection_id": "'$WEATHER_APP_PROJECT_CONNECTION_ID'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            },
            "components": {
              "securitySchemes": {
                "apiKeyHeader": {
                  "type": "apiKey",
                  "name": "x-api-key",
                  "in": "header"
                }
              }
            },
            "security": [
              { "apiKeyHeader": [] }
            ]
          }
        }
      }
    ]
  }'

Authentifizierung der verwalteten Identität

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "managed_identity",
            "security_scheme": {
              "audience": "'$MANAGED_IDENTITY_AUDIENCE'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Funktionsweise dieses Codes

Dieses REST-API-Beispiel zeigt, wie Sie ein OpenAPI-Tool mit verschiedenen Authentifizierungsmethoden aufrufen. Die Anforderung:

  1. Sendet eine Abfrage an den Agenten, der nach Seattles Wetter fragt.
  2. Enthält die OpenAPI-Tooldefinition im Einklang mit der Wetter-API-Spezifikation.
  3. Zeigt drei Authentifizierungsoptionen (anonym, API-Schlüssel über Projektverbindung, verwaltete Identität) als kommentierte Alternativen an.
  4. Der Agent verwendet das Tool, um die Wetter-API aufzurufen und formatierte Ergebnisse zurückgibt.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
  • Für die Authentifizierung des API-Schlüssels: WEATHER_APP_PROJECT_CONNECTION_ID.
  • Für verwaltete Identitätsauthentifizierung: MANAGED_IDENTITY_AUDIENCE.
  • Inline OpenAPI-Spezifikation im Anforderungstext.

Erwartete Ausgabe

{
  "id": "resp_abc123",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "text",
          "text": "The weather in Seattle, WA today is cloudy with a temperature of 52°F (11°C)..."
        }
      ]
    }
  ]
}

Häufige Fehler

  • 401 Unauthorized: Ungültiger oder fehlender AGENT_TOKEN oder API-Schlüssel nicht eingefügt, da securitySchemes und security in Ihrer OpenAPI-Spezifikation fehlen.
  • 404 Not Found: Falscher Endpunkt- oder Modellbereitstellungsname
  • 400 Bad Request: Ungültige OpenAPI-Spezifikation oder ungültige Authentifizierungskonfiguration
  • API-Schlüssel nicht mit Anforderung gesendet: Überprüfen Sie, ob der components.securitySchemes Abschnitt in Ihrer OpenAPI-Spezifikation ordnungsgemäß konfiguriert ist (nicht leer) und dem Namen des Projektverbindungsschlüssels entspricht.

Erstellen eines Agents mit OpenAPI-Toolfunktionen

Im folgenden TypeScript-Codebeispiel wird veranschaulicht, wie Ein KI-Agent mit OpenAPI-Toolfunktionen mithilfe des OpenApiTool und synchronen Azure AI Projects-Clients erstellt wird. Der Agent kann externe APIs aufrufen, die von OpenAPI-Spezifikationen definiert sind. Eine JavaScript-Version dieses Beispiels finden Sie im Beispiel im Azure SDK für JavaScript-Repository auf GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  OpenApiTool,
  OpenApiFunctionDefinition,
  OpenApiAnonymousAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";
const weatherSpecPath = path.resolve(__dirname, "../assets", "weather_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createWeatherTool(spec: unknown): OpenApiTool {
  const auth: OpenApiAnonymousAuthDetails = { type: "anonymous" };
  const definition: OpenApiFunctionDefinition = {
    name: "get_weather",
    description: "Retrieve weather information for a location using wttr.in",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  console.log("Loading OpenAPI specifications from assets directory...");
  const weatherSpec = loadOpenApiSpec(weatherSpecPath);

  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await project.getOpenAIClient();

  console.log("Creating agent with OpenAPI tool...");

  const agent = await project.agents.createVersion("MyOpenApiAgent", {
    kind: "prompt",
    model: deploymentName,
    instructions:
      "You are a helpful assistant that can call external APIs defined by OpenAPI specs to answer user questions.",
    tools: [createWeatherTool(weatherSpec)],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  console.log("\nSending request to OpenAPI-enabled agent with streaming...");
  const streamResponse = await openAIClient.responses.create(
    {
      input:
        "What's the weather in Seattle and how should I plan my outfit for the day based on the forecast?",
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      const item = event.item as any;
      if (item.type === "message") {
        const content = item.content?.[item.content.length - 1];
        if (content?.type === "output_text" && content.annotations) {
          for (const annotation of content.annotations) {
            if (annotation.type === "url_citation") {
              console.log(
                `URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
              );
            }
          }
        }
      } else if (item.type === "tool_call") {
        console.log(`Tool call completed: ${item.name ?? "unknown"}`);
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nOpenAPI agent sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Funktionsweise dieses Codes

In diesem TypeScript-Beispiel wird ein Agent mit einem OpenAPI-Tool für Wetterdaten mithilfe der anonymen Authentifizierung erstellt. Wenn Sie den Code ausführen:

  1. Sie lädt die Wetter-OpenAPI-Spezifikation aus einer lokalen JSON-Datei.
  2. Erstellt einen Agent mit dem konfigurierten Wettertool.
  3. Sendet eine Streaminganfrage, in der Sie nach der Wetter- und Outfitplanung von Seattle gefragt werden.
  4. Verarbeitet die Streaming-Antwort und zeigt Deltas an, sobald sie ankommen.
  5. Sie erzwingt die Verwendung von Tools, indem tool_choice: "required" verwendet wird, um sicherzustellen, dass die API aufgerufen wird.
  6. Wird bereinigt durch das Löschen des Agents.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • Lokale Datei: ../assets/weather_openapi.json (OpenAPI-Spezifikation)

Erwartete Ausgabe

Loading OpenAPI specifications from assets directory...
Creating agent with OpenAPI tool...
Agent created (id: asst_abc123, name: MyOpenApiAgent, version: 1)

Sending request to OpenAPI-enabled agent with streaming...
Follow-up response created with ID: resp_xyz789
The weather in Seattle is currently...
Tool call completed: get_weather

Follow-up completed!

Cleaning up resources...
Agent deleted

OpenAPI agent sample completed!

Häufige Fehler

  • Error: OpenAPI specification not found: Dateipfad falsch oder datei fehlt
  • Fehlende Umgebungsvariablen verursachen Initialisierungsfehler
  • AuthenticationError: Ungültige Azure-Anmeldeinformationen
  • API-Schlüssel funktioniert nicht: Wenn Sie von anonymer zu API-Schlüsselauthentifizierung wechseln, stellen Sie sicher, dass Ihre OpenAPI-Spezifikation securitySchemes und security ordnungsgemäß konfiguriert sind.

Erstellen eines Agents, der OpenAPI-Tools verwendet, die mit einer Projektverbindung authentifiziert sind

Im folgenden TypeScript-Codebeispiel wird veranschaulicht, wie ein KI-Agent erstellt wird, der OpenAPI-Tools verwendet, die über eine Projektverbindung authentifiziert wurden. Der Agent lädt die TripAdvisor OpenAPI-Spezifikation aus lokalen Ressourcen und kann die API über die konfigurierte Projektverbindung aufrufen. Eine JavaScript-Version dieses Beispiels finden Sie im Beispiel im Azure SDK für JavaScript-Repository auf GitHub.

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  OpenApiTool,
  OpenApiFunctionDefinition,
  OpenApiProjectConnectionAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";
const tripAdvisorProjectConnectionId =
  process.env["TRIPADVISOR_PROJECT_CONNECTION_ID"] || "<tripadvisor project connection id>";
const tripAdvisorSpecPath = path.resolve(__dirname, "../assets", "tripadvisor_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createTripAdvisorTool(spec: unknown): OpenApiTool {
  const auth: OpenApiProjectConnectionAuthDetails = {
    type: "project_connection",
    security_scheme: {
      project_connection_id: tripAdvisorProjectConnectionId,
    },
  };

  const definition: OpenApiFunctionDefinition = {
    name: "get_tripadvisor_location_details",
    description:
      "Fetch TripAdvisor location details, reviews, or photos using the Content API via project connection auth.",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  console.log("Loading TripAdvisor OpenAPI specification from assets directory...");
  const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);

  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await project.getOpenAIClient();

  console.log("Creating agent with OpenAPI project-connection tool...");

  const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
    kind: "prompt",
    model: deploymentName,
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  console.log("\nSending request to TripAdvisor OpenAPI agent with streaming...");
  const streamResponse = await openAIClient.responses.create(
    {
      input:
        "Provide a quick overview of the TripAdvisor location 293919 including its name, rating, and review count.",
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      const item = event.item as any;
      if (item.type === "message") {
        const content = item.content?.[item.content.length - 1];
        if (content?.type === "output_text" && content.annotations) {
          for (const annotation of content.annotations) {
            if (annotation.type === "url_citation") {
              console.log(
                `URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
              );
            }
          }
        }
      } else if (item.type === "tool_call") {
        console.log(`Tool call completed: ${item.name ?? "unknown"}`);
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nTripAdvisor OpenAPI agent sample completed!");
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

Funktionsweise dieses Codes

In diesem TypeScript-Beispiel wird die Verwendung eines OpenAPI-Tools mit API-Schlüsselauthentifizierung über eine Projektverbindung veranschaulicht. Wenn Sie den Code ausführen:

  1. Sie lädt die TripAdvisor OpenAPI-Spezifikation aus einer lokalen Datei.
  2. Sie konfiguriert die Authentifizierung mithilfe der TRIPADVISOR_PROJECT_CONNECTION_ID Umgebungsvariablen.
  3. Er erstellt einen Agent mit dem TripAdvisor-Tool, das die Projektverbindung für die API-Schlüsselauthentifizierung verwendet.
  4. Es sendet eine Streaminganforderung für TripAdvisor-Standortdetails.
  5. Sie erzwingt die Verwendung von Tools, indem tool_choice: "required" verwendet wird, um sicherzustellen, dass die API aufgerufen wird.
  6. Sie verarbeitet und zeigt die Streamingantwort an.
  7. Die Bereinigung erfolgt durch das Löschen des Agents.

Erforderliche Eingaben

  • Umgebungsvariablen: FOUNDRY_PROJECT_ENDPOINT, , FOUNDRY_MODEL_DEPLOYMENT_NAMETRIPADVISOR_PROJECT_CONNECTION_ID
  • Lokale Datei: ../assets/tripadvisor_openapi.json
  • Project-Verbindung mit TripAdvisor-API-Schlüssel konfiguriert

Erwartete Ausgabe

Loading TripAdvisor OpenAPI specification from assets directory...
Creating agent with OpenAPI project-connection tool...
Agent created (id: asst_abc123, name: MyOpenApiConnectionAgent, version: 1)

Sending request to TripAdvisor OpenAPI agent with streaming...
Follow-up response created with ID: resp_xyz789
Location 293919 is the Eiffel Tower in Paris, France. It has a rating of 4.5 stars with over 140,000 reviews...
Tool call completed: get_tripadvisor_location_details

Follow-up completed!

Cleaning up resources...
Agent deleted

TripAdvisor OpenAPI agent sample completed!

Häufige Fehler

  • Error: OpenAPI specification not found: Überprüfen Sie den Dateipfad.
  • Überprüfen Sie, ob TRIPADVISOR_PROJECT_CONNECTION_ID korrekt ist und die Verbindung besteht.
  • AuthenticationException: Ungültiger API-Schlüssel in der Projektverbindung.
  • API-Schlüssel, der nicht in Anforderungen eingefügt wird: Ihre OpenAPI-Spezifikation muss die richtigen securitySchemes (unter components) und security Abschnitte enthalten. Der Schlüsselname in securitySchemes muss mit dem Schlüssel in Ihrer Projektverbindung übereinstimmen.
  • Content type is not supported: Derzeit werden nur diese beiden Inhaltstypen unterstützt: application/json und application/json-patch+json.

Überlegungen zu Sicherheit und Daten

Wenn Sie einen Agent mit einem OpenAPI-Tool verbinden, kann der Agent Anforderungsparameter senden, die von der Benutzereingabe an die Ziel-API abgeleitet wurden.

  • Verwenden Sie Projektverbindungen für geheime Schlüssel (API-Schlüssel und Token). Vermeiden Sie das Einfügen geheimer Schlüssel in eine OpenAPI-Spezifikationsdatei oder einen Quellcode.
  • Überprüfen Sie, welche Daten die API empfängt und was sie zurückgibt, bevor Sie das Tool in der Produktion verwenden.
  • Verwenden Sie das Prinzip der minimalen Rechte. Weisen Sie für verwaltete Identität nur die Rollen zu, die der Zieldienst benötigt.

Authentifizieren mit einem API-Schlüssel

Mithilfe der API-Schlüsselauthentifizierung können Sie Ihre OpenAPI-Spezifikation mithilfe verschiedener Methoden wie einem API-Schlüssel oder Bearertoken authentifizieren. Sie können nur ein API-Schlüsselsicherheitsschema pro OpenAPI-Spezifikation verwenden. 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 API-Schlüssel gespeichert und über eine Verbindung übergeben wird, wie weiter unten in diesem Artikel beschrieben.

  4. Erstellen Sie eine Verbindung zum Speichern Ihres API-Schlüssels.

  5. Wechseln Sie zum Foundry-Portal , und öffnen Sie Ihr Projekt.

  6. Erstellen oder Auswählen einer Verbindung, die den geheimen Schlüssel speichert. Siehe Hinzufügen einer neuen Verbindung zu Ihrem Projekt.

    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.

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

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

Einrichten einer Verbindung mit Bearer-Token

Sie können die tokenbasierte Authentifizierung (z. B. ein Bearer-Token) mit demselben project_connection Authentifizierungstyp verwenden, der für API-Schlüssel verwendet wird. Der hauptunterschied besteht darin, wie Sie sowohl die OpenAPI-Spezifikation als auch die Projektverbindung konfigurieren.

Ihre OpenAPI-Spezifikation sieht wie folgt aus:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Sie müssen Folgendes tun:

  1. Aktualisieren Sie die OpenAPI-Spezifikation securitySchemes so, dass sie als Headername verwendet wird Authorization :

    "securitySchemes": {
    "bearerAuth": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
    }
}

  2. Fügen Sie einen security Abschnitt hinzu, der auf das Schema verweist:

    "security": [
    {
        "bearerAuth": []
    }
]

  3. Erstellen Sie eine Verbindung mit benutzerdefinierten Schlüsseln in Ihrem Foundry-Projekt:

    1. Wechseln Sie zum Foundry-Portal , und öffnen Sie Ihr Projekt.
    2. Erstellen oder Auswählen einer Verbindung, die den geheimen Schlüssel speichert. Siehe Hinzufügen einer neuen Verbindung zu Ihrem Projekt.
    3. Geben Sie die folgenden Werte ein:
      • Schlüssel: Authorization (muss mit dem name-Feld in Ihrem securitySchemes übereinstimmen)
      • value: Bearer <token> (ersetzen Sie <token> durch Ihren tatsächlichen Token)

    Von Bedeutung

    Der Wert muss das Wort Bearer gefolgt von einem Leerzeichen vor dem Token enthalten. Beispiel: Bearer eyJhbGciOiJSUzI1NiIs.... Wenn Sie weglassen Bearer , empfängt die API ein unformatiertes Token ohne das erforderliche Autorisierungsschemapräfix, und die Anforderung schlägt fehl.

  4. Nachdem Sie die Verbindung erstellt haben, verwenden Sie sie mit dem project_connection Authentifizierungstyp in Ihrem Code auf die gleiche Weise wie bei der API-Schlüsselauthentifizierung. Die Verbindungs-ID verwendet das gleiche Format: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Authentifizieren mithilfe der verwalteten 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 Ihren APIs zusätzliche Sicherheit hinzufügen, ohne API-Schlüssel verwenden zu müssen. Wenn Sie die verwaltete Identitätsauthentifizierung einrichten, authentifiziert sich der Agent über das von ihm verwendete Foundry-Tool.

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

  1. Stellen Sie sicher, dass Ihre Foundry-Ressource die verwaltete Identität des Systems aktiviert hat.

    Screenshot der verwalteten Identitätsauswahl im Azure-Portal.

  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.

      Screenshot der Rollenzuweisungsauswahl im Azure-Portal.

    3. Wählen Sie die richtige Rollenzuweisung aus, in der Regel erfordert sie mindestens die READER-Rolle . 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 Account , und wählen Sie dann das Foundry-Konto Ihres Agents aus.

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

  4. Wenn 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.

Häufige Fehler beheben

Symptom Wahrscheinliche Ursache Beschluss
DER API-Schlüssel ist nicht in Anforderungen enthalten. OpenAPI-Spezifikation fehlen securitySchemes oder security Abschnitte. Überprüfen Sie, ob die OpenAPI-Spezifikation sowohl components.securitySchemes als auch einen security-Abschnitt auf oberster Ebene enthält. Stellen Sie sicher, dass das Schema name dem Schlüsselnamen in Ihrer Projektverbindung entspricht.
Der Agent ruft das OpenAPI-Tool nicht auf. Die Werkzeugauswahl ist nicht festgelegt oder operationId ist nicht beschreibend. Wird verwendet tool_choice="required" , um den Aufruf von Tools zu erzwingen. Stellen Sie sicher, dass operationId Werte beschreibend sind, damit das Modell den richtigen Vorgang auswählen kann.
Die Authentifizierung schlägt bei verwalteter Identität fehl. Verwaltete Identität nicht aktiviert oder fehlende Rollenzuweisung. Aktivieren Sie die vom System zugewiesene verwaltete Identität in Ihrer Foundry-Ressource. Weisen Sie dem Zieldienst die erforderliche Rolle (Reader oder höher) zu.
Anforderung schlägt mit 400 ungültiger Anforderung fehl. Die OpenAPI-Spezifikation stimmt nicht mit der tatsächlichen API überein. Überprüfen Sie ihre OpenAPI-Spezifikation anhand der tatsächlichen API. Überprüfen Sie Parameternamen, Typen und erforderliche Felder.
Die Anforderung schlägt mit 401 Nicht autorisiert fehl. API-Schlüssel oder Token ungültig oder abgelaufen. Generieren Sie den API-Schlüssel/-Token neu, und aktualisieren Sie die Projektverbindung. Überprüfen Sie, ob die Verbindungs-ID korrekt ist.
Das Tool gibt ein unerwartetes Antwortformat zurück. Das Antwortschema wurde in der OpenAPI-Spezifikation nicht definiert. Fügen Sie Ihrer OpenAPI-Spezifikation Antwortschemas hinzu, um ein besseres Modellverständnis zu haben.
operationId Überprüfungsfehler. Ungültige Zeichen in operationId. Verwenden Sie nur Buchstaben, - und _ in operationId-Werten. Entfernen sie Zahlen und Sonderzeichen.
Fehler: Verbindung nicht gefunden. Verbindungsname oder ID stimmt nicht überein. Überprüfen Sie, ob OPENAPI_PROJECT_CONNECTION_NAME mit dem Verbindungsnamen Ihres Foundry-Projekts übereinstimmt.
Bearer-Token wurde nicht korrekt gesendet. Das Präfix Bearer für den Verbindungswert fehlt. Legen Sie den Verbindungswert auf Bearer <token> (mit dem Wort Bearer und einem Leerzeichen vor dem Token) fest. Überprüfen Sie, ob die OpenAPI-Spezifikation securitySchemes"name": "Authorization" verwendet wird.

Auswählen einer Authentifizierungsmethode

In der folgenden Tabelle können Sie die richtige Authentifizierungsmethode für Ihr OpenAPI-Tool auswählen:

Authentifizierungsmethode Am besten geeignet für: Die Einrichtungskomplexität
Anonym Öffentliche APIs ohne Authentifizierung Niedrig
API-Schlüssel APIs von Drittanbietern mit schlüsselbasiertem Zugriff Mittelstufe
Verwaltete Identität Azure-Dienste und microsoft Entra ID-geschützte APIs Mittelhoch

Verwandte Inhalte

  • Last updated on