Conexión de agentes a herramientas de OpenAPI

Conecte los agentes de Microsoft Foundry a las API externas mediante especificaciones de OpenAPI 3.0 y 3.1. El modelo foundry que impulsa el agente puede llamar a servicios externos, recuperar datos en tiempo real y ampliar sus funcionalidades más allá de las funciones integradas.

Las especificaciones de OpenAPI definen una manera estándar de describir las API HTTP para que pueda integrar los servicios existentes con los agentes. Microsoft Foundry admite tres métodos de autenticación: anonymous, API key y managed identity. Para obtener ayuda para elegir un método de autenticación, consulte Elegir un método de autenticación.

Sugerencia

Considere la posibilidad de agregar esta herramienta mediante un cuadro de herramientas. Mediante el uso de un cuadro de herramientas, puede reutilizar la herramienta entre agentes y entornos de ejecución, así como centralizar la administración de credenciales, el control de versiones y la aplicación de directivas a través de un punto de conexión de MCP administrado. Consulte el inicio rápido del cuadro de herramientas.

Requisitos previos

Antes de comenzar, asegúrese de que tiene:

  • Una suscripción Azure con los permisos adecuados.

  • Rol de usuario de Foundry en el proyecto Foundry para crear y ejecutar agentes.

    Importante

    Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se llamaban anteriormente Usuario de Azure AI, Propietario de Azure AI, Propietario de la cuenta de Azure AI y Administrador de proyectos de Azure AI. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

  • el rol de Foundry Project Manager en el proyecto de Foundry si crea una conexión de proyecto para la autenticación mediante clave de API o token.

  • Un proyecto de Foundry creado con un endpoint configurado.

  • Un modelo de IA implementado en el proyecto. Confirme que tanto el modelo como la región del proyecto admiten herramientas de OpenAPI en la compatibilidad con herramientas por región y modelo.

  • Un entorno de agente básico o estándar.

  • SDK instalado para su idioma preferido:

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

Variables de entorno

Variable Descripción
FOUNDRY_PROJECT_ENDPOINT Dirección URL del punto de conexión del proyecto de Foundry (no el punto de conexión de servicio OpenAPI externo).
FOUNDRY_MODEL_DEPLOYMENT_NAME Nombre del modelo implementado.
OPENAPI_PROJECT_CONNECTION_NAME (Para la autenticación de clave de API) Nombre de conexión del proyecto para el servicio OpenAPI.
  • Archivo de especificación openAPI 3.0 o 3.1 que cumple estos requisitos:
    • Cada función debe tener una operationId (necesaria para la herramienta OpenAPI).
    • operationId solo debe contener letras, -y _.
    • Use nombres descriptivos para ayudar a los modelos a decidir eficazmente qué función usar.
    • Tipos de contenido de cuerpo de solicitud admitidos: application/json, application/json-patch+json
  • Para la autenticación de identidad administrada: el rol de servicio de destino con privilegios mínimos que permite las operaciones de API necesarias, asignadas a la identidad administrada del proyecto Foundry en el ámbito del recurso de destino.
  • Para la autenticación mediante clave o token de API: una conexión de proyecto que esté configurada con tu clave de API o tu token. Consulte Agregar una nueva conexión al proyecto.

Nota

El valor FOUNDRY_PROJECT_ENDPOINT hace referencia al punto de conexión del proyecto Microsoft Foundry, no al punto de conexión de servicio openAPI externo. Puede encontrar este punto de conexión en el portal de Microsoft Foundry en la página Información general del proyecto. Este punto de conexión es necesario para autenticar el servicio del agente y es independiente de los puntos de conexión de OpenAPI definidos en el archivo de especificación.

Soporte de uso

En la tabla siguiente se muestra la compatibilidad con el SDK y la configuración.

compatibilidad con Microsoft Foundry SDK de Python C# SDK SDK de JavaScript SDK de Java REST API Configuración básica del agente Configuración del agente estándar
✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Nota

Para Java, use el paquete com.azure:azure-ai-agents para las herramientas del agente de OpenAPI. El com.azure:azure-ai-projects paquete no expone actualmente los tipos de herramientas del agente de OpenAPI.

Ejecuta el flujo anónimo del primer éxito

Comience con la API meteorológica anónima para comprobar que el agente puede cargar una especificación de OpenAPI y llamar a una operación. Esta vía no requiere una credencial de API externa ni una conexión a un proyecto de Foundry.

  1. Instale el paquete del SDK para el idioma seleccionado en Requisitos previos.
  2. Descargue weather_openapi.json, y guárdelo en la ruta assets utilizada por el ejemplo.
  3. Establezca los valores del punto de conexión y de la implementación del modelo del proyecto de Foundry.
  4. Ejecute el ejemplo anónimo en la sección de idioma seleccionado.
  5. Confirme que la respuesta contiene el tiempo actual de Seattle y, a continuación, elimine la versión del agente creada por el ejemplo.

