Łączenie agentów z narzędziami OpenAPI

Uwierzytelnianie anonimowe:

Najpierw utwórz połączenie OpenAPI za pomocą authType: "None", a następnie zastąp <OPENAPI_CONNECTION_ID> jego pełnym identyfikatorem zasobu.

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

Autoryzacja połączenia projektu:

Użyj tego wzorca, gdy interfejs API wymaga klucza lub tokenu przechowywanego w połączeniu projektu Foundry.

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

uwierzytelnianie tożsamości zarządzanej w usłudze Project:

Utwórz połączenie projektu OpenAPI z authType: "ProjectManagedIdentity" i przekaż jego pełny identyfikator zasobu za pomocą polecenia auth.type: "project_connection". Nie używaj bezpośredniej konfiguracji odbiorców managed_identity w przyborniku.

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

Przykład użycia agentów z narzędziem OpenAPI

W tym przykładzie pokazano, jak używać usług opisanych przez specyfikację interfejsu OpenAPI przy użyciu agenta. Używa usługi wttr.in, aby uzyskać pogodę i plik specyfikacji weather_openapi.json. Wybierz Prompt Agents, aby za pomocą zestawu SDK Azure AI Projects utworzyć po stronie serwera agenta opartego na monicie, lub Hosted Agents, aby za pomocą Microsoft Agent Framework utworzyć tymczasowego agenta działającego w procesie.

Pobudzaj agentów

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)

W tym przykładzie tworzony jest agent oparty na monicie z narzędziem OpenAPI, które wywołuje pogodowy interfejs API wttr.in z użyciem uwierzytelniania anonimowego. Narzędzie jest dołączone bezpośrednio do definicji agenta. Po uruchomieniu kodu:

1. Ładuje specyfikację OpenAPI dotyczącą pogody z lokalnego pliku JSON.
2. Tworzy agenta monitu za pomocą narzędzia do obsługi pogody skonfigurowanego pod kątem dostępu anonimowego.
3. Wysyła zapytanie z pytaniem o pogodę w Seattle.
4. Agent używa narzędzia OpenAPI do wywoływania interfejsu API pogody i zwraca sformatowane wyniki.
5. Czyści, usuwając wersję agenta.

Hostowani agenci

W tym przykładzie użyto FoundryChatClient ze środowiska Microsoft Agent Framework i połączono się z punktem końcowym MCP zestawu narzędzi za pomocą FoundryToolbox. Zainstaluj zgodne wersje pakietów za pomocą pip install "agent-framework-foundry==1.15.0" "azure-ai-projects>=2.3.0,<2.8.0" jsonrefpolecenia , ustaw zmienną FOUNDRY_PROJECT_ENDPOINT środowiskową i zaloguj się przy użyciu polecenia az login. OpenApiToolboxTool to model specyficzny dla zestawu narzędzi; używaj OpenApiTool tylko wtedy, gdy dołączasz narzędzie bezpośrednio do agenta promptu.

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

Oczekiwane dane wyjściowe

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

Przykład użycia agentów z narzędziem OpenAPI

W tym przykładzie pokazano, jak używać usług opisanych przez specyfikację interfejsu OpenAPI przy użyciu agenta. Używa usługi wttr.in, aby uzyskać pogodę i plik specyfikacji weather_openapi.json. Wybierz Prompt Agents, aby za pomocą zestawu SDK Azure AI Projects utworzyć po stronie serwera agenta opartego na monicie, lub Hosted Agents, aby za pomocą Microsoft Agent Framework utworzyć tymczasowego agenta działającego w procesie.

Pobudzaj agentów

W tym przykładzie użyto metod synchronicznych biblioteki klienta Azure AI Projects. Przykład, który używa metod asynchronicznych, zobacz sample w Azure SDK dla repozytorium .NET w 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);
    }
}

Co robi ten kod

Ten przykład w języku C# tworzy agenta z narzędziem OpenAPI, które pobiera informacje o pogodzie z wttr.in przy użyciu uwierzytelniania anonimowego. Po uruchomieniu kodu:

1. Odczytuje specyfikację weather OpenAPI z lokalnego pliku JSON.
2. Tworzy agenta ze skonfigurowanym narzędziem do obsługi pogody.
3. Wysyła żądanie z pytaniem o pogodę w Seattle przy użyciu narzędzia OpenAPI.
4. Agent wywołuje interfejs API pogody i zwraca wyniki.
5. Czyści, usuwając agenta.

