Partilhar via

Importar uma API de agente A2A (pré-visualização)

APLICA-SE A: Basic v2 | Padrão v2 | Premium v2

A Gestão de APIs suporta a gestão de APIs de agentes de IA compatíveis com a especificação do protocolo Agent2Agent (A2A). O protocolo A2A é um padrão aberto cliente-servidor que permite que diferentes sistemas de agentes de IA comuniquem e trabalhem em conjunto através de um modelo de interação partilhada. Com o suporte para APIs de agentes A2A na Gestão de APIs, pode gerir e governar APIs de agentes juntamente com outros tipos de APIs, incluindo APIs de modelos de IA, ferramentas de Protocolo de Contexto de Modelo (MCP) e APIs tradicionais como REST, SOAP e GraphQL.

Observação

Esta funcionalidade está em pré-visualização e tem algumas limitações.

Saiba mais sobre como gerenciar APIs de IA no Gerenciamento de API:

Capacidades chave

Quando importa uma API de agente A2A, a Gestão de APIs fornece as seguintes funcionalidades:

  • Medeia operações em tempo de execução JSON-RPC para o backend A2A.
    • Permite governação e controlo de tráfego através de políticas.
    • Quando a observabilidade através do Application Insights está ativada, adiciona os seguintes atributos específicos de A2A para cumprir a convenção semântica GenAI da OpenTelemetry:
      • genai.agent.id - Definir para o ID do agente configurado nas definições da API
      • genai.agent.name- Definir o nome da API nas configurações da API
  • Expõe a carta agente com as seguintes transformações:
    • Substitui o nome de host pelo nome de host da instância de Gestão de APIs.
    • Define o protocolo de transporte preferido para JSON-RPC.
    • Remove todas as outras interfaces em additionalInterfaces.
    • Reescreve os requisitos de segurança para incluir o requisito da chave de subscrição de Gestão de APIs.

Pré-requisitos

Importar a API do agente A2A usando o portal

Utilize os seguintes passos para importar uma API de agente A2A para a API Management.

  1. No portal do Azure, vá para sua instância de Gerenciamento de API.

  2. No menu à esquerda, em APIs, selecione APIs>+ Add API.

  3. Selecione a peça Agente A2A.

    Captura de ecrã da seleção do mosaico da API do agente A2A no portal.

  4. Em Cartão de Agente, introduza a URL que aponta para o documento JSON do cartão de agente. Selecione Avançar.

  5. Na página Criar uma API de agente A2A , configure as definições da API.

    1. Se o URL de runtime e ID do agente não forem configurados automaticamente com base no cartão do agente, forneça então o URL de runtime das operações de JSON-RPC ao seu agente e o ID do agente usado nos traços do OpenTelemetry emitidos pelo agente (gen_ai.agent.id atributo).
    2. Em Definições Gerais da API, introduza um nome de exibição à sua escolha na instância de Gestão de APIs e, opcionalmente, introduza uma Descrição.
    3. Em URL, introduza um caminho base que a sua instância de Gestão de API usa para aceder à API do agente A2A. A Gestão da API apresenta uma URL Base que os clientes podem usar para aceder à API JSON-RPC, e uma URL do cartão do Agente para aceder ao cartão do agente através da API Management.

  6. Selecione Criar para criar a API.

Captura de ecrã da criação de uma API compatível com agente A2A no portal.

Configurar políticas para a API do agente A2A

Configure uma ou mais políticas de Gestão de APIs para ajudar a gerir a API do agente A2A.

Para configurar políticas para a sua API de agente A2A:

  1. No portal do Azure, vá para sua instância de Gerenciamento de API.
  2. No menu à esquerda, em APIs, selecione a sua API de agente A2A.
  3. No menu à esquerda, em A2A, selecione Políticas.
  4. No editor de políticas, adicione ou edite as políticas que pretende aplicar à API do agente A2A. As políticas são definidas em formato XML.

Observação

A Gestão de APIs avalia as políticas configuradas no âmbito global (todas as APIs) antes das políticas no âmbito da API do agente A2A.

Configurar autenticação por chave de subscrição

Nas definições da API A2A, pode opcionalmente configurar a autenticação da chave de subscrição através da API Management. Saiba mais sobre autenticação de chaves de subscrição.

  1. Selecione a API que criou no passo anterior.
  2. Na página de Definições , em Subscrição, selecione (ativar) Subscrição necessária.

Se ativar a autenticação por chave de subscrição, os clientes devem incluir uma chave de subscrição válida no Ocp-Apim-Subscription-Key cabeçalho ou subscription-key no parâmetro de consulta ao chamar a API do agente A2A ou ao aceder ao cartão do agente.

Teste a API do agente A2A

Para garantir que a sua API de agente A2A funciona como esperado, ligue para o backend através da API Management:

  1. Selecione a API que criou no passo anterior.
  2. Na página Visão Geral, copie a base URL de tempo de execução. Use este URL para chamar a API do agente A2A através da API Management.
  3. Configure um cliente de teste ou use uma ferramenta como o curl para fazer um POST pedido ao agente. Se a autenticação por chave de subscrição estiver ativada, inclua um cabeçalho ou parâmetro de consulta com uma chave de subscrição válida no pedido.

Sugestão

De forma semelhante, aceda ao cartão de agente através da Gestão de APIs fazendo um GET pedido à URL do cartão de agente exibida na página de Visão Geral da sua API de agente A2A.

Limitações

  • Esta funcionalidade está atualmente disponível apenas em instâncias de Gestão de API nos níveis v2.
  • Apenas são suportadas APIs de agentes A2A baseadas em JSON-RPC.
  • A desserialização dos órgãos de resposta de saída não é suportada.

Conteúdo relacionado

  • Last updated on