Connettere gli agenti agli strumenti OpenAPI

Connettete gli agenti Foundry Microsoft alle API esterne utilizzando le specifiche OpenAPI 3.0 e 3.1. Il modello Foundry che alimenta l'agente può chiamare servizi esterni, recuperare dati in tempo reale ed estendere le funzionalità oltre le funzioni predefinite.

Le specifiche OpenAPI definiscono un modo standard per descrivere le API HTTP in modo da poter integrare i servizi esistenti con gli agenti. Microsoft Foundry supporta tre metodi di autenticazione: anonymous, API key e managed identity. Per informazioni sulla scelta di un metodo di autenticazione, vedere Scegliere un metodo di autenticazione.

Suggerimento

Prendere in considerazione l'aggiunta di questo strumento usando una casella degli strumenti. Usando una casella degli strumenti, è possibile riutilizzare lo strumento tra agenti e runtime, nonché centralizzare la gestione delle credenziali, il controllo delle versioni e l'imposizione dei criteri tramite un endpoint MCP gestito. Vedere la guida introduttiva alla casella degli strumenti.

Prerequisiti

Prima di iniziare, assicurarsi di avere:

  • Una sottoscrizione Azure con le autorizzazioni appropriate.

  • Ruolo utente foundry nel progetto Foundry per creare ed eseguire agenti.

    Importante

    I ruoli RBAC di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

  • Foundry Project Manager role on the Foundry project if you create a project connection for API key or token authentication.

  • Progetto Foundry creato con un endpoint configurato.

  • Un modello di intelligenza artificiale distribuito nel progetto.

  • Un ambiente agente di base o standard.

  • SDK installato per la lingua preferita:

    • Python:pip install azure-ai-projects jsonref
    • C#: Azure.AI.Extensions.OpenAI
    • TypeScript/JavaScript: @azure/ai-projects
    • Java:com.azure:azure-ai-agents

Variabili di ambiente

