Como usar o Foundry Agent Service com as Ferramentas Especificadas OpenAPI (clássico)

Agora pode ligar o seu Azure AI Agent a uma API externa usando uma ferramenta especificada pela OpenAPI 3.0, permitindo interoperabilidade escalável com várias aplicações. Ao usar 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 a sua experiência de chamada de funções ao fornecer integrações de API padronizadas, automatizadas e escaláveis que aumentam as capacidades 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 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 os esquemas de segurança da 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 só precisas de atualizar o name campo, que corresponde ao nome de key na ligação. Se os esquemas de segurança incluírem múltiplos esquemas, mantenha apenas um deles.

2. Atualize a sua especificação OpenAPI para incluir uma security secçã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. Cria uma custom keys ligação para guardar a tua chave API.

   1. Vai ao portal Microsoft Foundry e seleciona Centro de gestão no painel de navegação esquerdo.

      

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

   3. Selecionar + nova ligação na página de definições.

      Nota

      Se regenerares a chave API numa data posterior, precisas de atualizar a ligação com a nova chave.

      

   4. Selecione chaves personalizadasnoutros tipos de recursos.

      

   5. Introduza a seguinte informação

      • Chave: name campo do seu esquema de segurança. Neste exemplo, deveria 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. Só tens de garantir que, no código de exemplo abaixo, o projeto para o qual introduziste cadeia de ligação tem acesso a essa ligação.

5. Depois de criares uma ligação, usa-a através do SDK ou da API REST. Use os separadores no topo deste artigo para ver exemplos de código.

Autenticar com identidade gerida (Microsoft Entra ID)

Microsoft Entra ID é um serviço de gestão de identidade e acessos baseado na cloud que os seus colaboradores podem usar para aceder a 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 de fornecer um valor de Audiência. 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 típicos do público-alvo:

• Foundry Tools (anteriormente Serviços de IA do Azure ou Serviços Cognitivos): 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 a URI do ID da Aplicação encontrada no registo da 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 . Depois seleciona Próximo.

   4. Selecione Identidade Gerida e depois selecione membros.

   5. No menu suspenso de identidade gerida, procure por Ferramentas Foundry e depois selecione a Ferramenta Foundry do seu agente.

   6. Selecionar Acabamento.

4. Depois de concluir a configuração, pode usar a ferramenta através do portal Foundry, SDK ou API REST. Use os separadores no topo deste artigo para ver exemplos de código.