Agents verbinden met OpenAPI-hulpprogramma's

Anonieme authenticatie:

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

Authenticatie van projectverbinding:

Gebruik dit patroon wanneer voor de API een sleutel of token is vereist die is opgeslagen in een Foundry-projectverbinding.

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

Verificatie van beheerde identiteit:

Gebruik dit patroon wanneer de doel-API wordt geverifieerd via Microsoft Entra-id. De beheerde identiteit van het Foundry-project roept de API aan namens de agent. Zorg ervoor dat de beheerde identiteit de vereiste RBAC-rol heeft voor de doelservice voordat u dit patroon gebruikt.

{
  "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",
      },
    },
  },
];

Voorbeeld van het gebruik van agenten met de OpenAPI-tool

In dit voorbeeld ziet u hoe u services gebruikt die worden beschreven door een OpenAPI-specificatie met behulp van een agent. De service wttr.in wordt gebruikt voor het ophalen van het weer en het specificatiebestand weather_openapi.json. Selecteer Prompt Agents om de Azure AI Projects SDK te gebruiken om een promptagent aan de serverzijde te maken of Hosted Agents om het Microsoft Agent Framework te gebruiken om een tijdelijke, in-process agent te maken.

Agents aansturen

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

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

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

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

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

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

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

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

In dit voorbeeld wordt een promptagent gemaakt met een OpenAPI-hulpprogramma waarmee de wttr.in weer-API wordt aangeroepen met behulp van anonieme verificatie. Het hulpprogramma wordt rechtstreeks aan de agentdefinitie gekoppeld. Wanneer u de code uitvoert:

1. De Weer OpenAPI-specificatie wordt geladen vanuit een lokaal JSON-bestand.
2. Maakt een prompt-agent met de weertool geconfigureerd voor anonieme toegang.
3. Hiermee wordt een query verzonden waarin wordt gevraagd naar het weer van Seattle.
4. De agent gebruikt het OpenAPI-hulpprogramma om de weer-API aan te roepen en retourneert opgemaakte resultaten.
5. Schoont op door de agentversie te verwijderen.

Gehoste agents

In dit voorbeeld wordt FoundryChatClient gebruikgemaakt van het Microsoft Agent Framework en wordt verbinding gemaakt met het MCP-eindpunt van de werkset met behulp van FoundryToolbox. Installeer compatibele pakketversies met pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity jsonref, stel de FOUNDRY_PROJECT_ENDPOINT omgevingsvariabele in en meld u aan met az login. OpenApiToolboxTool is het werksetspecifieke model; alleen gebruiken OpenApiTool bij het rechtstreeks koppelen van het hulpprogramma aan een promptagent.

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

Verwachte uitvoer

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

Voorbeeld van het gebruik van agenten met de OpenAPI-tool

In dit voorbeeld ziet u hoe u services gebruikt die worden beschreven door een OpenAPI-specificatie met behulp van een agent. De service wttr.in wordt gebruikt voor het ophalen van het weer en het specificatiebestand weather_openapi.json. Selecteer Prompt Agents om de Azure AI Projects SDK te gebruiken om een promptagent aan de serverzijde te maken of Hosted Agents om het Microsoft Agent Framework te gebruiken om een tijdelijke, in-process agent te maken.

Agents aansturen

In dit voorbeeld worden synchrone methoden van de Azure AI Projects-clientbibliotheek gebruikt. Zie de sample in de Azure SDK voor .NET opslagplaats op GitHub voor een voorbeeld waarin asynchrone methoden worden gebruikt.

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

Wat deze code doet

In dit C#-voorbeeld wordt een agent gemaakt met een OpenAPI-hulpprogramma waarmee weergegevens uit wttr.in worden opgehaald met behulp van anonieme verificatie. Wanneer u de code uitvoert:

1. Het leest de Weer OpenAPI-specificatie uit een lokaal JSON-bestand.
2. Hiermee maakt u een agent met de weertool geconfigureerd.
3. Met de OpenAPI-tool wordt een aanvraag verzonden waarin gevraagd wordt naar het weer in Seattle.
4. De agent roept de weer-API aan en retourneert de resultaten.
5. Schoont de agent op door de agent te verwijderen.

