Verbinden von Agents mit OpenAPI-Tools

Verbinden Sie Ihre Microsoft Foundry-Agents mit externen APIs mithilfe von OpenAPI 3.0- und 3.1-Spezifikationen. Das Foundry-Modell, das Ihren Agent unterstützt, kann externe Dienste aufrufen, Echtzeitdaten abrufen und seine 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 key und managed identity. Hilfe zum Auswählen einer Authentifizierungsmethode finden Sie unter Auswählen einer Authentifizierungsmethode.

Tipp

Erwägen Sie das Hinzufügen dieses Tools mithilfe einer Toolbox. Mithilfe einer Toolbox können Sie das Tool über Agents und Laufzeiten hinweg wiederverwenden sowie die Verwaltung von Anmeldeinformationen, versionsverwaltung und Richtlinienerzwingung über einen verwalteten MCP-Endpunkt zentralisieren. Sehen Sie sich die Schnellstartanleitung der Toolbox an.

Voraussetzungen

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

  • Ein Azure-Abonnement mit den richtigen Berechtigungen.

  • Rolle "Foundry User " im Foundry-Projekt zum Erstellen und Ausführen von Agents.

    Wichtig

    Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

  • Foundry Project Manager-Rolle im Foundry-project, wenn Sie eine project Verbindung für API-Schlüssel oder Tokenauthentifizierung erstellen.

  • 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:pip install azure-ai-projects jsonref
    • C#: Azure.AI.Extensions.OpenAI
    • TypeScript/JavaScript: @azure/ai-projects
    • Java:com.azure:azure-ai-agents

Umgebungsvariablen

Variable Beschreibung
FOUNDRY_PROJECT_ENDPOINT Die URL des Foundry-Projekt-Endpunkts (nicht der externe OpenAPI-Dienst-Endpunkt).
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- oder 3.1-Spezifikationsdatei, die die folgenden Anforderungen erfüllt:
    • Jede Funktion muss über ein operationId verfügen (erforderlich für das OpenAPI-Tool).
    • operationId sollte nur Buchstaben, - und _ enthalten.
    • Verwenden Sie beschreibende Namen, damit die Modelle effizient entscheiden können, welche Funktion sie verwenden sollen.
    • Unterstützte Anforderungstextinhaltstypen: application/json, application/json-patch+json
  • Für die verwaltete Identitätsauthentifizierung: die Rolle mit den geringsten Rechten für den Zieldienst, die die erforderlichen API-Vorgänge zulässt, die der verwalteten Identität des Foundry-Projekts im Zielressourcenbereich zugewiesen sind.
  • 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 wert FOUNDRY_PROJECT_ENDPOINT bezieht sich auf Ihren Microsoft Foundry-Projektendpunkt, nicht auf den externen OpenAPI-Dienstendpunkt. Sie finden diesen Endpunkt im Microsoft Foundry-Portal unter der Übersichtsseite Ihres Projekts. Dieser Endpunkt ist erforderlich, um den Agentdienst zu authentifizieren und ist von allen openAPI-Endpunkten getrennt, die in Ihrer Spezifikationsdatei definiert sind.

Verwendungsunterstützung

Die folgende Tabelle zeigt die SDK- und Setupunterstützung.

Microsoft Foundry-Unterstützung Python SDK C# SDK JavaScript SDK Java SDK REST-API Grundlegendes Agent-Setup Standard-Agenten-Einrichtung
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Hinweis

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

Ausführen des anonymen Ersten Erfolgsablaufs

Beginnen Sie mit der anonymen Wetter-API, um zu überprüfen, ob Ihr Agent eine OpenAPI-Spezifikation laden und einen Vorgang aufrufen kann. Für diesen Pfad sind keine externen API-Anmeldeinformationen oder eine Foundry-Projektverbindung erforderlich.

  1. Installieren Sie das SDK-Paket für Ihre ausgewählte Sprache aus den Voraussetzungen.
  2. Laden Sie ihn herunter weather_openapi.json, und speichern Sie ihn in dem assets pfad, der vom Beispiel verwendet wird.
  3. Legen Sie den Endpunkt des Foundry-Projekts und die Modellbereitstellungswerte fest.
  4. Führen Sie das anonyme Beispiel im ausgewählten Sprachabschnitt aus.
  5. Vergewissern Sie sich, dass die Antwort das aktuelle Wetter für Seattle enthält, und löschen Sie dann die agent-Version, die vom Beispiel erstellt wurde.

