Connecter des agents aux outils OpenAPI

Authentification anonyme :

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

Authentification de connexion de projet :

Utilisez ce modèle lorsque l’API nécessite une clé ou un jeton stocké dans une connexion de projet Foundry.

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

Authentification d’identité managée :

Utilisez ce modèle lorsque l’API cible s’authentifie via Microsoft Entra ID. L’identité managée du projet Foundry appelle l’API pour le compte de l’agent. Vérifiez que l’identité managée a le rôle RBAC requis sur le service cible avant d’utiliser ce modèle.

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

from azure.ai.projects.models import OpenAPITool

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

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

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

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

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 le temps et son fichier de spécification weather_openapi.json. Sélectionnez Prompt Agents pour utiliser le SDK Azure AI Projects afin de créer un agent de prompt côté serveur, ou Agents hébergés pour utiliser le framework Microsoft Agent afin de créer un agent éphémère dans le processus.

Agents déclencheurs

import os
import jsonref
from typing import Any, cast
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    OpenApiTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

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

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

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

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

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

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

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

Cet exemple crée un assistant de requête avec un outil OpenAPI qui appelle l’API Weather wttr.in avec authentification anonyme. L’outil est attaché directement à la définition de l’agent. 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 assistant de requête avec l’outil Weather configuré pour un 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.

Agents hébergés

Cet exemple utilise FoundryChatClient du framework Microsoft Agent et se connecte au point de terminaison MCP de la boîte à outils en utilisant FoundryToolbox. Installez les versions de package compatibles avec pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity jsonref, définissez la variable d’environnement FOUNDRY_PROJECT_ENDPOINT et connectez-vous avec az login. OpenApiToolboxTool est le modèle propre à la boîte à outils ; utilisez OpenApiTool uniquement lorsque vous attachez l’outil directement à un agent de prompt.

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

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

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


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

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

    weather_asset_file_path = os.path.abspath(
        os.path.join(os.path.dirname(__file__), "../assets/weather_openapi.json")
    )
    with open(weather_asset_file_path, "r") as f:
        openapi_weather = cast(dict[str, Any], jsonref.loads(f.read()))

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

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

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

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
, timeout=120.0)
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

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

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


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

Sortie attendue

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

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 le temps et son fichier de spécification weather_openapi.json. Sélectionnez Prompt Agents pour utiliser le SDK Azure AI Projects afin de créer un agent de prompt côté serveur, ou Agents hébergés pour utiliser le framework Microsoft Agent afin de créer un agent éphémère dans le processus.

Agents déclencheurs

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 Kit de développement logiciel (SDK) Azure 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.
        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);
    }
}

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

Agents hébergés

Cet exemple crée la boîte à outils OpenAPI avec le SDK Azure AI Projects, puis utilise l’intégration Microsoft Agent Framework AddFoundryToolboxes pour rendre l’outil disponible pour l’agent hébergé. Installez les packages Agent Framework, définissez le AZURE_AI_PROJECT_ENDPOINT point de terminaison du projet et AZURE_AI_MODEL_DEPLOYMENT_NAME les variables d’environnement, puis connectez-vous avec az login.

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

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

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

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

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

// Create the hosted agent and register the toolbox integration.
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "You are a helpful assistant with access to the toolbox tools.",
    name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxVersion.Name);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Sortie attendue

L’agent appelle l’API météo via l’outil OpenAPI et retourne les conditions actuelles pour l’emplacement demandé :

The current weather in Seattle is <temperature> with <conditions>.

Pour obtenir l’exemple complet, y compris les modèles d’API authentifiés, consultez Agent_Step17_OpenAPITools.

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