Vereiste invoer

• Inline-tekenreekswaarde: projectEndpoint (het eindpunt van het Foundry-project)
• Lokaal bestand: Assets/weather_openapi.json (OpenAPI-specificatie)

Verwachte uitvoer

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

Veelvoorkomende fouten

• FileNotFoundException: Bestand met OpenAPI-specificatie is niet gevonden in de map Assets
• UnauthorizedAccessException: Ongeldige referentiegegevens of onvoldoende RBAC-machtigingen
• API-sleutel niet geïnjecteerd: Controleer of de OpenAPI-specificatie zowel securitySchemes (in components) als security secties met overeenkomende schemanamen bevat

Gehoste agents

In dit voorbeeld wordt de OpenAPI-werkset gemaakt met de Azure AI Projects SDK en wordt vervolgens de Microsoft Agent Framework-integratie AddFoundryToolboxes gebruikt om het hulpprogramma beschikbaar te maken voor de gehoste agent. Installeer de Agent Framework-pakketten, stel het projecteindpunt en AZURE_AI_PROJECT_ENDPOINT de AZURE_AI_MODEL_DEPLOYMENT_NAME omgevingsvariabelen in en meld u aan met 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();

Verwachte uitvoer

De agent roept de weer-API aan via het OpenAPI-hulpprogramma en retourneert de huidige voorwaarden voor de aangevraagde locatie:

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

Zie Agent_Step17_OpenAPITools voor het volledige voorbeeld, inclusief geverifieerde API-patronen.

Voorbeeld van het gebruik van agents met het OpenAPI-hulpprogramma in de webservice, waarvoor verificatie is vereist

In dit voorbeeld voegt u een geverifieerd OpenAPI-hulpprogramma toe aan een werkset, koppelt u de werkset als een MCP-hulpprogramma en gebruikt u de agent in een scenario waarvoor verificatie is vereist. U gebruikt de TripAdvisor-specificatie.

Voor de TripAdvisor-service is verificatie op basis van sleutels vereist. Als u een verbinding wilt maken, opent u Microsoft Foundry, selecteert u Beheren in de navigatie rechtsboven, selecteert u Project details en selecteert u vervolgens het tabblad Verbonden resources. Maak ten slotte een nieuwe verbinding van het type Aangepaste sleutels. Geef deze tripadvisor een naam en voeg een sleutelwaardepaar toe. Voeg een sleutel toe met de naam key en voer een waarde in met uw TripAdvisor-sleutel.

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

Wat deze code doet

In dit C#-voorbeeld ziet u hoe u een OpenAPI-hulpprogramma gebruikt met API-sleutelverificatie via een werkset en projectverbinding. Wanneer u de code uitvoert:

1. De TripAdvisor OpenAPI-specificatie wordt geladen vanuit een lokaal bestand.
2. Hiermee wordt de tripadvisor projectverbinding opgehaald die uw API-sleutel bevat.
3. Hiermee maakt u een toolboxversie met de TripAdvisor-tool die zo is geconfigureerd dat deze de verbinding voor authenticatie gebruikt.
4. Koppelt de toolbox aan de agent als een MCP-tool.
5. Stuurt een aanvraag voor hotelaanaanveling in Parijs.
6. De agent roept de TripAdvisor-API aan met behulp van uw opgeslagen API-sleutel en retourneert resultaten.
7. Schoont de agent op door de agent te verwijderen.

Vereiste invoer

• Inline-tekenreekswaarde: projectEndpoint (het eindpunt van het Foundry-project)
• Lokaal bestand: Assets/tripadvisor_openapi.json
• Project verbinding: tripadvisor met geldige API-sleutel geconfigureerd

Verwachte uitvoer

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

Veelvoorkomende fouten

• ConnectionNotFoundException: Geen projectverbinding genaamd tripadvisor gevonden.
• AuthenticationException: Ongeldige API-sleutel in projectverbinding, of ontbrekende/onjuiste securitySchemes-configuratie in de OpenAPI-specificatie.
• Hulpprogramma niet gebruikt: verifieer of ToolChoice = ResponseToolChoice.CreateRequiredChoice() het gebruik van het hulpprogramma afdwingt.
• API-sleutel wordt niet doorgegeven aan API: Zorg ervoor dat de secties securitySchemes en security in de OpenAPI-specificatie correct zijn geconfigureerd.