Nachdem der anonyme Aufruf erfolgreich war, konfigurieren Sie die von Der Ziel-API erforderliche Authentifizierung. Beibehalten der API-Schlüsselauthentifizierung, Bearertokenauthentifizierung und verwalteter Identitätsauthentifizierung als separate Varianten.

Einschränkungen verstehen

  • Ihre OpenAPI-Spezifikation muss operationId für jeden Vorgang enthalten und operationId darf nur Buchstaben, -, und _.
  • Unterstützte Anforderungstextinhaltstypen: 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.

Hinzufügen von OpenAPI-Tools zu einer Toolbox

Verwenden Sie dieses Muster, um eine REST-API offenzulegen, die durch eine OpenAPI-Spezifikation beschrieben ist. Wählen Sie das auth.type aus, das zu dem Sicherheitsmodell Ihrer API passt.

Wichtig

Wenn Sie verwaltete Identitätsauthentifizierung verwenden, weisen Sie nur die RBAC-Rolle mit den geringsten Rechten zu, die die erforderlichen API-Vorgänge der verwalteten Identität Ihres Foundry-Projekts für den Zieldienst zulässt. Weisen Sie z. B. reader für das Ziel Azure Ressource nur zu, wenn die API schreibgeschützten Azure Resource Manager Zugriff benötigt. Ohne die erforderliche Zuweisung empfängt der Agent beim Aufrufen der API eine 401 Unauthorized Antwort. Vollständige Einrichtungsschritte finden Sie unter Authentifizieren mithilfe der verwalteten Identität.

Anonyme Authentifizierung:

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "anonymous"
        }
      }
    }
  ]
}

Project-Verbindungsauthentifizierung:

Verwenden Sie dieses Muster, wenn für die API ein Schlüssel oder Token erforderlich ist, der in einer Foundry-Projektverbindung gespeichert ist.

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

Verwaltete Identitätsauthentifizierung:

Verwenden Sie dieses Muster, wenn sich die Ziel-API über die Microsoft Entra-ID authentifiziert. Die verwaltete Identität des Foundry-Projekts ruft die API im Namen des Agents auf. Stellen Sie sicher, dass die verwaltete Identität über die erforderliche RBAC-Rolle für den Zieldienst verfügt, bevor Sie dieses Muster verwenden.

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "REST API via OpenAPI spec"
);

const tools = [
  {
    type: "openapi",
    openapi: {
      name: "my-api",
      spec: { /* paste OpenAPI spec object here */ },
      auth: {
        type: "anonymous",
      },
    },
  },
];

Erstellen einer OpenAPI-Toolbox mit der Azure Developer CLI

OpenAPI-Tools betten die Spezifikation direkt unter tools: ein. Verbindungsbasierte Authentifizierung (connection_auth) verweist auf eine Projektverbindung. Anonyme OpenAPI-Tools benötigen keine Verbindung.

Schritt 1. (Optional) Erstellen der Authentifizierungsverbindung

Überspringen Sie diesen Schritt für anonyme OpenAPI-Tools.

# API-key auth (passed by the platform on every call)
# Set OPENAPI_AUTHORIZATION_HEADER in your shell without committing its value.
azd ai connection create my-api-conn \
  --kind remote-tool \
  --target https://api.example.com \
  --auth-type custom-keys \
  --custom-key "Authorization=$OPENAPI_AUTHORIZATION_HEADER"

OpenAPI-Tools akzeptieren auch --auth-type oauth2 Verbindungen. Den vollständigen Satz von azd ai connection create Flags finden Sie unter Toolbox MCP-Authentifizierung und -Konfiguration.

Schritt 2. Definieren der Toolbox

Die OpenAPI-Spezifikation ist inline unter tools[].openapi.spec.

# my-toolbox.yaml
description: OpenAPI toolbox
tools:
  - type: openapi
    name: my-api
    openapi:
      name: my-api
      spec:
        openapi: "3.0.1"
        info:
          title: "My API"
          version: "1.0"
        servers:
          - url: https://api.example.com/v1
        paths:
          /search:
            get:
              operationId: search
              parameters:
                - name: query
                  in: query
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: OK
      auth:
        type: connection_auth
        connection_id: my-api-conn