Una vez que la llamada anónima se realiza correctamente, configure la autenticación requerida por la API de destino. Mantenga la autenticación de clave de API, la autenticación de token de portador y la autenticación de identidad administrada como variantes independientes.

Descripción de las limitaciones

  • La especificación de OpenAPI debe incluir operationId para cada operación y operationId solo puede incluir letras, -y _.
  • Tipos de contenido del cuerpo de la solicitud admitidos: application/json, application/json-patch+json.
  • Para la autenticación de clave de API, use un esquema de seguridad de clave de API por herramienta OpenAPI. Si necesita varios esquemas de seguridad, cree varias herramientas de OpenAPI.
  • Gire las claves de API y los tokens de portador periódicamente y inmediatamente después de la sospecha de exposición. Actualice la conexión del proyecto cuando cambien las credenciales; no coloque credenciales en la especificación o el código fuente de OpenAPI.

Adición de herramientas de OpenAPI a un cuadro de herramientas

Use este patrón para exponer cualquier API REST descrita por una especificación de OpenAPI. Elija el que coincida con el auth.type modelo de seguridad de la API.

Importante

Al usar la autenticación de identidad administrada, asigne solo el rol de RBAC con privilegios mínimos que permita las operaciones de API necesarias a la identidad administrada del proyecto Foundry en el servicio de destino. Por ejemplo, asigne Lector en el recurso de Azure de destino solo cuando la API necesite acceso de solo lectura a Azure Resource Manager. Sin la asignación necesaria, el agente recibe una 401 Unauthorized respuesta al llamar a la API. Para ver los pasos de configuración completos, consulte Autenticación mediante la identidad administrada.

Autenticación anónima:

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

Autenticación de conexión del proyecto:

Use este patrón cuando la API requiera una clave o un token almacenados en una conexión de proyecto 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>"
          }
        }
      }
    }
  ]
}

Autenticación de identidad administrada:

Use este patrón cuando la API de destino se autentique a través de Microsoft Entra ID. La identidad administrada del proyecto Foundry llama a la API en nombre del agente. Asegúrese de que la identidad administrada tiene el rol RBAC necesario en el servicio de destino antes de usar este patrón.

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

Creación de un cuadro de herramientas de OpenAPI con la CLI para desarrolladores de Azure

Las herramientas de OpenAPI insertan la especificación directamente en tools:. La autenticación basada en conexión (connection_auth) hace referencia a una conexión de proyecto; las herramientas anónimas de OpenAPI no necesitan conexión.

Paso 1. (Opcional) Creación de la conexión de autenticación

Omita este paso para herramientas anónimas de OpenAPI.

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

Las herramientas de OpenAPI también aceptan --auth-type oauth2 conexiones. Para consultar el conjunto completo de azd ai connection create indicadores, consulte Autenticación y configuración de Toolbox MCP.

Paso 2. Definición del cuadro de herramientas

La especificación de OpenAPI está insertada en 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

En el caso de las API anónimas, reemplace el auth: bloque por:

      auth:
        type: anonymous
        security_scheme:
          type: anonymous

Paso 3. Creación del cuadro de herramientas

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

Antes de ejecutar los ejemplos de código

  • Descargue la versión mantenida de la especificación tripadvisor_openapi.json y guárdela en la ruta de acceso assets utilizada por el ejemplo de su lenguaje.

Nota

  • Necesita el paquete de SDK más reciente. El SDK de .NET está actualmente en versión preliminar. Consulte el inicio rápido para obtener más información.
  • Si usa la clave de API para la autenticación, el identificador de conexión debe tener el formato de /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Importante

Para que la autenticación de clave de API funcione, el archivo de especificación de OpenAPI debe incluir:

  1. Sección securitySchemes con la configuración de la clave de API, como el nombre del encabezado y el nombre del parámetro.
  2. Sección security que hace referencia al esquema de seguridad.
  3. Una conexión de proyecto configurada con el nombre y el valor de clave coincidentes.

Sin estas configuraciones, la clave de API no se incluye en las solicitudes. Para obtener instrucciones detalladas sobre la configuración, consulte la sección Autenticación con clave de API .