Dans cet exemple, vous ajoutez un outil OpenAPI authentifié à une boîte à outils, attachez la boîte à outils en tant qu’outil MCP et utilisez 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, ouvrez Microsoft Foundry, sélectionnez Gérer dans le volet de navigation supérieur droit, sélectionnez Project détails, puis sélectionnez l’onglet Ressources connectées. Enfin, créez une connexion de type de 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 OpenAPI tool with authentication by project connection security scheme.
        string filePath = GetFile();
        AIProjectConnection tripadvisorConnection = projectClient.Connections.GetConnection("tripadvisor");
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIProjectConnectionAuthenticationDetails(new OpenAPIProjectConnectionSecurityScheme(
                projectConnectionId: tripadvisorConnection.Id
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        ProjectsAgentTool openapiTool = new OpenAPITool(toolDefinition);

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

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

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

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

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

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: "gpt-4.1-mini")
        {
            Instructions = "You are a helpful assistant.",
            Tools = { toolboxTool }
        };
        AgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

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

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

Ce que fait ce code

Cet exemple C# illustre l’utilisation d’un outil OpenAPI avec l’authentification par clé API via une boîte à outils et 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 du projet tripadvisor contenant votre clé API.
3. Crée une version de la boîte à outils contenant l’outil TripAdvisor configuré pour utiliser la connexion à des fins d’authentification.
4. Attache la boîte à outils à l’assistant en tant qu’outil MCP.
5. Envoie une demande de recommandations d’hôtel à Paris.
6. L’agent appelle l’API Trip Advisor à l’aide de votre clé API stockée et retourne les résultats.
7. Nettoie en supprimant de 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 Project : 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é : vérifiez 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

Cette configuration Java peut référencer les outils MCP, mais le SDK Java n'expose pas encore d'API de création de boîte à outils.

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

Obtenez un jeton d’accès :

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

Authentification anonyme

Ajoutez des outils OpenAPI via une boîte à outils, puis attachez la boîte à outils à votre agent en tant qu’outil MCP. Pour plus d’informations, consultez Qu’est-ce qu’une boîte à outils ?

1. Créez une boîte à outils qui contient l’outil météo OpenAPI :

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

La boîte à outils expose un point de terminaison compatible MCP à l’emplacement $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1où <version> est la version retournée par l’appel précédent.

1. Créez une connexion de projet d’outil distant qui pointe vers le point de terminaison de la boîte à outils, en utilisant un jeton Entra utilisateur afin que l’identité de l’appelant soit transmise (audience https://ai.azure.com).

azd ai connection create openapi-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

1. Créez une réponse qui utilise la boîte à outils en l’attachant en tant qu’outil MCP.

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tool_choice": "required",
    "tools": [
      {
        "type": "mcp",
        "server_label": "toolbox",
        "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1",
        "require_approval": "never",
        "project_connection_id": "openapi-toolbox-conn"
      }
    ]
  }'

Authentification par clé API (connexion de projet)

Utilisez cette variante uniquement une fois le flux anonyme réussi. Configurez la connexion du projet et l’entrée OpenAPI securitySchemes , comme décrit dans Authentifier avec la clé API.

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

Pour une API de jeton de porteur, conservez la même project_connection forme de requête, mais utilisez une connexion configurée comme décrit dans Configurer une connexion de jeton du porteur. La valeur de connexion doit commencer par Bearer, suivi d’un espace.

Authentification d’identité managé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. La demande :

1. Pour l’authentification anonyme, crée une boîte à outils contenant la définition de l’outil OpenAPI et la spécification de l’API météo.
2. Crée une réponse qui attache la boîte à outils en tant qu’outil MCP et demande la météo de Seattle.
3. Affiche des définitions d’outils REST directes supplémentaires pour la clé API via la connexion de projet et l’authentification d’identité managée.
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 inline 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 manquant AGENT_TOKEN, ou clé API non injectée car securitySchemes et security sont manquants dans votre spécification OpenAPI
• 404 Not Found: nom de modèle ou de point de terminaison incorrect pour le déploiement
• 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 avec des fonctionnalités d’outil OpenAPI en ajoutant l’outil OpenAPI à une boîte à outils et en attachant la boîte à outils en tant qu’outil MCP. 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 Kit de développement logiciel (SDK) Azure 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();

  const weatherTool = createWeatherTool(weatherSpec);

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

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

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

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

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

  // Send a request and stream the response
  const streamResponse = await openai.responses.create(
    {
      input:
        "What's the weather in Seattle and how should I plan my outfit for the day based on the forecast?",
      stream: true,
    },
    {
      body: {
        agent_reference: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

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

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

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

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 une version de boîte à outils contenant l’outil météo.
3. Associe la boîte à outils à l’agent en tant qu’outil MCP, puis envoie une requête en streaming sur la météo à Seattle et la tenue à prévoir.
4. Traite la réponse en flux et affiche les deltas au fur et à mesure de leur arrivée.
5. Il impose l'utilisation de l'outil en utilisant tool_choice: "required" pour garantir que l'API est appelée.
6. Nettoie en supprimant de 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 non fonctionnelle : si vous passez de l’authentification anonyme à l’authentification par clé API, vérifiez que votre spécification OpenAPI a 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 Kit de développement logiciel (SDK) Azure 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-4.1-mini",
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });

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

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

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

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

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’outil TripAdvisor qui utilise la connexion de projet pour l’authentification par API clé.
4. Il envoie une demande de streaming pour les détails de l’emplacement TripAdvisor.
5. Il impose l'utilisation de l'outil en utilisant tool_choice: "required" pour garantir que l'API est appelée.
6. Il traite et affiche la réponse de diffusion en continu.
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 du projet configurée avec la clé API TripAdvisor

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 correctement les sections sous securitySchemes, components, et security. 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.