Agents verbinden met OpenAPI-hulpprogramma's

Anonieme authenticatie:

Maak eerst een OpenAPI-verbinding met authType: "None" en vervang <OPENAPI_CONNECTION_ID> door de volledige resource-id ervan.

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

Authenticatie van projectverbinding:

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

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

Projectauthenticatie met beheerde identiteit:

Maak een OpenAPI-projectverbinding met authType: "ProjectManagedIdentity"en geef de volledige resource-id door met auth.type: "project_connection". Gebruik de configuratie van de directe managed_identity doelgroep niet in een toolbox.

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

Voorbeeld van het gebruik van agenten met de OpenAPI-tool

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

Agents aansturen

import os
import jsonref
from typing import Any, cast
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    PromptAgentDefinition,
    OpenApiTool,
    OpenApiFunctionDefinition,
    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)

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

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

Gehoste agents

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

import asyncio
import os
import jsonref
from typing import Any, cast

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient, FoundryToolbox
from azure.identity import AzureCliCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    OpenApiToolboxTool,
    OpenApiFunctionDefinition,
    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())

Verwachte uitvoer

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

Voorbeeld van het gebruik van agenten met de OpenAPI-tool

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

Agents aansturen

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

using System;
using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.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);
    }
}

Wat deze code doet

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

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

Vereiste invoer

• Omgevingsvariabelen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEen OPENAPI_CONNECTION_ID.
• Lokaal bestand: Assets/weather_openapi.json (OpenAPI-specificatie)

Verwachte uitvoer

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

Veelvoorkomende fouten

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

Gehoste agents

In dit voorbeeld wordt de OpenAPI-werkset gemaakt met de Azure AI Projects SDK en wordt vervolgens de Microsoft Agent Framework-integratie AddFoundryToolboxes gebruikt. Gebruik een ASP.NET Core-project met Azure.AI.AgentServer.Responses enMicrosoft.Agents.AI.Foundry.Hosting, naast de C#-afhankelijkheden in Vereisten. Stel FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME en OPENAPI_CONNECTION_ID, en meld u aan met 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();

Verwachte uitvoer

Het voorbeeld start een HTTP-server. Wanneer u een Responses-aanvraag verzendt waarin naar het weer wordt gevraagd, roept de agent de API aan via de toolbox en retourneert de huidige omstandigheden:

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

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

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

In dit voorbeeld koppelt u een geauthenticeerd OpenAPI-hulpprogramma rechtstreeks aan een promptagent. U gebruikt de TripAdvisor-specificatie en een API-sleutel die is opgeslagen in een projectverbinding.

De TripAdvisor-service vereist API-sleutelverificatie. Maak de projectverbinding zoals beschreven in Verifiëren met API-sleutel en stel OPENAPI_CONNECTION_ID in op de volledige resource-id. De sleutelnaam van de verbinding moet overeenkomen met de TripAdvisor-specificatie.

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

Wat deze code doet

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

1. De TripAdvisor OpenAPI-specificatie wordt geladen vanuit een lokaal bestand.
2. Het verwijst naar de TripAdvisor-projectverbinding die uw API-sleutel bevat.
3. Het koppelt het TripAdvisor-hulpprogramma aan de agent, geconfigureerd voor het gebruik van de verbinding voor verificatie.
4. Stuurt een aanvraag voor hotelaanaanveling in Parijs.
5. De agent roept de TripAdvisor-API aan met behulp van uw opgeslagen API-sleutel en retourneert resultaten.
6. Schoont de agent op door de agent te verwijderen.

Vereiste invoer

• Omgevingsvariabelen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEen OPENAPI_CONNECTION_ID.
• Lokaal bestand: Assets/tripadvisor_openapi.json
• Project verbinding: tripadvisor met geldige API-sleutel geconfigureerd

Verwachte uitvoer

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

Veelvoorkomende fouten

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

Een Java-agent maken met openAPI-hulpprogrammamogelijkheden

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

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

Een toegangstoken ophalen:

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

Anonieme authenticatie

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

1. Maak een werkset met het openAPI-weerhulpmiddel:

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions?api-version=v1" \
  --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" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

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

1. Maak een projectverbinding voor externe hulpprogramma's die verwijst naar het toolbox-eindpunt, met behulp van een Entra-gebruikerstoken zodat de identiteit van de aanroeper wordt doorgestuurd (doelgroep https://ai.azure.com).

azd ai connection create openapi-toolbox-conn \
  --kind remote-tool \
  --target "$FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

1. Maak een antwoord dat gebruikmaakt van de werkset door deze als een MCP-hulpprogramma te koppelen.

   Stel TOOLBOX_CONNECTION_ID in op de volledige resource-id van openapi-toolbox-conn. Deze verbinding is gescheiden van de anonieme OpenAPI-verbinding in OPENAPI_CONNECTION_ID. Vervang <version> door de versie die is geretourneerd toen u de toolbox maakte.

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

