Connecter des agents aux outils OpenAPI

Authentification anonyme :

Créez d’abord une connexion authType: "None" OpenAPI et remplacez <OPENAPI_CONNECTION_ID> par son ID de ressource complet.

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": {},
        "auth": {
          "type": "project_connection",
          "security_scheme": {
            "project_connection_id": "<OPENAPI_CONNECTION_ID>"
          }
        }
      }
    }
  ]
}

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": {},
        "auth": {
          "type": "project_connection",
          "security_scheme": {
            "project_connection_id": "<OPENAPI_CONNECTION_ID>"
          }
        }
      }
    }
  ]
}

Authentification par identité managée du projet :

Créez une connexion de projet OpenAPI avec authType: "ProjectManagedIdentity", puis transmettez son ID de ressource complet avec auth.type: "project_connection". N'utilisez pas la configuration de l'audience directe managed_identity dans une boîte à outils.

{
  "description": "REST API with project managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": {},
        "auth": {
          "type": "project_connection",
          "security_scheme": {
            "project_connection_id": "<OPENAPI_CONNECTION_ID>"
          }
        }
      }
    }
  ]
}

import os
from azure.ai.projects.models import (
    OpenApiFunctionDefinition,
    OpenApiProjectConnectionAuthDetails,
    OpenApiProjectConnectionSecurityScheme,
    OpenApiToolboxTool,
)

tools = [
    OpenApiToolboxTool(
        openapi=OpenApiFunctionDefinition(
            name="my-api",
            spec={},
            auth=OpenApiProjectConnectionAuthDetails(
                security_scheme=OpenApiProjectConnectionSecurityScheme(
                    project_connection_id=os.environ["OPENAPI_CONNECTION_ID"]
                )
            ),
        )
    )
]

using System;
using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects.Agents;

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
OpenApiToolboxTool tool = new(
    new OpenApiFunctionDefinition(
        name: "my-api",
        specification: specBytes,
        authentication: new OpenApiProjectConnectionAuthenticationDetails(
            new OpenApiProjectConnectionSecurityScheme(
                Environment.GetEnvironmentVariable("OPENAPI_CONNECTION_ID")
                ?? throw new InvalidOperationException(
                    "Set OPENAPI_CONNECTION_ID before running.")))
    )
);

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

const connectionId = process.env.OPENAPI_CONNECTION_ID;
if (!connectionId) {
  throw new Error("Set OPENAPI_CONNECTION_ID before running.");
}

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

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,
    OpenApiProjectConnectionAuthDetails,
    OpenApiProjectConnectionSecurityScheme,
)

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

# Create a client to call Foundry API
with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    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=AGENT_NAME,
        definition=PromptAgentDefinition(
            model="gpt-4.1-mini",
            instructions="You are a helpful assistant.",
            tools=[weather_tool],
        ),
    )

    with project.get_openai_client(agent_name=agent.name) as openai:
        response = openai.responses.create(
            input="What's the weather in Seattle?",
        )
        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.15.0" "azure-ai-projects>=2.3.0,<2.8.0" 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,
    OpenApiProjectConnectionAuthDetails,
    OpenApiProjectConnectionSecurityScheme,
)

PROJECT_ENDPOINT = os.environ["FOUNDRY_PROJECT_ENDPOINT"]


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, encoding="utf-8") 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=OpenApiProjectConnectionAuthDetails(
                security_scheme=OpenApiProjectConnectionSecurityScheme(
                    project_connection_id=os.environ["OPENAPI_CONNECTION_ID"]
                )
            ),
        )
    )

    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.
    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.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP002

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()
    {
        var projectEndpoint =
            Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_PROJECT_ENDPOINT before running.");
        var deploymentName =
            Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_MODEL_DEPLOYMENT_NAME before running.");

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

        // The connection specifies anonymous authentication to the weather API.
        string filePath = GetFile();
        OpenApiFunctionDefinition toolDefinition = new(
            name: "get_weather",
            specification: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            authentication: new OpenApiProjectConnectionAuthenticationDetails(
                new OpenApiProjectConnectionSecurityScheme(
                    Environment.GetEnvironmentVariable("OPENAPI_CONNECTION_ID")
                    ?? throw new InvalidOperationException(
                        "Set OPENAPI_CONNECTION_ID before running.")))
        );
        toolDefinition.Description = "Retrieve weather information for a location.";
        OpenApiTool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: deploymentName)
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        ProjectsAgentVersion 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

