Ansluta agenter till OpenAPI-verktyg

Anonym autentisering:

Skapa en OpenAPI-anslutning med authType: "None" först och ersätt <OPENAPI_CONNECTION_ID> med dess fullständiga resurs-ID.

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

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

Projektets hanterade identitetsautentisering:

Skapa en OpenAPI-projektanslutning med authType: "ProjectManagedIdentity"och skicka dess fullständiga resurs-ID med auth.type: "project_connection". Använd inte den direkta målgruppskonfigurationen managed_identity i en verktygslåda.

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

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

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

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

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

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

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

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

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

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

# Create a client to call Foundry API
with AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
) as project:
    weather_asset_file_path = os.path.abspath(
        os.path.join(os.path.dirname(__file__), "../assets/weather_openapi.json")
    )

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

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

    agent = project.agents.create_version(
        agent_name=AGENT_NAME,
        definition=PromptAgentDefinition(
            model="gpt-4.1-mini",
            instructions="You are a helpful assistant.",
            tools=[weather_tool],
        ),
    )

    with project.get_openai_client(agent_name=agent.name) as openai:
        response = openai.responses.create(
            input="What's the weather in Seattle?",
        )
        print(response.output_text)

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

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.15.0" "azure-ai-projects>=2.3.0,<2.8.0" 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,
    OpenApiProjectConnectionAuthDetails,
    OpenApiProjectConnectionSecurityScheme,
)

PROJECT_ENDPOINT = os.environ["FOUNDRY_PROJECT_ENDPOINT"]


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

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

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

    weather_tool = OpenApiToolboxTool(
        openapi=OpenApiFunctionDefinition(
            name="get_weather",
            spec=openapi_weather,
            description="Retrieve weather information for a location.",
            auth=OpenApiProjectConnectionAuthDetails(
                security_scheme=OpenApiProjectConnectionSecurityScheme(
                    project_connection_id=os.environ["OPENAPI_CONNECTION_ID"]
                )
            ),
        )
    )

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

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

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

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

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


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

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

