Como usar o Serviço de Agente Foundry com Ferramentas Especificadas pela OpenAPI

Agora pode ligar o seu Azure AI Agent a uma API externa usando uma ferramenta especificada pelo OpenAPI 3.0, permitindo interoperabilidade escalável com várias aplicações. Ao utilizar identidades geridas (Microsoft Entra ID) para autenticação, pode ativar de forma segura as suas ferramentas personalizadas para autenticar acessos e ligações. Esta abordagem é ideal para integrar com infraestruturas ou serviços web existentes.

A ferramenta OpenAPI Specified melhora sua experiência de chamada de função fornecendo integrações de API padronizadas, automatizadas e escaláveis que aprimoram os recursos e a eficiência do seu agente. As especificações OpenAPI fornecem um padrão formal para descrever APIs HTTP. Este padrão ajuda as pessoas a compreender como funciona uma API, como uma sequência de APIs funciona em conjunto, e suporta a geração de código do cliente, a criação de testes, a aplicação de padrões de design e muito mais. Atualmente, as ferramentas especificadas pela OpenAPI 3.0 suportam três tipos de autenticação: anonymous, API key, e managed identity.

Suporte de utilização

Pré-requisitos

1. Certifique-se de que cumpre os pré-requisitos e os passos de configuração no quickstart.
2. Verifique a especificação do OpenAPI para os seguintes requisitos:
   1. Embora não seja exigido pela especificação OpenAPI, cada função deve ter um operationId para funcionar com a ferramenta OpenAPI.
   2. O operationId deve conter apenas letras, - e _. Pode modificá-lo para cumprir este requisito. Use um nome descritivo para ajudar os modelos a decidir eficientemente qual a função a utilizar.

Autenticar com chave de API

Ao usar autenticação por chave API, pode autenticar a sua especificação OpenAPI por diferentes métodos, como uma chave API ou token Bearer. Cada especificação OpenAPI suporta apenas um esquema de segurança de chave API. Se precisares de múltiplos esquemas de segurança, cria várias ferramentas de especificação OpenAPI.

1. Atualize seus esquemas de segurança de especificação OpenAPI. Tem uma securitySchemes secção e um esquema de tipo apiKey. Por exemplo:

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   Normalmente, você só precisa atualizar o name campo, que corresponde ao nome de key na conexão. Se os esquemas de segurança incluírem múltiplos esquemas, mantenha apenas um deles.

2. Atualize suas especificações OpenAPI para incluir uma security seção:

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. Remova qualquer parâmetro na especificação OpenAPI que necessite de chave API, porque a chave API é armazenada e passada através de uma ligação, conforme descrito mais adiante neste artigo.

4. Crie uma custom keys conexão para armazenar sua chave de API.

   1. Vá ao portal Microsoft Foundry e selecione Centro de Gestão no painel de navegação esquerdo.

      

   2. Selecione Recursos Conectados no projeto IA no painel de navegação esquerdo.

   3. Selecione + nova conexão na página de configurações.

      Observação

      Se você regenerar a chave da API em uma data posterior, precisará atualizar a conexão com a nova chave.

      

   4. Selecione chaves personalizadas em outros tipos de recursos.

      

   5. Introduza as seguintes informações

      • Chave: name campo do seu esquema de segurança. Neste exemplo, deve ser x-api-key

        "securitySchemes": {
            "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
        

      • Valor: YOUR_API_KEY

      • Nome da ligação: YOUR_CONNECTION_NAME (Usa este nome de ligação no código de exemplo abaixo.)

      • Acesso: pode escolher apenas este projeto ou partilhado com todos os projetos. Apenas certifique-se de que, no código de exemplo abaixo, o projeto para o qual você inseriu a cadeia de conexão tenha acesso a essa conexão.

5. Depois de criares uma ligação, usa-a através do SDK ou da API REST. Use as guias na parte superior deste artigo para ver exemplos de código.

Autenticar com identidade gerida (Microsoft Entra ID)

O Microsoft Entra ID é um serviço de gerenciamento de identidade e acesso baseado em nuvem que seus funcionários podem usar para acessar recursos externos. Ao usar o Microsoft Entra ID, pode adicionar segurança extra ao autenticar as suas APIs sem precisar de usar chaves de API. Depois de configurar a autenticação de identidade gerida, a ferramenta Foundry que o seu agente utiliza trata da autenticação.

Ao configurar a autenticação de identidade gerida, precisa fornecer um valor de Audience. O público é o identificador de recurso OAuth2 (também chamado de URI de âmbito ou ID de aplicação) que identifica a que API ou serviço a identidade gerida pode acedecer.

Valores comuns do público:

• Foundry Tools (anteriormente Azure AI Services ou Cognitive Services): https://cognitiveservices.azure.com/
• Azure Resource Manager APIs: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• APIs personalizadas registadas no Microsoft Entra ID: Use o URI do ID da Aplicação encontrado no registo de aplicação da API

Para configurar a autenticação usando Identidade Gerida:

1. Certifica-te de que o teu recurso Foundry tem uma identidade gerida atribuída ao sistema ativada.

   

2. Cria um recurso para o serviço ao qual queres ligar-te através da especificação OpenAPI.

3. Atribui o acesso adequado ao recurso.

   1. Selecione Controlo de Acesso para o seu recurso.

   2. Selecione Adicionar e depois adicione atribuição de função no topo do ecrã.

      

   3. Selecione a atribuição adequada de função necessária. Normalmente, requer pelo menos o papel de LEITOR . Em seguida, selecione Seguinte.

   4. Selecione Identidade Gerida e depois selecione membros selecionados.

   5. No menu suspenso de identidade gerida, procure Ferramentas de Fundição e depois selecione as Ferramentas de Fundição do seu agente.

   6. Selecione Concluir.

4. Depois de concluir a configuração, pode usar a ferramenta através do portal Foundry, SDK ou API REST. Use as guias na parte superior deste artigo para ver exemplos de código.