Compartir vía

Importación de una API de agente de A2A (versión preliminar)

SE APLICA A: Básico v2 | Estándar v2 |Premium v2

API Management admite la administración de las API del agente de IA compatibles con la especificación del protocolo Agent2Agent (A2A). El protocolo A2A es un estándar de servidor cliente abierto que permite que diferentes sistemas de agentes de IA se comuniquen y trabajen juntos mediante un modelo de interacción compartida. Con la compatibilidad con la API del agente A2A en API Management, puede administrar y controlar las API del agente junto con otros tipos de API, incluidas las API de modelo de IA, las herramientas del Protocolo de contexto de modelo (MCP) y las API tradicionales, como REST, SOAP y GraphQL.

Nota:

Esta característica está en versión preliminar y tiene algunas limitaciones.

Obtenga más información sobre cómo administrar las API de IA en API Management:

Funcionalidades clave

Al importar una API de agente de A2A, API Management proporciona las siguientes funcionalidades:

  • Gestiona operaciones JSON-RPC en tiempo de ejecución hacia el backend de A2A.
    • Habilita la gobernanza y el control de tráfico mediante directivas.
    • Cuando la observabilidad a través de Application Insights está habilitada, agrega los siguientes atributos específicos de A2A para cumplir con la convención semántica de OpenTelemetry GenAI:
      • genai.agent.id: se establece en el identificador del agente configurado en la configuración de la API
      • genai.agent.name: se establece en el nombre de la API en la configuración de la API.
  • Expone la tarjeta del agente con las siguientes transformaciones:
    • Reemplaza el nombre de host por el nombre de host de la instancia de API Management.
    • Establece el protocolo de transporte preferido en JSON-RPC.
    • Quita todas las demás interfaces de additionalInterfaces.
    • Vuelve a escribir los requisitos de seguridad para incluir el requisito de clave de suscripción de API Management.

Prerrequisitos

  • Una instancia existente de API Management. Créelo si aún no lo ha hecho.

  • Un agente A2A existente con operaciones JSON-RPC y una tarjeta de agente.

Importación de la API del agente de A2A mediante el portal

Siga estos pasos para importar una API de agente de A2A a API Management.

  1. En Azure Portal, vaya a la instancia de API Management.

  2. En el menú de la izquierda, en API, seleccioneAPI >+ Agregar API.

  3. Seleccione el mosaico Agente A2A.

    Captura de pantalla de la selección del icono de API del agente de A2A en el portal.

  4. En Tarjeta del agente, escriba la dirección URL que apunta al documento JSON de la tarjeta del agente. Seleccione Siguiente.

  5. En la página Crear una API de agente de A2A , configure las opciones de API.

    1. Si la dirección URL del entorno de ejecución y el identificador del agente no se configuran automáticamente en función de la tarjeta del agente, proporcione la dirección URL en tiempo de ejecución de las operaciones de JSON-RPC al agente y el identificador de agente usado en los seguimientos de OpenTelemetry emitidos por el agente (gen_ai.agent.id atributo).
    2. En Configuración de API general, escriba un nombre para mostrar de su elección en la instancia de API Management y, opcionalmente, escriba una descripción.
    3. En DIRECCIÓN URL, escriba una ruta de acceso base que use la instancia de Administración de API para acceder a la API del agente de A2A. API Management muestra una dirección URL base que los clientes pueden usar para acceder a la API de JSON-RPC y una dirección URL de tarjeta del agente para acceder a la tarjeta del agente a través de API Management.

  6. Seleccione Crear para crear la API.

Captura de pantalla de la creación de una API compatible con agente A2A en el portal.

Configuración de directivas para la API del agente de A2A

Configure una o varias directivas de API Management para facilitar la administración de la API del agente de A2A.

Para configurar directivas para la API del agente de A2A:

  1. En Azure Portal, vaya a la instancia de API Management.
  2. En el menú de la izquierda, en API, seleccione la API del agente de A2A.
  3. En el menú izquierdo, en A2A, seleccione Directivas.
  4. En el editor de directivas, agregue o edite las directivas que quiere aplicar a la API del agente de A2A. Las directivas se definen en formato XML.

Nota:

API Management evalúa las directivas configuradas en el ámbito global (todas las API) antes de las directivas en el ámbito de la API del agente de A2A.

Configuración de la autenticación de clave de suscripción

En la configuración de la API de A2A, puede configurar opcionalmente la autenticación de clave de suscripción mediante API Management. Obtenga más información sobre la autenticación de clave de suscripción.

  1. Seleccione la API que creó en los pasos anteriores.
  2. En la página Configuración , en Suscripción, seleccione (habilitar) Suscripción necesaria.

Si habilita la autenticación de clave de suscripción, los clientes deben incluir una clave de suscripción válida en el Ocp-Apim-Subscription-Key encabezado o subscription-key el parámetro de consulta al llamar a la API del agente de A2A o acceder a la tarjeta del agente.

Prueba de la API del agente de A2A

Para asegurarse de que la API del agente de A2A funciona según lo previsto, llame al back-end a través de API Management:

  1. Seleccione la API que creó en los pasos anteriores.
  2. En la página Información general , copie la dirección URL base del entorno de ejecución. Use esta dirección URL para llamar a la API del agente de A2A mediante API Management.
  3. Configure un cliente de prueba o use una herramienta como curl para realizar una POST solicitud al agente. Si la autenticación de clave de suscripción está habilitada, incluya un encabezado de clave de suscripción o un parámetro de consulta válidos en la solicitud.

Sugerencia

De forma similar, acceda a la tarjeta del agente a través de API Management realizando una GET solicitud a la dirección URL de la tarjeta del agente que se muestra en la página Información general de la API del agente de A2A.

Limitaciones

  • Esta característica solo está disponible actualmente en instancias de API Management en los niveles v2.
  • Solo se admiten las API del agente A2A basadas en JSON-RPC.
  • No se admite la deserialización de los cuerpos de respuesta salientes.

Contenido relacionado

  • Last updated on