Wymagane dane wejściowe

• Zmienne środowiskowe: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEi OPENAPI_CONNECTION_ID.
• Plik lokalny: Assets/weather_openapi.json (specyfikacja interfejsu OpenAPI)

Oczekiwane dane wyjściowe

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

Typowe błędy

• FileNotFoundException: Nie można odnaleźć pliku specyfikacji interfejsu OpenAPI w folderze Assets
• UnauthorizedAccessException: Nieprawidłowe dane uwierzytelniające lub niewystarczające uprawnienia kontroli dostępu opartej na rolach
• Klucz API nie został wstrzyknięty: Sprawdź, czy specyfikacja OpenAPI zawiera zarówno securitySchemes (w components) oraz sekcje security z pasującymi nazwami schematów

Hostowani agenci

Ten przykład tworzy przybornik interfejsu OpenAPI za pomocą zestawu SDK Azure AI Projects, a następnie używa integracji Microsoft Agent Framework AddFoundryToolboxes. Oprócz zależności języka C# w Microsoft.Agents.AI.Foundry.Hosting należy użyć projektu ASP.NET Core z elementami i Azure.AI.AgentServer.Responses. Ustaw FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME i OPENAPI_CONNECTION_ID, a następnie zaloguj się za pomocą 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();

Oczekiwane dane wyjściowe

Przykład uruchamia serwer HTTP. Po wysłaniu żądania Responses z pytaniem o pogodę agent wywołuje interfejs API za pomocą przybornika i zwraca bieżące warunki:

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

Aby zapoznać się z pełnym przykładem, w tym uwierzytelnionymi wzorcami interfejsu API, zobacz Agent_Step17_OpenAPITools.

Przykład użycia agentów z narzędziem OpenAPI w usłudze sieci Web wymagającym uwierzytelniania

W tym przykładzie dołączasz uwierzytelnione narzędzie OpenAPI bezpośrednio do agenta promptu. Używasz specyfikacji TripAdvisor i klucza interfejsu API przechowywanego w połączeniu projektu.

Usługa TripAdvisor wymaga uwierzytelniania za pomocą klucza API. Utwórz połączenie projektu zgodnie z opisem w artykule Uwierzytelnianie przy użyciu klucza interfejsu API i ustaw OPENAPI_CONNECTION_ID na pełny identyfikator zasobu. Nazwa klucza połączenia musi być zgodna ze specyfikacją TripAdvisor.

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

#pragma warning disable AAIP002

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

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

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

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

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

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

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

Co robi ten kod

W tym przykładzie w języku C# użyto narzędzia OpenAPI z uwierzytelnianiem klucza interfejsu API za pośrednictwem połączenia projektu. Po uruchomieniu kodu:

1. Ładuje specyfikację Interfejsu OpenAPI TripAdvisor z pliku lokalnego.
2. Odwołuje się do połączenia projektu TripAdvisor zawierającego klucz interfejsu API.
3. Dołącza do agenta narzędzie TripAdvisor skonfigurowane do używania połączenia na potrzeby uwierzytelniania.
4. Wysyła wniosek o rekomendacje hotelowe w Paryżu.
5. Agent wywołuje interfejs API TripAdvisor przy użyciu przechowywanego klucza interfejsu API i zwraca wyniki.
6. Czyści, usuwając agenta.

Wymagane dane wejściowe

• Zmienne środowiskowe: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEi OPENAPI_CONNECTION_ID.
• Plik lokalny: Assets/tripadvisor_openapi.json
• Połączenie projektu: tripadvisor skonfigurowane z prawidłowym kluczem API

Oczekiwane dane wyjściowe

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

Typowe błędy

• ConnectionNotFoundException: Nie znaleziono połączenia projektu o nazwie tripadvisor .
• AuthenticationException: Nieprawidłowy klucz API w połączeniu projektu lub brak/nieprawidłowa konfiguracja securitySchemes w specyfikacji OpenAPI.
• Narzędzie nie jest używane: Sprawdź, czy ToolChoice = ResponseToolChoice.CreateRequiredChoice() wymusza użycie narzędzia.
• Klucz interfejsu API nie został przekazany do interfejsu API: Upewnij się, że specyfikacja interfejsu OpenAPI ma skonfigurowane odpowiednie sekcje securitySchemes i security.

