Připojení agentů k nástrojům OpenAPI

Připojte agenty Microsoft Foundry k externím rozhraním API pomocí specifikací OpenAPI 3.0 a 3.1. Model Foundry, který pohání agenta, může volat externí služby, načítat data v reálném čase a rozšiřovat jeho možnosti nad rámec zabudovaných funkcí.

Specifikace OpenAPI definují standardní způsob popisu rozhraní HTTP API, abyste mohli integrovat stávající služby s vašimi agenty. Microsoft Foundry podporuje tři metody ověřování: anonymous, API key a managed identity. Nápovědu k volbě metody ověřování najdete v tématu Volba metody ověřování.

Podpora využití

Následující tabulka ukazuje podporu sady SDK a nastavení.

podpora Microsoft Foundry Python SDK C# SDK JavaScript SDK Java SDK REST API Základní nastavení agenta Nastavení standardního agenta
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Poznámka

Pro Java použijte balíček com.azure:azure-ai-agents pro nástroje agenta OpenAPI. Balíček com.azure:azure-ai-projects v současné době nezpřístupňuje typy nástrojů agenta OpenAPI.

Požadavky

Než začnete, ujistěte se, že máte:

  • Předplatné Azure se správnými oprávněními.
  • Role RBAC Azure: Přispěvatel nebo Vlastník projektu Foundry.
  • Projekt Foundry vytvořený s nakonfigurovaným koncovým bodem
  • Model AI nasazený ve vašem projektu
  • Základní nebo standardní prostředí agenta.
  • Sada SDK nainstalovaná pro preferovaný jazyk:
    • Python: azure-ai-projects
    • C#: Azure.AI.Extensions.OpenAI
    • TypeScript/JavaScript: @azure/ai-projects
    • Java: com.azure:azure-ai-agents

Proměnné prostředí

Proměnné Popis
FOUNDRY_PROJECT_ENDPOINT Adresa URL koncového bodu projektu Foundry (ne externí koncový bod služby OpenAPI).
FOUNDRY_MODEL_DEPLOYMENT_NAME Název vašeho nasazeného modelu.
OPENAPI_PROJECT_CONNECTION_NAME (Pro ověřování klíčů rozhraní API) Název připojení projektu pro službu OpenAPI.
  • Soubor specifikace OpenAPI 3.0 nebo 3.1, který splňuje tyto požadavky:
    • Každá funkce musí mít operationId (vyžadováno pro nástroj OpenAPI).
    • operationId by měla obsahovat pouze písmena, -a _.
    • Používejte popisné názvy, aby modely mohly efektivně rozhodnout, kterou funkci použít.
    • Podporované typy obsahu textu požadavku: application/json, application/json-patch+json
  • Pro ověřování spravované identity: Role čtenáře nebo vyšší u cílových prostředků služby.
  • Pro ověřování pomocí klíče nebo tokenu rozhraní API: připojení k projektu nakonfigurované s klíčem nebo tokenem rozhraní API. Viz Přidání nového připojení k projektu.

Poznámka

Hodnota FOUNDRY_PROJECT_ENDPOINT odkazuje na koncový bod projektu Microsoft Foundry, nikoli na externí koncový bod služby OpenAPI. Tento koncový bod najdete na portálu Microsoft Foundry na stránce Přehled projektu. Tento koncový bod je nutný k ověření služby agenta a je oddělený od všech koncových bodů OpenAPI definovaných v souboru specifikace.

Vysvětlení omezení

  • Specifikace OpenAPI musí obsahovat operationId pro každou operaci a operationId může obsahovat pouze písmena a -_.
  • Podporované typy obsahu textu požadavku: application/json, application/json-patch+json.
  • Pro ověřování klíčů rozhraní API použijte jedno schéma zabezpečení klíče rozhraní API na každý nástroj OpenAPI. Pokud potřebujete více schémat zabezpečení, vytvořte několik nástrojů OpenAPI.

Příklad kódu

Poznámka

  • Potřebujete nejnovější balíček sady SDK. Sada .NET SDK je aktuálně ve verzi Preview. Podrobnosti najdete v průvodci rychlým startem.
  • Pokud k ověřování používáte klíč rozhraní API, vaše ID připojení by mělo být ve formátu /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Důležité