También puede usar la autenticación basada en tokens (por ejemplo, un token de portador) almacenando el token en una conexión de proyecto. Para la autenticación del token de portador, cree una conexión de claves personalizadas con la clave configurada a Authorization y el valor configurado a Bearer <token> (reemplace <token> con el token real). La palabra Bearer seguida de un espacio debe incluirse en el valor . Para más información, consulte Configuración de una conexión de token de portador.

Ejemplo de uso de agentes con la herramienta OpenAPI

En este ejemplo se muestra cómo usar los servicios descritos por una especificación de OpenAPI mediante un agente. Usa el servicio wttr.in para obtener el tiempo y su archivo de especificación weather_openapi.json. Seleccione Prompt Agents para usar el SDK de proyectos de IA de Azure para crear un agente de mensajes del lado servidor o Agentes hospedados para usar el marco del agente de Microsoft para crear un agente efímero en proceso.

Agentes rápidos

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)

En este ejemplo se crea un agente de solicitud con una herramienta OpenAPI que llama a la API meteorológica wttr.in mediante la autenticación anónima. La herramienta se adjunta directamente a la definición del agente. Al ejecutar el código:

  1. Carga la especificación de OpenAPI meteorológica desde un archivo JSON local.
  2. Crea un agente de solicitud con la herramienta meteorológica configurada para el acceso anónimo.
  3. Envía una consulta sobre el tiempo de Seattle.
  4. El agente usa la herramienta OpenAPI para llamar a la API meteorológica y devuelve resultados con formato.
  5. Limpia eliminando la versión del agente.

Agentes hospedados

En este ejemplo se usa FoundryChatClient desde Microsoft Agent Framework y se conecta al punto de conexión mcP del cuadro de herramientas mediante FoundryToolbox. Instale versiones de paquete compatibles con pip install "agent-framework-foundry==1.10.4" "azure-ai-projects>=2.3.0,<2.4.0" azure-identity jsonref, establezca la FOUNDRY_PROJECT_ENDPOINT variable de entorno e inicie sesión con az login. OpenApiToolboxTool es el modelo específico de la caja de herramientas; utilice OpenApiTool solo cuando adjunte la herramienta directamente a un agente de prompts.

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

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

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


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.
, timeout=120.0)
    toolbox_tool = FoundryToolbox(credential, url=TOOLBOX_MCP_URL)

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

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


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

Salida esperada

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

Ejemplo de uso de agentes con la herramienta OpenAPI

En este ejemplo se muestra cómo usar los servicios descritos por una especificación de OpenAPI mediante un agente. Usa el servicio wttr.in para obtener el tiempo y su archivo de especificación weather_openapi.json. Seleccione Prompt Agents para usar el SDK de proyectos de IA de Azure para crear un agente de mensajes del lado servidor o Agentes hospedados para usar el marco del agente de Microsoft para crear un agente efímero en proceso.

Agentes rápidos

En este ejemplo se usan métodos sincrónicos de la biblioteca cliente de Azure AI Projects. Para ver un ejemplo que usa métodos asincrónicos, consulte el sample en el SDK de Azure para .NET repositorio en 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);
    }
}

Qué hace este código

En este ejemplo de C# se crea un agente con una herramienta OpenAPI que recupera información meteorológica de wttr.in mediante la autenticación anónima. Al ejecutar el código:

  1. Lee la especificación de OpenAPI meteorológica de un archivo JSON local.
  2. Crea un agente con la herramienta de meteorología configurada.
  3. Envía una solicitud que pregunta sobre el tiempo de Seattle mediante la herramienta OpenAPI.
  4. El agente llama a la API weather y devuelve los resultados.
  5. Limpia eliminando el agente.

Entradas necesarias

  • Valor de cadena integrado: projectEndpoint (el punto de conexión del proyecto de Foundry)
  • Archivo local: Assets/weather_openapi.json (especificación openAPI)

Salida esperada

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

Errores comunes

  • FileNotFoundException: no se encuentra el archivo de especificación openAPI en la carpeta Assets
  • UnauthorizedAccessException: credenciales no válidas o permisos de RBAC insuficientes
  • Clave de API no insertada: compruebe que la especificación de OpenAPI incluye securitySchemes (en components) y security secciones con nombres de esquema coincidentes

Agentes hospedados

En este ejemplo se crea el cuadro de herramientas de OpenAPI con el SDK de proyectos de IA de Azure y, a continuación, se usa la integración de Microsoft Agent Framework AddFoundryToolboxes para que la herramienta esté disponible para el agente hospedado. Instale los paquetes de Agent Framework, establezca el punto de conexión del proyecto y AZURE_AI_PROJECT_ENDPOINT las AZURE_AI_MODEL_DEPLOYMENT_NAME variables de entorno e inicie sesión 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.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

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