Variabile Descrizione
FOUNDRY_PROJECT_ENDPOINT URL dell'endpoint del progetto Foundry (non l'endpoint del servizio OpenAPI esterno).
FOUNDRY_MODEL_DEPLOYMENT_NAME Nome del modello distribuito.
OPENAPI_PROJECT_CONNECTION_NAME (Per l'autenticazione della chiave API) Nome della connessione del progetto per il servizio OpenAPI.
  • File di specifica OpenAPI 3.0 o 3.1 che soddisfa questi requisiti:
    • Ogni funzione deve avere un oggetto operationId (obbligatorio per lo strumento OpenAPI).
    • operationId deve contenere solo lettere, -e _.
    • Usare nomi descrittivi per consentire ai modelli di decidere in modo efficiente quale funzione usare.
    • Tipi di contenuto del corpo della richiesta supportati: application/json, application/json-patch+json
  • Per l'autenticazione dell'identità gestita: ruolo del servizio di destinazione con privilegi minimi che consente le operazioni API necessarie, assegnate all'identità gestita del progetto Foundry nell'ambito della risorsa di destinazione.
  • Per l'autenticazione con chiave API/token: una connessione di progetto configurata con la chiave API o il token. Vedere Aggiungere una nuova connessione al progetto.

Nota

Il valore FOUNDRY_PROJECT_ENDPOINT fa riferimento all'endpoint del progetto foundry Microsoft, non all'endpoint del servizio OpenAPI esterno. È possibile trovare questo endpoint nel portale di Microsoft Foundry nella pagina Panoramica del progetto. Questo endpoint è necessario per autenticare il servizio agente ed è separato da qualsiasi endpoint OpenAPI definito nel file di specifica.

Supporto per l'utilizzo

La tabella seguente illustra il supporto dell'SDK e della configurazione.

Supporto Foundry di Microsoft PYTHON SDK SDK di C# JavaScript SDK JAVA SDK REST API Configurazione dell'agente di base Configurazione dell'agente standard
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Nota

Per Java, usare il pacchetto com.azure:azure-ai-agents per gli strumenti dell'agente OpenAPI. Il com.azure:azure-ai-projects pacchetto non espone attualmente i tipi di strumenti dell'agente OpenAPI.

Eseguire il flusso anonimo first-success

Iniziare con l'API meteo anonima per verificare che l'agente possa caricare una specifica OpenAPI e chiamare un'operazione. Questo percorso non richiede credenziali API esterne o una connessione di progetto Foundry.

  1. Installare il pacchetto SDK per la lingua selezionata da Prerequisiti.
  2. Scaricare weather_openapi.jsone salvarlo nel assets percorso usato dall'esempio.
  3. Impostare i valori dell'endpoint del progetto Foundry e della distribuzione del modello.
  4. Eseguire l'esempio anonimo nella sezione della lingua selezionata.
  5. Verificare che la risposta contenga il meteo corrente per Seattle e quindi eliminare la versione dell'agente creata dall'esempio.

Al termine della chiamata anonima, configurare l'autenticazione richiesta dall'API di destinazione. Mantenere l'autenticazione della chiave API, l'autenticazione bearer-token e l'autenticazione dell'identità gestita come varianti separate.

Informazioni sulle limitazioni

  • La specifica OpenAPI deve includere operationId per ogni operazione, e operationId può includere solo lettere, -, e _.
  • Tipi di contenuto del corpo della richiesta supportati: application/json, application/json-patch+json.
  • Per l'autenticazione con chiave API, usare uno schema di sicurezza della chiave API per ogni strumento OpenAPI. Se sono necessari più schemi di sicurezza, creare più strumenti OpenAPI.

Aggiungere strumenti OpenAPI a una casella degli strumenti

Usare questo modello per esporre qualsiasi API REST descritta da una specifica OpenAPI. Scegliere l'oggetto auth.type corrispondente al modello di sicurezza dell'API.

Importante

Quando si usa l'autenticazione dell'identità gestita, assegnare solo il ruolo controllo degli accessi in base al ruolo con privilegi minimi che consente le operazioni API necessarie all'identità gestita del progetto Foundry nel servizio di destinazione. Ad esempio, assegnare Lettore nella risorsa Azure di destinazione solo quando l'API richiede l'accesso in sola lettura Azure Resource Manager. Senza l'assegnazione richiesta, l'agente riceve una 401 Unauthorized risposta quando si chiama l'API. Per la procedura di configurazione completa, vedere Eseguire l'autenticazione usando l'identità gestita.

Autenticazione anonima:

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

Autenticazione connessione progetto:

Usare questo modello quando l'API richiede una chiave o un token archiviato in una connessione di progetto Foundry.

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

Autenticazione dell'identità gestita:

Usare questo modello quando l'API di destinazione esegue l'autenticazione tramite Microsoft Entra ID. L'identità gestita del progetto Foundry chiama l'API per conto dell'agente. Assicurarsi che l'identità gestita abbia il ruolo RBAC richiesto sul servizio di destinazione prima di utilizzare questo schema.

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

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

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

Creare una casella degli strumenti OpenAPI con l'interfaccia della riga di comando per sviluppatori Azure

Gli strumenti OpenAPI incorporano la specifica direttamente in tools:. L'autenticazione basata sulla connessione (connection_auth) fa riferimento a una connessione di progetto. Gli strumenti OpenAPI anonimi non necessitano di alcuna connessione.

Passaggio 1: (Facoltativo) Creare la connessione di autenticazione

Ignorare questo passaggio per gli strumenti OpenAPI anonimi.

# API-key auth (passed by the platform on every call)
# Set OPENAPI_AUTHORIZATION_HEADER in your shell without committing its value.
azd ai connection create my-api-conn \
  --kind remote-tool \
  --target https://api.example.com \
  --auth-type custom-keys \
  --custom-key "Authorization=$OPENAPI_AUTHORIZATION_HEADER"

Gli strumenti OpenAPI accettano anche connessioni --auth-type oauth2. Per il set completo di azd ai connection create flag, vedere Autenticazione e configurazione mcp della casella degli strumenti.

Passaggio 2: Definire la casella degli strumenti

La specifica OpenAPI è in linea sotto tools[].openapi.spec.

# my-toolbox.yaml
description: OpenAPI toolbox
tools:
  - type: openapi
    name: my-api
    openapi:
      name: my-api
      spec:
        openapi: "3.0.1"
        info:
          title: "My API"
          version: "1.0"
        servers:
          - url: https://api.example.com/v1
        paths:
          /search:
            get:
              operationId: search
              parameters:
                - name: query
                  in: query
                  required: true
                  schema:
                    type: string
              responses:
                "200":
                  description: OK
      auth:
        type: connection_auth
        connection_id: my-api-conn

Per le API anonime, sostituire il auth: blocco con:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Passaggio 3. Creare la casella degli strumenti

azd ai toolbox create my-toolbox --from-file my-toolbox.yaml

Prima di eseguire gli esempi di codice

  • Scaricare la specifica gestita e salvarla tripadvisor_openapi.json nel assets percorso usato dall'esempio linguistico.

Nota

  • È necessario il pacchetto SDK più recente. L'SDK di .NET è attualmente in anteprima. Per informazioni dettagliate, vedere la guida introduttiva .
  • Se si usa la chiave API per l'autenticazione, l'ID connessione deve essere nel formato /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Importante

Per il corretto funzionamento dell'autenticazione della chiave API, il file di specifica OpenAPI deve includere:

  1. Sezione securitySchemes con la configurazione della chiave API, ad esempio il nome dell'intestazione e il nome del parametro.
  2. Sezione security che fa riferimento allo schema di sicurezza.
  3. Connessione di progetto configurata con il nome e il valore della chiave corrispondenti.

Senza queste configurazioni, la chiave API non è inclusa nelle richieste. Per istruzioni dettagliate sulla configurazione, vedere la sezione Eseguire l'autenticazione con la chiave API .

È anche possibile usare l'autenticazione basata su token, ad esempio un token di tipo Bearer, memorizzando il token in una connessione di progetto. Per l'autenticazione del token Bearer, creare una connessione con chiavi personalizzate con la chiave impostata su Authorization e il valore impostato su Bearer <token> (sostituire <token> con il token effettivo). La parola Bearer seguita da uno spazio deve essere inclusa nel valore . Per informazioni dettagliate, vedere Configurare una connessione token Bearer.

Esempio di uso degli agenti con lo strumento OpenAPI

Questo esempio illustra come usare i servizi descritti da una specifica OpenAPI usando un agente. Usa il servizio wttr.in per ottenere meteo e il relativo file di specifica weather_openapi.json. Selezionare Prompt Agents per usare Azure AI Projects SDK per creare un agente prompt sul lato server o Hosted Agents per usare Microsoft Agent Framework per creare un agente temporaneo e in-process.

Agenti rapidi

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

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

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

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

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

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

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

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

Questo esempio crea un agente prompt con uno strumento OpenAPI che chiama l'API meteo wttr.in usando l'autenticazione anonima. Lo strumento è collegato direttamente alla definizione dell'agente. Quando si esegue il codice:

  1. Carica la specifica OpenAPI per il meteo da un file JSON locale.
  2. Crea un agente di richiesta con lo strumento meteo configurato per l'accesso anonimo.
  3. Invia una query che chiede informazioni sul meteo di Seattle.
  4. L'agente usa lo strumento OpenAPI per chiamare l'API meteo e restituisce risultati formattati.
  5. Pulisce eliminando la versione dell'agente.

Agenti ospitati

Questo esempio usa FoundryChatClient il framework agente di Microsoft e si connette all'endpoint MCP della casella degli strumenti usando MCPStreamableHTTPTool. Installare le versioni dei pacchetti compatibili con pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity httpx jsonref, impostare la FOUNDRY_PROJECT_ENDPOINT variabile di ambiente e accedere con az login. OpenApiToolboxTool è il modello specifico della casella degli strumenti; utilizzare OpenApiTool solo quando si collega lo strumento direttamente a un agente prompt.

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

from agent_framework import Agent, MCPStreamableHTTPTool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential, get_bearer_token_provider
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    OpenApiToolboxTool,
    OpenApiFunctionDefinition,
    OpenApiAnonymousAuthDetails,
)