Aby ověřování pomocí klíče rozhraní API fungovalo, musí soubor specifikace OpenAPI obsahovat:

  1. Oddíl securitySchemes s konfigurací klíče rozhraní API, například název hlavičky a název parametru.
  2. Oddíl security , který odkazuje na schéma zabezpečení.
  3. Připojení projektu je nakonfigurováno s odpovídajícím názvem klíče a jeho hodnotou.

Bez těchto konfigurací klíč rozhraní API není součástí požadavků. Podrobné pokyny k nastavení najdete v části Ověřování pomocí klíče rozhraní API .

Můžete také použít ověřování na základě tokenu (například nosný token) uložením tokenu do připojení k projektu. V případě ověřování nosným tokenem vytvořte připojení vlastních klíčů s klíčem nastaveným na Authorization a hodnotou na Bearer <token> (nahraďte <token> skutečným tokenem). Bearer Slovo následované mezerou musí být součástí hodnoty. Podrobnosti najdete v Nastavit připojení Bearer token.

Kompletní příklad

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"
OPENAPI_CONNECTION_NAME = "my-openapi-connection"

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

# 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.connections.get(OPENAPI_CONNECTION_NAME)
connection_id = openapi_connection.id

openapi_key_auth_tool = {
    "type": "openapi",
    "openapi": {
        "name": "get_weather",
        "spec": openapi_weather,  # 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": "get_weather",
        "description": "Retrieve weather information for a location.",
        "spec": openapi_weather,
        "auth": {
            "type": "managed_identity",
            "security_scheme": {
                "audience": "https://storage.azure.com"  # Resource identifier of the target service
            }
        },
    }
}

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)

Co tento kód dělá

Tento příklad vytvoří agenta s nástrojem OpenAPI, který volá API pro počasí wttr.in pomocí anonymního ověřování. Při spuštění kódu:

  1. Načte specifikaci OpenAPI počasí z místního souboru JSON.
  2. Vytvoří agenta s nástrojem pro počasí nakonfigurovaným pro anonymní přístup.
  3. Odešle dotaz s dotazem o počasí v Seattlu.
  4. Agent používá nástroj OpenAPI k volání rozhraní API pro počasí a vrací formátované výsledky.
  5. Program vyčistí odstraněním verze agenta.

Požadované vstupy

  • Řetězcové hodnoty v horní části skriptu: PROJECT_ENDPOINT, OPENAPI_CONNECTION_NAME
  • Místní soubor: weather_openapi.json (specifikace OpenAPI)

Očekávaný výstup

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

Běžné chyby

  • FileNotFoundError: V zadané cestě nebyl nalezen soubor specifikace OpenAPI.
  • AuthenticationError: Neplatné přihlašovací údaje nebo nedostatečná oprávnění nebo chybějící securitySchemes ve specifikaci OpenAPI pro ověřování klíčů rozhraní API
  • Neplatný operationId formát ve specifikaci OpenAPI způsobuje selhání registrace nástroje
  • Klíč rozhraní API nebyl vložen: Ověřte, že specifikace OpenAPI zahrnuje jak oddíl securitySchemes, tak oddíl security, a že název klíče odpovídá připojení k projektu.

Ukázka použití agentů s nástrojem OpenAPI

Tento příklad ukazuje, jak používat služby popsané specifikací OpenAPI pomocí agenta. Používá službu wttr.in k získání počasí a souboru specifikace weather_openapi.json. Vyberte Prompt Agents, chcete-li pomocí sady Azure AI Projects SDK vytvořit serverového agenta pro prompty, nebo Hosted Agents, chcete-li pomocí Microsoft Agent Framework vytvořit dočasného agenta v procesu.

Tento příklad používá synchronní metody klientské knihovny Azure AI Projects. Příklad s asynchronními metodami najdete v ukázce v úložišti Azure SDK pro .NET na GitHubu.

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);
    }
}

Co tento kód dělá