• Variables d’environnement : FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEet OPENAPI_CONNECTION_ID.
• 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 FrameworkAddFoundryToolboxes. Utilisez un projet ASP.NET Core avec Azure.AI.AgentServer.Responses et Microsoft.Agents.AI.Foundry.Hosting, en plus des dépendances C# dans les conditions préalables. Définissez FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME et OPENAPI_CONNECTION_ID, puis connectez-vous avec az login.

using System;
using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.AgentServer.Responses;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.AspNetCore.Builder;
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(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT.");
string deploymentName = Environment.GetEnvironmentVariable(
    "FOUNDRY_MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("Set FOUNDRY_MODEL_DEPLOYMENT_NAME.");
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",
    specification: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
    authentication: new OpenApiProjectConnectionAuthenticationDetails(
        new OpenApiProjectConnectionSecurityScheme(
            Environment.GetEnvironmentVariable("OPENAPI_CONNECTION_ID")
            ?? throw new InvalidOperationException(
                "Set OPENAPI_CONNECTION_ID before running.")))
);
toolDefinition.Description = "Retrieve weather information for a location.";
OpenApiToolboxTool openapiTool = new(toolDefinition);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateVersion(
        name: "openapi-toolbox",
        tools: [openapiTool],
        description: "Toolbox with the OpenAPI weather tool");
projectClient.AgentAdministrationClient.GetAgentToolboxes()
    .UpdateDefaultVersion(toolboxVersion.Name, toolboxVersion.Version);

// 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’exemple démarre un serveur HTTP. Lorsque vous envoyez une demande de réponses concernant la météo, l’agent appelle l’API via la boîte à outils et retourne les conditions actuelles :

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 associez directement un outil OpenAPI authentifié à un agent de prompt. Vous utilisez la spécification Trip Advisor et une clé API stockée dans une connexion de projet.

Le service TripAdvisor nécessite l’authentification par clé API. Créez la connexion de projet comme décrit dans Authentifier avec la clé API et définissez OPENAPI_CONNECTION_ID sur son ID de ressource complet. Le nom de clé de la connexion doit correspondre à la spécification TripAdvisor.

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

#pragma warning disable AAIP002

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()
    {
        var projectEndpoint =
            Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_PROJECT_ENDPOINT before running.");
        var deploymentName =
            Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_MODEL_DEPLOYMENT_NAME before running.");

        // 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();
        var connectionId =
            Environment.GetEnvironmentVariable("OPENAPI_CONNECTION_ID")
            ?? throw new InvalidOperationException(
                "Set OPENAPI_CONNECTION_ID to the TripAdvisor connection ID.");
        OpenApiFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            specification: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            authentication: new OpenApiProjectConnectionAuthenticationDetails(new OpenApiProjectConnectionSecurityScheme(
                projectConnectionId: connectionId
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        OpenApiTool openapiTool = new(toolDefinition);

        // Create the agent definition and the agent version.
        DeclarativeAgentDefinition agentDefinition = new(model: deploymentName)
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        ProjectsAgentVersion 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# utilise 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 fait référence à la connexion de projet Trip Advisor contenant votre clé API.
3. Il attache l'outil TripAdvisorà l'agent, 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 de l’agent.

Entrées requises

• Variables d’environnement : FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEet OPENAPI_CONNECTION_ID.
• 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" \
  --header "Foundry-Features: Toolboxes=V1Preview" \
  -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": "project_connection",
            "security_scheme": {
              "project_connection_id": "'$OPENAPI_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" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

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.

   Définissez TOOLBOX_CONNECTION_ID sur l’ID de ressource complet de openapi-toolbox-conn. Cette connexion est distincte de la connexion OpenAPI anonyme dans OPENAPI_CONNECTION_ID. Remplacez <version> par la version retournée lorsque vous avez créé la toolbox.

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": "'$TOOLBOX_CONNECTION_ID'",
        "headers": {
          "Foundry-Features": "Toolboxes=V1Preview"
        }
      }
    ]
  }'

Authentification par clé API (connexion de projet)

Utilisez cette variante uniquement une fois le flux anonyme réussi. Téléchargez tripadvisor_openapi.json depuis Avant d'exécuter les exemples de code. Configurez la connexion à la clé API et les entrées securitySchemes et security de la spécification, comme décrit dans Authentifier avec la clé API. Définissez OPENAPI_CONNECTION_ID sur l’ID de ressource complet de cette connexion, et non sur la connexion météorologique anonyme.

Cet exemple Bash utilise jq pour inclure la spécification dans la même remote_tool structure de requête que les exemples d'identité managée du projet.

jq -n \
  --arg model "$FOUNDRY_MODEL_DEPLOYMENT_NAME" \
  --arg connection_id "$OPENAPI_CONNECTION_ID" \
  --slurpfile spec tripadvisor_openapi.json \
  '{
    model: $model,
    input: "Recommend five top hotels in the United States.",
    tools: [
      {
        type: "remote_tool",
        tool_arguments: [
          {
            name: "openapi",
            arguments: {
              name: "tripadvisor",
              description: "TripAdvisor travel information.",
              auth: {
                type: "project_connection",
                security_scheme: {
                  project_connection_id: $connection_id
                }
              },
              spec: $spec[0]
            }
          }
        ]
      }
    ],
    tool_choice: "required"
  }' > openapi-api-key-request.json

curl --fail-with-body --request POST \
  --url "${FOUNDRY_PROJECT_ENDPOINT%/}/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data @openapi-api-key-request.json

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

Pour l’identité managée du projet, créez d’abord une connexion de projet OpenAPI. Ensuite, transmettez son ID de ressource complet dans la requête Réponses. Consultez l’exemple REST dans Appeler un outil OpenAPI avec une identité managée affectée au projet.

L'identité managée du compte est prise en charge uniquement pour les outils OpenAPI associés directement aux agents de prompt dans les abonnements existants. Elle n'est pas prise en charge dans les boîtes à outils. Utilisez également l'identité managée du projet pour les agents de prompt. Migrez les configurations existantes dès que possible.

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 une définition d’outil REST directe supplémentaire pour l’authentification par clé API via une connexion de projet.
4. L’agent appelle l’API sélectionnée par la configuration de l’outil et retourne les résultats.

Entrées requises

• Variables d’environnement : FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• Pour l’authentification anonyme : OPENAPI_CONNECTION_ID, référençant la connexion de projet OpenAPI anonyme et TOOLBOX_CONNECTION_ID, référençant la connexion MCP de toolbox.
• Pour l’authentification par clé API : OPENAPI_CONNECTION_ID, faisant référence à la connexion de clé API TripAdvisor, et tripadvisor_openapi.json.
• Pour l’authentification d’identité managée du projet : OPENAPI_CONNECTION_ID, comme indiqué dans l’exemple d’identité managée du projet.
• Spécification OpenAPI inline dans le corps de la requête.

Sortie attendue

{
  "id": "resp_abc123",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_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,
  OpenApiToolboxTool,
  OpenApiFunctionDefinition,
  OpenApiProjectConnectionAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Set ${name} before running.`);
  }
  return value;
}
const PROJECT_ENDPOINT = requiredEnv("FOUNDRY_PROJECT_ENDPOINT");
const deploymentName = requiredEnv("FOUNDRY_MODEL_DEPLOYMENT_NAME");
const weatherSpecPath = path.resolve("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): OpenApiToolboxTool {
  const connectionId = process.env.OPENAPI_CONNECTION_ID;
  if (!connectionId) {
    throw new Error("Set OPENAPI_CONNECTION_ID before running.");
  }
  const auth: OpenApiProjectConnectionAuthDetails = {
    type: "project_connection",
    security_scheme: {
      project_connection_id: connectionId,
    },
  };
  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 toolboxConnectionId = process.env.TOOLBOX_CONNECTION_ID;
  if (!toolboxConnectionId) {
    throw new Error("Set TOOLBOX_CONNECTION_ID to the toolbox connection ID.");
  }

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

  // 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);
  process.exitCode = 1;
});

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

• Variables d’environnement : FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME, OPENAPI_CONNECTION_ID et TOOLBOX_CONNECTION_ID.
• Fichier local : assets/weather_openapi.json (spécification OpenAPI).

Sortie attendue

Creating a toolbox with the OpenAPI weather tool...
The weather in Seattle is <conditions>. Consider wearing <suggestion>.

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

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Set ${name} before running.`);
  }
  return value;
}
const PROJECT_ENDPOINT = requiredEnv("FOUNDRY_PROJECT_ENDPOINT");
const deploymentName = requiredEnv("FOUNDRY_MODEL_DEPLOYMENT_NAME");
const connectionId = requiredEnv("OPENAPI_CONNECTION_ID");
const tripAdvisorSpecPath = path.resolve("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: connectionId,
    },
  };

  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: deploymentName,
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });

  // 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);
  process.exitCode = 1;
});

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 fait référence à la connexion de clé API en utilisant OPENAPI_CONNECTION_ID.
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

