Compartilhar via

Importar uma API de agente A2A (versão prévia)

APLICA-SE A: Básico v2 | Standard v2 | Premium v2

O Gerenciamento de API dá suporte ao gerenciamento de APIs de agente de IA compatíveis com a especificação de protocolo Agent2Agent (A2A). O protocolo A2A é um padrão de cliente-servidor aberto que permite que diferentes sistemas de agente de IA se comuniquem e trabalhem juntos usando um modelo de interação compartilhado. Com o suporte à API do agente A2A no Gerenciamento de API, você pode gerenciar e controlar APIs de agente juntamente com outros tipos de API, incluindo APIs de modelo de IA, ferramentas mcp (protocolo de contexto de modelo) e APIs tradicionais, como REST, SOAP e GraphQL.

Observação

Esse recurso está em versão prévia e tem algumas limitações.

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

Principais capacidades

Quando você importa uma API de agente A2A, o Gerenciamento de API fornece os seguintes recursos:

  • Media as operações de runtime JSON-RPC para o back-end A2A.
    • Habilita a governança e o controle de tráfego usando políticas.
    • Quando a observabilidade por meio do Application Insights está habilitada, adiciona os seguintes atributos específicos para A2A para cumprir a convenção semântica do OpenTelemetry GenAI:
      • genai.agent.id - Definir como a ID do agente configurada nas configurações da API
      • genai.agent.name- Definir como o nome da API nas configurações da API
  • Expõe o cartão do agente com as seguintes transformações:
    • Substitui o nome do host pelo nome do host da instância de Gerenciamento de API.
    • Define o protocolo de transporte preferencial como JSON-RPC.
    • Remove todas as outras interfaces em additionalInterfaces.
    • Reescreve os requisitos de segurança para incluir o requisito de chave de assinatura do Gerenciamento de API.

Pré-requisitos

  • Uma instância de Gerenciamento de API existente. Crie uma, se ainda não tiver.

  • Um agente A2A existente com operações JSON-RPC e um cartão de agente.

Importar a API do agente A2A usando o portal

Use as etapas a seguir para importar uma API de agente A2A para o Gerenciamento de API.

  1. No portal do Azure, acesse sua instância de Gerenciamento de API.

  2. No menu do lado esquerdo, em APIs, selecione APIs>+ Adicionar API.

  3. Selecione o bloco Agente A2A.

    Captura de tela da seleção do ícone da API do agente A2A no portal.

  4. No cartão do Agente, insira a URL que aponta para o documento JSON do cartão do agente. Selecione Próximo.

  5. Na página Criar uma API do agente A2A , defina as configurações da API.

    1. Se a URL do Runtime e a ID do Agente não forem configuradas automaticamente com base no cartão do agente, forneça a URL de runtime de operações de JSON-RPC para o agente e a ID do agente usada em rastreamentos OpenTelemetry emitidos pelo agente (atributo gen_ai.agent.id).
    2. Em configurações gerais de API, insira um nome de exibição de sua escolha na instância de Gerenciamento de API e, opcionalmente, insira uma Descrição.
    3. Na URL, insira um caminho base que sua instância de Gerenciamento de API usa para acessar a API do agente A2A. O Gerenciamento de API exibe uma URL base que os clientes podem usar para acessar a API de JSON-RPC e uma URL de cartão do Agente para acessar o cartão do agente por meio do Gerenciamento de API.

  6. Selecione Criar para criar a API.

Captura de tela 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 Gerenciamento de API para ajudar a gerenciar a API do agente A2A.

Para configurar políticas para a API do agente A2A:

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

Observação

O Gerenciamento de API avalia as políticas configuradas no escopo global (todas as APIs) antes das políticas no escopo da API do agente A2A.

Configurar a autenticação de chave de assinatura

Nas configurações da API A2A, opcionalmente, você pode configurar a autenticação de chave de assinatura por meio do Gerenciamento de API. Saiba mais sobre a autenticação de chave de assinatura.

  1. Selecione a API que você criou na etapa anterior.
  2. Na página Configurações , em Assinatura, selecione (habilitar) Assinatura necessária.

Se você habilitar a autenticação de chave de assinatura, os clientes deverão incluir uma chave de assinatura válida no Ocp-Apim-Subscription-Key cabeçalho ou subscription-key parâmetro de consulta ao chamar a API do agente A2A ou acessar o cartão do agente.

Testar a API do agente A2A

Para garantir que a API do agente A2A funcione conforme o esperado, chame o back-end por meio do Gerenciamento de API:

  1. Selecione a API que você criou na etapa anterior.
  2. Na página Visão geral , copie a URL base do Runtime. Use essa URL para chamar a API do agente A2A por meio do Gerenciamento de API.
  3. Configure um cliente de teste ou use uma ferramenta como curl para fazer uma POST solicitação ao agente. Se a autenticação de chave de assinatura estiver habilitada, inclua um cabeçalho de chave de assinatura ou parâmetro de consulta válido na solicitação.

Dica

Da mesma forma, acesse o cartão do agente por meio do Gerenciamento de API fazendo uma GET solicitação à URL de cartão do Agente exibida na página Visão geral da API do agente A2A.

Limitações

  • No momento, esse recurso está disponível apenas em instâncias de Gerenciamento de API nas camadas v2.
  • Há suporte apenas para APIs de agente A2A baseadas em JSON-RPC.
  • Não há suporte para a desserialização de corpos de resposta de saída.

Conteúdo relacionado

  • Last updated on