Tento příklad jazyka C# vytvoří agenta s nástrojem OpenAPI, který načte informace o počasí z wttr.in pomocí anonymního ověřování. Při spuštění kódu:

  1. Čte specifikaci OpenAPI počasí z místního souboru JSON.
  2. Vytvoří agenta s nakonfigurovaným nástrojem pro počasí.
  3. Odešle žádost o počasí v Seattlu pomocí nástroje OpenAPI.
  4. Agent volá API pro počasí a vrací výsledky.
  5. Vyčištění je provedeno odstraněním agenta.

Požadované vstupy

  • Hodnota vloženého řetězce: projectEndpoint (koncový bod projektu Foundry)
  • Místní soubor: Assets/weather_openapi.json (specifikace OpenAPI)

Očekávaný výstup

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

Běžné chyby

  • FileNotFoundException: Soubor specifikace OpenAPI nebyl ve složce Assets nalezen.
  • UnauthorizedAccessException: Neplatné přihlašovací údaje nebo nedostatečná oprávnění RBAC
  • Klíč API nebyl vložen: Ověřte, že specifikace OpenAPI obsahuje jak securitySchemes (v components), tak i security v oddílech s odpovídajícími názvy schémat.

Ukázka použití agentů s nástrojem OpenAPI ve webové službě, která vyžaduje ověření

V tomto příkladu použijete služby se specifikací OpenAPI pomocí agenta ve scénáři, který vyžaduje ověření. Použijete specifikaci TripAdvisoru.

Služba TripAdvisor vyžaduje ověřování na základě klíčů. Pokud chcete vytvořit připojení na portálu Azure, otevřete Microsoft Foundry a na levém panelu vyberte Centra správy a pak vyberte Připojené prostředky. Nakonec vytvořte nové připojení typu Vlastní klíče . Pojmenujte ho tripadvisor a přidejte pár hodnot klíče. Přidejte klíč s názvem key a zadejte hodnotu s klíčem TripAdvisoru.

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 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(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.
        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 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);
    }
}

Co tento kód dělá

Tento příklad jazyka C# ukazuje použití nástroje OpenAPI s ověřováním pomocí klíče rozhraní API prostřednictvím připojení projektu. Při spuštění kódu:

  1. Načte specifikaci OpenAPI webu TripAdvisor z místního souboru.
  2. tripadvisor Načte připojení projektu obsahující klíč rozhraní API.
  3. Vytvoří agenta s nástrojem TripAdvisor nakonfigurovaným pro ověřování pomocí připojení.
  4. Odešle žádost o hotelová doporučení v Paříži.
  5. Agent volá rozhraní API TripAdvisoru pomocí uloženého klíče rozhraní API a vrací výsledky.
  6. Vyčištění je provedeno odstraněním agenta.

Požadované vstupy

  • Hodnota vloženého řetězce: projectEndpoint (koncový bod projektu Foundry)
  • Místní soubor: Assets/tripadvisor_openapi.json
  • Projektové připojení: tripadvisor s platným nakonfigurovaným klíčem rozhraní API

Očekávaný výstup

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

Běžné chyby

  • ConnectionNotFoundException: Nebylo nalezeno žádné připojení k projektu s názvem tripadvisor.
  • AuthenticationException: Neplatný klíč rozhraní API v připojení k projektu nebo chybějící nebo nesprávná securitySchemes konfigurace ve specifikaci OpenAPI.
  • Nástroj se nepoužívá: Ověřte ToolChoice = ResponseToolChoice.CreateRequiredChoice() použití nástroje.
  • Klíč rozhraní API nebyl předán: Ujistěte se, že specifikace OpenAPI a její securitySchemes oddíly security jsou správně nakonfigurovány.

Vytvoření agenta Java s možnostmi nástroje OpenAPI

Tento Java příklad vytvoří agenta s nástrojem OpenAPI pomocí com.azure:azure-ai-agents a místního souboru specifikace OpenAPI. Ukázka používá anonymní ověřování a volá koncový bod veřejného rozhraní API.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.ConversationsClient;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.*;
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.Paths;
import java.util.Arrays;
import java.util.Map;

