Nota
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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
Asegúrese de que ha completado los requisitos previos y los pasos de configuración en el inicio rápido.
Compruebe las especificaciones de OpenAPI para conocer los siguientes requisitos:
- Aunque no es necesario para la especificación de OpenAPI,
operationId
es necesario para que cada función se use con la herramienta OpenAPI. 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.
- Aunque no es necesario para la especificación de OpenAPI,
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.
Actualice los esquemas de seguridad de las especificaciones de OpenAPI. tiene una
securitySchemes
sección y un esquema de tipoapiKey
. Por ejemplo:"securitySchemes": { "apiKeyHeader": { "type": "apiKey", "name": "x-api-key", "in": "header" } }
Normalmente, solo es necesario actualizar el
name
campo , que corresponde al nombre dekey
en la conexión. Si los esquemas de seguridad incluyen varios esquemas, se recomienda mantener solo uno de ellos.Actualice la especificación de OpenAPI para incluir una
security
sección:"security": [ { "apiKeyHeader": [] } ]
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.
Cree una conexión
custom keys
para almacenar la clave de API.Vaya al portal de Azure AI Foundry y seleccione el proyecto de IA. Seleccione recursos conectados.
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.
Seleccione claves personalizadas en otros tipos de recursos.
Escriba la siguiente información
- clave:
name
campo del esquema de seguridad. En este ejemplo debería serx-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.
- clave:
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:
Habilite el servicio Azure AI, ya que su agente tiene
system assigned managed identity
habilitado.Cree un recurso del servicio al que desea conectarse a través de la especificación de OpenAPI.
Asigne el acceso adecuado al recurso.
Haga clic en Control de acceso para el recurso.
Haga clic en Agregar y agregue la asignación de roles en la parte superior de la pantalla.
Seleccione la asignación de roles adecuada, suele requerir al menos el rol LECTOR. A continuación, haga clic en Siguiente.
Seleccione Identidad administrada y, a continuación, haga clic en Seleccionar miembros.
En el menú desplegable identidad administrada, busque servicios de Azure AI y, a continuación, seleccione el servicio de IA del agente.
Haga clic en Finalizar
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.