Ersetzen Sie den auth: Block für anonyme APIs durch:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Schritt 3: Erstellen der Toolbox

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Bevor Sie die Codebeispiele ausführen

  • Laden Sie die verwaltete Spezifikation herunter tripadvisor_openapi.json , und speichern Sie sie auf dem Pfad, der assets von Ihrem Sprachbeispiel verwendet wird.

Hinweis

  • Sie benötigen das neueste SDK-Paket. Das .NET SDK ist derzeit als Vorschauversion verfügbar. 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.

Wichtig

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-Token-Authentifizierung eine Verbindung mit benutzerdefinierten Schlüsseln, wobei der Schlüssel auf Authorization und der Wert auf Bearer <token> festgelegt ist (ersetzen Sie <token> durch Ihren tatsächlichen Token). Das Wort Bearer gefolgt von einem Leerzeichen muss in den Wert eingeschlossen werden. Ausführliche Informationen finden Sie unter Einrichten einer Bearer-Tokenverbindung.

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 Dienst wttr.in, um Wetter und die Spezifikationsdatei weather_openapi.json abzurufen. Wählen Sie Prompt Agents aus, um das AZURE AI Projects SDK zum Erstellen eines serverseitigen Eingabeaufforderungs-Agents oder Hosted Agents zu verwenden, um das Microsoft Agent Framework zum Erstellen eines ephemeren, in-Process-Agents zu verwenden.

Prompt-Agenten

import os
import jsonref
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,
)

# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_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(),
    )
)

agent = project.agents.create_version(
    agent_name="MyAgent",
    definition=PromptAgentDefinition(
        model="gpt-4.1-mini",
        instructions="You are a helpful assistant.",
        tools=[weather_tool],
    ),
)
response = openai.responses.create(
    input="What's the weather in Seattle?",
    extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
)
print(response.output_text)

# Clean up resources
project.agents.delete_version(agent_name=agent.name, agent_version=agent.version)

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

  1. Sie lädt die Wetter-OpenAPI-Spezifikation aus einer lokalen JSON-Datei.
  2. Erstellt einen Eingabeaufforderungs-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.

Gehostete Agents

In diesem Beispiel wird FoundryChatClient das Microsoft Agent Framework verwendet und mithilfe der Verwendung MCPStreamableHTTPTooleine Verbindung mit dem MCP-Endpunkt der Toolbox hergestellt. Installieren Sie kompatible Paketversionen mit pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity httpx jsonref, legen Sie die FOUNDRY_PROJECT_ENDPOINT Umgebungsvariable fest, und melden Sie sich mit az login. OpenApiToolboxTool ist das toolboxspezifische Modell; wird nur verwendet OpenApiTool , wenn das Tool direkt an einen Eingabeaufforderungs-Agent angefügt wird.

import asyncio
import os
import httpx
import jsonref
from typing import Any, cast

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential, get_bearer_token_provider
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    OpenApiToolboxTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"


class _ToolboxAuth(httpx.Auth):
    def __init__(self, token_provider):
        self._token_provider = token_provider

    def auth_flow(self, request):
        request.headers["Authorization"] = "Bearer " + self._token_provider()
        yield request


async def main() -> None:
    credential = AzureCliCredential()

    # 1. Create the OpenAPI tool and add it to a toolbox. Using a toolbox is the
    #    recommended way to give agents tools: curate tools once and reuse the
    #    toolbox across agents. See /azure/foundry/agents/concepts/toolbox-overview
    project = AIProjectClient(endpoint=PROJECT_ENDPOINT, credential=credential)

    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()))

    weather_tool = OpenApiToolboxTool(
        openapi=OpenApiFunctionDefinition(
            name="get_weather",
            spec=openapi_weather,
            description="Retrieve weather information for a location.",
            auth=OpenApiAnonymousAuthDetails(),
        )
    )

    toolbox = project.toolboxes.create_version(
        name="openapi-toolbox",
        description="Toolbox with the OpenAPI weather tool",
        tools=[weather_tool],
    )

    # 2. The toolbox exposes an MCP-compatible endpoint.
    TOOLBOX_MCP_URL = (
        f"{PROJECT_ENDPOINT}/toolboxes/{toolbox.name}"
        f"/versions/{toolbox.version}/mcp?api-version=v1"
    )

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
    token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
    http_client = httpx.AsyncClient(auth=_ToolboxAuth(token_provider), timeout=120.0)
    mcp_tool = MCPStreamableHTTPTool(
        name="toolbox",
        url=TOOLBOX_MCP_URL,
        http_client=http_client,
        load_prompts=False,
    )

    agent = Agent(
        client=FoundryChatClient(credential=credential),
        instructions="You are a helpful assistant. Use the OpenAPI weather tool to answer questions.",
        tools=[mcp_tool],
    )

    result = await agent.run("What's the weather in Seattle?")
    print(f"Agent: {result.text}")