• Variables d’environnement : FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEet OPENAPI_CONNECTION_ID.
• Fichier local : ../assets/tripadvisor_openapi.json
• Connexion du projet configurée avec la clé API TripAdvisor

Sortie attendue

Location 293919: <name>, rating: <rating>, review count: <count>.

Erreurs courantes

• Error: OpenAPI specification not found: vérifiez le chemin du fichier.
• Connexion introuvable : vérifiez que OPENAPI_CONNECTION_ID est l’identifiant de ressource complet de la connexion de clé API.
• 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.

Installez les dépendances avec pip install openai azure-identity.

import json
import os

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from openai import OpenAI


def main() -> None:
    with open("translator_openapi.json", encoding="utf-8") as spec_file:
        spec = json.load(spec_file)

    tool = {
        "type": "remote_tool",
        "tool_arguments": [
            {
                "name": "openapi",
                "arguments": {
                    "name": "language",
                    "description": "Azure Translator API for text translation.",
                    "default_params": ["api-version"],
                    "auth": {
                        "type": "project_connection",
                        "security_scheme": {
                            "project_connection_id": os.environ[
                                "OPENAPI_CONNECTION_ID"
                            ],
                        },
                    },
                    "spec": spec,
                },
            }
        ],
    }

    with DefaultAzureCredential() as credential:
        token_provider = get_bearer_token_provider(
            credential, "https://ai.azure.com/.default"
        )
        with OpenAI(
            base_url=(
                os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
                + "/openai/v1/"
            ),
            api_key=token_provider,
        ) as client:
            response = client.responses.create(
                model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
                input="Translate 'Hello, how are you?' to Spanish.",
                extra_body={
                    "tools": [tool],
                    "tool_choice": "required",
                },
            )
            print(response.output_text)


