Como usar o Serviço do Foundry Agent com Ferramentas Especificadas para OpenAPI (clássico)

Agora você pode conectar seu agente de IA 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 (Microsoft Entra ID) 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. As 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 ao 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. Possui 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 custom keys conexão para armazenar sua chave de API.

   1. Vá para o portal Microsoft Foundry e selecione Management center 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.

      Nota

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

      

   4. Selecione chaves personalizadas em outros tipos de recurso.

      

   5. Insira as informações a seguir

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

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

      • value: 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. Basta verificar se, no código de exemplo abaixo, o projeto para o qual você inseriu 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 (Microsoft Entra ID)

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 Microsoft Entra ID, 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 Foundry Tool que seu agente usa manipula a autenticação.

Ao configurar a autenticação de identidade gerenciada, você precisa fornecer um valor para 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:

• Foundry Tools (anteriormente Serviços de IA do Azure ou Cognitive Services): https://cognitiveservices.azure.com/
• APIs Azure Resource Manager: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• APIs personalizadas registradas em Microsoft Entra ID: use o URI da ID Application encontrado 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.

   captura de tela

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 o 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 por Foundry Tools e selecione a Ferramenta Foundry 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.