Een Java-agent maken met openAPI-hulpprogrammamogelijkheden

Deze Java-installatie kan verwijzen naar MCP-hulpprogramma's, maar de Java SDK biedt nog geen API voor het maken van werksets.

In de volgende voorbeelden ziet u hoe u een OpenAPI-hulpprogramma aanroept met behulp van de REST API.

Een toegangstoken ophalen:

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

Anonieme authenticatie

Voeg OpenAPI-hulpprogramma's toe via een werkset en koppel de werkset als een MCP-hulpprogramma aan uw agent. Zie Wat is een werkset? voor meer informatie.

1. Maak een werkset met het openAPI-weerhulpmiddel:

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

De werkset toont een mcP-compatibel eindpunt op $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1, waarbij <version> de versie is die wordt geretourneerd door de vorige aanroep.

1. Maak een projectverbinding voor externe hulpprogramma's die verwijst naar het toolbox-eindpunt, met behulp van een Entra-gebruikerstoken zodat de identiteit van de aanroeper wordt doorgestuurd (doelgroep 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. Maak een antwoord dat gebruikmaakt van de werkset door deze als een MCP-hulpprogramma te koppelen.

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

API-sleutelverificatie (projectkoppeling)

Gebruik deze variant pas nadat de anonieme stroom is geslaagd. Configureer de projectverbinding en de OpenAPI-vermelding securitySchemes zoals beschreven in Verifiëren met API-sleutel.

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

Gebruik voor een API met bearertoken dezelfde project_connection aanvraagindeling, maar gebruik een verbinding die is geconfigureerd zoals beschreven onder Een verbinding met bearertoken instellen. De verbindingswaarde moet beginnen met Bearer gevolgd door een spatie.

Verificatie van beheerde identiteit

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

Wat deze code doet

In dit REST API-voorbeeld ziet u hoe u een OpenAPI-hulpprogramma aanroept met verschillende verificatiemethoden. De aanvraag:

1. Voor anonieme authenticatie wordt een toolbox gemaakt met de OpenAPI-tooldefinitie en de weerspecificatie van de API.
2. Maakt een antwoord dat de toolbox als MCP-hulpprogramma toevoegt en vraagt naar het weer in Seattle.
3. Toont aanvullende directe REST-hulpprogrammadefinities voor API-sleutel via projectverbinding en verificatie van beheerde identiteiten.
4. De agent gebruikt het hulpprogramma om de weer-API aan te roepen en retourneert opgemaakte resultaten.

Vereiste invoer

• Omgevingsvariabelen: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• Voor verificatie van API-sleutels: WEATHER_APP_PROJECT_CONNECTION_ID.
• Voor verificatie van beheerde identiteiten: MANAGED_IDENTITY_AUDIENCE.
• Inline OpenAPI-specificatie in verzoeklichaam.

Verwachte uitvoer

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

Veelvoorkomende fouten

• 401 Unauthorized: Ongeldig of ontbreekt AGENT_TOKEN, of API-sleutel is niet geïnjecteerd omdat securitySchemes en security ontbreekt in de OpenAPI-specificatie
• 404 Not Found: Onjuiste naam voor eindpunt- of modelimplementatie
• 400 Bad Request: Onjuiste OpenAPI-specificatie of ongeldige verificatie-instellingen
• API-sleutel niet verzonden met aanvraag: controleer of de components.securitySchemes sectie in de OpenAPI-specificatie juist is geconfigureerd (niet leeg) en overeenkomt met de naam van de projectverbindingssleutel

Een agent maken met openAPI-hulpprogrammamogelijkheden

In het volgende Voorbeeld van TypeScript-code ziet u hoe u een AI-agent maakt met de mogelijkheden van het OpenAPI-hulpprogramma door het OpenAPI-hulpprogramma toe te voegen aan een werkset en de werkset als een MCP-hulpprogramma te koppelen. De agent kan externe API's aanroepen die zijn gedefinieerd door OpenAPI-specificaties. Zie de sample in de Azure SDK voor JavaScript-opslagplaats op GitHub voor een JavaScript-versie van dit voorbeeld.

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