if __name__ == "__main__":
    main()

Référence : Fournisseur de jetons Azure Identity.

L’argument extra_body transmet la charge utile spécifique au service remote_tool sans nécessiter de modèle d’outil OpenAPI typé dans le Kit de développement logiciel (SDK) OpenAI.

Utilisez .NET 8 ou version ultérieure et installez la bibliothèque d'informations d'identification avec dotnet add package Azure.Identity. Cet exemple envoie la charge utile de l’outil spécifique au service avec HttpClient.

using System;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Net.Http.Json;
using System.Text.Json;
using Azure.Core;
using Azure.Identity;

static string RequiredEnvironmentVariable(string name) =>
    Environment.GetEnvironmentVariable(name)
    ?? throw new InvalidOperationException($"Set {name} before running.");

string endpoint = RequiredEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
string model = RequiredEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
string connectionId = RequiredEnvironmentVariable("OPENAPI_CONNECTION_ID");
JsonElement spec = JsonSerializer.Deserialize<JsonElement>(
    File.ReadAllText("translator_openapi.json"));

var tool = new
{
    type = "remote_tool",
    tool_arguments = new[]
    {
        new
        {
            name = "openapi",
            arguments = new
            {
                name = "language",
                description = "Azure Translator API for text translation.",
                default_params = new[] { "api-version" },
                auth = new
                {
                    type = "project_connection",
                    security_scheme = new
                    {
                        project_connection_id = connectionId
                    }
                },
                spec
            }
        }
    }
};

var credential = new DefaultAzureCredential();
AccessToken token = await credential.GetTokenAsync(
    new TokenRequestContext(new[] { "https://ai.azure.com/.default" }));
using var client = new HttpClient();
using var request = new HttpRequestMessage(
    HttpMethod.Post, $"{endpoint.TrimEnd('/')}/openai/v1/responses");
request.Headers.Authorization =
    new AuthenticationHeaderValue("Bearer", token.Token);
request.Content = JsonContent.Create(new
{
    model,
    input = "Translate 'Hello, how are you?' to Spanish.",
    tools = new[] { tool },
    tool_choice = "required"
});
using HttpResponseMessage response = await client.SendAsync(request);
string responseBody = await response.Content.ReadAsStringAsync();
if (!response.IsSuccessStatusCode)
{
    throw new HttpRequestException(
        $"HTTP {(int)response.StatusCode}: {responseBody}");
}
Console.WriteLine(responseBody);

Référence : DefaultAzureCredential, HttpClient.

Utilisez Node.js 20 ou version ultérieure et installez la bibliothèque d'identifiants avec npm install @azure/identity. Enregistrez cet exemple JavaScript en tant que openapi-project-mi.mjs.

import { readFile } from "node:fs/promises";
import { DefaultAzureCredential } from "@azure/identity";

