Estender seu agente com ferramentas de uma API REST (versão prévia)

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

Você pode usar APIs REST (inclusive API da OpenAI) para conectar um agente criado com sistemas externos e ter acesso a dados disponíveis a serem usados no agente. Você pode conectar o agente a uma API REST fornecendo três coisas ao Copilot Studio:

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

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

Os agentes do Copilot 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.

Os 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 a sites ou outros canais.

Pré-requisitos

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

Para todos os tipos de experiência do agente, você deve ter credenciais no nível de criador e uma licença do Copilot Studio.

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

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

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

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

Há algumas etapas no processo.

Adicionar uma ação ao agente

1. vá para a página Visão geral do agente.

   

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

   A página Adicionar ferramenta é exibida.

3. SelecioneNova ferramenta>API REST.

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

1. Carregue um arquivo de especificação da 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 em seu sistema para localizar o arquivo que deseja usar.

   

   Observação

   A especificação da OpenAPI deve ser um arquivo JSON em formato v2. Se uma especificação v3 for enviada, ela será automaticamente convertida em 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 que se seguem, baseamos o procedimento em um exemplo específico do SunnyADO, um sistema de gerenciamento de tíquetes do ADO. No exemplo, a intenção é permitir que os usuários recuperem e atualizem seus tíquetes por meio do agente.

2. Verifique os detalhes e selecione Próximo.

   É apresentada uma página de Detalhes do plugin da API onde você pode fornecer informações adicionais sobre a API.

   

   O campo de descrição é inicialmente preenchido com base na descrição na especificação da API carregada. Dê uma descrição detalhada, pois a orquestração do agente usa essa descrição para determinar quando usar a ferramenta em especial. Forneça detalhes, incluindo sinônimos, para ajudar seu agente com o processo de seleção.

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

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

3. Informe uma descrição aprimorada no campo Descrição.

4. Em Solução, um menu suspenso lista 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 da 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 você deixar a solução em branco, uma solução será criada para você com o nome da ação e o editor padrão. Armazenar sua ação em uma solução permite movê-la facilmente entre ambientes.

   Observação

   Se você não vir 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 vs. solução personalizada.

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

Forneça 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 que são obrigatórios para o método de autenticação. Os campos variam, conforme o método de autenticação.

   • Nenhum: nenhum outro campo é obrigatório.
   • Chave API:
     • Rótulo do parâmetro: um rótulo de texto para o parâmetro da API.
     • Nome do parâmetro: um nome de texto para o parâmetro da 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 posteriormente. No entanto, guarde o segredo, porque você 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.
     • Escopo: a URL do escopo atribuída à API para aplicativos Microsoft Entra.
     • Qual organização do Microsoft 365 tem acesso aos pontos de extremidade: isso limita o acesso à origem à organização do criador ou a todas as organizações.
     • Qual aplicativo (Cliente) pode usar os pontos de extremidade: GUID que define o sistema cliente que pode ser usado para acessar esses dados. Entre os aplicativos podem estar Microsoft 365, Power Automate e outras opções.

3. Depois que todos os campos forem preenchidos, selecione Avançar.

   Você verá uma página Selecionar e configurar sua ferramenta de plug-in na qual poderá selecionar as ferramentas a serem habilitadas para a API.

   

Selecionar ferramentas para a API

Escolha as ferramentas compatíveis com a API para habilitar. Geralmente, uma API REST oferece uma variedade de ferramentas por meio das várias combinações de endpoint e método HTTP (get, put, post, delete e assim por diante) definidos 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 de seu agente possam criar registros.

1. Selecione uma ferramenta na lista a ser configurada.

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

   

2. Configurar a ação selecionada. Assim como acontece com a API geral, você deve fornecer um nome de ferramenta e uma descrição da ferramenta. As descrições são inicialmente preenchidas a partir das descrições na especificação da API. O nome não precisa ser exclusivo, mas deve representar a própria ferramenta. A descrição, assim como na descrição geral da API, deve ser específica o suficiente para fornecer ao modelo de linguagem detalhes para identificar melhor se sua consulta está alinhada com essa ferramenta específica.

3. Depois que os campos forem preenchidos, selecione Avançar.

   A página Examinar 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ção 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 do que os valores são usados. Se qualquer uma das descrições estiver em branco, elas deverão ser concluídas antes que você possa 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 agora está configurada e aparece na lista de ferramentas selecionadas na página Selecionar e configurar sua ferramenta de plug-in .

   

6. Adicione quaisquer outras ações que você deseja incluir no momento. Depois de terminar de adicionar ferramentas que deseja que o agente dê suporte, selecione Avançar.

   A página Examinar sua ferramenta é exibida. A página fornece os detalhes da ferramenta de API REST configurada.

   

Examinar e publicar

1. Se você precisar fazer atualizações, poderá selecionar Voltar e fazer as alterações. Caso contrário, selecione Próximo.

   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ê será retornado para a tela Escolher uma ferramenta . Aqui você pode adicionar a API REST recém-configurada ao agente do Copilot ou agente personalizado e concluir a configuração do componente.

   

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