Estenda o seu agente com ferramentas de uma REST API (pré-visualização)

[Este artigo é uma documentação de pré-lançamento e está sujeito a alterações.]

Você pode usar APIs REST (incluindo OpenAI API) para conectar um agente criado com sistemas externos e acessar dados disponíveis para uso em seu agente. Pode ligar o seu agente a uma API REST fornecendo ao Copilot Studio três coisas:

• Uma especificação OpenAPI que define as funções da API e as ações disponíveis
• Detalhes sobre o tipo de autenticação necessária e os detalhes de autenticação para que os usuários se conectem à API para acessar o sistema externo
• Descrições para ajudar o modelo de linguagem a determinar quando invocar a API para utilizar os dados

Podes adicionar APIs REST aos agentes Copilot e agentes personalizados através do Copilot Studio.

Os agentes Copilot permitem que um criador combine múltiplas fontes de dados como conectores, APIs, prompts e fontes de conhecimento num único agente. Use este agente para ampliar experiências com a marca Microsoft, como o Microsoft 365 Copilot.

Agentes personalizados são agentes autônomos que contêm conectores, APIs, prompts e fontes de conhecimento. Você pode usar agentes personalizados diretamente, integrando-os em sites ou outros canais.

Pré-requisitos

• Credenciais de nível Maker e licença de Copilot Studio.
• Uma cópia da especificação OpenAPI para a API REST à qual pretende ligar-se
• Conhecimento do tipo de autenticação necessário para se ligar à API e dos detalhes da autenticação.

Adicione uma ferramenta de API REST ao seu agente

Para adicionar uma ferramenta de API REST ao seu agente, complete os seguintes passos:

1. Adicione uma nova ferramenta de agente e selecione a API REST
2. Fornecer especificação, descrição e solução da API
3. Fornecer detalhes de autenticação
4. Selecione ferramentas da API
5. Rever e publicar

As secções seguintes guiam-no pelo processo, passo a passo.

O processo para adicionar uma API REST é o mesmo tanto para agentes personalizados como para agentes Microsoft 365 Copilot.

Adicionar nova ferramenta de agente e selecionar REST API

1. Vá à página de Visão Geral do seu agente.

2. Na seção Ferramentas , selecione Adicionar ferramenta. Você também pode ir para a guia Ferramentas e selecionar Adicionar uma ferramenta.

   A página Adicionar ferramenta é exibida.

3. Selecione Nova ferramenta>API REST.

Fornecer especificação, descrição e solução da API

1. Carregue um arquivo de especificação OpenAPI para a API REST à qual você deseja se conectar. Você pode arrastar e soltar o arquivo de especificação na tela Carregar uma API REST ou navegar no sistema para localizar o arquivo que deseja usar.

   

   Observação

   A especificação OpenAPI deve ser um arquivo JSON no formato v2. Se submeteres uma especificação v3, o processo de criação traduz-a automaticamente para uma especificação v2.

   Depois de carregar a especificação, o ecrã atualiza para mostrar o nome do ficheiro da especificação e os detalhes.

   

   Nos passos seguintes, o procedimento utiliza um exemplo específico do SunnyADO, um sistema de gestão de tickets ADO. No exemplo, a intenção é permitir que os usuários recuperem e atualizem seus tickets por meio do agente.

2. Verifique os detalhes e depois selecione Próximo.

   Você receberá uma página de detalhes do plug-in da API onde poderá fornecer informações adicionais sobre a API.

   

   O campo de descrição é inicialmente preenchido com base na descrição da especificação da API que você carregou. Forneça uma descrição detalhada, pois a orquestração do agente utiliza a descrição para determinar quando usar a ferramenta particular. Forneça detalhes, incluindo sinónimos, para ajudar o seu agente no processo de seleção.

   Por exemplo, a descrição inicial fornecida é: "Um serviço simples para gerenciar tickets".

   Uma descrição melhor é: "Um sistema usado para obter, recuperar, encontrar e exibir bilhetes existentes do SunnyADO. Ele permite que os usuários atualizem, alterem e gerenciem tíquetes para fornecer mais dados para melhorar os registros."