if __name__ == "__main__":
    asyncio.run(main())

Erwartete Ausgabe

Agent: The weather in Seattle is currently cloudy with a temperature of 52°F (11°C)...

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 Dienst wttr.in, um Wetter und die Spezifikationsdatei weather_openapi.json abzurufen. Wählen Sie Prompt Agents aus, um das AZURE AI Projects SDK zum Erstellen eines serverseitigen Eingabeaufforderungs-Agents oder Hosted Agents zu verwenden, um das Microsoft Agent Framework zum Erstellen eines ephemeren, in-Process-Agents zu verwenden.

Prompt-Agenten

In diesem Beispiel werden synchrone Methoden der Azure AI Projects-Clientbibliothek verwendet. Ein Beispiel, das asynchrone Methoden verwendet, finden Sie unter sample im Azure SDK für .NET Repository für GitHub.

using System;
using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;

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()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        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(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.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the weather in Seattle, WA.
        ProjectResponsesClient responseClient = projectClient.ProjectOpenAIClient.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.AgentAdministrationClient.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. Räumt auf, indem es den Agenten löscht.

Erforderliche Eingaben

  • Inlinezeichenfolgenwert: projectEndpoint (Ihr Foundry-Projektendpunkt)
  • 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
  • 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.

Gehostete Agents

In diesem Beispiel wird die OpenAPI-Toolbox mit dem Azure AI Projects SDK erstellt. Anschließend wird ResponsesServer das Microsoft Agent Framework mit einer benutzerdefinierten ToolboxMcpClient Anwendung verwendet, um das Tool über den MCP-Endpunkt der Toolbox zu ermitteln und aufzurufen. Installieren Sie die Agent Framework-Pakete, legen Sie die AZURE_AI_PROJECT_ENDPOINT Projektendpunkt- und AZURE_AI_MODEL_DEPLOYMENT_NAME Umgebungsvariablen fest, und melden Sie sich mit az login.

using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

string GetFile([CallerFilePath] string pth = "")
{
    var dirName = Path.GetDirectoryName(pth) ?? "";
    return Path.Combine(dirName, "Assets", "weather_openapi.json");
}

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

var openAiEndpoint = new Uri(projectEndpoint).GetLeftPart(UriPartial.Authority);
DefaultAzureCredential credential = new();

// 1. Create the OpenAPI tool and add it to a toolbox. Using a toolbox is the
//    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
string filePath = GetFile();
OpenAPIFunctionDefinition toolDefinition = new(
    name: "get_weather",
    spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
    auth: new OpenAPIAnonymousAuthenticationDetails()
);
toolDefinition.Description = "Retrieve weather information for a location.";
ProjectsAgentTool openapiTool = new OpenAPITool(toolDefinition);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "openapi-toolbox",
        tools: [openapiTool],
        description: "Toolbox with the OpenAPI weather tool");

// 2. The toolbox exposes an MCP-compatible endpoint.
string toolboxMcpEndpoint =
    $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}/versions/{toolboxVersion.Version}/mcp?api-version=v1";

// 3. Attach the toolbox to the hosted agent.
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
ChatClient chatClient = openAIClient.GetChatClient(deploymentName);