string projectEndpoint = Environment.GetEnvironmentVariable("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");

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

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

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

Salida esperada

El agente llama a la API meteorológica a través de la herramienta OpenAPI y devuelve las condiciones actuales para la ubicación solicitada:

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

Para obtener el ejemplo completo, incluidos los patrones de API autenticados, consulte Agent_Step17_OpenAPITools.

Ejemplo de uso de agentes con la herramienta OpenAPI en el servicio web, lo que requiere autenticación

En este ejemplo, agregará una herramienta OpenAPI autenticada a un cuadro de herramientas, asociará el cuadro de herramientas como una herramienta MCP y usará el agente en un escenario que requiera autenticación. Usted usa la especificación de TripAdvisor.

El servicio TripAdvisor requiere autenticación basada en claves. Para crear una conexión, abra Microsoft Foundry, seleccione Administrar en la navegación superior derecha, seleccione Project detalles y, a continuación, seleccione la pestaña Recursos conectados. Por último, cree una nueva conexión del tipo de claves personalizadas. Asígnele el nombre tripadvisor y agregue un par clave-valor. Agregue la clave denominada key y escriba un valor con su clave de 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);
    }
}

Qué hace este código

En este ejemplo de C# se muestra el uso de una herramienta OpenAPI con autenticación de clave de API a través de un cuadro de herramientas y una conexión de proyecto. Al ejecutar el código:

  1. Carga la especificación de OpenAPI de TripAdvisor desde un archivo local.
  2. Recupera la conexión de proyecto que contiene tu tripadvisor clave de API.
  3. Crea una versión de la caja de herramientas que contiene la herramienta de TripAdvisor configurada para usar la conexión para autenticarse.
  4. Adjunta la caja de herramientas al agente como una herramienta MCP.
  5. Envía una solicitud de recomendaciones de hotel en París.
  6. El agente llama a la API de TripAdvisor mediante la clave de API almacenada y devuelve resultados.
  7. Limpia eliminando el agente.

Entradas necesarias

  • Valor de cadena integrado: projectEndpoint (el punto de conexión del proyecto de Foundry)
  • Archivo local: Assets/tripadvisor_openapi.json
  • Conexión del proyecto: tripadvisor con la clave de API válida configurada

Salida esperada

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

Errores comunes

  • ConnectionNotFoundException: No se encontró ninguna conexión de proyecto llamada tripadvisor.
  • AuthenticationException: clave de API no válida en la conexión del proyecto o configuración incorrecta securitySchemes o que falta en la especificación de OpenAPI.
  • Herramienta no utilizada: verifique que ToolChoice = ResponseToolChoice.CreateRequiredChoice() fuerza el uso de la herramienta.
  • La clave de API no se ha pasado a la API: asegúrese de que la especificación de OpenAPI tiene bien configuradas las secciones securitySchemes y security.

Creación de un agente de Java con funcionalidades de la herramienta OpenAPI

Esta Java configuración puede hacer referencia a herramientas de MCP, pero el SDK de Java aún no expone una API de creación de cuadros de herramientas.

Sugerencia

Recomendado: Para la mayoría de los agentes, agregue la herramienta OpenAPI a través de un cuadro de herramientas y adjunte el cuadro de herramientas al agente como una herramienta MCP. Cree el cuadro de herramientas mediante el ejemplo de Python, API REST, C#o TypeScript o el portal foundry y, a continuación, haga referencia a su punto de conexión de MCP desde el agente de Java como .McpTool

En los ejemplos siguientes se muestra cómo llamar a una herramienta OpenAPI mediante la API REST.

Obtención de un token de acceso:

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

Autenticación anónima

Agregue herramientas de OpenAPI a través de un cuadro de herramientas y, a continuación, adjunte el cuadro de herramientas al agente como una herramienta MCP. Para obtener más información, consulte ¿Qué es un cuadro de herramientas?

  1. Cree un cuadro de herramientas que contenga la herramienta meteorológica 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" }
                  }
                }
              }
            }
          }
        }
      }
    ]
  }'

El cuadro de herramientas expone un punto de conexión compatible con MCP en $FOUNDRY_PROJECT_ENDPOINT/toolboxes/openapi-toolbox/versions/<version>/mcp?api-version=v1, donde <version> es la versión devuelta por la llamada anterior.

  1. Cree una conexión de proyecto de herramienta remota que apunte al punto de conexión de toolbox mediante un token de Entra de usuario, para que se transmita la identidad de quien realiza la llamada (audiencia 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. Cree una respuesta que use el cuadro de herramientas adjuntandola como una herramienta 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"
      }
    ]
  }'