Tworzenie agenta Java z funkcjami narzędzi OpenAPI

Ta konfiguracja w Javie może odwoływać się do narzędzi MCP, ale SDK Javy nie udostępnia jeszcze interfejsu API do tworzenia zestawu narzędzi.

W poniższych przykładach pokazano, jak wywołać narzędzie OpenAPI przy użyciu interfejsu API REST.

Uzyskiwanie tokenu dostępu:

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

Uwierzytelnianie anonimowe

Dodaj narzędzia OpenAPI za pomocą przybornika, a następnie dołącz przybornik do agenta jako narzędzie MCP. Aby uzyskać więcej informacji, zobacz Co to jest przybornik?

1. Utwórz przybornik zawierający narzędzie pogodowe OpenAPI:

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

Zestaw narzędzi udostępnia zgodny z MCP punkt końcowy pod adresem $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1, gdzie <version> to wersja zwrócona przez poprzednie wywołanie.

1. Utwórz połączenie projektu zdalnego narzędzia, które wskazuje punkt końcowy zestawu narzędzi, używając tokenu Entra użytkownika, aby tożsamość wywołującego została przekazana dalej (identyfikator odbiorcy 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. Utwórz odpowiedź, która korzysta z zestawu narzędzi, poprzez dołączenie go jako narzędzia MCP.

   Ustaw TOOLBOX_CONNECTION_ID na pełny identyfikator zasobu openapi-toolbox-conn. To połączenie jest oddzielone od anonimowego połączenia OpenAPI w OPENAPI_CONNECTION_ID. Zastąp element <version> wersją zwróconą podczas tworzenia toolbox.

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

Uwierzytelnianie klucza API (połączenie z projektem)

Użyj tego wariantu dopiero, gdy anonimowy przepływ zakończy się pomyślnie. Pobierz tripadvisor_openapi.json, korzystając z artykułu Przed uruchomieniem przykładów kodu. Skonfiguruj połączenie klucza interfejsu API oraz wpisy securitySchemes i security specyfikacji zgodnie z opisem w temacie Uwierzytelnianie za pomocą klucza interfejsu API. Ustaw OPENAPI_CONNECTION_ID na pełny identyfikator zasobu tego połączenia, a nie anonimowe połączenie pogodowe.

W tym przykładzie powłoki Bash użyto języka jq do uwzględnienia specyfikacji w tej samej remote_tool strukturze żądania co przykłady zarządzanej tożsamości projektu.

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

W przypadku interfejsu API z tokenem okaziciela zachowaj ten sam project_connection format żądania, ale użyj połączenia skonfigurowanego zgodnie z opisem w sekcji Konfigurowanie połączenia z tokenem okaziciela. Wartość połączenia musi zaczynać się od Bearer, po którym należy wstawić spację.

Uwierzytelnianie tożsamości zarządzanej

W przypadku tożsamości zarządzanej dla projektu najpierw utwórz połączenie OpenAPI projektu. Następnie przekaż pełny identyfikator zasobu w żądaniu Responses. Zobacz przykład REST w artykule Wywoływanie narzędzia OpenAPI przy użyciu tożsamości zarządzanej projektu.

Tożsamość zarządzana konta jest obsługiwana tylko w przypadku narzędzi OpenAPI dołączonych bezpośrednio do agentów promptów w istniejących subskrypcjach. Nie jest obsługiwana w zestawach narzędzi. Użyj zarządzanej tożsamości projektu również dla agentów promptów. Zmigruj istniejące konfiguracje tak szybko, jak to możliwe.

Co robi ten kod

W tym przykładzie interfejsu API REST pokazano, jak wywołać narzędzie OpenAPI z różnymi metodami uwierzytelniania. Żądanie:

1. Na potrzeby uwierzytelniania anonimowego tworzy zestaw narzędzi zawierający definicję narzędzia OpenAPI i specyfikację API pogody.
2. Tworzy odpowiedź, która dołącza zestaw narzędzi jako narzędzie MCP i pyta o pogodę w Seattle.
3. Przedstawia dodatkową bezpośrednią definicję narzędzia REST na potrzeby uwierzytelniania klucza interfejsu API za pośrednictwem połączenia projektu.
4. Agent wywołuje interfejs API wybrany przez konfigurację narzędzia i zwraca wyniki.

Wymagane dane wejściowe

• Zmienne środowiskowe: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• W przypadku anonimowego uwierzytelniania: OPENAPI_CONNECTION_ID, odwołując się do anonimowego połączenia projektu OpenAPI i TOOLBOX_CONNECTION_ID, odwołując się do połączenia MCP przybornika.
• W przypadku uwierzytelniania za pomocą klucza API: OPENAPI_CONNECTION_ID, odwołanie do odwołania do klucza API TripAdvisor oraz tripadvisor_openapi.json.
• W przypadku uwierzytelniania tożsamości zarządzanej projektu: OPENAPI_CONNECTION_ID, jak pokazano w przykładzie tożsamości zarządzanej projektu.
• Wbudowana specyfikacja interfejsu OpenAPI w treści żądania.

Oczekiwane dane wyjściowe

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

Typowe błędy

• 401 Unauthorized: Nieprawidłowy lub brak AGENT_TOKEN klucza interfejsu API lub nie został wstrzyknięty z powodu, że brakuje securitySchemes i security w specyfikacji OpenAPI
• 404 Not Found: Nieprawidłowa nazwa wdrożenia punktu końcowego lub modelu
• 400 Bad Request: Źle sformułowana specyfikacja interfejsu OpenAPI lub nieprawidłowa konfiguracja uwierzytelniania
• Klucz API nie został wysłany z żądaniem: Sprawdź, czy sekcja w specyfikacji OpenAPI jest poprawnie skonfigurowana (niepusta) i pasuje do nazwy klucza połączenia projektu

Tworzenie agenta za pomocą narzędzi OpenAPI

Poniższy przykład kodu TypeScript pokazuje, jak utworzyć agenta sztucznej inteligencji z funkcjami narzędzi OpenAPI, dodając narzędzie OpenAPI do przybornika i dołączając przybornik jako narzędzie MCP. Agent może wywoływać zewnętrzne interfejsy API zdefiniowane przez specyfikacje interfejsu OpenAPI. Aby zapoznać się z wersją języka JavaScript w tym przykładzie, zobacz sample w repozytorium Azure SDK dla języka JavaScript w 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;
});

