Compartir a través de


Uso del servicio agente de Azure AI Foundry con las herramientas especificadas de OpenAPI

Ahora puede conectar el agente de Azure AI a una API externa mediante una herramienta especificada de OpenAPI 3.0, lo que permite una interoperabilidad escalable con varias aplicaciones. Habilite las herramientas personalizadas para autenticar el acceso y las conexiones con identidades administradas (Microsoft Entra ID) para mayor seguridad, lo que lo convierte en ideal para la integración con servicios web o infraestructura existentes.

La herramienta especificada de OpenAPI mejora la experiencia de llamada de funciones al proporcionar integraciones de API estandarizadas, automatizadas y escalables que mejoran las funcionalidades y la eficacia del agente. Las especificaciones de OpenAPI proporcionan un estándar formal para describir las API HTTP. Esto permite a las personas comprender cómo funciona una API, cómo funciona una secuencia de API, generar código de cliente, crear pruebas, aplicar estándares de diseño, etc. Actualmente, se admiten tres tipos de autenticación con las herramientas especificadas de OpenAPI 3.0: anonymous, API key, managed identity.

Soporte de uso

Compatibilidad con la Fundición de IA de Azure SDK de Python SDK DE C# REST API Instalación básica del agente Configuración del agente estándar
✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Prerrequisitos

  1. Asegúrese de que ha completado los requisitos previos y los pasos de configuración en el inicio rápido.

  2. Compruebe las especificaciones de OpenAPI para conocer los siguientes requisitos:

    1. Aunque no es necesario para la especificación de OpenAPI, operationId es necesario para que cada función se use con la herramienta OpenAPI.
    2. operationId solo debe contener letras, - y _. Puede modificarlo para cumplir el requisito. Se recomienda usar el nombre descriptivo para ayudar a los modelos a decidir eficazmente qué función usar.

Autenticación con clave de API

Con la autenticación de clave de API, puede autenticar la especificación de OpenAPI mediante varios métodos, como una clave de API o un token de portador. Solo se admite un esquema de seguridad de clave de API según las especificaciones de OpenAPI. Si necesita varios esquemas de seguridad, cree varias herramientas de especificación de OpenAPI.

  1. Actualice los esquemas de seguridad de las especificaciones de OpenAPI. tiene una securitySchemes sección y un 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, se recomienda mantener 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 almacenará y pasará a través de una conexión, como se describe más adelante en este artículo.

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

    1. Vaya al portal de Azure AI Foundry y seleccione el proyecto de IA. Seleccione recursos conectados. Recorte de pantalla del botón de configuración de un proyecto de IA.

    2. Seleccione + nueva conexión en la página de configuración.

      Nota:

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

      Recorte de pantalla de conexiones para el proyecto de IA.

    3. Seleccione claves personalizadas en otros tipos de recursos.

      Recorte de pantalla de la selección de claves personalizadas para el proyecto de IA.

    4. Escriba la siguiente información

      • clave: name campo del esquema de seguridad. En este ejemplo debería ser x-api-key
               "securitySchemes": {
                  "apiKeyHeader": {
                            "type": "apiKey",
                            "name": "x-api-key",
                            "in": "header"
                        }
                }
        
      • valor: YOUR_API_KEY
      • Nombre de conexión: YOUR_CONNECTION_NAME (usará este nombre de conexión en el código de ejemplo siguiente).
      • Acceso: puede elegir solo este proyecto o compartirlo en todos los proyectos. Solo tiene que asegurarse de que, en el código de ejemplo siguiente, el proyecto para el que escribió la cadena de conexión tenga acceso a esta conexión.
  5. Una vez que haya creado 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.

Autenticación con identidad administrada (Id. de Microsoft Entra)

Microsoft Entra ID es un servicio de administración de identidades y acceso basado en la nube que los empleados pueden usar para acceder a recursos externos. Microsoft Entra ID permite autenticar las API con seguridad adicional sin necesidad de pasar claves de API. Una vez que haya configurado la autenticación de identidad administrada, se autenticará a través del servicio Azure AI que usa el agente.

Para configurar la autenticación con identidad administrada:

  1. Habilite el servicio Azure AI, ya que su agente tiene system assigned managed identity habilitado.

    Captura de pantalla que muestra el selector de identidades administradas en Azure Portal.

  2. Cree un recurso del servicio al que desea conectarse a través de la especificación de OpenAPI.

  3. Asigne el acceso adecuado al recurso.

    1. Haga clic en Control de acceso para el recurso.

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

      Captura de pantalla que muestra el selector de asignación de roles en Azure Portal.

    3. Seleccione la asignación de roles adecuada, suele requerir al menos el rol LECTOR. A continuación, haga clic en Siguiente.

    4. Seleccione Identidad administrada y, a continuación, haga clic en Seleccionar miembros.

    5. En el menú desplegable identidad administrada, busque servicios de Azure AI y, a continuación, seleccione el servicio de IA del agente.

    6. Haga clic en Finalizar

  4. Una vez finalizada la instalación, puede continuar con la herramienta a través del 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.