3. Insira uma descrição melhorada no campo Descrição .

4. No menu Solução, uma lista suspensa exibe todas as soluções disponíveis no ambiente atual. Selecione a solução que deseja usar. Saiba mais sobre soluções em Conceitos de Solução.

   

   Se você tiver uma solução preferida ou se o conector selecionado já estiver na solução, essa solução será selecionada automaticamente.

   Você pode selecionar uma solução ou deixá-la em branco. Se deixar a solução em branco, uma solução será criada para si com o nome da ação e o publicador padrão. Armazenar sua ação em uma solução permite movê-la facilmente entre ambientes.

   Observação

   Se não vires a solução padrão ou a solução padrão do CDS como opção neste caso, adiciona uma solução personalizada para facilitar a gestão. Saiba mais sobre Solução padrão vs. solução personalizada.

5. Com uma solução selecionada, selecione Avançar para continuar.

Fornecer detalhes de autenticação

A página de Autenticação aparece. Selecione o tipo de autenticação a usar para a API.

1. Selecione um método de autenticação na lista. Escolha entre três opções:

   • Nenhuma: Não é necessária autenticação para aceder à API.
   • Chave API: Selecione esta opção se a sua API exigir uma chave API para autenticação. Em tempo de execução, quando o agente quer usar a ferramenta API, o agente pede ao utilizador que se autentique. O utilizador fornece uma chave API e o agente liga-se à API usando essa chave.
   • Auth 2.0: Selecione esta opção se o seu servidor MCP usar OAuth 2.0 para autenticação. O OAuth 2.0 permite que utilizadores individuais se autentiquem na API através de um fornecedor de identidade. Este método de autenticação permite ao utilizador conceder permissões à sua aplicação (agente) sem partilhar as suas credenciais com o agente.

2. Introduza os campos obrigatórios para o método de autenticação selecionado. Os campos variam de acordo com o método de autenticação.

   • Nenhum: Nenhuma informação a fornecer.
   • Chave de API:
     • Rótulo de parâmetro: Um rótulo de texto para o parâmetro da API apresentar aos utilizadores.
     • Nome do parâmetro: O nome real do parâmetro da chave API a usar no cabeçalho ou na cadeia de consulta.
     • Localização de parâmetros: Como envia a chave para a API. Selecione Cabeçalho ou Consulta.
   • Autenticação 2.0:
     • ID do cliente: o identificador do cliente que o provedor de identidade emite quando você registra seu aplicativo. O ID do cliente permite que o provedor de identidade saiba qual aplicativo está fazendo a solicitação.
     • Segredo do cliente: o segredo do cliente que o provedor de identidade emite quando você registra seu aplicativo. Seu agente envia o segredo do cliente junto com o ID do cliente para provar que seu agente está autorizado a solicitar tokens de acesso para o servidor MCP.
     • URL de autorização: o ponto final do fornecedor de identidade para onde o seu agente redireciona o utilizador para iniciar sessão e conceder permissões ao seu agente (cartão de consentimento apresentado no chat do agente). O usuário se autentica aqui e, em seguida, o provedor de identidade responde de volta ao agente na URL de retorno de chamada com um código de autorização.
     • URL do Token: O endpoint onde o seu agente troca o código de autorização (ou token de atualização) por um token de acesso e token de atualização. O token de acesso permite que o agente use o servidor MCP em nome do usuário. Os tokens de atualização permitem que o seu agente obtenha novos tokens de acesso e de atualização a partir do ponto final de atualização quando o token de acesso anterior expira.
     • URL de atualização: o endpoint para solicitar um novo token de acesso usando um token de renovação (para que o usuário não precise entrar novamente quando o token expirar).
     • Âmbito: (Opcional): As permissões que a sua aplicação está a pedir, como uma lista separada por espaço.
     • Que organização Microsoft 365 acede aos endpoints: Esta definição limita o acesso à origem à organização do autor ou a todas as organizações. Selecione uma das seguintes opções:
       • Apenas a minha organização
       • Alguma Microsoft 365 organização
     • Qual a aplicação (cliente) que pode usar os endpoints: GUID que define o sistema cliente que pode ser usado para aceder a estes dados. As aplicações podem incluir Microsoft 365, Power Automate e outras opções.