// ToolboxMcpClient discovers tools from the toolbox MCP endpoint and calls them
// through tools/call. ToolboxHandler maps model tool calls to that MCP client.
var toolboxClient = new ToolboxMcpClient(toolboxMcpEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

Erwartete Ausgabe

Der Agent ruft die REST-Länder-API über das OpenAPI-Tool auf und listet die entsprechenden Länder auf:

Countries that use the Euro (EUR) as their currency include: Austria, Belgium, Croatia, Cyprus, Estonia, Finland, France, Germany, Greece, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain ...

Das vollständige Beispiel einschließlich authentifizierter API-Muster finden Sie unter Agent_Step17_OpenAPITools.

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

In diesem Beispiel fügen Sie einer Toolbox ein authentifizierte OpenAPI-Tool hinzu, fügen die Toolbox als MCP-Tool an und verwenden den Agent in einem Szenario, das eine Authentifizierung erfordert. Sie verwenden die TripAdvisor-Spezifikation.

Der TripAdvisor-Dienst erfordert eine schlüsselbasierte Authentifizierung. Um eine Verbindung zu erstellen, öffnen Sie Microsoft Foundry, wählen Sie "Verwalten" in der oberen rechten Navigation aus, wählen Sie Project Details aus, und wählen Sie dann die Registerkarte "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 einen Wert mit Ihrem TripAdvisor-Schlüssel 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()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

        // Create project client to call Foundry API
        AIProjectClient projectClient = new(
            endpoint: new Uri(projectEndpoint),
            tokenProvider: new DefaultAzureCredential());

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

        // 1. Add the authenticated OpenAPI tool to a toolbox. Using a toolbox is the
        //    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
        AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

        ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
            .GetAgentToolboxes().CreateToolboxVersion(
                toolboxName: "openapi-toolbox",
                tools: [openapiTool],
                description: "Toolbox with the authenticated TripAdvisor OpenAPI tool");

        // 2. The toolbox exposes an MCP-compatible endpoint.
        var toolboxMcpUrl = new Uri(
            $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}" +
            $"/versions/{toolboxVersion.Version}/mcp?api-version=v1");

        // 3. Create a remote-tool project connection that points at the toolbox endpoint.
        //    Use a user Entra token so the caller's identity is passed through
        //    (audience https://ai.azure.com). Create the connection once, for example
        //    with the Azure Developer CLI:
        //
        //    azd ai connection create openapi-toolbox-conn \
        //      --kind remote-tool \
        //      --target "<toolboxMcpUrl>" \
        //      --auth-type user-entra-token \
        //      --audience https://ai.azure.com
        var toolboxConnectionName = "openapi-toolbox-conn";

        // 4. Attach the toolbox to a prompt agent as an MCP tool.
        McpTool toolboxTool = ResponseTool.CreateMcpTool(
            serverLabel: "toolbox",
            serverUri: toolboxMcpUrl,
            toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
                GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
        toolboxTool.ProjectConnectionId = toolboxConnectionName;

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { toolboxTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.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.ProjectOpenAIClient.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.AgentAdministrationClient.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 Toolbox und 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 eine Toolboxversion, die das TripAdvisor-Tool enthält, das für die Verwendung der Verbindung für die Authentifizierung konfiguriert ist.
  4. Fügt die Toolbox als MCP-Tool an den Agent an.
  5. Sendet eine Anfrage nach Hotelempfehlungen in Paris.
  6. Der Agent ruft die TripAdvisor-API mit Ihrem gespeicherten API-Schlüssel auf und gibt Ergebnisse zurück.
  7. Räumt auf, indem es den Agenten löscht.

Erforderliche Eingaben

  • Inlinezeichenfolgenwert: projectEndpoint (Ihr Foundry-Projektendpunkt)
  • Lokale Datei: Assets/tripadvisor_openapi.json
  • Projektverbindung: tripadvisor mit konfiguriertem gültigem API-Schlüssel

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 Tool-Nutzung erzwingt.
  • API-Schlüssel nicht an API übergeben: Stellen Sie sicher, dass in der OpenAPI-Spezifikation die richtigen Abschnitte securitySchemes und security konfiguriert sind.

Erstellen eines Java-Agents mit OpenAPI-Toolfunktionen

Dieses Java-Setup kann auf MCP-Tools verweisen, aber das Java SDK macht noch keine Toolboxerstellungs-API verfügbar.

Tipp

Empfohlen: Fügen Sie für die meisten Agents das OpenAPI-Tool über eine Toolbox hinzu, und fügen Sie die Toolbox als MCP-Tool an Ihren Agent an. Erstellen Sie die Toolbox mithilfe des Python-, REST-API-, C#- oder TypeScript-Beispiels oder des Foundry-Portals, und verweisen Sie dann auf den MCP-Endpunkt von Ihrem Java-Agent als ein McpTool.

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

Zugriffstoken abrufen:

AGENT_TOKEN=$(az account get-access-token --scope https://ai.azure.com/.default --query accessToken -o tsv)

Anonyme Authentifizierung

Fügen Sie OpenAPI-Tools über eine Toolbox hinzu, und fügen Sie die Toolbox dann als MCP-Tool an Ihren Agent an. Weitere Informationen finden Sie unter Was ist eine Toolbox?

  1. Erstellen Sie eine Toolbox, die das OpenAPI-Wettertool enthält:
curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the OpenAPI weather tool",
    "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" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Die Toolbox macht einen MCP-kompatiblen Endpunkt bei , bei dem $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1 es sich um <version>die vom vorherigen Aufruf zurückgegebene Version handelt.

  1. Erstellen Sie eine Remote-Tool-Projektverbindung, die auf den Toolboxendpunkt zeigt, indem Sie ein Benutzer-Entra-Token verwenden, damit die Identität des Anrufers (Zielgruppe https://ai.azure.com) übergeben wird.
azd ai connection create openapi-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com
  1. Erstellen Sie eine Antwort, die die Toolbox verwendet, indem Sie sie als MCP-Tool anfügen.
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.",
    "tool_choice": "required",
    "tools": [
      {
        "type": "mcp",
        "server_label": "toolbox",
        "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1",
        "require_approval": "never",
        "project_connection_id": "openapi-toolbox-conn"
      }
    ]
  }'

API-Schlüsselauthentifizierung (Projektverbindung)

Verwenden Sie diese Variante nur, nachdem der anonyme Fluss erfolgreich war. Konfigurieren Sie die Projektverbindung und den OpenAPI-Eintrag securitySchemes , wie unter "Authentifizieren mit API-Schlüssel" beschrieben.

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": [] }
            ]
          }
        }
      }
    ]
  }'