public class OpenApiAgentJavaSample {
    public static void main(String[] args) throws Exception {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        String projectEndpoint = "your_project_endpoint";

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .endpoint(projectEndpoint)
            .credential(new DefaultAzureCredentialBuilder().build());

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

        Map<String, BinaryData> spec = OpenApiFunctionDefinition.readSpecFromFile(
            Paths.get("openapi_spec.json"));

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

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-4.1-mini")
            .setInstructions("Use the OpenAPI tool for HTTP request metadata.")
            .setTools(Arrays.asList(new OpenApiTool(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.createAzureResponse(
                new AzureCreateResponseOptions().setAgentReference(agentReference),
                options.conversation(conversation.id()));

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

Co tento kód dělá

Tento Java příklad vytvoří agenta s nástrojem OpenAPI a spustí odpověď s oborem konverzace:

  1. Načte specifikaci OpenAPI z openapi_spec.json.
  2. Vytvoří verzi agenta s OpenApiTool.
  3. Vytvoří konverzaci a přidá zprávu uživatele.
  4. Vytvoří odpověď předáním AgentReference a ID konverzace.
  5. Program vyčistí odstraněním verze agenta.

Požadované vstupy

  • Hodnota vloženého řetězce: projectEndpoint (koncový bod projektu Foundry)
  • Místní soubor: openapi_spec.json (specifikace OpenAPI 3.0 nebo 3.1)

Očekávaný výstup

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

Běžné chyby

  • Invalid OpenAPI specification: Parsujte JSON OpenAPI do objektu před jeho předáním OpenApiFunctionDefinition.
  • Invalid conversation id: Vytvořte konverzaci a předejte conversation.id() ji createAzureResponse prostřednictvím ResponseCreateParams.builder().conversation().
  • AuthenticationFailedException: Ověřte, zda DefaultAzureCredential může získat token pro váš přihlášený účet.

Následující příklady ukazují, jak volat nástroj OpenAPI pomocí rozhraní REST API.

Získání přístupového tokenu:

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

Anonymní ověřování

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

Ověřování klíče rozhraní API (připojení k projektu)

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

Ověřování spravované identity

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

Co tento kód dělá

Tento příklad rozhraní REST API ukazuje, jak volat nástroj OpenAPI s různými metodami ověřování. Požadavek:

  1. Pošle agentovi dotaz na počasí v Seattlu.
  2. Obsahuje definici nástroje OpenAPI v souladu se specifikací rozhraní API pro počasí.
  3. Zobrazuje tři možnosti ověřování (anonymní klíč rozhraní API prostřednictvím připojení k projektu, spravovaná identita) jako okomentované alternativy.
  4. Agent používá nástroj k volání rozhraní API pro počasí a vrací formátované výsledky.

Požadované vstupy

  • Proměnné prostředí: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN. FOUNDRY_MODEL_DEPLOYMENT_NAME
  • Pro autentizaci pomocí klíče API: WEATHER_APP_PROJECT_CONNECTION_ID.
  • Pro ověřování spravované identity: MANAGED_IDENTITY_AUDIENCE.
  • Vložená specifikace OpenAPI v textu požadavku.

Očekávaný výstup

{
  "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)..."
        }
      ]
    }
  ]
}

Běžné chyby

  • 401 Unauthorized: Neplatný nebo chybějící AGENT_TOKEN, nebo klíč rozhraní API není vložen, protože securitySchemes a security chybí ve specifikaci OpenAPI.
  • 404 Not Found: Nesprávný koncový bod nebo název nasazení modelu
  • 400 Bad Request: Poškozená specifikace OpenAPI nebo neplatná konfigurace ověřování
  • Klíč rozhraní API nebyl odeslán s požadavkem: Ověřte, že je oddíl ve specifikaci OpenAPI správně nakonfigurován (není prázdný) a shoduje se s názvem klíče připojení projektu.

Vytvoření agenta s možnostmi nástrojů OpenAPI

Následující příklad kódu TypeScript ukazuje, jak vytvořit agenta AI s funkcemi nástroje OpenAPI pomocí OpenApiTool a synchronního klienta projektu Azure AI. Agent může volat externí rozhraní API definovaná specifikacemi OpenAPI. Verzi JavaScriptu tohoto příkladu najdete v GitHub v sample v úložišti Azure SDK pro JavaScript.

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