3. Quando preencher todos os campos, selecione Próximo.

   A página Selecionar e configurar a sua ferramenta aparece onde pode selecionar ferramentas para ativar a partir da API.

   

Selecione ferramentas da API

Selecione as ferramentas suportadas pela API da API REST para adicionar ao seu agente. Geralmente, uma API REST oferece uma variedade de ferramentas através das várias combinações de métodos endpoint e HTTP (get, get, post, delete, etc.) definidas na especificação da API. Em alguns casos, talvez você não queira que os usuários do agente tenham a capacidade de executar todas as ações que a API geralmente oferece. Por exemplo, a especificação da tua API pode incluir a possibilidade de atualizar e eliminar, mas só queres que os utilizadores do teu agente consigam criar registos.

1. Selecione uma ferramenta na lista para configurar.

   A página Configurar a sua ferramenta é exibida.

   

2. Configure o nome e a descrição da ferramenta selecionada. Semelhante à API geral, forneça um nome e uma descrição da Ferramenta. As descrições são inicialmente pré-preenchidas a partir das descrições na especificação da API. O nome não precisa ser exclusivo, mas deve representar a ferramenta em si. A descrição, tal como a descrição geral da API, deve ser suficientemente específica para fornecer ao modelo de linguagem detalhes que permitam melhor identificar se a sua consulta está alinhada com esta ferramenta específica.

3. Quando os campos estiverem preenchidos, selecione Avançar.

   A página Revisar os parâmetros da ferramenta é exibida.

   

   Esta página mostra os valores esperados para a entrada e os valores de saída que são devolvidos. Não podes alterar esses valores, mas podes atualizar as descrições das entradas e saídas. Todo o conteúdo desta página é extraído diretamente da especificação da API carregada.

4. Atualize as descrições conforme necessário. As descrições fornecem uma definição de para que os valores são usados. Se alguma das descrições estiver em branco, deve completá-las antes de poder avançar. Podes colar o nome se não tiveres uma descrição melhor.

5. Depois de concluir as descrições, selecione Avançar.

   A primeira ferramenta está agora configurada e aparece na lista de Ferramentas selecionadas na página Selecionar e configurar a ferramenta do plugin .

   

6. Adicione quaisquer outras ferramentas da API que deseje incluir neste momento. Quando terminares de adicionar as ferramentas que queres que o teu agente apoie, seleciona Próximo.

   A página Rever a ferramenta é apresentada. A página fornece os detalhes da ferramenta REST API configurada.

   

Rever e publicar

1. Se precisares de fazer atualizações, seleciona Voltar e faz as tuas alterações. Caso contrário, selecione Avançar.

   Aparece um ecrã a indicar que a sua ferramenta está a ser publicada enquanto o processo está em andamento. Você será informado assim que a publicação for concluída.

2. Selecione Criar ligação para continuar. É redirecionado para o ecrã Adicionar ferramenta.

3. Selecione a API REST no seletor de tipos de ferramenta. Pode ver as ferramentas recém-criadas a partir da sua API. Deverá haver uma entrada por cada ferramenta que adicionaste da API.

4. Para cada uma das ferramentas recém-configuradas da API, crie ou selecione uma ligação à API e adicione a ferramenta ao seu agente:

   1. No ecrã Adicionar ferramenta , selecione a ferramenta.
   2. Em Ligação, selecione uma ligação existente ou selecione Criar nova ligação.
   3. Introduza qualquer informação necessária para a ligação e depois selecione Criar para criar a ligação à ferramenta.
   4. Selecione Adicionar e configurar para adicionar a ferramenta ao seu agente.

   

As ferramentas da API REST estão agora disponíveis para uso no seu agente.