PROJECT_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>"


class _ToolboxAuth(httpx.Auth):
    def __init__(self, token_provider):
        self._token_provider = token_provider

    def auth_flow(self, request):
        request.headers["Authorization"] = "Bearer " + self._token_provider()
        yield request


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

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

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

    weather_tool = OpenApiToolboxTool(
        openapi=OpenApiFunctionDefinition(
            name="get_weather",
            spec=openapi_weather,
            description="Retrieve weather information for a location.",
            auth=OpenApiAnonymousAuthDetails(),
        )
    )

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

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

    # 3. Attach the toolbox to the hosted agent as an MCP tool.
    token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
    http_client = httpx.AsyncClient(auth=_ToolboxAuth(token_provider), timeout=120.0)
    mcp_tool = MCPStreamableHTTPTool(
        name="toolbox",
        url=TOOLBOX_MCP_URL,
        http_client=http_client,
        load_prompts=False,
    )

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

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


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

Output previsto

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

Esempio di uso degli agenti con lo strumento OpenAPI

Questo esempio illustra come usare i servizi descritti da una specifica OpenAPI usando un agente. Usa il servizio wttr.in per ottenere meteo e il relativo file di specifica weather_openapi.json. Selezionare Prompt Agents per usare Azure AI Projects SDK per creare un agente prompt sul lato server o Hosted Agents per usare Microsoft Agent Framework per creare un agente temporaneo e in-process.

Agenti rapidi

Questo esempio usa metodi sincroni della libreria client di Azure AI Projects. Per un esempio che usa metodi asincroni, vedere sample nel Azure SDK per .NET repository in GitHub.

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

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

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

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

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

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

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

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

Che cosa fa questo codice

Questo esempio C# crea un agente con uno strumento OpenAPI che recupera le informazioni meteo da wttr.in usando l'autenticazione anonima. Quando si esegue il codice:

  1. Legge la specifica OpenAPI del meteo da un file JSON locale.
  2. Crea un agente con lo strumento meteo configurato.
  3. Invia una richiesta che chiede informazioni sul meteo di Seattle usando lo strumento OpenAPI.
  4. L'agente chiama l'API meteo e restituisce i risultati.
  5. Pulisce eliminando l'agente.

Input necessari

  • Valore stringa inline: projectEndpoint (endpoint del progetto Foundry)
  • File locale: Assets/weather_openapi.json (specifica OpenAPI)

Output previsto

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

Errori comuni

  • FileNotFoundException: file di specifica OpenAPI non trovato nella cartella Assets
  • UnauthorizedAccessException: credenziali non valide o autorizzazioni di controllo degli accessi basato sui ruoli insufficienti
  • Chiave API non inserita: verificare che la specifica OpenAPI includa sia securitySchemes che le sezioni components e security con nomi di schemi corrispondenti

Agenti ospitati

Questo esempio crea la casella degli strumenti OpenAPI con Azure AI Projects SDK, quindi usa ResponsesServer da Microsoft Agent Framework con un personalizzato ToolboxMcpClient per individuare e richiamare lo strumento tramite l'endpoint MCP della casella degli strumenti. Installare i pacchetti di Agent Framework, impostare l'endpoint del AZURE_AI_PROJECT_ENDPOINT progetto e AZURE_AI_MODEL_DEPLOYMENT_NAME le variabili di ambiente e accedere con az login.

using System.IO;
using System.Runtime.CompilerServices;
using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

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

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? "https://<account>.services.ai.azure.com/api/projects/<project>";
string deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5-mini";

var openAiEndpoint = new Uri(projectEndpoint).GetLeftPart(UriPartial.Authority);
DefaultAzureCredential credential = new();

// 1. Create the OpenAPI tool and add it to a toolbox. Using a toolbox is the
//    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
string filePath = GetFile();
OpenAPIFunctionDefinition toolDefinition = new(
    name: "get_weather",
    spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
    auth: new OpenAPIAnonymousAuthenticationDetails()
);
toolDefinition.Description = "Retrieve weather information for a location.";
ProjectsAgentTool openapiTool = new OpenAPITool(toolDefinition);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateToolboxVersion(
        toolboxName: "openapi-toolbox",
        tools: [openapiTool],
        description: "Toolbox with the OpenAPI weather tool");

// 2. The toolbox exposes an MCP-compatible endpoint.
string toolboxMcpEndpoint =
    $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}/versions/{toolboxVersion.Version}/mcp?api-version=v1";

// 3. Attach the toolbox to the hosted agent.
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
ChatClient chatClient = openAIClient.GetChatClient(deploymentName);

