Partage via

Connecter des agents aux outils OpenAPI

Connectez vos agents Microsoft Foundry aux API externes à l’aide des spécifications OpenAPI 3.0 et 3.1. Les agents qui se connectent aux outils OpenAPI peuvent appeler des services externes, récupérer des données en temps réel et étendre leurs fonctionnalités au-delà des fonctions intégrées.

Les spécifications OpenAPI définissent un moyen standard de décrire les API HTTP afin de pouvoir intégrer des services existants à vos agents. Microsoft Foundry prend en charge trois méthodes d’authentification : anonymous, API keyet managed identity. Pour obtenir de l’aide sur le choix d’une méthode d’authentification, consultez Choisir une méthode d’authentification.

Assistance à l'utilisation

✔️ (GA) indique une disponibilité générale, ✔️ (préversion) indique un aperçu public et un tiret (-) indique que la fonctionnalité n’est pas disponible.

Support de Microsoft Foundry SDK Python Kit de développement logiciel (SDK) C# Kit de développement logiciel (SDK) JavaScript Kit de développement logiciel (SDK) Java API REST Configuration d’agent de base Configuration d’agent standard
✔️ ✔️ (GA) ✔️ (Préversion) ✔️ (GA) ✔️ (Préversion) ✔️ (GA) ✔️ ✔️

Note

Pour Java, utilisez le package com.azure:azure-ai-agents pour les outils de l’agent OpenAPI. Le com.azure:azure-ai-projects package n’expose actuellement pas les types d’outils de l’agent OpenAPI.

Prerequisites

Avant de commencer, assurez-vous d’avoir :

  • Un abonnement Azure disposant des autorisations appropriées.
  • rôle RBAC Azure : Contributeur ou Propriétaire dans le projet Foundry.
  • Projet Foundry créé avec un point de terminaison configuré.
  • Modèle IA déployé dans votre projet.
  • Environnement d’agent de base ou standard.
  • Kit de développement logiciel (SDK) installé pour votre langue préférée :
    • Python : azure-ai-projects
    • C# : Azure.AI.Extensions.OpenAI (version préliminaire)
    • TypeScript/JavaScript : @azure/ai-projects
    • Java : com.azure:azure-ai-agents (préversion)

Variables d'environnement

Variable Descriptif
FOUNDRY_PROJECT_ENDPOINT URL du point de terminaison de votre projet Foundry (pas le point de terminaison de service OpenAPI externe).
FOUNDRY_MODEL_DEPLOYMENT_NAME Nom de votre modèle déployé.
OPENAPI_PROJECT_CONNECTION_NAME (Pour l’authentification de clé API) Nom de connexion de votre projet pour le service OpenAPI.
  • Fichier de spécification OpenAPI 3.0 ou 3.1 qui répond aux exigences suivantes :
    • Chaque fonction doit avoir un operationId (requis pour l’outil OpenAPI).
    • operationId ne doit contenir que des lettres, -et _.
    • Utilisez des noms descriptifs pour aider les modèles à choisir efficacement la fonction à utiliser.
    • Types de contenu du corps de la requête pris en charge : application/json, application/json-patch+json
  • Pour l’authentification par identité managée : rôle Lecteur ou supérieur sur les ressources du service cible.
  • Pour l’authentification par clé/jeton d’API : connexion de projet configurée avec votre clé d’API ou votre jeton. Consultez Ajouter une nouvelle connexion à votre projet.

Note

La FOUNDRY_PROJECT_ENDPOINT valeur fait référence à votre point de terminaison de projet Microsoft Foundry, et non au point de terminaison de service OpenAPI externe. Vous trouverez ce point de terminaison dans le portail Microsoft Foundry sous la page Vue d’ensemble de votre projet. Ce point de terminaison est requis pour authentifier le service d’agent et est distinct de tous les points de terminaison OpenAPI définis dans votre fichier de spécification.

Comprendre les limitations

  • Votre spécification OpenAPI doit inclure operationId pour chaque opération et operationId peut inclure uniquement des lettres, -et _.
  • Types de contenu du corps de la demande pris en charge : application/json, application/json-patch+json.
  • Pour l’authentification par clé API, utilisez un schéma de sécurité de clé API par outil OpenAPI. Si vous avez besoin de plusieurs schémas de sécurité, créez plusieurs outils OpenAPI.

Exemple de code