Behalten Sie für eine Bearertoken-API das gleiche project_connection Anforderungs-Shape bei, verwenden Sie jedoch eine Verbindung, die wie unter "Einrichten einer Bearertokenverbindung" beschrieben ist. Der Verbindungswert muss das Bearer Präfix enthalten.

Verwaltete Identitätsauthentifizierung

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. Erstellt für die anonyme Authentifizierung eine Toolbox mit der OpenAPI-Tooldefinition und der Wetter-API-Spezifikation.
  2. Erstellt eine Antwort, die die Toolbox als MCP-Tool anfügt und nach Seattles Wetter fragt.
  3. Zeigt zusätzliche direkte REST-Tooldefinitionen für API-Schlüssel über die Projektverbindung und die verwaltete Identitätsauthentifizierung 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 der API-Schlüssel wurde nicht eingefügt, weil 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 Sie einen KI-Agent mit OpenAPI-Toolfunktionen erstellen, indem Sie das OpenAPI-Tool zu einer Toolbox hinzufügen und die Toolbox als MCP-Tool anfügen. Der Agent kann externe APIs aufrufen, die von OpenAPI-Spezifikationen definiert sind. Eine JavaScript-Version dieses Beispiels finden Sie im GitHub im Azure SDK für JavaScript-Repository sample.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
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> {
  const weatherSpec = loadOpenApiSpec(weatherSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  const weatherTool = createWeatherTool(weatherSpec);

  console.log("Creating a toolbox with the OpenAPI weather tool...");

  // 1. Add the OpenAPI tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "openapi-toolbox",
    [weatherTool],
    { description: "Toolbox with the OpenAPI weather tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${PROJECT_ENDPOINT}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create openapi-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "openapi-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("MyOpenApiAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a helpful assistant that can call external APIs defined by OpenAPI specs to answer user questions.",
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });

  // Send a request and stream the response
  const streamResponse = await openai.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_reference: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

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 eine Toolboxversion, die das Wettertool enthält.
  3. Fügt die Toolbox als MCP-Tool an den Agent an und sendet dann eine Streaminganforderung, die nach der Wetter- und Outfitplanung von Seattle fragt.
  4. Verarbeitet die Streamingantwort 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. Räumt auf, indem es den Agenten löscht.

Erforderliche Eingaben

  • Inlinezeichenfolgenwert: PROJECT_ENDPOINT (Ihr Foundry-Projektendpunkt)
  • 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
  • AuthenticationError: Ungültige Azure Anmeldeinformationen
  • API-Schlüssel funktioniert nicht: Wenn Sie von anonymer zu API-Schlüssel-Authentifizierung wechseln, stellen Sie sicher, dass Ihre OpenAPI-Spezifikation mit securitySchemes und security ordnungsgemäß konfiguriert ist.

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 GitHub im Azure SDK für JavaScript-Repository sample.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const TRIPADVISOR_CONNECTION_ID = "your-tripadvisor-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: TRIPADVISOR_CONNECTION_ID,
    },
  };

  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> {
  const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create an agent with the OpenAPI project-connection tool
  const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });

  // Send a request and stream the response
  const streamResponse = await openai.responses.create(
    {
      input:
        "Provide a quick overview of the TripAdvisor location 293919 including its name, rating, and review count.",
      stream: true,
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n");
    }
  }

  // Clean up resources
  await project.agents.deleteVersion(agent.name, agent.version);
}

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

  • Inlinezeichenfolgenwerte: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
  • Lokale Datei: ../assets/tripadvisor_openapi.json
  • Projektverbindung 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.
  • Verbindung nicht gefunden: Überprüfen Sie, ob TRIPADVISOR_CONNECTION_ID korrekt ist und eine 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 Anforderungstextinhaltstypen unterstützt: application/json und application/json-patch+json. Antwortinhaltstypen sind nicht eingeschränkt.