// ToolboxMcpClient discovers tools from the toolbox MCP endpoint and calls them
// through tools/call. ToolboxHandler maps model tool calls to that MCP client.
var toolboxClient = new ToolboxMcpClient(toolboxMcpEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

Output previsto

L'agente chiama l'API dei paesi REST tramite lo strumento OpenAPI ed elenca i paesi corrispondenti:

Countries that use the Euro (EUR) as their currency include: Austria, Belgium, Croatia, Cyprus, Estonia, Finland, France, Germany, Greece, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, Netherlands, Portugal, Slovakia, Slovenia, Spain ...

Per l'esempio completo, inclusi i modelli api autenticati, vedere Agent_Step17_OpenAPITools.

Esempio di uso degli agenti con lo strumento OpenAPI nel servizio Web, che richiede l'autenticazione

In questo esempio si aggiunge uno strumento OpenAPI autenticato a una casella degli strumenti, si collega la casella degli strumenti come strumento MCP e si usa l'agente in uno scenario che richiede l'autenticazione. Usi la specifica TripAdvisor.

Il servizio TripAdvisor richiede l'autenticazione basata su chiave. Per creare una connessione, aprire Microsoft Foundry, selezionare Gestisci nel riquadro di spostamento in alto a destra, selezionare Project dettagli e quindi selezionare la scheda Risorse connesse. Creare infine una nuova connessione del tipo di chiavi personalizzate. Denominarlo tripadvisor e aggiungere una coppia chiave-valore. Aggiungere la chiave denominata key e immettere un valore con la chiave di TripAdvisor.

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

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

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

        // Create an OpenAPI tool with authentication by project connection security scheme.
        string filePath = GetFile();
        AIProjectConnection tripadvisorConnection = projectClient.Connections.GetConnection("tripadvisor");
        OpenAPIFunctionDefinition toolDefinition = new(
            name: "tripadvisor",
            spec: BinaryData.FromBytes(File.ReadAllBytes(filePath)),
            auth: new OpenAPIProjectConnectionAuthenticationDetails(new OpenAPIProjectConnectionSecurityScheme(
                projectConnectionId: tripadvisorConnection.Id
            ))
        );
        toolDefinition.Description = "Trip Advisor API to get travel information.";
        ProjectsAgentTool openapiTool = new OpenAPITool(toolDefinition);

        // 1. Add the authenticated OpenAPI tool to a toolbox. Using a toolbox is the
        //    recommended way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
        AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

        ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
            .GetAgentToolboxes().CreateToolboxVersion(
                toolboxName: "openapi-toolbox",
                tools: [openapiTool],
                description: "Toolbox with the authenticated TripAdvisor OpenAPI tool");

        // 2. The toolbox exposes an MCP-compatible endpoint.
        var toolboxMcpUrl = new Uri(
            $"{projectEndpoint}/toolboxes/{toolboxVersion.Name}" +
            $"/versions/{toolboxVersion.Version}/mcp?api-version=v1");

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

        // 4. Attach the toolbox to a prompt agent as an MCP tool.
        McpTool toolboxTool = ResponseTool.CreateMcpTool(
            serverLabel: "toolbox",
            serverUri: toolboxMcpUrl,
            toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
                GlobalMcpToolCallApprovalPolicy.NeverRequireApproval));
        toolboxTool.ProjectConnectionId = toolboxConnectionName;

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

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

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

Che cosa fa questo codice

Questo esempio C# illustra l'uso di uno strumento OpenAPI con l'autenticazione della chiave API tramite una casella degli strumenti e una connessione al progetto. Quando si esegue il codice:

  1. Carica la specifica OpenAPI di TripAdvisor da un file locale.
  2. Recupera la connessione progetto di tripadvisor contenente la chiave API.
  3. Crea una versione della casella degli strumenti contenente lo strumento TripAdvisor configurato per utilizzare la connessione per l'autenticazione.
  4. Collega la casella degli strumenti all'agente come strumento MCP.
  5. Invia una richiesta di consigli per gli hotel a Parigi.
  6. L'agente chiama l'API TripAdvisor usando la chiave API archiviata e restituisce i risultati.
  7. Pulisce eliminando l'agente.

Input necessari

  • Valore stringa inline: projectEndpoint (endpoint del progetto Foundry)
  • File locale: Assets/tripadvisor_openapi.json
  • connessione Project: tripadvisor con chiave API valida configurata

Output previsto

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

Errori comuni

  • ConnectionNotFoundException: nessuna connessione di progetto denominata tripadvisor trovata.
  • AuthenticationException: chiave API non valida nella connessione al progetto o configurazione mancante/errata securitySchemes nella specifica OpenAPI.
  • Strumento non usato: verificare che ToolChoice = ResponseToolChoice.CreateRequiredChoice() imponga l'uso dello strumento.
  • Chiave API non passata all'API: assicurarsi che la specifica OpenAPI abbia configurate correttamente le sezioni securitySchemes e security.

Creare un agente Java con le funzionalità degli strumenti OpenAPI

Questa Java configurazione può fare riferimento agli strumenti MCP, ma Java SDK non espone ancora un'API di creazione della casella degli strumenti.

Suggerimento

Consigliato: Per la maggior parte degli agenti, aggiungere lo strumento OpenAPI tramite una casella degli strumenti e allegare la casella degli strumenti all'agente come strumento MCP. Creare la casella degli strumenti usando l'esempio Python, l'API REST, C# o TypeScript o il portale Foundry e quindi fare riferimento al relativo endpoint MCP dall'agente Java come McpTool.

Gli esempi seguenti illustrano come chiamare uno strumento OpenAPI usando l'API REST.

Ottenere un token di accesso:

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

Autenticazione anonima

Aggiungere strumenti OpenAPI tramite una casella degli strumenti e quindi collegare la casella degli strumenti all'agente come strumento MCP. Per altre informazioni, vedere Che cos'è una casella degli strumenti?

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