Note

  • Vous avez besoin du dernier package sdk. Les sdk .NET et Java sont actuellement en préversion. Pour plus d’informations, consultez le guide de démarrage rapide .
  • Si vous utilisez la clé API pour l’authentification, votre ID de connexion doit être au format ./subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}

Important

Pour que l’authentification par clé API fonctionne, votre fichier de spécification OpenAPI doit inclure :

  1. Section securitySchemes avec votre configuration de clé API, telle que le nom d’en-tête et le nom du paramètre.
  2. Section security qui fait référence au schéma de sécurité.
  3. Connexion de projet configurée avec le nom et la valeur de clé correspondants.

Sans ces configurations, la clé API n’est pas incluse dans les requêtes. Pour obtenir des instructions d’installation détaillées, consultez la section Authentifier avec la clé API .

Vous pouvez également utiliser l’authentification basée sur les jetons (par exemple, un jeton du porteur) en stockant le jeton dans une connexion de projet. Pour l’authentification par jeton porteur, créez une connexion de clés personnalisées avec la clé définie sur Authorization et la valeur définie sur Bearer <token> (remplacez <token> par votre jeton réel). Le mot Bearer suivi d’un espace doit être inclus dans la valeur. Pour plus d’informations, consultez Configurer une connexion avec jeton d'authentification.

Exemple complet

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

Ce que fait ce code

Cet exemple crée un agent avec un outil OpenAPI qui appelle l’API météo wttr.in à l’aide de l’authentification anonyme. Lorsque vous exécutez le code :

  1. Il charge la spécification OpenAPI météorologique à partir d’un fichier JSON local.
  2. Crée un agent avec l’outil météo configuré pour l’accès anonyme.
  3. Envoie une requête demandant la météo de Seattle.
  4. L’agent utilise l’outil OpenAPI pour appeler l’API météo et retourne les résultats mis en forme.
  5. Nettoie en supprimant la version de l’agent.

Entrées requises

  • Valeurs de chaîne en haut du script : PROJECT_ENDPOINT, OPENAPI_CONNECTION_NAME
  • Fichier local : weather_openapi.json (spécification OpenAPI)

Sortie attendue

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

Erreurs courantes

  • FileNotFoundError: fichier de spécification OpenAPI introuvable au chemin d’accès spécifié
  • AuthenticationError: informations d’identification non valides ou autorisations insuffisantes ou manquantes securitySchemes dans les spécifications OpenAPI pour l’authentification par clé API
  • Le format non valide operationId dans les spécifications OpenAPI provoque l’échec de l’inscription de l’outil
  • Clé API non injectée : vérifiez que votre spécification OpenAPI inclut les deux securitySchemes et security les sections, et que le nom de clé correspond à votre connexion de projet

Exemple d’utilisation d’agents avec l’outil OpenAPI