Autenticación de clave de API (conexión de proyecto)

Use esta variante solo después de que el flujo anónimo se realice correctamente. Configure la conexión del proyecto y la entrada openAPI securitySchemes tal como se describe en Autenticación con clave de 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": [] }
            ]
          }
        }
      }
    ]
  }'

Para una API de token de portador, mantenga la misma project_connection forma de solicitud, pero use una conexión configurada como se describe en Configuración de una conexión de token de portador. El valor de conexión debe comenzar con Bearer seguido de un espacio.

Autenticación de identidad administrada

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

Qué hace este código

En este ejemplo de API REST se muestra cómo llamar a una herramienta OpenAPI con distintos métodos de autenticación. La solicitud:

  1. Para la autenticación anónima, crea un cuadro de herramientas que contiene la definición de la herramienta OpenAPI y la especificación de la API meteorológica.
  2. Crea una respuesta que adjunta el cuadro de herramientas como una herramienta MCP y pregunta sobre el tiempo de Seattle.
  3. Muestra definiciones adicionales de herramientas REST directas para la clave de API a través de la conexión del proyecto y la autenticación de identidad administrada.
  4. El agente usa la herramienta para llamar a la API meteorológica y devuelve resultados con formato.

Entradas necesarias

  • Variables de entorno: FOUNDRY_PROJECT_ENDPOINT, AGENT_TOKEN, FOUNDRY_MODEL_DEPLOYMENT_NAME.
  • Para la autenticación de clave de API: WEATHER_APP_PROJECT_CONNECTION_ID.
  • Para la autenticación de identidad administrada: MANAGED_IDENTITY_AUDIENCE.
  • Especificación de OpenAPI insertada en el cuerpo de la solicitud.

Salida esperada

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

Errores comunes

  • 401 Unauthorized: no es válido o falta AGENT_TOKENla clave de API o no se inserta porque securitySchemes y security faltan en la especificación de OpenAPI.
  • 404 Not Found: punto de conexión incorrecto o nombre de implementación del modelo
  • 400 Bad Request: especificación openAPI con formato incorrecto o configuración de autenticación no válida
  • Clave de API no enviada con solicitud: compruebe que la sección de la especificación de OpenAPI está configurada correctamente (no vacía) y coincide con el components.securitySchemes nombre de la clave de conexión del proyecto.

Creación de un agente con funcionalidades de la herramienta OpenAPI

En el siguiente ejemplo de código de TypeScript se muestra cómo crear un agente de IA con funcionalidades de herramientas de OpenAPI agregando la herramienta OpenAPI a un cuadro de herramientas y adjuntando el cuadro de herramientas como una herramienta MCP. El agente puede llamar a las API externas definidas por las especificaciones de OpenAPI. Para obtener una versión de JavaScript de este ejemplo, vea el sample en el repositorio SDK de Azure para JavaScript en 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);
});

Qué hace este código

En este ejemplo de TypeScript se crea un agente con una herramienta OpenAPI para los datos meteorológicos mediante la autenticación anónima. Al ejecutar el código:

  1. Carga la especificación de OpenAPI meteorológica desde un archivo JSON local.
  2. Crea una versión de la caja de herramientas que contiene la herramienta del clima.
  3. Adjunta la caja de herramientas al agente como una herramienta MCP y, a continuación, envía una solicitud en streaming en la que se pregunta por el tiempo en Seattle y qué ponerse.
  4. Procesa la respuesta de streaming y muestra deltas a medida que llegan.
  5. Fuerza el uso de la herramienta utilizando tool_choice: "required" para garantizar que se llame a la API.
  6. Limpia eliminando el agente.

Entradas necesarias

  • Valor de cadena integrado: PROJECT_ENDPOINT (el punto de conexión del proyecto de Foundry)
  • Archivo local: ../assets/weather_openapi.json (especificación openAPI)

Salida esperada

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!

Errores comunes

  • Error: OpenAPI specification not found: Ruta de acceso del archivo incorrecta o archivo faltante
  • AuthenticationError: credenciales de Azure no válidas
  • Clave de API que no funciona: si cambia de autenticación anónima a clave de API, asegúrese de que la especificación de OpenAPI tenga securitySchemes y security configure correctamente.

Creación de un agente que use herramientas de OpenAPI autenticadas con una conexión de proyecto

En el siguiente ejemplo de código de TypeScript se muestra cómo crear un agente de IA que use herramientas de OpenAPI autenticadas a través de una conexión de proyecto. El agente carga la especificación de OpenAPI de TripAdvisor desde recursos locales y puede invocar la API a través de la conexión de proyecto configurada. Para obtener una versión de JavaScript de este ejemplo, vea el sample en el repositorio SDK de Azure para JavaScript en 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);
});

