Condividi tramite

Connettere gli agenti agli strumenti OpenAPI

Connettere gli agenti Microsoft Foundry alle API esterne usando le specifiche OpenAPI 3.0. Gli agenti che si connettono agli strumenti OpenAPI possono 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 keye managed identity. Per informazioni sulla scelta di un metodo di autenticazione, vedere Scegliere un metodo di autenticazione.

Supporto per l'utilizzo

✔️ (GA) indica la disponibilità generale, ✔️ (anteprima) indica l'anteprima pubblica e un trattino (-) indica che la funzionalità non è disponibile.

Supporto di Microsoft Foundry Python SDK SDK di C# JavaScript SDK Java SDK REST API Configurazione dell'agente di base Configurazione dell'agente standard
✔️ ✔️ (Anteprima) ✔️ (Anteprima) ✔️ (Anteprima) ✔️ (Anteprima) ✔️ (GA) ✔️ ✔️

Annotazioni

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

Prerequisiti

Prima di iniziare, assicurarsi di avere:

  • Una sottoscrizione di Azure con le autorizzazioni appropriate.
  • Ruolo di Azure per il controllo degli accessi: Contributor o Owner nel progetto Foundry.
  • Progetto Foundry creato con un endpoint configurato.
  • Un modello di intelligenza artificiale distribuito nel progetto.
  • Ambiente di agenti base o standard.
  • SDK installato per la lingua preferita:
    • Python: azure-ai-projects (versione non definitiva più recente)
    • C#: Azure.AI.Projects.OpenAI
    • TypeScript/JavaScript: @azure/ai-projects
    • Java: com.azure:azure-ai-agents

Variabili di ambiente

Variable Descrzione
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 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.
    • Tipo di contenuto supportato: "application/json", "application/json-patch+json"
  • Per l'autenticazione dell'identità gestita: ruolo di lettore o superiore nelle risorse del servizio 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.

Annotazioni

Il FOUNDRY_PROJECT_ENDPOINT valore fa riferimento all'endpoint del progetto Microsoft Foundry, 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.

Comprendere le limitazioni

  • La specifica OpenAPI deve includere operationId per ogni operazione e operationId può includere solo lettere, -, e _.
  • Tipi di contenuto 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.

Esempio di codice

Annotazioni

  • È necessario il pacchetto versione non definitiva più recente. 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) archiviando il token in una connessione di progetto. Per l'autenticazione tramite Bearer token, creare una connessione 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.

Verifica rapida

Prima di tutto, verificare che l'ambiente sia configurato correttamente:

# Verify authentication and project connection
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with DefaultAzureCredential() as credential, \
     AIProjectClient(endpoint=endpoint, credential=credential) as project_client:
    print(f"Successfully connected to project")

Se questo comando viene eseguito senza errori, è possibile creare un agente con gli strumenti OpenAPI.

Esempio completo