Cet exemple montre comment utiliser des services décrits par une spécification OpenAPI à l’aide d’un agent. Il utilise le service wttr.in pour obtenir la météo et son fichier de spécification weather_openapi.json. Cet exemple utilise des méthodes synchrones de la bibliothèque cliente Azure AI Projects. Pour obtenir un exemple qui utilise des méthodes asynchrones, consultez le sample dans le Azure SDK pour .NET référentiel sur 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.
        PromptAgentDefinition agentDefinition = new(model: "gpt-5-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

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

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

Ce que fait ce code

Cet exemple C# crée un agent avec un outil OpenAPI qui récupère les informations météorologiques de wttr.in à l’aide de l’authentification anonyme. Lorsque vous exécutez le code :

  1. Il lit la spécification OpenAPI météorologique à partir d’un fichier JSON local.
  2. Crée un agent avec l’outil météo configuré.
  3. Envoie une demande demandant la météo de Seattle à l’aide de l’outil OpenAPI.
  4. L’agent appelle l’API météo et retourne les résultats.
  5. Nettoie en supprimant l’agent.

Entrées requises

  • Valeur de chaîne inline : projectEndpoint (point de terminaison de votre projet Foundry)
  • Fichier local : Assets/weather_openapi.json (spécification OpenAPI)

Sortie attendue

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

Erreurs courantes

  • FileNotFoundException: Fichier de spécification OpenAPI introuvable dans le dossier Assets
  • UnauthorizedAccessException: informations d’identification non valides ou autorisations RBAC insuffisantes
  • Clé API non injectée : vérifiez que votre spécification OpenAPI inclut à la fois securitySchemes (en components) et security les sections avec des noms de schéma correspondants

Exemple d’utilisation d’agents avec l’outil OpenAPI sur le service web, nécessitant une authentification

Dans cet exemple, vous utilisez des services avec une spécification OpenAPI à l’aide de l’agent dans un scénario nécessitant une authentification. Vous utilisez la spécification TripAdvisor.

Le service Trip Advisor nécessite une authentification basée sur des clés. Pour créer une connexion dans le portail Azure, ouvrez Microsoft Foundry et, dans le volet gauche, sélectionnez Centre de gestion puis sélectionnez Ressources connectées. Enfin, créez une connexion de type Clés personnalisées. Nommez-le tripadvisor et ajoutez une paire clé-valeur. Ajoutez une clé nommée key et entrez une valeur avec votre clé Trip Advisor.

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.
        PromptAgentDefinition agentDefinition = new(model: "gpt-5-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

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

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

Ce que fait ce code

Cet exemple C# illustre l’utilisation d’un outil OpenAPI avec l’authentification par clé API via une connexion de projet. Lorsque vous exécutez le code :

  1. Il charge la spécification TripAdvisor OpenAPI à partir d’un fichier local.
  2. Récupère la connexion projet tripadvisor contenant votre clé API.
  3. Crée un agent avec l'outil TripAdvisor configuré pour utiliser la connexion pour l'authentification.
  4. Envoie une demande de recommandations d’hôtel à Paris.
  5. L’agent appelle l’API Trip Advisor à l’aide de votre clé API stockée et retourne les résultats.
  6. Nettoie en supprimant l’agent.

Entrées requises

  • Valeur de chaîne inline : projectEndpoint (point de terminaison de votre projet Foundry)
  • Fichier local : Assets/tripadvisor_openapi.json
  • Connexion de projet : tripadvisor avec une clé API valide configurée

Sortie attendue

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

Erreurs courantes

  • ConnectionNotFoundException: Aucune connexion de projet nommée tripadvisor trouvée.
  • AuthenticationException: clé API non valide dans la connexion de projet, ou configuration manquante/incorrecte securitySchemes dans la spécification OpenAPI.
  • Outil non utilisé : assurez-vous que ToolChoice = ResponseToolChoice.CreateRequiredChoice() impose l'utilisation de l'outil.
  • Clé API non transmise à l’API : vérifiez que la spécification OpenAPI a des sections appropriées securitySchemes et security configurées.

Créer un agent Java avec des fonctionnalités d’outil OpenAPI

Cet exemple Java crée un agent avec un outil OpenAPI à l’aide de com.azure:azure-ai-agents et d’un fichier de spécification OpenAPI local. L’exemple utilise l’authentification anonyme et appelle un point de terminaison d’API public.

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-5-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.createWithAgentConversation(agentReference, conversation.id(), options);

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

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

Ce que fait ce code

Cet exemple Java crée un agent avec un outil OpenAPI et exécute une réponse étendue à une conversation :

  1. Charge la spécification OpenAPI à partir de openapi_spec.json.
  2. Crée une version de l’agent avec OpenApiTool.
  3. Crée une conversation et ajoute un message utilisateur.
  4. Crée une réponse en passant AgentReference et l'identifiant de conversation.
  5. Nettoie en supprimant la version de l’agent.

Entrées requises

  • Valeur de chaîne inline : projectEndpoint (point de terminaison de votre projet Foundry)
  • Fichier local : openapi_spec.json (spécification OpenAPI 3.0 ou 3.1)

Sortie attendue

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

Erreurs courantes

  • Invalid OpenAPI specification: analysez le json OpenAPI dans un objet avant de le passer à OpenApiFunctionDefinition.
  • Invalid conversation id: Créer une conversation et passer conversation.id() à createWithAgentConversation.
  • AuthenticationFailedException : vérifiez que DefaultAzureCredential peut obtenir un jeton pour votre compte connecté.

Les exemples suivants montrent comment appeler un outil OpenAPI à l’aide de l’API REST.

Obtenez un jeton d’accès :

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

Authentification anonyme

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

Authentification par clé API (connexion de projet)

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

Authentification d'une identité gérée

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

Ce que fait ce code

Cet exemple d’API REST montre comment appeler un outil OpenAPI avec différentes méthodes d’authentification. Requête :

  1. Envoie une requête à l’agent en demandant la météo de Seattle.
  2. Inclut la définition de l’outil OpenAPI conformément à la spécification de l’API météo.
  3. Affiche trois options d’authentification (anonyme, clé API via la connexion de projet, identité managée) comme alternatives commentées.
  4. L’agent utilise l’outil pour appeler l’API météo et retourner des résultats mis en forme.

Entrées requises

  • Variables d’environnement : FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
  • Pour l’authentification de clé API : WEATHER_APP_PROJECT_CONNECTION_ID.
  • Pour l’authentification d’identité managée : MANAGED_IDENTITY_AUDIENCE.
  • Spécification OpenAPI intégrée dans le corps de la requête.

Sortie attendue

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

Erreurs courantes

  • 401 Unauthorized: non valide ou AGENT_TOKEN manquant, ou clé API non injectée car securitySchemes et security sont manquants dans votre spécification OpenAPI
  • 404 Not Found: nom de déploiement de modèle ou de point de terminaison incorrect
  • 400 Bad Request: Spécification OpenAPI incorrecte ou configuration d’authentification non valide
  • Clé API non envoyée avec demande : vérifiez que la components.securitySchemes section de votre spécification OpenAPI est correctement configurée (pas vide) et correspond au nom de la clé de connexion de votre projet.

Créer un agent avec des fonctionnalités d’outil OpenAPI

L'exemple de code TypeScript suivant montre comment créer un agent IA doté des capacités de l'outil OpenAPI à l'aide du client Azure AI Projects synchrone OpenApiTool. L’agent peut appeler des API externes définies par les spécifications OpenAPI. Pour obtenir une version JavaScript de cet exemple, consultez l'sample dans le Azure SDK pour le référentiel JavaScript sur GitHub.

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

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

Ce que fait ce code

Cet exemple TypeScript crée un agent avec un outil OpenAPI pour les données météorologiques à l’aide de l’authentification anonyme. Lorsque vous exécutez le code :

  1. Il charge la spécification OpenAPI météorologique à partir d’un fichier JSON local.
  2. Crée un agent avec l’outil météo configuré.
  3. Envoie une demande de diffusion en flux concernant la météo de Seattle et la préparation de tenue.
  4. Traite la réponse de streaming et affiche les deltas au fur et à mesure de leur arrivée.
  5. Il force l’utilisation de l’outil en utilisant tool_choice: "required" pour s’assurer que l’API est appelée.
  6. Nettoie en supprimant l’agent.

Entrées requises

  • Valeur de chaîne inline : PROJECT_ENDPOINT (point de terminaison de votre projet Foundry)
  • Fichier local : ../assets/weather_openapi.json (spécification OpenAPI)

Sortie attendue

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!

Erreurs courantes

  • Error: OpenAPI specification not found: chemin d’accès du fichier incorrect ou fichier manquant
  • AuthenticationError : informations d’identification de Azure non valides
  • Clé API qui ne fonctionne pas : si vous passez de l'authentification anonyme à l'authentification par clé API, assurez-vous que votre spécification OpenAPI comporte securitySchemes et security correctement configurés

Créer un agent qui utilise des outils OpenAPI authentifiés avec une connexion de projet

L’exemple de code TypeScript suivant montre comment créer un agent IA qui utilise des outils OpenAPI authentifiés via une connexion de projet. L’agent charge la spécification Trip Advisor OpenAPI à partir de ressources locales et peut appeler l’API via la connexion de projet configurée. Pour obtenir une version JavaScript de cet exemple, consultez l'sample dans le Azure SDK pour le référentiel JavaScript sur GitHub.

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

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

Ce que fait ce code

Cet exemple TypeScript illustre l’utilisation d’un outil OpenAPI avec l’authentification par clé API via une connexion de projet. Lorsque vous exécutez le code :

  1. Il charge la spécification TripAdvisor OpenAPI à partir d’un fichier local.
  2. Il configure l’authentification à l’aide de la TRIPADVISOR_CONNECTION_ID constante.
  3. Il crée un agent avec l'application TripAdvisor utilisant la connexion du projet pour l'authentification à l'aide d'une clé API.
  4. Il envoie une demande de streaming pour les détails de l’emplacement TripAdvisor.
  5. Il force l’utilisation de l’outil en utilisant tool_choice: "required" pour s’assurer que l’API est appelée.
  6. Il traite et affiche la réponse de streaming.
  7. Il effectue un nettoyage en supprimant l’agent.

Entrées requises

  • Valeurs de chaîne en ligne : PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
  • Fichier local : ../assets/tripadvisor_openapi.json
  • Connexion de projet configurée avec la clé API Trip Advisor

Sortie attendue

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!

Erreurs courantes

  • Error: OpenAPI specification not found: vérifiez le chemin du fichier.
  • Connexion introuvable : vérifiez TRIPADVISOR_CONNECTION_ID que la connexion est correcte et qu’elle existe.
  • AuthenticationException: clé API non valide dans la connexion de projet.
  • Clé API non injectée dans les requêtes : votre spécification OpenAPI doit inclure des sections securitySchemes, components et security appropriées. Le nom de clé dans securitySchemes doit correspondre à la clé dans votre connexion de projet.
  • Content type is not supported: Actuellement, seuls ces deux types de contenu de corps de requête sont pris en charge : application/json et application/json-patch+json. Les types de contenu de réponse ne sont pas limités.

Considérations relatives à la sécurité et aux données

Lorsque vous connectez un agent à un outil OpenAPI, l’agent peut envoyer des paramètres de requête dérivés de l’entrée utilisateur à l’API cible.

  • Utilisez des connexions de projet pour les secrets (clés API et jetons). Évitez de placer des secrets dans un fichier de spécification OpenAPI ou du code source.
  • Passez en revue les données reçues par l’API et ce qu’elle retourne avant d’utiliser l’outil en production.
  • Utilisez l’accès avec des privilèges minimum. Pour l’identité managée, affectez uniquement les rôles dont le service cible a besoin.

S’authentifier avec la clé API

En utilisant l’authentification par clé API, vous pouvez authentifier votre spécification OpenAPI à l’aide de différentes méthodes telles qu’une clé API ou un jeton porteur. Vous ne pouvez utiliser qu’un seul schéma de sécurité de clé API par spécification OpenAPI. Si vous avez besoin de plusieurs schémas de sécurité, créez plusieurs outils de spécification OpenAPI.

  1. Mettez à jour vos schémas de sécurité de spécification OpenAPI. Il a une securitySchemes section et un schéma de type apiKey. Par exemple:

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

    Vous devez généralement mettre à jour le champ name, qui correspond au nom key dans la connexion. Si les schémas de sécurité incluent plusieurs schémas, ne conservez qu’un seul d’entre eux.

  2. Mettez à jour votre spécification OpenAPI pour inclure une security section :

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

  3. Supprimez n’importe quel paramètre dans la spécification OpenAPI nécessitant une clé API, car la clé API est stockée et transmise via une connexion, comme décrit plus loin dans cet article.

  4. Créez une connexion pour stocker votre clé API.

  5. Accédez au portail Foundry et ouvrez votre projet.

  6. Créez ou sélectionnez une connexion qui stocke le secret. Consultez Ajouter une nouvelle connexion à votre projet.

    Note

    Si vous regénérez la clé API à une date ultérieure, vous devez mettre à jour la connexion avec la nouvelle clé.

  7. Entrez les informations ci-après

    • clé : name champ de votre schéma de sécurité. Dans cet exemple, cela devrait être x-api-key

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

    • valeur : YOUR_API_KEY

  8. Après avoir créé une connexion, vous pouvez l’utiliser via le Kit de développement logiciel (SDK) ou l’API REST. Utilisez les onglets en haut de cet article pour afficher des exemples de code.

Configurer une connexion de jeton porteur

Vous pouvez utiliser l’authentification basée sur un jeton (par exemple, un jeton porteur) avec le même project_connection type d’authentification que celui utilisé pour les clés API. La principale différence est la façon dont vous configurez les spécifications OpenAPI et la connexion au projet.

Votre spécification OpenAPI se présente comme suit :

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Vous devez :

  1. Mettez à jour votre spécification securitySchemes OpenAPI pour l’utiliser Authorization comme nom d’en-tête :

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

  2. Ajoutez une security section qui référence le schéma :

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

  3. Créez une connexion de clés personnalisées dans votre projet Foundry :

    1. Accédez au portail Foundry et ouvrez votre projet.
    2. Créez ou sélectionnez une connexion qui stocke le secret. Consultez Ajouter une nouvelle connexion à votre projet.
    3. Entrez les valeurs suivantes :
      • clé : Authorization (doit correspondre au name champ dans votre securitySchemes)
      • valeur : Bearer <token> (remplacez <token> par votre jeton réel)

    Important

    La valeur doit inclure le mot Bearer suivi d’un espace avant le jeton. Par exemple : Bearer eyJhbGciOiJSUzI1NiIs.... Si vous omettez Bearer , l’API reçoit un jeton brut sans le préfixe de schéma d’autorisation requis et la demande échoue.

  4. Après avoir créé la connexion, utilisez-la avec le project_connection type d’authentification dans votre code, de la même façon que pour l’authentification par clé API. L’ID de connexion utilise le même format : /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

S’authentifier à l’aide de l’identité managée (Microsoft Entra ID)

Microsoft Entra ID est un service de gestion des identités et des accès cloud que vos employés peuvent utiliser pour accéder aux ressources externes. En utilisant Microsoft Entra ID, vous pouvez ajouter une sécurité supplémentaire à vos API sans avoir à utiliser de clés API. Lorsque vous configurez l’authentification d’identité managée, l’agent s’authentifie via l’outil Foundry qu’il utilise.

Important

L’authentification d’identité managée fonctionne uniquement lorsque le service cible accepte les jetons d’ID Microsoft Entra. Si l’API cible utilise un schéma d’authentification personnalisé qui ne prend pas en charge l’ID Entra, utilisez plutôt la clé API ou l’authentification par jeton du porteur .

Comprendre l’URI de l’audience

L’audience (parfois appelée identificateur de ressource ou URI d’ID d’application) indique à Microsoft Entra ID quel service ou API le jeton est destiné à accéder. La valeur d’audience doit correspondre à ce que le service cible attend, ou l’authentification échoue avec une erreur 401.

Note

Le public n’est pas votre point de terminaison de projet Foundry. Il s’agit de l’identificateur de ressource du service cible que votre outil OpenAPI appelle.

Le tableau suivant répertorie les URI d’audience pour les services Azure courants :

Service cible URI d’audience
Azure Storage https://storage.azure.com
Azure Key Vault https://vault.azure.net
Recherche d’IA Azure https://search.azure.com
Azure Logic Apps https://logic.azure.com
Gestion des API Azure (plan de gestion) https://management.azure.com
API protégée par une inscription d’application Entra (y compris APIM avec OAuth) URI d'ID d'application de l'enregistrement de votre application (par exemple, api://<client-id>)

Conseil / Astuce

Si vous utilisez Gestion des API Azure pour protéger une API personnalisée avec une stratégie de validation OAuth 2.0, l’audience est l’URI d’ID d’application de l’inscription d’application qui protège l’API , et non https://management.azure.com. L’audience du plan de gestion concerne exclusivement les opérations de gestion des ressources Azure sur la ressource APIM en elle-même.

Pour plus d’informations sur la façon dont les agents s’authentifient avec l’ID Microsoft Entra, consultez l’identité et l’authentification de l’agent.

Rechercher et vérifier votre audience

Procédez comme suit pour déterminer et vérifier la valeur d’audience correcte :

  • Pour les services Azure : consultez la documentation du service pour son identificateur de ressource Microsoft Entra ID. La plupart des services Azure répertorient l’URI d’audience dans leur documentation d’authentification.
  • Pour les API protégées par une inscription d’application Entra : dans le portail Azure, accédez à Microsoft Entra ID>Inscriptions d'applications>, sélectionnez votre application > et choisissez Exposer une API. L’URI d’ID d’application en haut de la page correspond à votre valeur d’audience.
  • Pour vérifier l’audience d’un jeton : décoder le jeton d’accès et https://jwt.ms vérifier l’affirmation aud. La aud valeur doit correspondre à l’audience attendue par votre service cible.

Configurer l’authentification d’identité managée

Pour configurer l’authentification à l’aide de Managed Identity :

  1. Vérifiez que votre ressource Foundry a activé l’identité managée affectée par le système.

    capture d’écran A montrant le sélecteur d’identité managée dans le portail Azure.

  2. Créez une ressource pour le service auquel vous souhaitez vous connecter via la spécification OpenAPI.

  3. Attribuez un accès approprié à la ressource.

    1. Sélectionnez Access Control pour votre ressource.

    2. Sélectionnez Ajouter , puis ajoutez une attribution de rôle en haut de l’écran.

      capture d’écran A montrant le sélecteur d’attribution de rôle dans le portail Azure.

    3. Sélectionnez l’attribution de rôle appropriée nécessaire, généralement elle nécessite au moins le rôle LECTEUR . Ensuite, sélectionnez Suivant.

    4. Sélectionnez Identité managée , puis sélectionnez membres.

    5. Dans le menu déroulant identité managée, recherchez Le compte Foundry , puis sélectionnez le compte Foundry de votre agent.

    6. Sélectionnez Terminer.

  4. Une fois l’installation terminée, vous pouvez continuer à l’aide de l’outil via le portail Foundry, le SDK ou l’API REST. Utilisez les onglets en haut de cet article pour afficher des exemples de code.

Résoudre les erreurs courantes

Symptôme Cause probable Résolution
La clé API n’est pas incluse dans les requêtes. Les sections securitySchemes ou security des spécifications OpenAPI sont manquantes. Vérifiez que votre spécification OpenAPI inclut à la fois components.securitySchemes et une section de niveau security supérieur. Vérifiez que le schéma name correspond au nom de clé dans la connexion de votre projet.
L’agent n’appelle pas l’outil OpenAPI. Le choix de l’outil n’est pas défini ou operationId non descriptif. Utilisez tool_choice="required" pour forcer l’appel de l’outil. Vérifiez que les operationId valeurs sont descriptives afin que le modèle puisse choisir l’opération appropriée.
L’authentification échoue pour l’identité managée. Identité managée non activée ou attribution de rôle manquante. Activez l’identité managée affectée par le système sur votre ressource Foundry. Attribuez le rôle requis (Reader ou supérieur) sur le service cible.
L’identité managée retourne 401 même si le rôle est attribué. L’URI d’audience ne correspond pas à ce que le service cible attend. Vérifiez que l’URI d’audience correspond à l’identificateur de ressource du service cible. Pour les services Azure, consultez la documentation du service. Pour les API protégées par Entra, utilisez l’URI d’ID d’application de votre inscription d’application. Décodez le jeton à https://jwt.ms et confirmez que la revendication aud correspond. Consultez Comprendre l’URI de l’audience.
Jeton d’identité managée rejeté par l’API cible. Le service cible n’accepte pas les jetons d’ID Microsoft Entra. Vérifiez que le service cible prend en charge l’authentification Microsoft Entra ID. Si ce n’est pas le cas, utilisez plutôt la clé API ou l’authentification par jeton du porteur.
La requête échoue avec 400 Demande incorrecte. Les spécifications OpenAPI ne correspondent pas à l’API réelle. Validez votre spécification OpenAPI par rapport à l’API réelle. Vérifiez les noms, les types et les champs obligatoires des paramètres.
La demande échoue avec 401 Non autorisé. Clé API ou jeton non valide ou expiré. Régénérez la clé/le jeton d’API et mettez à jour votre connexion de projet. Vérifiez que l’ID de connexion est correct.
L’outil retourne un format de réponse inattendu. Schéma de réponse non défini dans la spécification OpenAPI. Ajoutez des schémas de réponse à votre spécification OpenAPI pour une meilleure compréhension du modèle.
operationId erreur de validation. Caractères non valides dans operationId. Utilisez uniquement des lettres, -, et _ dans les valeurs operationId. Supprimez des nombres et des caractères spéciaux.
Erreur : connexion introuvable. Nom de connexion ou incompatibilité d’ID. Vérifiez que OPENAPI_PROJECT_CONNECTION_NAME est conforme au nom de connexion dans votre projet Foundry.
Jeton porteur non envoyé correctement. Préfixe Bearer manquant pour la valeur de connexion. Définissez la valeur Bearer <token> de connexion sur (avec le mot Bearer et un espace avant le jeton). Vérifiez que la spécification securitySchemes OpenAPI utilise "name": "Authorization".

Choisir une méthode d’authentification

Le tableau suivant vous aide à choisir la méthode d’authentification appropriée pour votre outil OpenAPI :

Méthode d'authentification Idéal pour Complexité de l’installation
Anonyme API publiques sans authentification Faible
Clé API API tierces avec accès basé sur des clés Moyenne
Identité managée Services Azure et API protégées par l’ID Microsoft Entra. Nécessite que le service cible accepte les jetons d’ID Entra et prend en charge le contrôle d’accès en fonction du rôle (RBAC) Azure ou Entra. Moyen-élevé

Contenu connexe

  • Last updated on