Co robi ten kod

Ten przykład języka TypeScript tworzy agenta z narzędziem OpenAPI do obsługi danych pogodowych przy użyciu uwierzytelniania anonimowego. Po uruchomieniu kodu:

1. Ładuje specyfikację OpenAPI dotyczącą pogody z lokalnego pliku JSON.
2. Tworzy wersję zestawu narzędzi zawierającą narzędzie pogody.
3. Dołącza zestaw narzędzi do agenta jako narzędzie MCP, a następnie wysyła żądanie strumieniowe z pytaniem dotyczącym pogody w Seattle i doboru stroju.
4. Przetwarza odpowiedź przesyłania strumieniowego i wyświetla zmiany po ich nadejściu.
5. Wymusza użycie narzędzia, korzystając z elementu tool_choice: "required", aby zapewnić wywołanie interfejsu API.
6. Czyści, usuwając agenta.

Wymagane dane wejściowe

• Zmienne środowiskowe: FOUNDRY_PROJECT_ENDPOINT, OPENAPI_CONNECTION_ID, FOUNDRY_MODEL_DEPLOYMENT_NAME i TOOLBOX_CONNECTION_ID.
• Plik lokalny: assets/weather_openapi.json (specyfikacja interfejsu OpenAPI).

Oczekiwane dane wyjściowe

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

Typowe błędy

• Error: OpenAPI specification not found: Nieprawidłowa ścieżka pliku lub brak pliku
• AuthenticationError: Nieprawidłowe poświadczenia Azure
• Klucz interfejsu API nie działa: Jeśli przełączasz się z anonimowego uwierzytelniania na uwierzytelnianie przy użyciu klucza API, upewnij się, że specyfikacja interfejsu OpenAPI została securitySchemessecurity prawidłowo skonfigurowana

Tworzenie agenta korzystającego z narzędzi OpenAPI uwierzytelnionych za pomocą połączenia projektu