Gebruik deze variant pas nadat de anonieme stroom is geslaagd. Download tripadvisor_openapi.json via Voordat u de codevoorbeelden uitvoert. Configureer de API-sleutelverbinding en de securitySchemes- en security-vermeldingen van de specificatie zoals beschreven in Verifiëren met API-sleutel. Stel OPENAPI_CONNECTION_ID in op de volledige resource-id van die verbinding, niet op de anonieme weerverbinding.

In dit Bash-voorbeeld wordt jq gebruikt om de specificatie op te nemen in dezelfde remote_tool aanvraagshape als de voorbeelden van door het project beheerde identiteiten.

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

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

Verificatie van beheerde identiteit

Voor een door project beheerde identiteit, maakt u eerst een OpenAPI-projectverbinding. Geef vervolgens de volledige resource-id door in de Responses-request. Zie het REST-voorbeeld in Een OpenAPI-hulpprogramma aanroepen met een door project beheerde identiteit.

Door account beheerde identiteit wordt alleen ondersteund voor OpenAPI-hulpprogramma's die rechtstreeks aan promptagents in bestaande abonnementen zijn gekoppeld. Het wordt niet ondersteund in toolboxen. Gebruik ook een projectbeheerde identiteit voor promptagenten. Bestaande configuraties zo snel mogelijk migreren.

Wat deze code doet

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

1. Voor anonieme authenticatie wordt een toolbox gemaakt met de OpenAPI-tooldefinitie en de weerspecificatie van de API.
2. Maakt een antwoord dat de toolbox als MCP-hulpprogramma toevoegt en vraagt naar het weer in Seattle.
3. Toont een extra directe REST-hulpprogrammadefinitie voor API-sleutelverificatie via een projectverbinding.
4. De agent roept de API aan die is geselecteerd door de configuratie van het hulpprogramma en retourneert de resultaten.

Vereiste invoer

• Omgevingsvariabelen: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
• Voor anonieme authenticatie: OPENAPI_CONNECTION_ID, die verwijst naar de anonieme OpenAPI-projectverbinding, en TOOLBOX_CONNECTION_ID, die verwijst naar de MCP-verbinding van de werkset.
• Voor API-sleutelauthenticatie: OPENAPI_CONNECTION_ID, waarmee wordt verwezen naar de TripAdvisor-API-sleutelverbinding, en tripadvisor_openapi.json.
• Voor verificatie van door een project beheerde identiteit: OPENAPI_CONNECTION_ID, zoals wordt weergegeven in het voorbeeld van de door een project beheerde identiteit.
• Inline OpenAPI-specificatie in verzoeklichaam.

Verwachte uitvoer

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

Veelvoorkomende fouten

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

Een agent maken met openAPI-hulpprogrammamogelijkheden

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

import { DefaultAzureCredential } from "@azure/identity";
import {
  AIProjectClient,
  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;
});

Wat deze code doet

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

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

Vereiste invoer

• Omgevingsvariabelen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME, OPENAPI_CONNECTION_IDen TOOLBOX_CONNECTION_ID.
• Lokaal bestand: assets/weather_openapi.json (OpenAPI-specificatie).

Verwachte uitvoer

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

Veelvoorkomende fouten

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

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

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

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

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

Wat deze code doet

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

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

Vereiste invoer

• Omgevingsvariabelen: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAMEen OPENAPI_CONNECTION_ID.
• Lokaal bestand: ../assets/tripadvisor_openapi.json
• Project verbinding geconfigureerd met TripAdvisor-API-sleutel

Verwachte uitvoer

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

Veelvoorkomende fouten

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

Installeer de afhankelijkheden met 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()

Referentie: Azure Identity-tokenprovider.

Het extra_body argument geeft de servicespecifieke remote_tool payload door zonder een getypt OpenAPI-hulpprogrammamodel in de OpenAI SDK te vereisen.

Gebruik .NET 8 of hoger en installeer de referentiegegevensbibliotheek met dotnet add package Azure.Identity. In dit voorbeeld wordt de servicespecifieke payload van het hulpprogramma verzonden met 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);

Referentie: DefaultAzureCredential, HttpClient.

Gebruik Node.js 20 of hoger en installeer de credentialbibliotheek met npm install @azure/identity. Sla dit JavaScript-voorbeeld op als 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);

Referentie: DefaultAzureCredential.

Gebruik Java 11 of hoger. Voeg com.azure:azure-identity en com.fasterxml.jackson.core:jackson-databind aan uw Maven-afhankelijkheden toe. In dit voorbeeld wordt de servicespecifieke payload van het hulpprogramma verzonden met de HTTP-client van 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());
    }
}

Referentie: DefaultAzureCredentialBuilder.

Gebruik Bash, Azure CLI, curl en jq om de aanvraag vanuit translator_openapi.jsonte bouwen. Het aanroepertoken is gericht op Foundry, niet op Azure Resource Manager of 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

Naslaginformatie: Azure CLI toegangstokens.