Ansluta agenter till OpenAPI-verktyg

Anonym autentisering:

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

Projektanslutningsautentisering:

Använd det här mönstret när API:et kräver en nyckel eller token som lagras i en Foundry-projektanslutning.

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

Hanterad identitetsautentisering:

Använd det här mönstret när mål-API:et autentiseras via Microsoft Entra-ID. Foundry-projektets hanterade identitet anropar API:et för agentens räkning. Kontrollera att den hanterade identiteten har den RBAC-roll som krävs för måltjänsten innan du använder det här mönstret.

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

Exempel på hur du använder agenter med OpenAPI-verktyget

Det här exemplet visar hur du använder tjänster som beskrivs av en OpenAPI-specifikation med hjälp av en agent. Tjänsten wttr.in används för att hämta väder och dess specifikationsfil weather_openapi.json. Välj Prompt Agents om du vill använda Azure AI Projects SDK för att skapa en agent på serversidan eller Hosted Agents för att använda Microsoft Agent Framework för att skapa en tillfällig agent i processen.

Aktivera agenter

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)

I det här exemplet skapas en promptagent med ett OpenAPI-verktyg som anropar wttr.in väder-API:et med hjälp av anonym autentisering. Verktyget är kopplat direkt till agentdefinitionen. När du kör koden:

1. Den läser in OpenAPI-specifikationen för väder från en lokal JSON-fil.
2. Skapar en promptagent med väderverktyget konfigurerat för anonym åtkomst.
3. Skickar en fråga om Seattles väder.
4. Agenten använder OpenAPI-verktyget för att anropa väder-API:et och returnerar formaterade resultat.
5. Rensar genom att ta bort agentversionen.

Hostade agenter

Det här exemplet använder FoundryChatClient från Microsoft Agent Framework och ansluter till verktygslådans MCP-slutpunkt med hjälp av FoundryToolbox. Installera kompatibla paketversioner med pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity jsonref, ange FOUNDRY_PROJECT_ENDPOINT miljövariabeln och logga in med az login. OpenApiToolboxTool är den verktygslådespecifika modellen. använd OpenApiTool endast när du kopplar verktyget direkt till en 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())

Förväntade utdata

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

Exempel på hur du använder agenter med OpenAPI-verktyget

Det här exemplet visar hur du använder tjänster som beskrivs av en OpenAPI-specifikation med hjälp av en agent. Tjänsten wttr.in används för att hämta väder och dess specifikationsfil weather_openapi.json. Välj Prompt Agents om du vill använda Azure AI Projects SDK för att skapa en agent på serversidan eller Hosted Agents för att använda Microsoft Agent Framework för att skapa en tillfällig agent i processen.

Aktivera agenter

I det här exemplet används synkrona metoder för klientbiblioteket Azure AI Projects. Ett exempel som använder asynkrona metoder finns i sample i Azure SDKs för .NET lagringsplats på GitHub.

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

class OpenAPIDemo
{
    // Utility method to get the OpenAPI specification file from the Assets folder.
    private static string GetFile([CallerFilePath] string pth = "")
    {
        var dirName = Path.GetDirectoryName(pth) ?? "";
        return Path.Combine(dirName, "Assets", "weather_openapi.json");
    }