Qué hace este código

En este ejemplo de TypeScript se muestra el uso de una herramienta OpenAPI con autenticación de clave de API a través de una conexión de proyecto. Al ejecutar el código:

  1. Carga la especificación de OpenAPI de TripAdvisor desde un archivo local.
  2. Configura la autenticación mediante la TRIPADVISOR_CONNECTION_ID constante .
  3. Crea un agente con la herramienta TripAdvisor que usa la conexión del proyecto para la autenticación de clave de API.
  4. Envía una solicitud de transmisión para obtener los detalles de la ubicación de TripAdvisor.
  5. Fuerza el uso de la herramienta utilizando tool_choice: "required" para garantizar que se llame a la API.
  6. Procesa y muestra la respuesta en streaming.
  7. Limpia eliminando el agente.

Entradas necesarias

  • Valores de cadena en línea: PROJECT_ENDPOINT, TRIPADVISOR_CONNECTION_ID
  • Archivo local: ../assets/tripadvisor_openapi.json
  • Conexión del proyecto configurada con la clave de API de TripAdvisor

Salida esperada

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!

Errores comunes

  • Error: OpenAPI specification not found: compruebe la ruta de acceso del archivo.
  • Conexión no encontrada: compruebe TRIPADVISOR_CONNECTION_ID que la conexión es correcta y existe.
  • AuthenticationException: clave de API no válida en la conexión del proyecto.
  • Clave de API no insertada en solicitudes: la especificación de OpenAPI debe incluir secciones adecuadas securitySchemes (en components) y security. El nombre de clave de securitySchemes debe coincidir con la clave de la conexión del proyecto.
  • Content type is not supported: actualmente, solo se admiten estos dos tipos de contenido de cuerpo de solicitud: application/json y application/json-patch+json. Los tipos de contenido de respuesta no están restringidos.

Consideraciones sobre seguridad y datos

Al conectar un agente a una herramienta OpenAPI, el agente puede enviar parámetros de solicitud derivados de la entrada del usuario a la API de destino.

  • Use conexiones de proyecto para secretos (claves de API y tokens). Evite colocar secretos en un archivo de especificación de OpenAPI o código fuente.
  • Revise los datos que recibe la API y lo que devuelve antes de usar la herramienta en producción.
  • Use el acceso con privilegios mínimos. Para la identidad administrada, asigne solo los roles que requiere el servicio de destino.

Autenticación con clave de API

Use esta variante para una API que espera una clave en un encabezado o parámetro de consulta. Solo puede usar un esquema de seguridad de clave de API por herramienta OpenAPI. Si la API requiere varios esquemas de seguridad, cree varias herramientas de OpenAPI.

  1. Actualice los esquemas de seguridad de las especificaciones de OpenAPI. Tiene una securitySchemes sección y uno esquema de tipo apiKey. Por ejemplo:

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

    Normalmente, solo es necesario actualizar el name campo , que corresponde al nombre de key en la conexión. Si los esquemas de seguridad incluyen varios esquemas, mantenga solo uno de ellos.

  2. Actualice la especificación de OpenAPI para incluir una security sección:

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

  3. Quite cualquier parámetro de la especificación de OpenAPI que necesite clave de API, ya que la clave de API se almacena y pasa a través de una conexión, como se describe más adelante en este artículo.

  4. Cree una conexión para almacenar la clave de API.

  5. Vaya al portal de Foundry y abra el proyecto.

  6. Cree o seleccione una conexión que almacene el secreto. Consulte Agregar una nueva conexión al proyecto.

    Nota

    Si vuelve a generar la clave de API en una fecha posterior, debe actualizar la conexión con la nueva clave.

  7. Escriba la siguiente información.

    • clave: campo name del esquema de seguridad. En este ejemplo, debe ser x-api-key

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

    • valor: YOUR_API_KEY

  8. Después de crear una conexión, puede usarla a través del SDK o la API REST. Use las pestañas de la parte superior de este artículo para ver ejemplos de código.

Configurar una conexión de token de portador

Use esta variante para una API que espera un token de portador en el Authorization encabezado. Usa el mismo tipo de autenticación project_connection que la autenticación mediante clave de API, pero el esquema de seguridad de OpenAPI y los valores de conexión son diferentes.

La especificación de OpenAPI tendrá este aspecto:

  BearerAuth:
    type: http
    scheme: bearer
    bearerFormat: JWT