#pragma warning disable AAIP002

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

    public static void Main()
    {
        var projectEndpoint =
            Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_PROJECT_ENDPOINT before running.");
        var deploymentName =
            Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_MODEL_DEPLOYMENT_NAME before running.");

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

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

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

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

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

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

• Miljövariabler: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEoch OPENAPI_CONNECTION_ID.
• 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 integreringen med Microsoft Agent Framework AddFoundryToolboxes. Använd ett ASP.NET Core projekt med Azure.AI.AgentServer.Responses och Microsoft.Agents.AI.Foundry.Hosting, utöver C#-beroendena i Krav. Ange FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEoch OPENAPI_CONNECTION_IDoch logga in med az login.

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

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

string projectEndpoint = Environment.GetEnvironmentVariable(
    "FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("Set FOUNDRY_PROJECT_ENDPOINT.");
string deploymentName = Environment.GetEnvironmentVariable(
    "FOUNDRY_MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("Set FOUNDRY_MODEL_DEPLOYMENT_NAME.");
DefaultAzureCredential credential = new();

// 1. Create the OpenAPI tool and add it to a toolbox. Using a toolbox is the
//    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
string filePath = GetFile();
OpenApiFunctionDefinition toolDefinition = new(
    name: "get_weather",
    specification: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
    authentication: new OpenApiProjectConnectionAuthenticationDetails(
        new OpenApiProjectConnectionSecurityScheme(
            Environment.GetEnvironmentVariable("OPENAPI_CONNECTION_ID")
            ?? throw new InvalidOperationException(
                "Set OPENAPI_CONNECTION_ID before running.")))
);
toolDefinition.Description = "Retrieve weather information for a location.";
OpenApiToolboxTool openapiTool = new(toolDefinition);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateVersion(
        name: "openapi-toolbox",
        tools: [openapiTool],
        description: "Toolbox with the OpenAPI weather tool");
projectClient.AgentAdministrationClient.GetAgentToolboxes()
    .UpdateDefaultVersion(toolboxVersion.Name, toolboxVersion.Version);

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

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

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

Förväntade utdata

Exemplet startar en HTTP-server. När du skickar en Responses-begäran som frågar om vädret anropar agenten API:et via verktygslådan och returnerar de aktuella väderförhållandena:

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 kopplar du ett autentiserat OpenAPI-verktyg direkt till en promptagent. Du använder TripAdvisor-specifikationen och en API-nyckel som lagras i en projektanslutning.

TripAdvisor-tjänsten kräver API-nyckelautentisering. Skapa projektanslutningen enligt beskrivningen i Autentisera med API-nyckeln och ange OPENAPI_CONNECTION_ID till dess fullständiga resurs-ID. Anslutningens nyckelnamn måste matcha TripAdvisor-specifikationen.

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

#pragma warning disable AAIP002

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

    public static void Main()
    {
        var projectEndpoint =
            Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_PROJECT_ENDPOINT before running.");
        var deploymentName =
            Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME")
            ?? throw new InvalidOperationException(
                "Set FOUNDRY_MODEL_DEPLOYMENT_NAME before running.");

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

        // Create an OpenAPI tool with authentication by project connection security scheme.
        string filePath = GetFile();
        var connectionId =
            Environment.GetEnvironmentVariable("OPENAPI_CONNECTION_ID")
            ?? throw new InvalidOperationException(
                "Set OPENAPI_CONNECTION_ID to the TripAdvisor connection ID.");
        OpenApiFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            specification: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            authentication: new OpenApiProjectConnectionAuthenticationDetails(new OpenApiProjectConnectionSecurityScheme(
                projectConnectionId: connectionId
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        OpenApiTool openapiTool = new(toolDefinition);

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

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

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

Vad den här koden gör

I det här C#-exemplet används 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 refererar till TripAdvisor-projektanslutningen som innehåller din API-nyckel.
3. Det bifogar TripAdvisor-verktyget till agenten, som konfigurerats för att använda anslutningen för autentisering.
4. Skickar en begäran om hotellrekommendationer i Paris.
5. Agenten anropar TripAdvisor-API:et med hjälp av din lagrade API-nyckel och returnerar resultat.
6. Rensar genom att ta bort agenten.

Obligatoriska indata

• Miljövariabler: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEoch OPENAPI_CONNECTION_ID.
• 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" \
  --header "Foundry-Features: Toolboxes=V1Preview" \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the OpenAPI weather tool",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "project_connection",
            "security_scheme": {
              "project_connection_id": "'$OPENAPI_CONNECTION_ID'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

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.

   Ställ in TOOLBOX_CONNECTION_ID till det fullständiga resurs-ID:t för openapi-toolbox-conn. Den här anslutningen är separat från den anonyma OpenAPI-anslutningen i OPENAPI_CONNECTION_ID. Ersätt <version> med den version som returnerades när du skapade verktygslådan.

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

API-nyckelautentisering (projektanslutning)

Använd endast den här varianten när det anonyma flödet har lyckats. Ladda ned tripadvisor_openapi.json från Innan du kör kodexemplen. Konfigurera API-nyckelanslutningen och specifikationens securitySchemes och security poster enligt beskrivningen i Autentisera med API-nyckel. Ställ in OPENAPI_CONNECTION_ID på det fullständiga resurs-ID:t för den anslutningen, inte den anonyma väderanslutningen.

I det här Bash-exemplet används jq för att inkludera specifikationen i samma remote_tool begärandeformat som exemplen på projekthanterade identiteter.

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

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

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

För projekthanterad identitet, skapa först en OpenAPI-projektanslutning. Ange sedan hela resurs-ID:t i Responses-begäran. Se REST-exemplet i Anropa ett OpenAPI-verktyg med projekthanterad identitet.

Kontohanterad hanterad identitet stöds endast för OpenAPI-verktyg som är kopplade direkt till promptagenter i befintliga prenumerationer. Det stöds inte i verktygspaneler. Använd hanterad identitet för projekt även för promptagenter. Migrera befintliga konfigurationer så snart som möjligt.

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 en direkt REST-verktygsdefinition för API-nyckelautentisering via en projektanslutning.
4. Agenten anropar api:et som valts av verktygskonfigurationen och returnerar resultatet.

Obligatoriska indata

• Miljövariabler: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• För anonym autentisering: OPENAPI_CONNECTION_ID, refererar till den anonyma OpenAPI-projektanslutningen, och TOOLBOX_CONNECTION_ID, refererar till verktygslådans MCP-anslutning.
• För API-nyckelautentisering: OPENAPI_CONNECTION_ID, som refererar till TripAdvisor API-nyckelanslutningen, och tripadvisor_openapi.json.
• För autentisering med hanterad identitet för projekt: OPENAPI_CONNECTION_ID, enligt exemplet på hanterad identitet för projekt.
• Infogad OpenAPI-specifikation i begärandetexten.

Förväntade utdata

{
  "id": "resp_abc123",
  "object": "response",
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "The weather in Seattle, WA today is cloudy with a temperature of 52°F (11°C)..."
        }
      ]
    }
  ]
}

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,
  OpenApiToolboxTool,
  OpenApiFunctionDefinition,
  OpenApiProjectConnectionAuthDetails,
} from "@azure/ai-projects";
import * as fs from "fs";
import * as path from "path";

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Set ${name} before running.`);
  }
  return value;
}
const PROJECT_ENDPOINT = requiredEnv("FOUNDRY_PROJECT_ENDPOINT");
const deploymentName = requiredEnv("FOUNDRY_MODEL_DEPLOYMENT_NAME");
const weatherSpecPath = path.resolve("assets", "weather_openapi.json");

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

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

function createWeatherTool(spec: unknown): OpenApiToolboxTool {
  const connectionId = process.env.OPENAPI_CONNECTION_ID;
  if (!connectionId) {
    throw new Error("Set OPENAPI_CONNECTION_ID before running.");
  }
  const auth: OpenApiProjectConnectionAuthDetails = {
    type: "project_connection",
    security_scheme: {
      project_connection_id: connectionId,
    },
  };
  const definition: OpenApiFunctionDefinition = {
    name: "get_weather",
    description: "Retrieve weather information for a location using wttr.in",
    spec,
    auth,
  };

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

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

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

  const weatherTool = createWeatherTool(weatherSpec);

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

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

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

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

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

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

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

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

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

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

• Miljövariabler: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME, OPENAPI_CONNECTION_IDoch TOOLBOX_CONNECTION_ID.
• Lokal fil: assets/weather_openapi.json (OpenAPI-specifikation).

Förväntade utdata

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

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

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Set ${name} before running.`);
  }
  return value;
}
const PROJECT_ENDPOINT = requiredEnv("FOUNDRY_PROJECT_ENDPOINT");
const deploymentName = requiredEnv("FOUNDRY_MODEL_DEPLOYMENT_NAME");
const connectionId = requiredEnv("OPENAPI_CONNECTION_ID");
const tripAdvisorSpecPath = path.resolve("assets", "tripadvisor_openapi.json");

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

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

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

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

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

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

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

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

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

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

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

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

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 refererar till API-nyckelanslutningen med hjälp av OPENAPI_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