# Import required libraries
import os
import jsonref
from dotenv import load_dotenv
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,
)

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as 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(),
        )
    )

    # If you want to use key-based authentication
    # IMPORTANT: Your OpenAPI spec must include securitySchemes and security sections
    # Example spec structure for API key auth:
    # {
    #   "components": {
    #     "securitySchemes": {
    #       "apiKeyHeader": {
    #         "type": "apiKey",
    #         "name": "x-api-key",  # This must match the key name in your project connection
    #         "in": "header"
    #       }
    #     }
    #   },
    #   "security": [{"apiKeyHeader": []}]
    # }
    #
    # For Bearer token authentication, use this securitySchemes structure instead:
    # {
    #   "components": {
    #     "securitySchemes": {
    #       "bearerAuth": {
    #         "type": "apiKey",
    #         "name": "Authorization",
    #         "in": "header"
    #       }
    #     }
    #   },
    #   "security": [{"bearerAuth": []}]
    # }
    # Then set connection key = "Authorization" and value = "Bearer <token>"
    # The word "Bearer" followed by a space MUST be included in the value.

    openapi_connection = project_client.connections.get(os.environ["OPENAPI_PROJECT_CONNECTION_NAME"])
    connection_id = openapi_connection.id
    print(f"OpenAPI connection ID: {connection_id}")

    openapi_key_auth_tool={
        "type": "openapi",
        "openapi":{
            "name": "TOOL_NAME",
            "spec": SPEC_NAME,  # Must include securitySchemes and security sections
            "auth": {
                "type": "project_connection",
                "security_scheme": {
                    "project_connection_id": connection_id
                }
            },
        }
    }

    # If you want to use Managed Identity authentication
    openapi_mi_auth_tool={
        "type": "openapi",
        "openapi":{
            "name": "TOOL_NAME",
            "description": "",
            "spec": SPEC_NAME,
            "auth": {
                "type": "managed_identity",
                "security_scheme": {
                    "audience": ""  #audience to the service, such as https://ai.azure.com
                }
            },
        }
    }

    agent = project_client.agents.create_version(
        agent_name="MyAgent",
        definition=PromptAgentDefinition(
            model=os.environ["FOUNDRY_MODEL_DEPLOYMENT_NAME"],
            instructions="You are a helpful assistant.",
            tools=[weather_tool],
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    response = openai_client.responses.create(
        input="What's the weather in Seattle?",
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    )
    print(f"Agent response: {response.output_text}")

    print("\nCleaning up...")
    project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

Che cosa fa questo codice

Questo esempio crea un agente con uno strumento OpenAPI che chiama l'API meteo wttr.in usando l'autenticazione anonima. Quando si esegue il codice:

  1. Carica la specifica OpenAPI del meteo da un file JSON locale.
  2. Crea un agente 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.

Input necessari

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • File locale: weather_openapi.json (specifica OpenAPI)

Output previsto

Agent created (id: asst_abc123, name: MyAgent23, version: 1)
Response created: The weather in Seattle is currently cloudy with a temperature of 52°F (11°C)...

Cleaning up...
Agent deleted

Errori comuni

  • FileNotFoundError: file di specifica OpenAPI non trovato nel percorso specificato
  • KeyError: variabili di ambiente necessarie mancanti
  • AuthenticationError: credenziali non valide o autorizzazioni insufficienti o mancanti securitySchemes nella specifica OpenAPI per l'autenticazione con chiave API
  • Il formato non valido operationId nella specifica OpenAPI causa un errore di registrazione dello strumento
  • Chiave API non inserita: verificare che la specifica OpenAPI includa sezioni securitySchemes e security e che il nome della chiave corrisponda alla connessione al progetto

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 il meteo e il file di specifica weather_openapi.json. Questo esempio usa metodi sincroni della libreria client di Azure AI Projects. Per un esempio che usa metodi asincroni, vedere l'esempio nel repository Azure SDK per .NET in GitHub.

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()
    {
        // First, create an agent client and read the environment variables, which will be used in the next steps.
        var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
        var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        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(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.
        PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
            agentName: "myAgent",
            options: new(agentDefinition));

        // Create a response object and ask the question about the weather in Seattle, WA.
        ProjectResponsesClient responseClient = projectClient.OpenAI.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.Agents.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 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

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • 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
  • ArgumentNullException: variabili di ambiente necessarie mancanti
  • UnauthorizedAccessException: credenziali non valide o autorizzazioni di controllo degli accessi basato sui ruoli insufficienti
  • Chiave API non inserita: verifica che la tua specifica OpenAPI includa sia la sezione securitySchemes (in components) sia la sezione security con nomi di schemi corrispondenti.

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

In questo esempio si usano servizi con una specifica OpenAPI usando l'agente in uno scenario che richiede l'autenticazione. Utilizzi la specifica TripAdvisor.

Il servizio TripAdvisor richiede l'autenticazione basata su chiave. Per creare una connessione nel portale di Azure, aprire Microsoft Foundry e nel pannello sinistro selezionare Centro gestione e quindi 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()
    {
        // First, we need to create agent client and read the environment variables, which will be used in the next steps.
        var projectEndpoint = System.Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
        var modelDeploymentName = System.Environment.GetEnvironmentVariable("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

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

        // Create the agent definition and the agent version.
        PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
        {
            Instructions = "You are a helpful assistant.",
            Tools = { openapiTool }
        };
        AgentVersion agentVersion = projectClient.Agents.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.OpenAI.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.Agents.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 con chiave API tramite una connessione di progetto. Quando si esegue il codice:

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

Input necessari

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • File locale di: Assets/tripadvisor_openapi.json
  • Connessione di progetto: tripadvisor con la 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: verifica che ToolChoice = ResponseToolChoice.CreateRequiredChoice() forzi l'utilizzo dello strumento.
  • Chiave API non passata all'API: assicurarsi che la specifica OpenAPI abbia le sezioni securitySchemes e security correttamente configurate.

Creare un agente Java con le funzionalità degli strumenti OpenAPI

Questo esempio Java crea un agente con uno strumento OpenAPI usando com.azure:azure-ai-agents e un file di specifiche OpenAPI 3.0 locale. L'esempio usa l'autenticazione anonima e chiama un endpoint API pubblico.

import com.azure.ai.agents.AgentsClient;
import com.azure.ai.agents.AgentsClientBuilder;
import com.azure.ai.agents.AgentsServiceVersion;
import com.azure.ai.agents.ConversationsClient;
import com.azure.ai.agents.ResponsesClient;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.OpenApiAgentTool;
import com.azure.ai.agents.models.OpenApiAnonymousAuthDetails;
import com.azure.ai.agents.models.OpenApiFunctionDefinition;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.core.util.BinaryData;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.json.JsonProviders;
import com.azure.json.JsonReader;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Arrays;

public class OpenApiAgentJavaSample {
    public static void main(String[] args) throws Exception {
        String endpoint = System.getenv("FOUNDRY_PROJECT_ENDPOINT");
        if (endpoint == null || endpoint.isBlank()) {
            endpoint = System.getenv("PROJECT_ENDPOINT");
        }

        String model = System.getenv("FOUNDRY_MODEL_DEPLOYMENT_NAME");
        if (model == null || model.isBlank()) {
            model = System.getenv("MODEL_DEPLOYMENT_NAME");
        }

        AgentsClientBuilder builder = new AgentsClientBuilder()
            .endpoint(endpoint)
            .credential(new DefaultAzureCredentialBuilder().build())
            .serviceVersion(AgentsServiceVersion.V2025_11_15_PREVIEW);

        AgentsClient agentsClient = builder.buildAgentsClient();
        ResponsesClient responsesClient = builder.buildResponsesClient();
        ConversationsClient conversationsClient = builder.buildConversationsClient();

        JsonReader reader = JsonProviders.createReader(Files.readAllBytes(Path.of("openapi_spec.json")));
        BinaryData spec = reader.getNullable(nonNullReader -> BinaryData.fromObject(nonNullReader.readUntyped()));

        OpenApiFunctionDefinition toolDefinition = new OpenApiFunctionDefinition(
            "httpbin_get",
            spec,
            new OpenApiAnonymousAuthDetails())
            .setDescription("Get request metadata from an OpenAPI endpoint.");

        PromptAgentDefinition agentDefinition = new PromptAgentDefinition(model)
            .setInstructions("Use the OpenAPI tool for HTTP request metadata.")
            .setTools(Arrays.asList(new OpenApiAgentTool(toolDefinition)));

        AgentVersionDetails agentVersion = agentsClient.createAgentVersion("openapiValidationAgentJava", agentDefinition);
        System.out.println("Agent: " + agentVersion.getName() + ", version: " + agentVersion.getVersion());

        Conversation conversation = conversationsClient.getConversationService().create();
        conversationsClient.getConversationService().items().create(
            ItemCreateParams.builder()
                .conversationId(conversation.id())
                .addItem(EasyInputMessage.builder()
                    .role(EasyInputMessage.Role.USER)
                    .content("Use the OpenAPI tool and summarize the returned URL and origin in one sentence.")
                    .build())
                .build());

        try {
            AgentReference agentReference = new AgentReference(agentVersion.getName()).setVersion(agentVersion.getVersion());
            ResponseCreateParams.Builder options = ResponseCreateParams.builder().maxOutputTokens(300L);
            Response response = responsesClient.createWithAgentConversation(agentReference, conversation.id(), options);

            String text = response.output().stream()
                .filter(item -> item.isMessage())
                .map(item -> item.asMessage().content()
                    .get(item.asMessage().content().size() - 1)
                    .asOutputText()
                    .text())
                .reduce((first, second) -> second)
                .orElse("<no message output>");

            System.out.println("Status: " + response.status().map(Object::toString).orElse("unknown"));
            System.out.println("Response: " + text);
        } finally {
            agentsClient.deleteAgentVersion(agentVersion.getName(), agentVersion.getVersion());
            System.out.println("Agent deleted");
        }
    }
}

Che cosa fa questo codice

Questo esempio Java crea un agente con uno strumento OpenAPI ed esegue una risposta a livello di conversazione.

  1. Carica la specifica OpenAPI da openapi_spec.json.
  2. Crea una versione dell'agente con OpenApiAgentTool.
  3. Crea una conversazione e aggiunge un messaggio utente.
  4. Crea una risposta passando AgentReference e l'ID conversazione.
  5. Pulisce eliminando la versione dell'agente.

Input necessari

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT (o PROJECT_ENDPOINT) e FOUNDRY_MODEL_DEPLOYMENT_NAME (o MODEL_DEPLOYMENT_NAME)
  • File locale: openapi_spec.json (specifica OpenAPI 3.0)

Output previsto

Agent: openapiValidationAgentJava, version: 1
Status: completed
Response: The API response reports URL ... and origin ...
Agent deleted

Errori comuni

  • Invalid OpenAPI specification: analizzare il codice JSON OpenAPI in un oggetto prima di passarlo a OpenApiFunctionDefinition.
  • Invalid conversation id: creare una conversazione e passare conversation.id() a createWithAgentConversation.
  • AuthenticationFailedException: Verifica che DefaultAzureCredential sia possibile ottenere un token per l'account con cui è stato effettuato l'accesso.

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

Autenticazione anonima

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

Autenticazione della chiave API (connessione di progetto)

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

Autenticazione 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. Richiesta:

  1. Invia una query all'agente chiedendo informazioni sul meteo di Seattle.
  2. Includere la definizione dello strumento OpenAPI in linea con la specifica dell'API meteo.
  3. Mostra tre opzioni di autenticazione (anonima, chiave API tramite connessione di progetto, identità gestita) come alternative commentate.
  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 basata su 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 AGENT_TOKEN, non inserita perché securitySchemes e security mancano nelle specifiche 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 le funzionalità degli strumenti OpenAPI, utilizzando il client sincrono di Azure AI Projects e il OpenApiTool. L'agente può chiamare API esterne definite dalle specifiche OpenAPI. Per una versione JavaScript di questo esempio, vedere l'esempio 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";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";
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> {
  console.log("Loading OpenAPI specifications from assets directory...");
  const weatherSpec = loadOpenApiSpec(weatherSpecPath);

  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await project.getOpenAIClient();

  console.log("Creating agent with OpenAPI 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: [createWeatherTool(weatherSpec)],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  console.log("\nSending request to OpenAPI-enabled agent with streaming...");
  const streamResponse = await openAIClient.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: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      const item = event.item as any;
      if (item.type === "message") {
        const content = item.content?.[item.content.length - 1];
        if (content?.type === "output_text" && content.annotations) {
          for (const annotation of content.annotations) {
            if (annotation.type === "url_citation") {
              console.log(
                `URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
              );
            }
          }
        }
      } else if (item.type === "tool_call") {
        console.log(`Tool call completed: ${item.name ?? "unknown"}`);
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nOpenAPI agent sample completed!");
}

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 del meteo da un file JSON locale.
  2. Crea un agente con lo strumento meteo configurato.
  3. 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

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME
  • 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
  • Le variabili di ambiente mancanti causano un errore di inizializzazione
  • 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 l'esempio 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";
import "dotenv/config";

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["FOUNDRY_MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";
const tripAdvisorProjectConnectionId =
  process.env["TRIPADVISOR_PROJECT_CONNECTION_ID"] || "<tripadvisor project 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: tripAdvisorProjectConnectionId,
    },
  };

  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> {
  console.log("Loading TripAdvisor OpenAPI specification from assets directory...");
  const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);

  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openAIClient = await project.getOpenAIClient();

  console.log("Creating agent with 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)],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  console.log("\nSending request to TripAdvisor OpenAPI agent with streaming...");
  const streamResponse = await openAIClient.responses.create(
    {
      input:
        "Provide a quick overview of the TripAdvisor location 293919 including its name, rating, and review count.",
      stream: true,
    },
    {
      body: {
        agent: { name: agent.name, type: "agent_reference" },
        tool_choice: "required",
      },
    },
  );

  // Process the streaming response
  for await (const event of streamResponse) {
    if (event.type === "response.created") {
      console.log(`Follow-up response created with ID: ${event.response.id}`);
    } else if (event.type === "response.output_text.delta") {
      process.stdout.write(event.delta);
    } else if (event.type === "response.output_text.done") {
      console.log("\n\nFollow-up response done!");
    } else if (event.type === "response.output_item.done") {
      const item = event.item as any;
      if (item.type === "message") {
        const content = item.content?.[item.content.length - 1];
        if (content?.type === "output_text" && content.annotations) {
          for (const annotation of content.annotations) {
            if (annotation.type === "url_citation") {
              console.log(
                `URL Citation: ${annotation.url}, Start index: ${annotation.start_index}, End index: ${annotation.end_index}`,
              );
            }
          }
        }
      } else if (item.type === "tool_call") {
        console.log(`Tool call completed: ${item.name ?? "unknown"}`);
      }
    } else if (event.type === "response.completed") {
      console.log("\nFollow-up completed!");
    }
  }

  // Clean up resources by deleting the agent version
  // This prevents accumulation of unused resources in your project
  console.log("\nCleaning up resources...");
  await project.agents.deleteVersion(agent.name, agent.version);
  console.log("Agent deleted");

  console.log("\nTripAdvisor OpenAPI agent sample completed!");
}

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_PROJECT_CONNECTION_ID variabile di ambiente.
  3. Crea un agente con lo strumento TripAdvisor che usa la connessione di progetto per l'autenticazione della chiave API.
  4. Invia una richiesta di 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

  • Variabili di ambiente: FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_DEPLOYMENT_NAME, TRIPADVISOR_PROJECT_CONNECTION_ID
  • File locale di: ../assets/tripadvisor_openapi.json
  • Connessione di 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_PROJECT_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 le 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: application/json e application/json-patch+json.

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

Usando l'autenticazione della chiave API, è possibile autenticare la specifica OpenAPI usando vari metodi, ad esempio una chiave API o un token di connessione. È possibile usare un solo schema di sicurezza della chiave API per ogni specifica OpenAPI. Se sono necessari più schemi di sicurezza, creare più strumenti per specifiche 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.

    Annotazioni

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

  7. Immettere le informazioni seguenti

    • chiave: 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'

È possibile usare l'autenticazione basata su token (ad esempio, un Bearer token) con lo stesso project_connection tipo di autenticazione usato per le chiavi API. La differenza principale è il modo in cui si configurano sia la specifica OpenAPI che la connessione al progetto.

La specifica OpenAPI sarà simile alla seguente:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Dovrai:

  1. Aggiorna la specifica OpenAPI securitySchemes per utilizzare 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 campo name 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 con l'identità gestita (ID Microsoft Entra)

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 dell'identità gestita, l'agente esegue l'autenticazione attraverso lo strumento Foundry che utilizza.

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

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

    Screenshot che mostra il selettore di identità gestita nel portale di Azure.

  2. Creare una risorsa per il servizio a cui connettersi tramite la specifica OpenAPI.

  3. 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 che mostra il selettore di assegnazione di ruolo nel portale di Azure.

    3. Selezionare l'assegnazione di ruolo appropriata necessaria, in genere richiede almeno il ruolo READER . Quindi, seleziona 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.

  4. 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 Causa possibile Risoluzione
La chiave API non è inclusa nelle richieste. Mancano le sezioni securitySchemes o security della specifica OpenAPI. 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.
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 ha esito negativo con 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 di operationId. Rimuovere numeri e caratteri speciali.
Errore: connessione non trovata. Nome della connessione o mancata corrispondenza dell'ID. Verificare che OPENAPI_PROJECT_CONNECTION_NAME corrisponda al nome della connessione nel progetto Foundry.
Token di tipo Bearer non inviato correttamente. Manca il 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 specifica securitySchemes OpenAPI 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 Ideale per Complessità della configurazione
Anonimo API pubbliche senza autenticazione Low
Chiave dell'API API di terze parti con accesso basato su chiave Intermedio
Identità gestita Servizi di Azure e API protette con ID Microsoft Entra Medio-alto

Contenuti correlati

  • Last updated on