  // Create an agent with the OpenAPI weather 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: [createWeatherTool(weatherSpec)],
  });

  // 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: { 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);
});

Co tento kód dělá

Tento příklad TypeScriptu vytvoří agenta s nástrojem OpenAPI pro data o počasí pomocí anonymního ověřování. Při spuštění kódu:

  1. Načte specifikaci OpenAPI počasí z místního souboru JSON.
  2. Vytvoří agenta s nakonfigurovaným nástrojem pro počasí.
  3. Odešle žádost o streamování s dotazem na počasí a plánování oblečení v Seattlu.
  4. Zpracuje streamovanou odpověď a zobrazí rozdíly při jejich příchodu.
  5. Vynutí použití nástroje s tool_choice: "required", aby se zajistilo volání API.
  6. Vyčištění je provedeno odstraněním agenta.

Požadované vstupy

  • Hodnota vloženého řetězce: PROJECT_ENDPOINT (koncový bod projektu Foundry)
  • Místní soubor: ../assets/weather_openapi.json (specifikace OpenAPI)

Očekávaný výstup

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!

Běžné chyby

  • Error: OpenAPI specification not found: Nesprávná cesta k souboru nebo chybějící soubor
  • AuthenticationError: Neplatné přihlašovací údaje Azure
  • Klíč rozhraní API nefunguje: Pokud přecházíte z anonymního na ověřování pomocí klíče rozhraní API, ujistěte se, že specifikace OpenAPI má securitySchemes a security správně nakonfigurovanou.

Vytvoření agenta, který používá nástroje OpenAPI ověřené pomocí připojení k projektu

Následující příklad kódu TypeScript ukazuje, jak vytvořit agenta AI, který používá nástroje OpenAPI ověřené prostřednictvím připojení projektu. Agent načte specifikaci OpenAPI webu TripAdvisor z místních prostředků a může vyvolat rozhraní API prostřednictvím nakonfigurovaného připojení projektu. Verzi JavaScriptu tohoto příkladu najdete v GitHub v sample v úložišti Azure SDK pro JavaScript.

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: { 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);
});

Co tento kód dělá

Tento příklad TypeScriptu ukazuje použití nástroje OpenAPI s ověřováním klíče rozhraní API prostřednictvím připojení projektu. Při spuštění kódu:

  1. Načte specifikaci OpenAPI webu TripAdvisor z místního souboru.
  2. Konfiguruje ověřování pomocí konstanty TRIPADVISOR_CONNECTION_ID .
  3. Vytvoří agenta pomocí nástroje TripAdvisor, který používá projektové připojení pro autentizaci klíčem API.
  4. Odešle žádost o streamování podrobností o poloze na TripAdvisor.
  5. Vynutí použití nástroje s tool_choice: "required", aby se zajistilo volání API.
  6. Zpracovává a zobrazuje streamovanou odpověď.
  7. Vyčistí se odstraněním agenta.

Požadované vstupy

  • Vložené řetězcové hodnoty: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
  • Místní soubor: ../assets/tripadvisor_openapi.json
  • Připojení projektu nakonfigurované pomocí klíče rozhraní API webu TripAdvisor

Očekávaný výstup

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!

Běžné chyby

  • Error: OpenAPI specification not found: Zkontrolujte cestu k souboru.
  • Připojení se nenašlo: Ověřte, zda TRIPADVISOR_CONNECTION_ID je správné a zda připojení existuje.
  • AuthenticationException: Neplatný klíč rozhraní API v připojení projektu.
  • Klíč rozhraní API nebyl vložen do požadavků: Specifikace OpenAPI musí obsahovat správné securitySchemes (v části components) a security sekce. Název securitySchemes klíče musí odpovídat klíči v připojení k projektu.
  • Content type is not supported: V současné době jsou podporovány pouze tyto dva typy obsahu textu požadavku: application/json a application/json-patch+json. Typy obsahu odpovědi nejsou omezeny.

Aspekty zabezpečení a dat