• Miljövariabler: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEoch OPENAPI_CONNECTION_ID.
• Lokal fil: ../assets/tripadvisor_openapi.json
• Projektanslutning konfigurerad med TripAdvisor API-nyckel

Förväntade utdata

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

Vanliga fel

• Error: OpenAPI specification not found: Kontrollera filsökvägen.
• Anslutningen hittades inte: Kontrollera att OPENAPI_CONNECTION_ID är det fullständiga resurs-ID:t för API-nyckelanslutningen.
• 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.

Installera beroendena med pip install openai azure-identity.

import json
import os

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


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

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

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


if __name__ == "__main__":
    main()

Referens: Azure Identity-tokenprovider.

Argumentet extra_body vidarebefordrar den tjänstspecifika remote_tool nyttolasten utan att det krävs någon typ av OpenAPI-verktygsmodell i OpenAI SDK.

Använd .NET 8 eller senare och installera biblioteket för autentiseringsuppgifter med dotnet add package Azure.Identity. I det här exemplet skickas nyttolasten för det tjänstspecifika verktyget med HttpClient.

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

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

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

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

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

Referens: DefaultAzureCredential, HttpClient.

Använd Node.js 20 eller senare och installera inloggningsbiblioteket med npm install @azure/identity. Spara det här JavaScript-exemplet som openapi-project-mi.mjs.

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

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

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

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

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

Referens: DefaultAzureCredential.

Använd Java 11 eller senare. Lägg till com.azure:azure-identity och com.fasterxml.jackson.core:jackson-databind till dina Maven-beroenden. I det här exemplet skickas nyttolasten för det tjänstspecifika verktyget med Java HTTP-klienten.

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

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

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

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

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

Referens: DefaultAzureCredentialBuilder.

Använd Bash, Azure CLI, curl och jq för att skapa begäran från translator_openapi.json. Anropartoken riktar sig mot Foundry, inte Azure Resource Manager eller Translator.

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

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

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

Referens: Azure CLI åtkomsttoken.