Ü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 geringstmöglichen Rechtevergabe. Weisen Sie für verwaltete Identität nur die Rollen zu, die der Zieldienst benötigt.

Authentifizieren mit API-Schlüssel

Verwenden Sie diese Variante für eine API, die einen Schlüssel in einem Header oder Abfrageparameter erwartet. Sie können nur ein API-Schlüsselsicherheitsschema pro OpenAPI-Tool verwenden. Wenn für die API mehrere Sicherheitsschemas erforderlich sind, erstellen Sie mehrere OpenAPI-Tools.

  1. Aktualisieren Sie Ihre OpenAPI-Spezifikationssicherheitsschemas. Es verfügt über einen securitySchemes Abschnitt und ein Schema vom Typ apiKey. Zum 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 neu 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 es sich um x-api-key

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

    • Wert: YOUR_API_KEY

  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 Bearer-Token-Verbindung

Verwenden Sie diese Variante für eine API, die ein Bearertoken im Authorization Header erwartet. Er verwendet denselben project_connection Authentifizierungstyp wie die API-Schlüsselauthentifizierung, aber das OpenAPI-Sicherheitsschema und die Verbindungswerte unterscheiden sich.

Ihre OpenAPI-Spezifikation sieht wie folgt aus:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Sie müssen:

  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)
      • value: Bearer <token> (ersetzen Sie <token> durch Ihren tatsächlichen Token)

    Wichtig

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

Wichtig

Die verwaltete Identitätsauthentifizierung funktioniert nur, wenn der Zieldienst Microsoft Entra ID Token akzeptiert. Wenn die Ziel-API ein benutzerdefiniertes Authentifizierungsschema verwendet, das Microsoft Entra ID nicht unterstützt, verwenden Sie stattdessen API-Schlüssel oder Bearer-TokenAuthentifizierung.

Verstehen des Zielgruppen-URI

Der Zielgruppe (manchmal auch als Ressourcen-Identifikator oder Anwendungs-ID-URI bezeichnet) teilt Microsoft Entra ID mit, auf welchen Dienst oder welche API das Token zugreifen möchte. Der Zielgruppenwert muss mit dem erwarteten Zieldienst übereinstimmen, oder die Authentifizierung schlägt mit einem 401-Fehler fehl.

Hinweis

Die Zielgruppe ist nicht Ihr Foundry-Projektendpunkt. Es ist der Ressourcenbezeichner des Zieldiensts, den Ihr OpenAPI-Tool aufruft.

In der folgenden Tabelle sind Benutzergruppen-URIs für allgemeine Azure Dienste aufgeführt:

Zielservice Zielgruppen-URI
Azure Storage https://storage.azure.com
Azure Key Vault https://vault.azure.net
Azure KI-Suche https://search.azure.com
Azure Logic Apps https://logic.azure.com
Azure API Management (Verwaltungsebene) https://management.azure.com
API geschützt durch eine Microsoft Entra-App-Registrierung (einschließlich APIM mit OAuth) Der Anwendungs-ID-URI aus Ihrer App-Registrierung (z. B. api://<client-id>)

Tipp

Wenn Sie Azure API Management verwenden, um eine benutzerdefinierte API mit einer OAuth 2.0-Validierungsrichtlinie zu schützen, ist die Zielgruppe der Application ID URI vor der App-Registrierung, die die API schützt , nicht https://management.azure.com. Die Benutzergruppe der Verwaltungsebene gilt nur für Azure Resource Manager Vorgänge in der APIM-Ressource selbst.

Weitere Informationen zur Authentifizierung von Agents mit Microsoft Entra ID finden Sie unter Agent-Identität und -Authentifizierung.

Suchen und Überprüfen Ihrer Zielgruppe

Führen Sie die folgenden Schritte aus, um den richtigen Zielgruppenwert zu ermitteln und zu überprüfen:

  • Für Azure-Dienste: Überprüfen Sie die Dokumentation des Dienstes auf dessen Microsoft Entra ID-Ressourcenidentifikator. Die meisten Azure Dienste listen den Zielgruppen-URI in ihrer Authentifizierungsdokumentation auf.
  • Für APIs, die durch eine Microsoft Entra-App-Registrierung geschützt sind: Wechseln Sie im Azure-Portal zu Microsoft Entra ID>App-Registrierungen>, wählen Sie Ihre App aus, >API bereitstellen. Der Anwendungs-ID-URI oben auf der Seite ist Ihr Zielgruppenwert.
  • So überprüfen Sie die Zielgruppe eines Tokens: Decodieren Sie das Zugriffstoken bei https://jwt.ms und überprüfen Sie den aud Anspruch. Der aud Wert muss der Zielgruppe entsprechen, die Ihr Zieldienst erwartet.

Einrichten der verwalteten Identitätsauthentifizierung

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

  1. Stellen Sie sicher, dass für Ihre Foundry-Ressource die vom System zugewiesene verwaltete Identität aktiviert ist.

Screenshot des Azure Portals mit vom System zugewiesenen Einstellungen für verwaltete Identitäten.

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

    1. Wählen Sie Access Control 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 des Azure Portals mit der Aktion

    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.

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

Fehlerbehebung bei häufigen Problemen

Symptom Wahrscheinliche Ursache Auflösung
DER API-Schlüssel ist nicht in Anforderungen enthalten. OpenAPI-Spezifikation fehlt der securitySchemes oder security Abschnitt. Überprüfen Sie, ob Ihre OpenAPI-Spezifikation sowohl components.securitySchemes als auch einen Abschnitt auf oberster Ebene security 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 Werkzeugwahl ist nicht festgelegt oder operationId nicht aussagekräftig. Verwenden Sie tool_choice="required", um den Aufruf des 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.
Verwaltete Identität gibt 401 zurück, obwohl die Rolle zugewiesen ist. Der Zielgruppen-URI stimmt nicht mit dem überein, was der Zieldienst erwartet. Überprüfen Sie, ob der Zielgruppen-URI mit dem Ressourcenbezeichner des Zieldiensts übereinstimmt. Informationen zu Azure Diensten finden Sie in der Dienstdokumentation. Verwenden Sie für Microsoft Entra-geschützte APIs den Anwendungs-ID-URI aus Ihrer App-Registrierung. Dekodieren Sie das Token bei https://jwt.ms und bestätigen Sie die Übereinstimmung des aud-Anspruchs. Siehe "Grundlegendes zum Benutzergruppen-URI".
Verwaltetes Identitätstoken, das von der Ziel-API abgelehnt wurde. Der Zieldienst akzeptiert keine Microsoft Entra ID Token. Bestätigen Sie, dass der Zieldienst Microsoft Entra ID Authentifizierung unterstützt. Wenn dies nicht der Fall ist, verwende stattdessen einen API-Schlüssel oder ein Bearer Token zur Authentifizierung.
Anforderung schlägt mit 400 „Ungültige 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.
Der Fehler "Verbindung wurde nicht gefunden". Verbindungsname oder ID stimmt nicht überein. Überprüfen Sie, ob OPENAPI_PROJECT_CONNECTION_NAME mit dem Verbindungsnamen in Ihrem Foundry-Projekt ü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.

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 Einrichtungskomplexität
Anonym Öffentliche APIs ohne Authentifizierung Niedrig
API-Schlüssel Nicht Microsoft-APIs mit schlüsselbasiertem Zugriff Mittel
Verwaltete Identität Azure Dienste und von Microsoft Entra ID geschützte APIs. Erfordert, dass der Zieldienst Microsoft Entra ID Token akzeptiert und Azure RBAC oder Microsoft Entra basierte Zugriffssteuerung unterstützt. Mittel-Hoch

Verwandte Inhalte

  • Last updated on