La casella degli strumenti espone un endpoint compatibile con MCP in $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1, dove <version> è la versione restituita dalla chiamata precedente.

  1. Creare una connessione al progetto strumento remoto che punta all'endpoint della casella degli strumenti usando un token Entra utente in modo che l'identità del chiamante venga passata (gruppo di destinatari 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. Creare una risposta che usa la casella degli strumenti collegandola come strumento MCP.
curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tool_choice": "required",
    "tools": [
      {
        "type": "mcp",
        "server_label": "toolbox",
        "server_url": "'$FOUNDRY_PROJECT_ENDPOINT'/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1",
        "require_approval": "never",
        "project_connection_id": "openapi-toolbox-conn"
      }
    ]
  }'

Autenticazione della chiave API (connessione di progetto)

Usare questa variante solo dopo che il flusso anonimo ha esito positivo. Configurare la connessione al progetto e la voce OpenAPI securitySchemes come descritto in Eseguire l'autenticazione con la chiave API.

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "project_connection",
            "security_scheme": {
              "project_connection_id": "'$WEATHER_APP_PROJECT_CONNECTION_ID'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            },
            "components": {
              "securitySchemes": {
                "apiKeyHeader": {
                  "type": "apiKey",
                  "name": "x-api-key",
                  "in": "header"
                }
              }
            },
            "security": [
              { "apiKeyHeader": [] }
            ]
          }
        }
      }
    ]
  }'

Per un'API bearer-token mantenere la stessa project_connection forma di richiesta, ma usare una connessione configurata come descritto in Configurare una connessione token di connessione. Il valore di connessione deve includere il Bearer prefisso.

Autenticazione dell'identità gestita

