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 seu agente a uma API REST fornecendo Copilot Studio com três coisas:

• 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

Você pode adicionar APIs REST para Copilot agentes e agentes personalizados por meio de Copilot Studio.

Importante

Este artigo contém a documentação de visualização do Microsoft Copilot Studio e está sujeito a alterações.

Os recursos de visualização não são destinados ao uso de produção e podem ter funcionalidade restrita. Esses recursos estão disponíveis antes de um lançamento oficial para que você possa obter acesso antecipado e fornecer comentários.

Se você estiver criando um agente pronto para produção, consulte Microsoft Copilot Studio Visão geral.

Os agentes Copilot permitem a um criador combinar múltiplas fontes de dados, como conectores, APIs, prompts e fontes de conhecimento em um único agente. Use esse agente para estender experiências de agente da marca Microsoft, como 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.

Observação

Você deve criar ferramentas de API REST com base em uma especificação do OpenAPI v2. Esse requisito ocorre devido ao comportamento do Power Platform no processamento de especificações de API. Se você enviar uma especificação v3, o processo de criação o converterá automaticamente em uma especificação v2.

Pré-requisitos

• Credenciais de Maker e uma licença de Copilot Studio.
• Uma cópia da especificação OpenAPI para a API REST à qual você deseja se conectar
• Conhecimento do tipo de autenticação necessário para se conectar à API e dos detalhes da autenticação.

Adicione uma ferramenta de API REST ao seu agente

Para adicionar uma ferramenta de API REST ao agente, conclua as seguintes etapas:

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

As seções seguintes guiam você pelo processo, passo a passo.

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

Adicionar uma nova ferramenta de agente e selecionar a API REST

1. Vá para a página de Visão Geral do seu 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.

Forneça 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 você enviar uma especificação v3, o processo de criação o converterá automaticamente em uma especificação v2.

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

   

   Nas etapas a seguir, o procedimento usa 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 Avançar.

   É 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 que você carregou. 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. 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 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 do CDS como uma opção nesse caso, adicione uma solução personalizada para facilitar o gerenciamento. Saiba mais em Solução padrão versus 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. Selecione o tipo de autenticação a ser usado para a API.

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

   • Nenhuma: Não é necessária autenticação para acessar a API.
   • Chave de API: Selecione esta opção se sua API exigir uma chave de API para autenticação. Em tempo de execução, quando o agente deseja usar a ferramenta da API, ele solicita ao usuário que se autentique. O usuário fornece uma chave de API e o agente se conecta à API usando essa chave.
   • Auth 2.0: Selecione esta opção se seu servidor MCP usar OAuth 2.0 para autenticação. O OAuth 2.0 permite que usuários individuais se autentiquem na API por meio de um provedor de identidade. Esse método de autenticação permite que o usuário conceda permissões ao seu aplicativo (agente) sem compartilhar suas credenciais com o agente.

2. Insira os campos exigidos para o método de autenticação selecionado. Os campos variam, conforme o método de autenticação.

   • Nenhuma: Nenhuma informação a fornecer.
   • Chave API:
     • Rótulo de parâmetro: Um rótulo de texto para o parâmetro da API apresentar aos usuários.
     • Nome do parâmetro: o nome real do parâmetro de chave de API a ser usado na cadeia de caracteres de cabeçalho ou consulta.
     • Local do parâmetro: como você 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 ao registrar seu aplicativo. A 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 a 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 de extremidade do provedor de identidade em que o agente redireciona o usuário para entrar e conceder permissões ao agente (cartão de consentimento apresentado no chat do agente). O usuário é autenticado aqui e, em seguida, o provedor de identidade responde ao agente na URL de retorno de chamada com um código de autorização.
     • URL do token: O endpoint onde 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 seu agente use o servidor MCP em nome do usuário. Os tokens de atualização permitem que seu agente obtenha novo acesso e atualize tokens do ponto de extremidade de atualização quando o token de acesso anterior expirar.
     • URL de Atualização: o ponto de extremidade para solicitar um novo token de acesso usando um token de atualização (para que o usuário não precise entrar novamente quando o token expirar).
     • Escopo: (Opcional): As permissões que seu aplicativo está solicitando, em uma lista separada por espaço.
     • Qual organização Microsoft 365 acessa os endpoints: essa configuração limita o acesso à fonte à organização do fabricante ou a todas as organizações. Selecione:
       • Minha organização apenas
       • Quaisquer organizações Microsoft 365
     • Qual aplicativo (cliente) pode usar os endpoints: GUID que define o sistema cliente que pode ser usado para acessar esses dados. Os aplicativos podem incluir Microsoft 365, Power Automate e outras opções.

3. Ao concluir todos os campos, selecione Avançar.

   A página Selecionar e configurar sua ferramenta é exibida onde você pode selecionar ferramentas para habilitar na 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 por meio 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, sua especificação de API pode incluir a possibilidade de atualizar e excluir, mas você só quer que os usuários do seu agente possam criar registros.

1. Selecione uma ferramenta na lista a ser configurada.

   A página Configurar sua ferramenta é exibida.

   

2. Configure o nome e a descrição da ferramenta selecionada. Semelhante à API geral, forneça 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 a descrição geral da API, deve ser específica o suficiente para fornecer ao modelo de linguagem detalhes e assim 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 esperados para entrada e os valores de saída que são retornados. Você não pode alterar esses valores, mas pode 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 do que os valores são usados. Se qualquer uma das descrições estiver em branco, você deverá preencha-as antes de seguir em frente. 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 outras ferramentas da API que você deseja incluir no momento. Quando 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, selecione Voltar e fazer suas alterações. Caso contrário, selecione Próximo.

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

2. Selecione Criar conexão para continuar. Você retorna à tela Adicionar ferramenta.

3. Selecione a API REST no seletor de tipos de ferramenta. Você pode ver as ferramentas recém-criadas pela sua API. Deveria haver uma entrada para cada ferramenta que você adicionou da API.

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

   1. Na tela Adicionar ferramenta , selecione a ferramenta.
   2. Em Conexão, selecione uma conexão existente ou selecione Criar nova conexão.
   3. Insira todas as informações necessárias para a conexão e selecione Criar para criar a conexão com a ferramenta.
   4. Selecione Adicionar e configurar para adicionar a ferramenta ao seu agente.

   

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

Dica

Para localizar sua ferramenta com mais facilidade, use a barra de pesquisa para localizá-la.