W poniższym przykładzie kodu TypeScript pokazano, jak utworzyć agenta sztucznej inteligencji, który używa narzędzi OpenAPI uwierzytelnionych za pośrednictwem połączenia projektu. Agent ładuje specyfikację interfejsu OpenAPI TripAdvisor z zasobów lokalnych i może wywołać interfejs API za pośrednictwem skonfigurowanego połączenia projektu. Aby zapoznać się z wersją języka JavaScript w tym przykładzie, zobacz sample w repozytorium Azure SDK dla języka JavaScript w 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;
});

Co robi ten kod

W tym przykładzie języka TypeScript pokazano, jak używać narzędzia OpenAPI z uwierzytelnianiem klucza interfejsu API za pośrednictwem połączenia projektu. Po uruchomieniu kodu:

1. Ładuje specyfikację Interfejsu OpenAPI TripAdvisor z pliku lokalnego.
2. Odwołuje się do połączenia klucza interfejsu API przy użyciu OPENAPI_CONNECTION_ID.
3. Tworzy agenta za pomocą narzędzia TripAdvisor, które używa połączenia projektu do uwierzytelniania za pomocą klucza API.
4. Wysyła żądanie dotyczące przesyłania strumieniowego szczegółów lokalizacji TripAdvisor.
5. Wymusza użycie narzędzia, korzystając z elementu tool_choice: "required", aby zapewnić wywołanie interfejsu API.
6. Przetwarza i wyświetla odpowiedź strumieniową.
7. Czyści poprzez usunięcie agenta.

Wymagane dane wejściowe

• Zmienne środowiskowe: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEi OPENAPI_CONNECTION_ID.
• Plik lokalny: ../assets/tripadvisor_openapi.json
• Konfiguracja połączenia projektu z kluczem API TripAdvisor

Oczekiwane dane wyjściowe

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

Typowe błędy

• Error: OpenAPI specification not found: Sprawdź ścieżkę pliku.
• Nie można odnaleźć połączenia: Sprawdź, czy OPENAPI_CONNECTION_ID jest pełnym identyfikatorem zasobu połączenia klucza API.
• AuthenticationException: Nieprawidłowy klucz API w połączeniu z projektem.
• Klucz interfejsu API nie jest wstrzykiwany w żądaniach: specyfikacja interfejsu OpenAPI musi zawierać odpowiednie securitySchemes (w obszarze components) i security sekcje. Nazwa klucza w securitySchemes musi być zgodna z kluczem w połączeniu projektu.
• Content type is not supported: Obecnie obsługiwane są tylko te dwa typy zawartości treści żądań: application/json i application/json-patch+json. Typy zawartości odpowiedzi nie są ograniczone.

Zainstaluj zależności za pomocą polecenia 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()

Odwołanie: dostawca tokenów Azure Identity.

Argument extra_body przekazuje specyficzny dla usługi remote_tool payload bez konieczności stosowania typizowanego modelu narzędzia OpenAPI w zestawie OpenAI SDK.

Użyj .NET 8 lub nowszego, a następnie zainstaluj bibliotekę poświadczeń za pomocą polecenia dotnet add package Azure.Identity. Ten przykład wysyła ładunek danych narzędzia specyficznego dla usługi z użyciem 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);

Dokumentacja referencyjna: DefaultAzureCredential, HttpClient.

Użyj Node.js 20 lub nowszej, a następnie zainstaluj bibliotekę poświadczeń za pomocą polecenia npm install @azure/identity. Zapisz ten przykład w języku JavaScript jako 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);

Odwołanie: DefaultAzureCredential.

Użyj Java 11 lub nowszego. Dodaj com.azure:azure-identity i com.fasterxml.jackson.core:jackson-databind do zależności Maven. Ten przykład wysyła ładunek danych narzędzia specyficznego dla usługi za pomocą klienta HTTP języka Java.

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

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

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

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

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

Dokumentacja referencyjna: DefaultAzureCredentialBuilder.

Użyj powłoki Bash, Azure CLI, curl i jq, aby utworzyć żądanie na podstawie translator_openapi.json. Token wywołującego jest przeznaczony dla rozwiązania Foundry, a nie Azure Resource Manager ani 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

Odwołanie: tokeny dostępu Azure CLI.