curl --request POST \
  --url "$FOUNDRY_PROJECT_ENDPOINT/openai/v1/responses" \
  --header "Authorization: Bearer $AGENT_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "'$FOUNDRY_MODEL_DEPLOYMENT_NAME'",
    "input": "Use the OpenAPI tool to get the weather in Seattle, WA today.",
    "tools": [
      {
        "type": "openapi",
        "openapi": {
          "name": "weather",
          "description": "Tool to get weather data",
          "auth": {
            "type": "managed_identity",
            "security_scheme": {
              "audience": "'$MANAGED_IDENTITY_AUDIENCE'"
            }
          },
          "spec": {
            "openapi": "3.1.0",
            "info": {
              "title": "get weather data",
              "description": "Retrieves current weather data for a location.",
              "version": "v1.0.0"
            },
            "servers": [{ "url": "https://wttr.in" }],
            "paths": {
              "/{location}": {
                "get": {
                  "description": "Get weather information for a specific location",
                  "operationId": "GetCurrentWeather",
                  "parameters": [
                    {
                      "name": "location",
                      "in": "path",
                      "description": "City or location to retrieve the weather for",
                      "required": true,
                      "schema": { "type": "string" }
                    },
                    {
                      "name": "format",
                      "in": "query",
                      "description": "Format in which to return data. Always use 3.",
                      "required": true,
                      "schema": { "type": "integer", "default": 3 }
                    }
                  ],
                  "responses": {
                    "200": {
                      "description": "Successful response",
                      "content": {
                        "text/plain": {
                          "schema": { "type": "string" }
                        }
                      }
                    },
                    "404": { "description": "Location not found" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

Che cosa fa questo codice

Questo esempio di API REST illustra come chiamare uno strumento OpenAPI con metodi di autenticazione diversi. La richiesta:

  1. Per l'autenticazione anonima, crea una casella degli strumenti contenente la definizione dello strumento OpenAPI e la specifica dell'API meteo.
  2. Crea una risposta che collega la casella degli strumenti come strumento MCP e chiede informazioni sul meteo di Seattle.
  3. Mostra altre definizioni di strumenti REST diretti per la chiave API tramite la connessione al progetto e l'autenticazione dell'identità gestita.
  4. L'agente usa lo strumento per chiamare l'API meteo e restituisce risultati formattati.

Input necessari

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
  • Per l'autenticazione della chiave API: WEATHER_APP_PROJECT_CONNECTION_ID.
  • Per l'autenticazione dell'identità gestita: MANAGED_IDENTITY_AUDIENCE.
  • Specifica OpenAPI inline nel corpo della richiesta.

Output previsto

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

Errori comuni

  • 401 Unauthorized: chiave API non valida o mancante, o AGENT_TOKEN non inserita perché securitySchemes e security sono mancanti nella specifica OpenAPI
  • 404 Not Found: nome di distribuzione dell'endpoint o del modello non corretto
  • 400 Bad Request: specifica OpenAPI non valida o configurazione dell'autenticazione non valida
  • Chiave API non inviata con richiesta: verificare che la components.securitySchemes sezione nella specifica OpenAPI sia configurata correttamente (non vuota) e corrisponda al nome della chiave di connessione del progetto

Creare un agente con le funzionalità degli strumenti OpenAPI

L'esempio di codice TypeScript seguente illustra come creare un agente di intelligenza artificiale con funzionalità degli strumenti OpenAPI aggiungendo lo strumento OpenAPI a una casella degli strumenti e collegando la casella degli strumenti come strumento MCP. L'agente può chiamare API esterne definite dalle specifiche OpenAPI. Per una versione JavaScript di questo esempio, vedere sample nel repository Azure SDK per JavaScript in GitHub.

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

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

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

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

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

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

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

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

  const weatherTool = createWeatherTool(weatherSpec);

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

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

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

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

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

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

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

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

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

Che cosa fa questo codice

Questo esempio TypeScript crea un agente con uno strumento OpenAPI per i dati meteo usando l'autenticazione anonima. Quando si esegue il codice:

  1. Carica la specifica OpenAPI per il meteo da un file JSON locale.
  2. Crea una versione della casella degli strumenti contenente lo strumento meteo.
  3. Collega la casella degli strumenti all'agente come strumento MCP, quindi invia una richiesta di streaming che chiede informazioni sul meteo e sulla pianificazione dell'outfit di Seattle.
  4. Elabora la risposta di streaming e visualizza i delta non appena arrivano.
  5. Forza l'utilizzo degli strumenti usando tool_choice: "required" per assicurarsi che venga chiamata l'API.
  6. Pulisce eliminando l'agente.

Input necessari

  • Valore stringa inline: PROJECT_ENDPOINT (endpoint del progetto Foundry)
  • File locale: ../assets/weather_openapi.json (specifica OpenAPI)

Output previsto

Loading OpenAPI specifications from assets directory...
Creating agent with OpenAPI tool...
Agent created (id: asst_abc123, name: MyOpenApiAgent, version: 1)

Sending request to OpenAPI-enabled agent with streaming...
Follow-up response created with ID: resp_xyz789
The weather in Seattle is currently...
Tool call completed: get_weather

Follow-up completed!

Cleaning up resources...
Agent deleted

OpenAPI agent sample completed!

Errori comuni

  • Error: OpenAPI specification not found: percorso del file non corretto o file mancante
  • AuthenticationError: credenziali di Azure non valide
  • Chiave API non funzionante: se si passa dall'autenticazione anonima alla chiave API, verificare che la specifica OpenAPI sia securitySchemes configurata e security configurata correttamente

Creare un agente che usa gli strumenti OpenAPI autenticati con una connessione al progetto

L'esempio di codice TypeScript seguente illustra come creare un agente di intelligenza artificiale che usa gli strumenti OpenAPI autenticati tramite una connessione al progetto. L'agente carica la specifica OpenAPI di TripAdvisor dagli asset locali e può richiamare l'API tramite la connessione al progetto configurata. Per una versione JavaScript di questo esempio, vedere sample nel repository Azure SDK per JavaScript in GitHub.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Che cosa fa questo codice

Questo esempio di TypeScript illustra l'uso di uno strumento OpenAPI con l'autenticazione della chiave API tramite una connessione di progetto. Quando si esegue il codice:

  1. Carica la specifica OpenAPI di TripAdvisor da un file locale.
  2. Configura l'autenticazione usando la TRIPADVISOR_CONNECTION_ID costante .
  3. Crea un agente con lo strumento TripAdvisor che usa la connessione di progetto per l'autenticazione della chiave API.
  4. Invia una richiesta streaming per i dettagli della posizione di TripAdvisor.
  5. Forza l'utilizzo degli strumenti usando tool_choice: "required" per assicurarsi che venga chiamata l'API.
  6. Elabora e visualizza la risposta di streaming.
  7. Esegue la pulizia eliminando l'agente.

Input necessari

  • Valori stringa inline: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
  • File locale: ../assets/tripadvisor_openapi.json
  • Connessione del progetto configurata con la chiave API di TripAdvisor

Output previsto

Loading TripAdvisor OpenAPI specification from assets directory...
Creating agent with OpenAPI project-connection tool...
Agent created (id: asst_abc123, name: MyOpenApiConnectionAgent, version: 1)

Sending request to TripAdvisor OpenAPI agent with streaming...
Follow-up response created with ID: resp_xyz789
Location 293919 is the Eiffel Tower in Paris, France. It has a rating of 4.5 stars with over 140,000 reviews...
Tool call completed: get_tripadvisor_location_details

Follow-up completed!

Cleaning up resources...
Agent deleted

TripAdvisor OpenAPI agent sample completed!

Errori comuni

  • Error: OpenAPI specification not found: controllare il percorso del file.
  • Connessione non trovata: verificare TRIPADVISOR_CONNECTION_ID che sia corretta e che esista una connessione.
  • AuthenticationException: chiave API non valida nella connessione al progetto.
  • Chiave API non inserita nelle richieste: la specifica OpenAPI deve includere sezioni securitySchemes appropriate (sotto components) e security. Il nome della chiave in securitySchemes deve corrispondere alla chiave nella connessione al progetto.
  • Content type is not supported: attualmente sono supportati solo questi due tipi di contenuto del corpo della richiesta: application/json e application/json-patch+json. I tipi di contenuto della risposta non sono limitati.

Considerazioni sulla sicurezza e i dati

Quando si connette un agente a uno strumento OpenAPI, l'agente può inviare parametri di richiesta derivati dall'input dell'utente all'API di destinazione.

  • Usare le connessioni di progetto per i segreti (chiavi API e token). Evitare di inserire segreti in un file di specifiche OpenAPI o in un codice sorgente.
  • Esaminare i dati ricevuti dall'API e gli elementi restituiti prima di usare lo strumento nell'ambiente di produzione.
  • Usare l'accesso con privilegi minimi. Per l'identità gestita, assegnare solo i ruoli richiesti dal servizio di destinazione.

Eseguire l'autenticazione con la chiave API

Usare questa variante per un'API che prevede una chiave in un'intestazione o un parametro di query. È possibile usare un solo schema di sicurezza della chiave API per ogni strumento OpenAPI. Se l'API richiede più schemi di sicurezza, creare più strumenti OpenAPI.

  1. Aggiornare gli schemi di sicurezza delle specifiche OpenAPI. Ha una securitySchemes sezione e uno schema di tipo apiKey. Per esempio:

     "securitySchemes": {
     "apiKeyHeader": {
             "type": "apiKey",
             "name": "x-api-key",
             "in": "header"
         }
 }

    In genere è sufficiente aggiornare il name campo, che corrisponde al nome di key nella connessione. Se gli schemi di sicurezza includono più schemi, mantenerli solo uno di essi.

  2. Aggiornare la specifica OpenAPI per includere una security sezione:

    "security": [
     {  
     "apiKeyHeader": []  
     }  
 ]

  3. Rimuovere qualsiasi parametro nella specifica OpenAPI che richiede la chiave API, perché la chiave API viene archiviata e passata tramite una connessione, come descritto più avanti in questo articolo.

  4. Creare una connessione per archiviare la chiave API.

  5. Passare al portale Foundry e aprire il progetto.

  6. Creare o selezionare una connessione in cui è archiviato il segreto. Vedere Aggiungere una nuova connessione al progetto.

    Nota

    Se si rigenera la chiave API in un secondo momento, è necessario aggiornare la connessione con la nuova chiave.

  7. Immettere le informazioni seguenti

    • key: name campo del tuo schema di sicurezza. In questo esempio deve essere x-api-key

             "securitySchemes": {
          "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }

    • valore: YOUR_API_KEY

  8. Dopo aver creato una connessione, è possibile usarla tramite l'SDK o l'API REST. Usare le schede nella parte superiore di questo articolo per visualizzare esempi di codice.

Configurare una connessione Bearer Token

Usare questa variante per un'API che prevede un token di connessione nell'intestazione Authorization . Usa lo stesso project_connection tipo di autenticazione dell'autenticazione con chiave API, ma lo schema di sicurezza OpenAPI e i valori di connessione differiscono.

La specifica OpenAPI sarà simile alla seguente:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

È necessario:

  1. Aggiorna la specifica OpenAPI securitySchemes per usare Authorization come nome dell'intestazione:

    "securitySchemes": {
    "bearerAuth": {
        "type": "apiKey",
        "name": "Authorization",
        "in": "header"
    }
}

  2. Aggiungere una security sezione che fa riferimento allo schema:

    "security": [
    {
        "bearerAuth": []
    }
]

  3. Creare una connessione chiavi personalizzate nel progetto Foundry:

    1. Passare al portale Foundry e aprire il progetto.
    2. Creare o selezionare una connessione in cui è archiviato il segreto. Vedere Aggiungere una nuova connessione al progetto.
    3. Immettere i valori seguenti:
      • key: Authorization (deve corrispondere al name campo nel tuo securitySchemes)
      • value: Bearer <token> (sostituire <token> con il token effettivo)

    Importante

    Il valore deve includere la parola Bearer seguita da uno spazio prima del token. Ad esempio: Bearer eyJhbGciOiJSUzI1NiIs.... Se si omette Bearer , l'API riceve un token non elaborato senza il prefisso dello schema di autorizzazione richiesto e la richiesta ha esito negativo.

  4. Dopo aver creato la connessione, usarla con il project_connection tipo di autenticazione nel codice, allo stesso modo per l'autenticazione della chiave API. L'ID connessione usa lo stesso formato: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Eseguire l'autenticazione usando l'identità gestita (Microsoft Entra ID)

Microsoft Entra ID è un servizio di gestione delle identità e degli accessi basato sul cloud che i dipendenti possono usare per accedere alle risorse esterne. Usando Microsoft Entra ID, è possibile aggiungere sicurezza aggiuntiva alle API senza dover usare le chiavi API. Quando si configura l'autenticazione tramite identità gestita, l'agente esegue l'autenticazione tramite lo strumento Foundry utilizzato.

Importante

L'autenticazione dell'identità gestita funziona solo quando il servizio di destinazione accetta token Microsoft Entra ID. Se l'API di destinazione usa uno schema di autenticazione personalizzato che non supporta Microsoft Entra ID, si utilizza in alternativa l'autenticazione con chiave API o token Bearer.

Comprendere l'URI del gruppo di destinatari

Il audience (talvolta chiamato identificatore risorsa o URI ID applicazione) indica a Microsoft Entra ID quale servizio o API il token è destinato ad accedere. Il valore del gruppo di destinatari deve corrispondere a quello previsto dal servizio di destinazione oppure l'autenticazione ha esito negativo con un errore 401.

Nota

I destinatari non sono dati dall'endpoint del progetto Foundry. Si tratta dell'identificatore di risorsa del servizio di destinazione chiamato dallo strumento OpenAPI.

La tabella seguente elenca gli URI del gruppo di destinatari per i servizi di Azure comuni:

Servizio di destinazione URI destinatario
Archiviazione di Azure https://storage.azure.com
Azure Key Vault https://vault.azure.net
Azure AI Search https://search.azure.com
App per la logica di Azure https://logic.azure.com
Gestione API di Azure (piano di gestione) https://management.azure.com
API protetta da una registrazione di applicazione Microsoft Entra (incluso APIM con OAuth) URI ID dell'applicazione dalla registrazione dell'app (ad esempio, api://<client-id>)

Suggerimento

Se si usa Gestione API di Azure per proteggere un'API personalizzata con criteri di convalida OAuth 2.0, il gruppo di destinatari è URI ID applicazione dalla registrazione dell'app che protegge l'API, non https://management.azure.com. I destinatari del piano di gestione si applicano solo alle operazioni di Azure Resource Manager nella risorsa APIM stessa.

Per altre informazioni su come gli agenti eseguono l'autenticazione con Microsoft Entra ID, vedere Agent identity and authentication.For more information about how agents authenticate with Microsoft Entra ID, see Agent identity and authentication.

Trovare e verificare il pubblico

Usare la procedura seguente per determinare e verificare il valore corretto del gruppo di destinatari:

  • Per i servizi di Azure: consulta la documentazione del servizio per ottenere l'identificatore di risorsa Microsoft Entra ID. La maggior parte dei servizi Azure elenca l'URI del gruppo di destinatari nella documentazione di autenticazione.
  • Per le API protette da una registrazione dell'app Microsoft Entra: nel portale di Azure, passare a Microsoft Entra ID>Registrazioni delle app>, selezionare l'app >Esporre un'API. L'URI ID dell'applicazione nella parte superiore della pagina è il valore dei destinatari.
  • Per verificare il gruppo di destinatari di un token: decodificare il token di accesso in https://jwt.ms e controllare l'attestazione aud . Il aud valore deve corrispondere al gruppo di destinatari previsto dal servizio di destinazione.

Configurare l'autenticazione dell'identità gestita

Per configurare l'autenticazione usando l'identità gestita:

  1. Assicurarsi che alla risorsa Foundry sia abilitata l'identità gestita assegnata dal sistema.

Screenshot del portale di Azure che mostra le impostazioni di identità gestite assegnate dal sistema.

  1. Creare una risorsa per il servizio a cui connettersi tramite la specifica OpenAPI.
  2. Assegnare l'accesso appropriato alla risorsa.

    1. Selezionare Controllo di accesso per la risorsa.

    2. Selezionare Aggiungi e quindi aggiungere un'assegnazione di ruolo nella parte superiore della schermata.

      Screenshot del portale di Azure che mostra l'azione Aggiungi assegnazione di ruolo.

    3. Selezionare l'assegnazione di ruolo appropriata necessaria, in genere richiede almeno il ruolo READER . Quindi selezionare Avanti.

    4. Selezionare Identità gestita e quindi selezionare membri.

    5. Nel menu a discesa Identità gestita cercare Account Foundry e quindi selezionare l'account Foundry dell'agente.

    6. Selezionare Fine.

  3. Al termine dell'installazione, è possibile continuare usando lo strumento tramite il portale foundry, l'SDK o l'API REST. Usare le schede nella parte superiore di questo articolo per visualizzare gli esempi di codice.

Risolvere gli errori comuni

Sintomo Probabile causa Risoluzione
La chiave API non è inclusa nelle richieste. La specifica OpenAPI è mancante delle sezioni securitySchemes o security. Verificare che la specifica OpenAPI includa sia components.securitySchemes che una sezione di primo livello security . Verificare che lo schema name corrisponda al nome della chiave nella connessione al progetto.
Agent non chiama lo strumento OpenAPI. Scelta dello strumento non impostata o operationId non descrittiva. Usare tool_choice="required" per forzare la chiamata allo strumento. Verificare che operationId i valori siano descrittivi in modo che il modello possa scegliere l'operazione corretta.
L'autenticazione non riesce per l'identità gestita. Identità gestita non abilitata o assegnazione di ruolo mancante. Abilitare l'identità gestita assegnata dal sistema nella risorsa Foundry. Assegnare il ruolo richiesto (lettore o superiore) nel servizio di destinazione.
L'identità gestita restituisce 401 nonostante il ruolo sia assegnato. L'URI del gruppo di destinatari non corrisponde a quello previsto dal servizio di destinazione. Verificare che l'URI del gruppo di destinatari corrisponda all'identificatore di risorsa del servizio di destinazione. Per i servizi di Azure, consultare la documentazione dei servizi. Per le API protette da Microsoft Entra, usare l'Application ID URI dalla registrazione dell'applicazione. Decodificare il token in https://jwt.ms e confermare che la dichiarazione aud corrisponda. Vedere Informazioni sull'URI del gruppo di destinatari.
Token di identità gestito rifiutato dall'API di destinazione. Il servizio di destinazione non accetta token Microsoft Entra ID. Verificare che il servizio di destinazione supporti l'autenticazione Microsoft Entra ID. In caso contrario, usare l'autenticazione con chiave API o Bearer token.
La richiesta ha esito negativo con 400 richiesta non valida. La specifica OpenAPI non corrisponde all'API effettiva. Convalidare la specifica OpenAPI rispetto all'API effettiva. Controllare i nomi dei parametri, i tipi e i campi obbligatori.
La richiesta fallisce con il codice di errore "401 Non autorizzato". Chiave API o token non valido o scaduto. Rigenerare la chiave API/token e aggiornare la connessione al progetto. Verificare che l'ID connessione sia corretto.
Lo strumento restituisce un formato di risposta imprevisto. Schema di risposta non definito nella specifica OpenAPI. Aggiungere schemi di risposta alla specifica OpenAPI per una migliore comprensione del modello.
operationId errore di convalida. Caratteri non validi in operationId. Usare solo lettere, -, e _ nei valori operationId. Rimuovere numeri e caratteri speciali.
Errore: connessione non trovata. Nome o ID della connessione non corrisponde. Verificare che OPENAPI_PROJECT_CONNECTION_NAME corrisponda al nome della connessione nel tuo progetto Foundry.
Token di connessione non inviato correttamente. Mancanza del prefisso Bearer nel valore di connessione. Impostare il valore di connessione su Bearer <token> (con la parola Bearer e uno spazio prima del token). Verificare che la OpenAPI specifica securitySchemes usi "name": "Authorization".

Scegliere un metodo di autenticazione

La tabella seguente consente di scegliere il metodo di autenticazione appropriato per lo strumento OpenAPI:

Metodo di autenticazione Migliore per Complessità della configurazione
Anonimo API pubbliche senza autenticazione Basso
Chiave API API non Microsoft con accesso basato su chiave Medio
Identità gestita Azure servizi e API protette da Microsoft Entra ID. Richiede al servizio di destinazione di accettare i token Microsoft Entra ID e di supportare il controllo degli accessi in base al ruolo di Azure o il controllo degli accessi basato su Microsoft Entra. Medio-Alto

Contenuto correlato

  • Last updated on