Když připojíte agenta k nástroji OpenAPI, může agent odesílat parametry požadavku odvozené ze vstupu uživatele do cílového rozhraní API.

  • Používejte připojení k projektům pro tajné kódy (klíče rozhraní API a tokeny). Vyhněte se vkládání tajných kódů do souboru specifikace OpenAPI nebo zdrojového kódu.
  • Než použijete nástroj v produkčním prostředí, zkontrolujte, jaká data rozhraní API přijímá a co vrací.
  • Použijte přístup s nejnižšími oprávněními. Pro spravovanou identitu přiřaďte jenom role, které cílová služba vyžaduje.

Ověřování pomocí klíče rozhraní API

Pomocí ověřování pomocí klíče rozhraní API můžete ověřit specifikaci OpenAPI pomocí různých metod, jako je klíč rozhraní API nebo nosný token. Pro každou specifikaci OpenAPI můžete použít pouze jedno schéma zabezpečení klíče rozhraní API. Pokud potřebujete více schémat zabezpečení, vytvořte několik nástrojů specifikace OpenAPI.

  1. Aktualizujte schémata zabezpečení specifikace OpenAPI. Má securitySchemes oddíl a jedno schéma typu apiKey. Příklad:

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

    Obvykle potřebujete pouze aktualizovat to pole name, které odpovídá názvu key v připojení. Pokud schémata zabezpečení obsahují více schémat, ponechejte pouze jedno z nich.

  2. Aktualizujte specifikaci OpenAPI tak, aby obsahovala security oddíl:

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

  3. Odeberte všechny parametry ve specifikaci OpenAPI, které potřebují klíč rozhraní API, protože klíč rozhraní API je uložený a předán prostřednictvím připojení, jak je popsáno dále v tomto článku.

  4. Vytvořte připojení pro uložení klíče rozhraní API.

  5. Přejděte na portál Foundry a otevřete projekt.

  6. Vytvořte nebo vyberte připojení, které ukládá tajný klíč. Viz Přidání nového připojení k projektu.

    Poznámka

    Pokud klíč rozhraní API znovu vygenerujete později, musíte připojení aktualizovat novým klíčem.

  7. Zadejte následující informace.

    • key: name pole vašeho schématu zabezpečení. V tomto příkladu by měl být x-api-key

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

    • hodnota: YOUR_API_KEY

  8. Po vytvoření připojení ho můžete použít prostřednictvím sady SDK nebo rozhraní REST API. Použijte karty v horní části stránky, abyste si mohli zobrazit příklady kódu.

Nastavit připojení pomocí Bearer tokenu

Můžete použít ověřování založené na tokenech (například nosný token) se stejným project_connection typem ověřování, který se používá pro klíče rozhraní API. Klíčovým rozdílem je způsob konfigurace specifikace OpenAPI i připojení projektu.

Specifikace OpenAPI bude vypadat takto:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Potřebujete:

  1. Aktualizujte specifikaci securitySchemes OpenAPI tak, aby se používala Authorization jako název hlavičky:

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

  2. security Přidejte oddíl, který odkazuje na schéma:

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

  3. Vytvořte připojení typu Custom Keys ve vašem projektu Foundry.

    1. Přejděte na portál Foundry a otevřete projekt.
    2. Vytvořte nebo vyberte připojení, které ukládá tajný klíč. Viz Přidání nového připojení k projektu.
    3. Zadejte následující hodnoty:
      • key: Authorization (musí odpovídat name poli ve vašem securitySchemes)
      • value: Bearer <token> (nahraďte <token> skutečným tokenem)

    Důležité

    Hodnota musí obsahovat slovo Bearer následované mezerou před tokenem. Příklad: Bearer eyJhbGciOiJSUzI1NiIs.... Pokud vynecháte Bearer , rozhraní API obdrží nezpracovaný token bez požadované předpony schématu autorizace a požadavek selže.

  4. Po vytvoření připojení ho použijte s project_connection typem ověřování v kódu stejným způsobem jako pro ověřování klíčů rozhraní API. ID připojení používá stejný formát: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Ověřování pomocí spravované identity (Microsoft Entra ID)

Microsoft Entra ID je cloudová služba pro správu identit a přístupu, kterou vaši zaměstnanci můžou použít pro přístup k externím prostředkům. Pomocí Microsoft Entra ID můžete do rozhraní API přidat další zabezpečení, aniž byste museli používat klíče rozhraní API. Když nastavíte ověřování spravované identity, agent se ověří pomocí nástroje Foundry, který používá.