Wat deze code doet

In dit TypeScript-voorbeeld wordt een agent gemaakt met een OpenAPI-hulpprogramma voor weergegevens door gebruik te maken van anonieme authenticatie. Wanneer u de code uitvoert:

1. De Weer OpenAPI-specificatie wordt geladen vanuit een lokaal JSON-bestand.
2. Maakt een toolboxversie met de weertool.
3. Koppelt de toolbox als een MCP-tool aan de agent en verzendt vervolgens een streaming-verzoek met een vraag over het weer in Seattle en kledingadvies.
4. Verwerkt het streaming-antwoord en geeft delta's weer zodra ze binnenkomen.
5. Het dwingt het gebruik van hulpprogramma's af door tool_choice: "required" te gebruiken om ervoor te zorgen dat de API wordt aangeroepen.
6. Schoont de agent op door de agent te verwijderen.

Vereiste invoer

• Inline-tekenreekswaarde: PROJECT_ENDPOINT (het eindpunt van het Foundry-project)
• Lokaal bestand: ../assets/weather_openapi.json (OpenAPI-specificatie)

Verwachte uitvoer

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!

Veelvoorkomende fouten

• Error: OpenAPI specification not found: Bestandspad incorrect of bestand ontbreekt
• AuthenticationError: ongeldige referenties voor Azure
• API-sleutel werkt niet: als u overschakelt van anonieme naar API-sleutelverificatie, zorg er dan voor dat de OpenAPI-specificatie en securitySchemes en security correct geconfigureerd zijn.

Een agent maken die gebruikmaakt van OpenAPI-hulpprogramma's die zijn geverifieerd met een projectverbinding

In het volgende TypeScript-codevoorbeeld ziet u hoe u een AI-agent maakt die gebruikmaakt van OpenAPI-hulpprogramma's die zijn geverifieerd via een projectverbinding. De agent laadt de TripAdvisor OpenAPI-specificatie van lokale assets en kan de API aanroepen via de geconfigureerde projectverbinding. Zie de sample in de Azure SDK voor JavaScript-opslagplaats op GitHub voor een JavaScript-versie van dit voorbeeld.

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

Wat deze code doet

In dit TypeScript-voorbeeld ziet u hoe u een OpenAPI-hulpprogramma gebruikt met API-sleutelverificatie via een projectverbinding. Wanneer u de code uitvoert:

1. De TripAdvisor OpenAPI-specificatie wordt geladen vanuit een lokaal bestand.
2. Verificatie wordt geconfigureerd met behulp van de TRIPADVISOR_CONNECTION_ID constante.
3. Er wordt een agent gemaakt met het TripAdvisor-hulpprogramma dat gebruikmaakt van de projectverbinding voor API-sleutelverificatie.
4. Er wordt een streamingaanvraag verzonden voor locatiegegevens van TripAdvisor.
5. Het dwingt het gebruik van hulpprogramma's af door tool_choice: "required" te gebruiken om ervoor te zorgen dat de API wordt aangeroepen.
6. Het verwerkt en geeft het streaming-antwoord weer.
7. De agent wordt opgeschoond door deze te verwijderen.

Vereiste invoer

• Inline-tekenreekswaarden: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
• Lokaal bestand: ../assets/tripadvisor_openapi.json
• Project verbinding geconfigureerd met TripAdvisor-API-sleutel

Verwachte uitvoer

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!

Veelvoorkomende fouten

• Error: OpenAPI specification not found: Controleer het bestandspad.
• Er is geen verbinding gevonden: Controleer of TRIPADVISOR_CONNECTION_ID de verbinding juist is en of de verbinding bestaat.
• AuthenticationException: Ongeldige API-key in projectverbinding.
• API-sleutel die niet is geïnjecteerd in aanvragen: uw OpenAPI-specificatie moet de juiste securitySchemes (onder components) en security secties bevatten. De sleutelnaam in securitySchemes moet overeenkomen met de sleutel in uw projectverbinding.
• Content type is not supported: Momenteel worden slechts deze twee inhoudstypen voor de hoofdtekst van de aanvraag ondersteund: application/json en application/json-patch+json. Antwoordinhoudstypen zijn niet beperkt.