Debe hacer lo siguiente:

  1. Actualice la especificación securitySchemes de OpenAPI para usarla Authorization como nombre de encabezado:

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

  2. Agregue una security sección que haga referencia al esquema:

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

  3. Cree una conexión de claves personalizadas en el proyecto de Foundry.

    1. Vaya al portal de Foundry y abra el proyecto.
    2. Cree o seleccione una conexión que almacene el secreto. Consulte Agregar una nueva conexión al proyecto.
    3. Escriba los valores siguientes:
      • key: Authorization (debe coincidir con el name campo de su securitySchemes)
      • value: Bearer <token> (reemplace <token> por su token correspondiente)

    Importante

El valor debe incluir la palabra Bearer seguida de un espacio antes del token. Por ejemplo: Bearer eyJhbGciOiJSUzI1NiIs.... Si omite el prefijo Bearer y el espacio siguiente, la API recibe un token en bruto sin el prefijo requerido del esquema de autorización, y la solicitud falla.

  1. Después de crear la conexión, úsela con el tipo de autenticación project_connection en su código, de la misma manera que lo haría para la autenticación de clave API. El identificador de conexión usa el mismo formato: /subscriptions/{{subscriptionID}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.CognitiveServices/accounts/{{foundryAccountName}}/projects/{{foundryProjectName}}/connections/{{foundryConnectionName}}.

Autenticación mediante la identidad administrada (Microsoft Entra ID)

Microsoft Entra ID es un servicio de administración de acceso e identidades basado en la nube que los empleados pueden usar para acceder a recursos externos. Con Microsoft Entra ID, puede agregar seguridad adicional a las API sin necesidad de usar claves de API. Al configurar la autenticación de identidad administrada, el agente se autentica a través de la herramienta Foundry que usa.

Importante

La autenticación de identidad administrada solo funciona cuando el servicio de destino acepta tokens Microsoft Entra ID. Si la API de destino usa un esquema de autenticación personalizado que no admite Microsoft Entra ID, use clave API o token Bearer en su lugar.

Comprender el URI de audiencia

El audience (a veces denominado resource identifier o Application ID URI) indica Microsoft Entra ID a qué servicio o API está destinado el token. El valor de audiencia debe coincidir con lo que espera el servicio de destino o se produce un error de autenticación 401.

Nota

El público no es el punto de conexión del proyecto Foundry. Es el identificador de recurso del servicio de destino al que llama la herramienta OpenAPI.

En la tabla siguiente se enumeran los URI de audiencia para los servicios comunes de Azure:

Servicio de destino URI de audiencia
Azure Storage https://storage.azure.com
Azure Key Vault https://vault.azure.net
Búsqueda de Azure AI https://search.azure.com
Azure Logic Apps https://logic.azure.com
Azure API Management (plano de administración) https://management.azure.com
API protegida por un registro de aplicación de Microsoft Entra (incluido APIM con OAuth) El URI del identificador de aplicación del registro de la aplicación (por ejemplo, api://<client-id>)

Sugerencia

Si usa Azure API Management para proteger una API personalizada con una directiva de validación de OAuth 2.0, el público es el URI de id. de aplicación del registro de aplicaciones que protege la API, no https://management.azure.com. El público del plano de administración solo se aplica a las operaciones de Azure Resource Manager en el propio recurso de APIM.

Para obtener más información sobre cómo los agentes se autentican con Microsoft Entra ID, consulte Agent identity and authentication.

Búsqueda y comprobación de la audiencia

Siga estos pasos para determinar y comprobar el valor de audiencia correcto:

  • Para servicios de Azure: compruebe la documentación del servicio para ver su identificador de recursos de Microsoft Entra ID. La mayoría de los servicios Azure enumeran el URI de audiencia en su documentación de autenticación.
  • Para APIs protegidas por un registro de aplicación de Microsoft Entra: en el portal de Azure, vaya a Microsoft Entra ID>Registros de aplicaciones> seleccione su aplicación >Exponer una API. El URI del identificador de aplicación de la parte superior de la página es el valor de audiencia.
  • Para verificar el público de un token: descodifique el token de acceso en https://jwt.ms y compruebe la reclamación aud. El aud valor debe coincidir con la audiencia que espera el servicio de destino.

Configurar la autenticación de identidades administradas

Para configurar la autenticación mediante identidad administrada:

  1. Asegúrese de que el recurso foundry tiene habilitada la identidad administrada asignada por el sistema.

Captura de pantalla del portal de Azure que muestra la configuración de identidad administrada asignada por el sistema.

  1. Cree un recurso para el servicio al que desea conectarse a través de la especificación de OpenAPI.

  2. Asigne el acceso adecuado al recurso.

    1. Seleccione Access Control para el recurso.

    2. Seleccione Agregar y agregue la asignación de roles en la parte superior de la pantalla.

      Captura de pantalla del portal de Azure que muestra la acción Agregar asignación de roles.

  3. Seleccione el rol del plano de datos o de la aplicación con el menor nivel de privilegios que permita realizar las operaciones definidas en su especificación OpenAPI. Azure Resource Manager acceso de lector por sí solo no concede acceso al plano de datos. A continuación, seleccione Siguiente.

  4. Seleccione Identidad administrada y, a continuación, seleccione Miembros.

  5. En el menú desplegable identidad administrada, busque Foundry Account (Cuenta de Foundry ) y, a continuación, seleccione la cuenta Foundry del agente.

  6. Seleccione Finalizar.

  7. Cuando termine la instalación, puede continuar con la herramienta mediante el portal de Foundry, el SDK o la API REST. Use las pestañas de la parte superior de este artículo para ver ejemplos de código.

Solución de errores comunes

Síntoma Causa probable Resolución
La clave de API no se incluye en las solicitudes. Faltan especificaciones de OpenAPI o secciones securitySchemes o security Compruebe que la especificación de OpenAPI incluye tanto components.securitySchemes como una sección de nivel superior security. Asegúrese de que el esquema name coincide con el nombre de clave en la conexión del proyecto.
El agente no llama a la herramienta OpenAPI. Opción de herramienta no establecida o operationId no descriptiva. Use tool_choice="required" para forzar la invocación de herramientas. Asegúrese operationId de que los valores son descriptivos para que el modelo pueda elegir la operación correcta.
Se produce un error de autenticación para la identidad administrada. La identidad administrada no está habilitada o falta la asignación de roles. Habilitar la identidad administrada asignada por el sistema en el recurso Foundry. Asigne el rol de aplicación o plano de datos con privilegios mínimos del servicio de destino para las operaciones de la especificación de OpenAPI.
La identidad administrada devuelve un error 401 aunque el rol esté asignado. El URI de audiencia no coincide con lo que espera el servicio de destino. Compruebe que el URI de audiencia coincide con el identificador de recursos del servicio de destino. Para Azure servicios, consulte la documentación del servicio. Para las API protegidas por Microsoft Entra, use el URI de identificador de aplicación del registro de la aplicación. Descodifique el token en https://jwt.ms y confirme que la reclamación aud coincida. Consulte Descripción del URI de audiencia.
Token de identidad administrada rechazado por la API de destino. El servicio de destino no acepta tokens de Microsoft Entra ID. Confirme que el servicio de destino admite la autenticación Microsoft Entra ID. Si no es así, use la clave de API o la autenticación de token de portador en su lugar.
Se produce un error en la solicitud con 400 Solicitud incorrecta. La especificación de OpenAPI no coincide con la API real. Valide la especificación de OpenAPI con la API real. Compruebe los nombres de parámetros, los tipos y los campos obligatorios.
Error de solicitud con 401 No autorizado. Clave de API o token no válido o expirado. Vuelva a generar la clave o el token de API y actualice la conexión del proyecto. Compruebe que el identificador de conexión es correcto.
La herramienta devuelve un formato de respuesta inesperado. Esquema de respuesta no definido en la especificación de OpenAPI. Agregue esquemas de respuesta a la especificación de OpenAPI para mejorar la comprensión del modelo.
operationId error de validación. Caracteres no válidos en operationId. Utilice solo letras, - y _ en valores de operationId. Quite números y caracteres especiales.
Error: conexión no encontrada. Error de coincidencia del nombre de conexión o del identificador. Compruebe que OPENAPI_PROJECT_CONNECTION_NAME coincide con el nombre de conexión en el proyecto Foundry.
El token de portador no se ha enviado correctamente. Al valor de conexión le faltan el prefijo Bearer y el espacio a continuación. Establezca el valor de conexión en Bearer <token> (con la palabra Bearer y un espacio antes del token). Compruebe que la especificación securitySchemes de OpenAPI usa "name": "Authorization".

Elección de un método de autenticación

La tabla siguiente le ayuda a elegir el método de autenticación adecuado para la herramienta OpenAPI:

Método de autenticación Más adecuado para Complejidad de la instalación
Anónimo API públicas sin autenticación Bajo
Clave de API API que no son de Microsoft con acceso basado en claves Medio
Identidad administrada Servicios de Azure y las API protegidas por Microsoft Entra ID. Requiere que el servicio de destino acepte tokens de Microsoft Entra ID y admita Azure RBAC o control de acceso basado en Microsoft Entra. Medio-Alto

Contenido relacionado

  • Last updated on