Důležité

Ověřování spravované identity funguje jenom v případech, kdy cílová služba přijímá Microsoft Entra ID tokeny. Pokud cílové rozhraní API používá vlastní schéma ověřování, které nepodporuje Microsoft Entra ID, použijte místo toho ověřování pomocí klíče API nebo tokenu Bearer.

Pochopení identifikátoru URI cílové skupiny

Identifikátor audience (někdy označovaný jako identifikátor zdroje nebo URI ID aplikace) říká Microsoft Entra ID, která služba nebo API je cílem tokenu. Hodnota cílové skupiny musí odpovídat tomu, co cílová služba očekává, nebo ověřování selže s chybou 401.

Poznámka

Cílová skupina není vaším koncovým bodem projektu Foundry. Jedná se o identifikátor prostředku cílové služby, kterou nástroj OpenAPI volá.

Následující tabulka uvádí identifikátory URI cílové skupiny pro běžné služby Azure:

Cílová služba Identifikátor URI cílové skupiny
Azure Storage https://storage.azure.com
Azure Key Vault https://vault.azure.net
Azure AI Vyhledávač https://search.azure.com
Azure Logic Apps https://logic.azure.com
Azure API Management (správní vrstva) https://management.azure.com
Rozhraní API chráněné registrací aplikace Microsoft Entra (včetně rozhraní APIM s OAuth) Identifikátor URI ID aplikace z registrace aplikace (napříkladapi://<client-id>)

Tip

Pokud používáte Azure API Management k ochraně vlastního rozhraní API pomocí zásad ověřování OAuth 2.0, cílová skupina je identifikátor URI ID aplikace z registrace aplikace, která chrání rozhraní API – nikoli https://management.azure.com. Cílová skupina úrovně správy se vztahuje pouze na operace Azure Resource Manageru na samotném prostředku APIM.

Další informace o tom, jak se agenti ověřují pomocí Microsoft Entra ID, najdete v tématu Identita a ověřování agentů.

Vyhledání a ověření cílové skupiny

Pomocí následujících kroků určete a ověřte správnou hodnotu cílové skupiny:

  • Pro služby Azure: Zkontrolujte dokumentaci služby pro identifikátor prostředku Microsoft Entra ID. Většina služeb Azure uvádí identifikátor URI cílové skupiny v dokumentaci k ověřování.
  • Pro rozhraní API chráněná registrací aplikace Microsoft Entra: Na portálu Azure přejděte na Microsoft Entra ID>, Registrace aplikace>, vyberte svou aplikaci > a zpřístupněte API. Identifikátor URI ID aplikace v horní části stránky je hodnota cílové skupiny.
  • Ověření cílové skupiny tokenu: Dekódujte přístupový token https://jwt.ms a zkontrolujte aud deklaraci identity. Hodnota aud musí odpovídat cílové skupině, kterou vaše cílová služba očekává.

Nastavení ověřování spravovaných identit

Nastavení ověřování pomocí spravované identity:

  1. Ujistěte se, že váš prostředek Foundry má povolenou spravovanou identitu přiřazenou systémem.

    Snímek obrazovky znázorňující selektor spravované identity na Azure portálu.

  2. Vytvořte prostředek pro službu, ke které se chcete připojit prostřednictvím specifikace OpenAPI.

  3. Přiřaďte k prostředku správný přístup.

    1. Vyberte Access Control pro váš zdroj.

    2. Vyberte Přidat a potom přidejte přiřazení role v horní části obrazovky.

      Snímek obrazovky zobrazující výběr přiřazení role na portálu Azure.

    3. Vyberte požadované správné přiřazení role, obvykle vyžaduje alespoň roli ČTENÁŘ . Pak vyberte Další.

    4. Vyberte Spravovanou identitu a pak vyberte členy.

    5. V rozevírací nabídce spravované identity vyhledejte Účet Foundry a pak vyberte účet Foundry vašeho agenta.

    6. Vyberte Dokončit.

  4. Po dokončení instalace můžete pokračovat pomocí nástroje prostřednictvím portálu Foundry, sady SDK nebo rozhraní REST API. Pomocí karet v horní části tohoto článku zobrazíte ukázky kódu.

Řešení běžných chyb

Příznak Pravděpodobná příčina Rozlišení
Klíč rozhraní API není součástí požadavků. Chybí sekce securitySchemes nebo security ve specifikaci OpenAPI. Ověřte, že specifikace OpenAPI obsahuje oddíl components.securitySchemes i oddíl nejvyšší úrovně security . Ujistěte se, že schéma name odpovídá názvu klíče v připojení k projektu.
Agent nevolá nástroj OpenAPI. Volba nástroje není nastavena nebo operationId není popisná. Použijte tool_choice="required" pro vynucení vyvolání nástroje. Ujistěte se operationId , že hodnoty jsou popisné, aby model mohl zvolit správnou operaci.
Ověřování pro spravovanou identitu se nezdařilo. Spravovaná identita není povolená nebo chybí přiřazení role. Povolte spravovanou identitu přiřazenou systémem pro váš prostředek Foundry. Přiřaďte požadovanou roli (Čtenář nebo vyšší) na cílovou službu.
Spravovaná identita vrací hodnotu 401, i když je přiřazená role. Identifikátor URI cílové skupiny neodpovídá tomu, co cílová služba očekává. Ověřte, že identifikátor URI cílové skupiny odpovídá identifikátoru prostředku cílové služby. Informace o Azure službách najdete v dokumentaci ke službě. Pro rozhraní API chráněná službou Microsoft Entra použijte identifikátor URI ID aplikace z registrace vaší aplikace. Dekódujte token na https://jwt.ms a potvrďte, že nárok aud odpovídá. Viz Vysvětlení identifikátoru URI cílové skupiny.
Token spravované identity odmítnutý cílovým rozhraním API Cílová služba nepřijímá tokeny Microsoft Entra ID. Ověřte, že cílová služba podporuje ověřování Microsoft Entra ID. Pokud ne, použijte místo toho klíč rozhraní API nebo ověřování pomocí přenosového tokenu.
Požadavek selže s chybou 400 Chybný požadavek. Specifikace OpenAPI neodpovídá skutečnému rozhraní API. Ověřte specifikaci OpenAPI vůči skutečnému rozhraní API. Zkontrolujte názvy parametrů, typy a povinná pole.
Požadavek selže s chybou 401 Neautorizováno. Klíč rozhraní API nebo token je neplatný nebo vypršela jeho platnost. Znovu vygenerujte klíč nebo token rozhraní API a aktualizujte připojení k projektu. Ověřte správnost ID připojení.
Nástroj vrátí neočekávaný formát odpovědi. Schéma odpovědi není definováno ve specifikaci OpenAPI. Přidejte schémata odpovědí do specifikace OpenAPI, abyste lépe porozuměli modelu.
operationId chyba ověření. Neplatné znaky v operationId. Používejte pouze písmena -a _ v operationId hodnotách. Odeberte čísla a speciální znaky.
Chyba: Připojení nebylo nalezeno. Neshoda názvu nebo ID připojení Ověřte, že OPENAPI_PROJECT_CONNECTION_NAME odpovídá názvu připojení v projektu Foundry.
Nosný token se neodesílal správně. Chybí předpona Bearer u hodnoty připojení. Nastavte hodnotu připojení na Bearer <token> (se slovem Bearer a mezerou před tokenem). Ověřte, že specifikace securitySchemes OpenAPI používá "name": "Authorization".

Volba metody ověřování

Následující tabulka vám pomůže zvolit správnou metodu ověřování pro nástroj OpenAPI:

Metoda ověřování Nejlepší pro Složitost nastavení
Anonymní Veřejná rozhraní API bez ověřování Nízké
klíč rozhraní API Rozhraní API jiná než Microsoft s přístupem na základě klíčů Střední
Spravovaná identita Služby Azure a rozhraní API chráněná pomocí Microsoft Entra ID. Vyžaduje, aby cílová služba přijímala tokeny Microsoft Entra ID a podporovala řízení přístupu na základě role v Azure nebo přístupové řízení založené na Microsoft Entra. Středně vysoká

Související obsah

  • Last updated on