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. Você pode conectar 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

APIs REST podem ser adicionadas a agentes Copilot e agentes personalizados por meio do Copilot Studio.

Os agentes copiloto permitem que um criador combine várias fontes de dados, como conectores, APIs, prompts e fontes de conhecimento em um único agente. Você pode usar esse agente para estender experiências de agente da 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

Alguns pré-requisitos são necessários para expandir as experiências de agente da marca Microsoft com ações de conector.

Para todos os tipos de experiência de agente, é necessário possuir credenciais de criador e uma licença do Copilot Studio.

Você também precisa de uma cópia da especificação OpenAPI, conhecimento do tipo de autenticação necessária e os detalhes de autenticação.

Adicionar uma ação da API REST a um agente

Adicionar uma API REST ao seu agente envolve algumas etapas. As seções a seguir orientam você pelo processo.

O processo para adicionar uma API REST é idêntico para agentes personalizados e Copilot.

Existem algumas etapas no processo.

Adicionar uma ação ao agente

1. vá para a página 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 de 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 uma especificação v3 for enviada, ela será automaticamente convertida para uma especificação v2 durante o processo de criação.

   Depois de carregar a especificação, a tela é atualizada para indicar o nome do arquivo de especificação e os detalhes.

   

   Nas etapas a seguir, baseamos o procedimento em um exemplo específico do SunnyADO, um sistema de gerenciamento de tíquetes 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 selecione Avançar.

   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 na 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. Para obter mais informações sobre o que são soluções, consulte 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 você não vê a solução padrão ou a solução padrão CDS como uma opção neste caso, recomendamos ter uma solução personalizada para facilitar o gerenciamento. Para obter mais informações, consulte: Solução padrão versus solução personalizada.

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

Fornecer detalhes de autenticação

A página Autenticação é exibida para selecionar o tipo de autenticação a ser usado para a API.

1. Selecione um método de autenticação na lista.

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

   • Nenhum: Nenhum outro campo é obrigatório.
   • Chave de API:
     • Parameter Label: um rótulo de texto para o parâmetro API.
     • Nome do parâmetro: um nome de texto para o parâmetro API.
     • Localização do parâmetro: A posição onde o parâmetro pode ser encontrado.
   • Autenticação 2.0:
     • ID do cliente: GUID do cliente para o serviço de destino.
     • Segredo do Cliente – Valor secreto para o cliente. O segredo não é exibido quando o usuário abre o painel de edição depois. No entanto, guarde o segredo, porque você vai precisar dele se optar por fazer mais edições.
     • URL de autorização: URL usada para autorizar o sistema de origem.
     • URL do token: URL onde o token pode ser recuperado.
     • URL de atualização: para qual URL você é redirecionado em um cenário de atualização.
     • Âmbito: A URL de âmbito atribuída à API para aplicações Microsoft Entra.
     • Que organização do Microsoft 365 acede aos pontos finais: Isto limita o acesso à origem apenas à organização do criador ou a todas as organizações.
     • Que aplicação (Cliente) pode utilizar os endpoints: GUID que define o sistema do cliente que pode ser usado para aceder a esses dados. As aplicações podem incluir o Microsoft 365, Power Automatize e outras opções.

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

   Você é apresentado a uma página Selecionar e configurar sua ferramenta de plug-in , onde você pode selecionar ferramentas para habilitar para a API.

   

Selecionar ferramentas para a API

Escolha as ferramentas suportadas pela API para habilitar. Geralmente, uma API REST oferece uma variedade de ferramentas através das várias combinações de endpoint e método HTTP (get, put, post, delete e assim por diante) 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, sua especificação de API pode incluir ações para atualizar e excluir, mas você só deseja que os usuários do seu agente possam criar registros.

1. Selecione uma ferramenta na lista para configurar.

   A página Configurar sua ação de plug-in é exibida.

   

2. Configure a ação selecionada. Tal como acontece com a API geral, é-lhe pedido que 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, assim como a descrição geral da API, deve ser específica o suficiente para fornecer detalhes ao modelo de linguagem para identificar melhor se sua consulta está alinhada com essa 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 fornecidos como parte dos possíveis valores de entrada e saída. Esses valores não podem ser alterados , no entanto, as descrições das entradas e saídas podem ser atualizadas. Todo o conteúdo desta página é extraído diretamente da especificação da API carregada.

4. Preencha os valores conforme necessário para as descrições. As descrições fornecem uma definição de para que os valores são usados. Se alguma das descrições estiver em branco, deve ser preenchida antes de poder avançar. Você pode colar o nome se não tiver 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 ações que deseje incluir neste momento. Quando terminar de adicionar as ferramentas que deseja que seu agente suporte, selecione Avançar.

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

   

Rever e publicar

1. Se precisar fazer atualizações, selecione Voltar e faça as alterações. Caso contrário, selecione Avançar.

   Uma tela é apresentada indicando que sua ferramenta está sendo publicada enquanto o processo está sendo concluído. Você será informado assim que a publicação for concluída.

2. Após a conclusão da publicação, você retornará à tela Escolha uma ferramenta . Aqui você pode adicionar a API REST recém-configurada ao seu agente Copilot ou agente personalizado e concluir a configuração do componente.

   

A ferramenta REST API agora está disponível para uso em seu agente.