    public static void Main()
    {
        // Format: "https://resource_name.ai.azure.com/api/projects/project_name"
        var projectEndpoint = "your_project_endpoint";

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

        // Create an Agent with `OpenAPIAgentTool` and anonymous authentication.
        string filePath = GetFile();
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "get_weather",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIAnonymousAuthenticationDetails()
        );
        toolDefinition.Description = "Retrieve weather information for a location.";
        OpenAPITool openapiTool = new(toolDefinition);

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

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

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

Vad den här koden gör

Det här C#-exemplet skapar en agent med ett OpenAPI-verktyg som hämtar väderinformation från wttr.in med hjälp av anonym autentisering. När du kör koden:

1. Den läser väder OpenAPI-specifikationen från en lokal JSON-fil.
2. Skapar en agent med väderverktyget konfigurerat.
3. Skickar en begäran som frågar om Seattles väder med hjälp av OpenAPI-verktyget.
4. Agenten anropar väder-API:et och returnerar resultatet.
5. Rensar genom att ta bort agenten.

Obligatoriska indata

• Infogat strängvärde: projectEndpoint (slutpunkten för Foundry-projektet)
• Lokal fil: Assets/weather_openapi.json (OpenAPI-specifikation)

Förväntade utdata

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

Vanliga fel

• FileNotFoundException: OpenAPI-specifikationsfilen hittades inte i mappen Tillgångar
• UnauthorizedAccessException: Ogiltiga autentiseringsuppgifter eller otillräckliga RBAC-behörigheter
• API-nyckeln har inte matats in: Kontrollera att OpenAPI-specifikationen innehåller både securitySchemes (i components) och security avsnitt med matchande schemanamn

Hostade agenter

Det här exemplet skapar OpenAPI-verktygslådan med Azure AI Projects SDK och använder sedan Microsoft Agent Framework-integreringen AddFoundryToolboxes för att göra verktyget tillgängligt för den värdbaserade agenten. Installera Agent Framework-paketen AZURE_AI_PROJECT_ENDPOINT , ange projektslutpunkts- och AZURE_AI_MODEL_DEPLOYMENT_NAME miljövariablerna och logga in med 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();

Förväntade utdata

Agenten anropar väder-API:et via OpenAPI-verktyget och returnerar de aktuella villkoren för den begärda platsen:

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

Det fullständiga exemplet, inklusive autentiserade API-mönster, finns i Agent_Step17_OpenAPITools.

Exempel på att använda agenter med OpenAPI-verktyget på webbtjänsten, som kräver autentisering

I det här exemplet lägger du till ett autentiserat OpenAPI-verktyg i en verktygslåda, bifogar verktygslådan som ett MCP-verktyg och använder agenten i ett scenario som kräver autentisering. Du använder TripAdvisor-specifikationen.

TripAdvisor-tjänsten kräver nyckelbaserad autentisering. Om du vill skapa en anslutning öppnar du Microsoft Foundry, väljer Hantera i det övre högra navigeringsfältet, väljer Project information och väljer sedan fliken Anslutna resurser. Skapa slutligen en ny anslutning av typen Anpassade nycklar. Ge det namnet tripadvisor och lägg till ett nyckelvärdepar. Lägg till nyckeln med namnet key och ange ett värde med din TripAdvisor-nyckel.

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

Vad den här koden gör

Det här C#-exemplet visar hur du använder ett OpenAPI-verktyg med API-nyckelautentisering via en verktygslåda och projektanslutning. När du kör koden:

1. Den läser in TripAdvisor OpenAPI-specifikationen från en lokal fil.
2. Hämtar projektanslutningen tripadvisor som innehåller din API-nyckel.
3. Skapar en verktygslådeversion som innehåller verktyget TripAdvisor som konfigurerats för att använda anslutningen för autentisering.
4. Kopplar verktygslådan till agenten som ett MCP-verktyg.
5. Skickar en begäran om hotellrekommendationer i Paris.
6. Agenten anropar TripAdvisor-API:et med hjälp av din lagrade API-nyckel och returnerar resultat.
7. Rensar genom att ta bort agenten.

Obligatoriska indata

• Infogat strängvärde: projectEndpoint (slutpunkten för Foundry-projektet)
• Lokal fil: Assets/tripadvisor_openapi.json
• Projektanslutning: tripadvisor med giltig API-nyckel konfigurerad.

Förväntade utdata

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

Vanliga fel

• ConnectionNotFoundException: Ingen projektanslutning med namnet tripadvisor hittades.
• AuthenticationException: Ogiltig API-nyckel i projektanslutningen eller saknade/felaktiga securitySchemes konfigurationer i OpenAPI-specifikationen.
• Verktyget används inte: Verifiering av ToolChoice = ResponseToolChoice.CreateRequiredChoice() tvingar användningen av verktyget.
• API-nyckeln skickas inte till API: Kontrollera att OpenAPI-specifikationen har rätt securitySchemes och security konfigurerade avsnitt.

Skapa en Java agent med OpenAPI-verktygsfunktioner

Den här Java konfigurationen kan referera till MCP-verktyg, men Java SDK visar ännu inte ett API för att skapa verktygslådan.

I följande exempel visas hur du anropar ett OpenAPI-verktyg med hjälp av REST-API:et.

Hämta en åtkomsttoken:

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

Anonym autentisering

Lägg till OpenAPI-verktyg via en verktygslåda och koppla sedan verktygslådan till din agent som ett MCP-verktyg. Mer information finns i Vad är en verktygslåda?

1. Skapa en verktygslåda som innehåller OpenAPI-väderverktyget:

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

Verktygslådan exponerar en MCP-kompatibel ändpunkt på $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1, där <version> är den version som returnerades av föregående anrop.

1. Skapa en projektanslutning för fjärrverktyg som pekar på toolbox-slutpunkten, med hjälp av en Entra-användartoken så att anroparens identitet vidarebefordras (målgrupp 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. Skapa ett svar som använder verktygslådan genom att koppla den som ett MCP-verktyg.

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

Använd endast den här varianten när det anonyma flödet har lyckats. Konfigurera projektanslutningen och OpenAPI-posten securitySchemes enligt beskrivningen i Autentisera med API-nyckel.

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

För ett API för ägartoken behåller du samma project_connection form för begäran, men använder en anslutning som konfigurerats enligt beskrivningen i Konfigurera en anslutning för ägartoken. Anslutningsvärdet måste börja med Bearer följt av ett blanksteg.

Hanterad identitetsautentisering

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

Vad den här koden gör

Det här REST API-exemplet visar hur du anropar ett OpenAPI-verktyg med olika autentiseringsmetoder. Begäran:

1. För anonym autentisering skapar du en verktygslåda som innehåller OpenAPI-verktygsdefinitionen och väder-API-specifikationen.
2. Skapar ett svar som bifogar verktygslådan som ett MCP-verktyg och frågar om Seattles väder.
3. Visar ytterligare direkta REST-verktygsdefinitioner för API-nyckel via projektanslutning och hanterad identitetsautentisering.
4. Agenten använder verktyget för att anropa väder-API:et och returnerar formaterade resultat.

Obligatoriska indata

• Miljövariabler: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• För API-nyckelautentisering: WEATHER_APP_PROJECT_CONNECTION_ID.
• För hanterad identitetsautentisering: MANAGED_IDENTITY_AUDIENCE.
• Infogad OpenAPI-specifikation i begärandetexten.

Förväntade utdata

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

Vanliga fel

• 401 Unauthorized: Ogiltig eller saknas AGENT_TOKEN, eller API-nyckeln har inte matats in eftersom securitySchemes och security saknas i OpenAPI-specifikationen
• 404 Not Found: Felaktigt namn på slutpunkts- eller modelldistribution
• 400 Bad Request: Felaktig OpenAPI-specifikation eller ogiltig autentiseringskonfiguration
• API-nyckeln skickas inte med begäran: Kontrollera att components.securitySchemes avsnittet i OpenAPI-specifikationen är korrekt konfigurerat (inte tomt) och matchar namnet på projektanslutningsnyckeln

Skapa en agent med OpenAPI-verktygsfunktioner

Följande TypeScript-kodexempel visar hur du skapar en AI-agent med OpenAPI-verktygsfunktioner genom att lägga till OpenAPI-verktyget i en verktygslåda och bifoga verktygslådan som ett MCP-verktyg. Agenten kan anropa externa API:er som definierats av OpenAPI-specifikationer. En JavaScript-version av det här exemplet finns i sample i Azure SDKs för JavaScript-lagringsplatsen på GitHub.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const weatherSpecPath = path.resolve(__dirname, "../assets", "weather_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createWeatherTool(spec: unknown): OpenApiTool {
  const auth: OpenApiAnonymousAuthDetails = { type: "anonymous" };
  const definition: OpenApiFunctionDefinition = {
    name: "get_weather",
    description: "Retrieve weather information for a location using wttr.in",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  const weatherSpec = loadOpenApiSpec(weatherSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  const weatherTool = createWeatherTool(weatherSpec);

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

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

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

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

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

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

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

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

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

Vad den här koden gör

Det här TypeScript-exemplet skapar en agent med ett OpenAPI-verktyg för väderdata med hjälp av anonym autentisering. När du kör koden:

1. Den läser in OpenAPI-specifikationen för väder från en lokal JSON-fil.
2. Skapar en verktygslåda som innehåller väderverktyget.
3. Kopplar verktygslådan till agenten som ett MCP-verktyg och skickar sedan en begäran om strömmande svar med en fråga om vädret i Seattle och vad man bör ha på sig.
4. Bearbetar strömningssvaret och visar deltan när de tas emot.
5. Det tvingar verktygsanvändningen att använda tool_choice: "required" för att säkerställa att API:et anropas.
6. Rensar genom att ta bort agenten.

Obligatoriska indata

• Infogat strängvärde: PROJECT_ENDPOINT (slutpunkten för Foundry-projektet)
• Lokal fil: ../assets/weather_openapi.json (OpenAPI-specifikation)

Förväntade utdata

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!

Vanliga fel

• Error: OpenAPI specification not found: Filsökvägen är felaktig eller så saknas filen
• AuthenticationError: Ogiltiga Azure autentiseringsuppgifter
• API-nyckeln fungerar inte: Om du byter från anonym till API-nyckelautentisering kontrollerar du att OpenAPI-specifikationen har securitySchemes och security är korrekt konfigurerad

Skapa en agent som använder OpenAPI-verktyg autentiserade med en projektanslutning

Följande TypeScript-kodexempel visar hur du skapar en AI-agent som använder OpenAPI-verktyg som autentiseras via en projektanslutning. Agenten läser in TripAdvisor OpenAPI-specifikationen från lokala tillgångar och kan anropa API:et via den konfigurerade projektanslutningen. En JavaScript-version av det här exemplet finns i sample i Azure SDKs för JavaScript-lagringsplatsen på GitHub.

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

// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const TRIPADVISOR_CONNECTION_ID = "your-tripadvisor-connection-id";
const tripAdvisorSpecPath = path.resolve(__dirname, "../assets", "tripadvisor_openapi.json");

function loadOpenApiSpec(specPath: string): unknown {
  if (!fs.existsSync(specPath)) {
    throw new Error(`OpenAPI specification not found at: ${specPath}`);
  }

  try {
    const data = fs.readFileSync(specPath, "utf-8");
    return JSON.parse(data);
  } catch (error) {
    throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
  }
}

function createTripAdvisorTool(spec: unknown): OpenApiTool {
  const auth: OpenApiProjectConnectionAuthDetails = {
    type: "project_connection",
    security_scheme: {
      project_connection_id: TRIPADVISOR_CONNECTION_ID,
    },
  };

  const definition: OpenApiFunctionDefinition = {
    name: "get_tripadvisor_location_details",
    description:
      "Fetch TripAdvisor location details, reviews, or photos using the Content API via project connection auth.",
    spec,
    auth,
  };

  return {
    type: "openapi",
    openapi: definition,
  };
}

export async function main(): Promise<void> {
  const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);

  // Create clients to call Foundry API
  const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  // Create an agent with the OpenAPI project-connection tool
  const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
    kind: "prompt",
    model: "gpt-4.1-mini",
    instructions:
      "You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
    tools: [createTripAdvisorTool(tripAdvisorSpec)],
  });

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

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

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

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

Vad den här koden gör

Det här TypeScript-exemplet visar hur du använder ett OpenAPI-verktyg med API-nyckelautentisering via en projektanslutning. När du kör koden:

1. Den läser in TripAdvisor OpenAPI-specifikationen från en lokal fil.
2. Den konfigurerar autentisering med hjälp av konstanten TRIPADVISOR_CONNECTION_ID .
3. Den skapar en agent med TripAdvisor-verktyget som använder projektanslutningen för API-nyckelautentisering.
4. Den skickar en streamingförfrågan för TripAdvisor-platsdetaljer.
5. Det tvingar verktygsanvändningen att använda tool_choice: "required" för att säkerställa att API:et anropas.
6. Den bearbetar och visar strömningssvaret.
7. Den rensar genom att ta bort agenten.

Obligatoriska indata

• Infogade strängvärden: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
• Lokal fil: ../assets/tripadvisor_openapi.json
• Projektanslutning konfigurerad med TripAdvisor API-nyckel

Förväntade utdata

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!

Vanliga fel

• Error: OpenAPI specification not found: Kontrollera filsökvägen.
• Det går inte att hitta anslutningen: Kontrollera TRIPADVISOR_CONNECTION_ID att den är korrekt och att anslutningen finns.
• AuthenticationException: Ogiltig API-nyckel i projektanslutningen.
• API-nyckeln matas inte in i begäranden: OpenAPI-specifikationen måste innehålla rätt securitySchemes (under components) och security avsnitt. Nyckelnamnet i securitySchemes måste matcha nyckeln i projektanslutningen.
• Content type is not supported: För närvarande stöds endast dessa två innehållstyper för begärandetext: application/json och application/json-patch+json. Svarsinnehållstyper är inte begränsade.