function requiredEnvironmentVariable(name) {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Set ${name} before running.`);
  }
  return value;
}

const endpoint = requiredEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
const model = requiredEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
const connectionId = requiredEnvironmentVariable("OPENAPI_CONNECTION_ID");
const spec = JSON.parse(
  await readFile("translator_openapi.json", "utf8"),
);

const tool = {
  type: "remote_tool",
  tool_arguments: [
    {
      name: "openapi",
      arguments: {
        name: "language",
        description: "Azure Translator API for text translation.",
        default_params: ["api-version"],
        auth: {
          type: "project_connection",
          security_scheme: {
            project_connection_id: connectionId,
          },
        },
        spec,
      },
    },
  ],
};

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");
const response = await fetch(
  `${endpoint.replace(/\/$/, "")}/openai/v1/responses`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token.token}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model,
      input: "Translate 'Hello, how are you?' to Spanish.",
      tools: [tool],
      tool_choice: "required",
    }),
  },
);
const responseBody = await response.text();
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${responseBody}`);
}
console.log(responseBody);

Référence : DefaultAzureCredential.

Utilisez Java 11 ou version ultérieure. Ajoutez com.fasterxml.jackson.core:jackson-databind et com.azure:azure-identity à vos dépendances Maven. Cet exemple envoie la charge utile de l'outil spécifique au service avec le client HTTP de Java.

import com.azure.core.credential.AccessToken;
import com.azure.core.credential.TokenRequestContext;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.File;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.List;
import java.util.Map;
import java.util.Objects;

public class OpenApiProjectMi {
    private static String requiredEnvironmentVariable(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) {
            throw new IllegalStateException("Set " + name + " before running.");
        }
        return value;
    }

    public static void main(String[] args) throws Exception {
        String endpoint = requiredEnvironmentVariable(
            "FOUNDRY_PROJECT_ENDPOINT");
        String model = requiredEnvironmentVariable(
            "FOUNDRY_MODEL_DEPLOYMENT_NAME");
        String connectionId = requiredEnvironmentVariable(
            "OPENAPI_CONNECTION_ID");
        ObjectMapper mapper = new ObjectMapper();
        Map<String, Object> spec = mapper.readValue(
            new File("translator_openapi.json"),
            new TypeReference<Map<String, Object>>() { });

        Map<String, Object> tool = Map.of(
            "type", "remote_tool",
            "tool_arguments", List.of(Map.of(
                "name", "openapi",
                "arguments", Map.of(
                    "name", "language",
                    "description",
                        "Azure Translator API for text translation.",
                    "default_params", List.of("api-version"),
                    "auth", Map.of(
                        "type", "project_connection",
                        "security_scheme", Map.of(
                            "project_connection_id", connectionId)),
                    "spec", spec))));
        Map<String, Object> body = Map.of(
            "model", model,
            "input", "Translate 'Hello, how are you?' to Spanish.",
            "tools", List.of(tool),
            "tool_choice", "required");

        var credential = new DefaultAzureCredentialBuilder().build();
        AccessToken token = Objects.requireNonNull(credential.getToken(
            new TokenRequestContext()
                .addScopes("https://ai.azure.com/.default")).block());
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(endpoint.replaceAll("/$", "")
                + "/openai/v1/responses"))
            .header("Authorization", "Bearer " + token.getToken())
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(
                mapper.writeValueAsString(body)))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient().send(
            request, HttpResponse.BodyHandlers.ofString());
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            throw new IllegalStateException(
                "HTTP " + response.statusCode() + ": " + response.body());
        }
        System.out.println(response.body());
    }
}

Référence : DefaultAzureCredentialBuilder.

Utilisez Bash, Azure CLI, curl et jq pour générer la requête à partir de translator_openapi.json. Le jeton de l’appelant cible Foundry, pas Azure Resource Manager ni Translator.

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

jq -n \
  --arg model "$FOUNDRY_MODEL_DEPLOYMENT_NAME" \
  --arg connection_id "$OPENAPI_CONNECTION_ID" \
  --slurpfile spec translator_openapi.json \
  '{
    model: $model,
    input: "Translate '\''Hello, how are you?'\'' to Spanish.",
    tools: [
      {
        type: "remote_tool",
        tool_arguments: [
          {
            name: "openapi",
            arguments: {
              name: "language",
              description: "Azure Translator API for text translation.",
              default_params: ["api-version"],
              auth: {
                type: "project_connection",
                security_scheme: {
                  project_connection_id: $connection_id
                }
              },
              spec: $spec[0]
            }
          }
        ]
      }
    ],
    tool_choice: "required"
  }' > openapi-project-mi-request.json

curl --fail-with-body --request POST \
  --url "${FOUNDRY_PROJECT_ENDPOINT%/}/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data @openapi-project-mi-request.json

Référence : Azure CLI jetons d’accès.