Como usar o Serviço do Foundry Agent com ferramentas especificadas do OpenAPI

Agora você pode conectar seu Agente de IA do Azure a uma API externa usando uma ferramenta especificada do OpenAPI 3.0, permitindo a interoperabilidade escalonável com vários aplicativos. Usando identidades gerenciadas (ID do Microsoft Entra) para autenticação, você pode habilitar com segurança suas ferramentas personalizadas para autenticar o acesso e as conexões. Essa abordagem é ideal para a integração com a infraestrutura ou os serviços Web existentes.

A ferramenta Especificada do OpenAPI melhora sua experiência de chamada de função fornecendo integrações de API padronizadas, automatizadas e escalonáveis que aprimoram os recursos e a eficiência do agente. Especificações OpenAPI fornecem um padrão formal para descrever APIs HTTP. Esse padrão ajuda as pessoas a entender como uma API funciona, como uma sequência de APIs funciona em conjunto e dá suporte à geração de código do cliente, à criação de testes, à aplicação de padrões de design e muito mais. Atualmente, as ferramentas especificadas do OpenAPI 3.0 dão suporte a três tipos de autenticação: anonymous, API keye managed identity.

Suporte de uso

Pré-requisitos

1. Verifique se você concluiu os pré-requisitos e as etapas de instalação no início rápido.
2. Verifique a especificação OpenAPI para obter os seguintes requisitos:
   1. Embora não seja exigido pela especificação OpenAPI, cada função deve ter um operationId para trabalhar com a ferramenta OpenAPI.
   2. O operationId deve conter apenas letras, -e _. Você pode modificá-lo para atender a esse requisito. Use um nome descritivo para ajudar os modelos a decidir com eficiência qual função usar.

Autenticar com a chave de API

Usando a autenticação de chave de API, você pode autenticar sua especificação OpenAPI por meio de métodos diferentes, como uma chave de API ou um token de portador. Cada especificação OpenAPI dá suporte a apenas um esquema de segurança de chave de API. Se você precisar de vários esquemas de segurança, crie várias ferramentas de especificação OpenAPI.

1. Atualize os esquemas de segurança de especificação do OpenAPI. Ele tem uma seção securitySchemes e um esquema do 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 da key conexão. Se os esquemas de segurança incluirem vários esquemas, mantenha apenas um deles.

2. Atualize sua especificação OpenAPI para incluir uma security seção:

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

3. Remova qualquer parâmetro na especificação OpenAPI que precise de chave de API, pois a chave de API é armazenada e passada por uma conexão, conforme descrito posteriormente neste artigo.

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

   1. Acesse o portal do Microsoft Foundry e selecione o Centro de Gerenciamento no painel de navegação esquerdo.

      

   2. Selecione Recursos conectados no projeto de 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 de API posteriormente, precisará atualizar a conexão com a nova chave.

      

   4. Selecione chaves personalizadas em outros tipos de recurso.

      

   5. Inserir as seguintes informações

      • chave: campo name 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 conexão: YOUR_CONNECTION_NAME (você usa esse nome de conexão no código de exemplo abaixo.)

      • Acesso: você pode escolher somente este projeto ou compartilhado com todos os projetos. Apenas verifique se, no código de exemplo abaixo, o projeto para o qual você inseriu a cadeia de conexão tem acesso a essa conexão.

5. Depois de criar uma conexão, use-a por meio do SDK ou da API REST. Use as guias na parte superior deste artigo para ver exemplos de código.

Autenticar com identidade gerenciada (ID do Microsoft Entra)

O Microsoft Entra ID é um serviço de gerenciamento de acesso e identidade baseado em nuvem que seus funcionários podem usar para acessar recursos externos. Usando a ID do Microsoft Entra, você pode adicionar segurança extra ao autenticar suas APIs sem precisar usar chaves de API. Depois de configurar a autenticação de identidade gerenciada, a ferramenta Foundry que o agente usa gerencia a autenticação.

Ao configurar a autenticação de identidade gerenciada, você precisa fornecer um valor Audience. O público-alvo é o identificador de recurso OAuth2 (também chamado de escopo ou URI de ID do aplicativo) que identifica qual API ou serviço a identidade gerenciada pode acessar.

Valores comuns de audiência:

• Ferramentas de Fundação (anteriormente serviços de IA do Azure ou Serviços Cognitivos): https://cognitiveservices.azure.com/
• APIs do Azure Resource Manager: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• APIs personalizadas registradas no Microsoft Entra ID: use a URI do ID do Aplicativo encontrada no registro de aplicativo da API

Para configurar a autenticação usando a Identidade Gerenciada:

1. Verifique se o recurso Foundry tem uma identidade gerenciada atribuída pelo sistema habilitada.

   

2. Crie um recurso para o serviço ao qual você deseja se conectar por meio da especificação OpenAPI.

3. Atribua o acesso adequado ao recurso.

   1. Selecione Controle de Acesso para seu recurso.

   2. Selecione Adicionar e, em seguida, adicione a atribuição de função na parte superior da tela.

      

   3. Selecione a atribuição de função adequada necessária. Normalmente, ele requer pelo menos a função READER . Em seguida, selecione Avançar.

   4. Selecione Identidade Gerenciada e selecione membros.

   5. No menu suspenso de identidade gerenciada, pesquise Foundry Tools e selecione a Foundry Tool do seu agente.

   6. Selecione Concluir.

4. Depois de concluir a instalação, você pode usar a ferramenta por meio do portal do Foundry, do SDK ou da API REST. Use as guias na parte superior deste artigo para ver exemplos de código.