Compartilhar via

Handoff copilot

  • Artigo

Observação

As handoffs do Copilot são ligações avançadas fornecidas por plug-in que transportam o contexto de chat, permitindo que os utilizadores transitem facilmente o seu chat com o Copilot para o Microsoft 365 para o seu serviço de bot. Pode melhorar o plug-in da extensão de mensagens copilot para entregar uma conversação ao copilot do motor personalizado para lidar com cenários em que são necessários conhecimentos ou ações especializados, tais como consultas complexas de suporte de TI, perguntas detalhadas sobre produtos ou gestão de encomendas interativa.

No gráfico seguinte, um utilizador procura ajuda sobre problemas tecnológicos com o Copilot e recebe resultados do conjunto de dados empresarial. O utilizador considera as informações disponíveis insuficientes e quer continuar a interação com um plug-in de bot da Contoso. Quando o utilizador seleciona o bot da Contoso, é iniciada uma nova conversação e a conversa continua no bot da Contoso. Esta mudança totalmente integrada de Copilot para o bot contoso, sem perder o contexto de conversação, é denominada handoff copilot.

O GIF mostra a entrega da conversação entre o copilot do Microsoft 365 e o chat bot da Contoso.

Como funciona a entrega de copilot

Um copilot de motor personalizado envia uma ligação avançada com um token de continuação para o Copilot para o Microsoft 365. O parâmetro de consulta de ligação avançada com um token de continuação garante que todas as informações dos parâmetros de invocação do plug-in são referenciadas. Quando o utilizador seleciona a ligação avançada, o Copilot envia uma chamada de invocação para o bot com o token de continuação e, em seguida, o bot retoma a conversação com base no contexto. Este processo permite uma transição totalmente integrada do Copilot para o Microsoft 365 para o copilot do motor personalizado, mantendo a continuidade e o contexto da conversação, o que otimiza a experiência do utilizador.

Captura de ecrã a mostrar o fluxo de entrega entre o utilizador, o Copilot, o plug-in, o Teams e o bot.

Tem de criar um URL de ligação avançada com um continuation parâmetro de consulta para o botão de ação e atribuir um token de continuação ao parâmetro para facilitar o processo de entrega. Quando o utilizador seleciona o botão de ação, o Microsoft Teams lê o token de continuação a partir do URL e inicia uma chamada de invocação para o bot. O bot ou plug-in utiliza o token de continuação para criar uma resposta, que é depois apresentada ao utilizador na janela de chat do plug-in.

Ativar a entrega do copilot

Para ativar a entrega de copilot no Teams, siga estes passos:

  1. Configurar um URL de ligação avançada: crie uma ligação avançada para um chat e adicione o 28:<botId> e continuationToken ao formato de ligação avançada. O formato de ligação avançada tem de ser https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}.

    Exemplo:

    { 
"type": "Action.OpenUrl", 
"title": "Handoff to Bot", 
"url": "https://teams.microsoft.com/l/chat/0/0?users=28:${botId}&continuation=${continuationToken}" 
}

    A Action.OpenUrl propriedade permite ao utilizador entregar a conversação a um bot. Quando um utilizador seleciona o botão de ação, a ligação avançada é ativada e abre uma nova janela de chat com o bot. O bot recebe uma chamada de invocação com um payload, que contém o token de continuação do URL e utiliza o token para manter o contexto da conversação.

    Payload de exemplo

    { 
 "name": "handoff/action", 
 "type": "invoke", 
 "timestamp": "2024-04-15T19:50:32.945Z", 
 "localTimestamp": "2024-04-15T19:50:32.945Z", 
 "id": "f:00000000-0000-0000-0000-000000000000",
 "channelId": "msteams", 
 "serviceUrl": "https://smba.trafficmanager.net/amer/", 
 "from": { 
     "id": "29:1jzORtjcfpYTLQDR9O4TyLz9LDwHskubQN1Ljc-aFO4L8dnZatjFpSw1PCGa-Mm-Jo4uLp67Lvekcjq2hkPoxdA", 
     "aadObjectId": "00000000-0000-0000-0000-000000000000" 
 }, 
 "conversation": { 
     "conversationType": "personal", 
     "tenantId": "00000000-0000-0000-0000-000000000000",
     "id": "a:13tOiSzRqeub3zaqoTHKpvOkk8Y1zFxk-g8WKdAUM2tjhTBFMt4RSuL8YWi7uwFNBmbxsyzYYktJEyfimYXYiEoplQ34aJs1y8trDb7EIcG09xOjSUieHVzFZ2b8tkagZ" 
 }, 
 "recipient": { 
     "id": "28:00000000-0000-0000-0000-000000000000", 
     "name": "NorthwindProducts" 
 }, 
 "entities": [ 
     { 
         "locale": "en-US", 
         "country": "US", 
         "platform": "Android", 
         "timezone": "America/Chicago", 
         "type": "clientInfo" 
     } 
 ], 
 "channelData": { 
     "tenant": { 
         "id": "00000000-0000-0000-0000-000000000000" 
     }, 
     "source": { 
         "name": "message" 
     }, 
     "legacy": { 
         "replyToId": "1:1_qLAAGcfze29QAWxzicc7gvR3vuNAlKvth08vavxYYs" 
     } 
 }, 
 "replyToId": "1713210583687", 
 "value": { 
     "continuation": "test-continuation-token" 
 }, 
 "locale": "en-US", 
 "localTimezone": "America/Chicago", 
 "rawTimestamp": "2024-04-15T19:50:32.945Z", 
 "rawLocalTimestamp": "2024-04-15T14:50:32.945-05:00", 
 "callerId": "urn:botframework:azure" 
}

    O handoff/action tipo de invocação permite ao bot transferir o controlo da conversação para outro serviço ou iniciar uma ação específica que requer processamento adicional. Quando o bot recebe a handoff/action atividade de invocação, utiliza o token de continuação para procurar as informações necessárias para continuar a conversa de forma totalmente integrada. Isto envolve obter o histórico de conversações, as preferências do utilizador ou qualquer outro contexto necessário para proporcionar uma experiência consistente.

  2. Processe o tipo de invocação: no código do bot, faça a gestão da handoff/action invocação com o onInvokeActivity processador. No código do bot, faça a gestão da handoff/action invocação com o onInvokeActivity processador. Tem de substituir o onInvokeActivity método para processar a chamada de invocação. Se a chamada de invocação for efetuada com êxito, o bot tem de devolver um código de estado HTTP de 200. Se existir um erro, o bot tem de responder com um código de estado HTTP adequado no intervalo de 400 ou 500-. Se o utilizador receber um erro, terá de aguardar e tentar novamente enquanto os erros são registados no serviço de back-end.

    Observação

    Não envie qualquer payload com esta resposta, uma vez que não é composta na janela de chat. As respostas baseadas no token de continuação têm de ser enviadas ao utilizador separadamente.

    Eis um exemplo de como processar a chamada de invocação no searchApp.ts ficheiro:

             case "handoff/action": {
           // TODO: Save the continuation token and use it to process final response to user later
          return {status: 200}; // return just the http status
         }

    Quando o bot recebe a chamada de invocação, context.activity.value.continuation contém o continuationToken que foi definido no URL da ligação avançada. Se a aplicação não estiver instalada durante a entrega, o utilizador será redirecionado para a Loja Teams para instalar a aplicação.

Práticas recomendadas

  • O bot tem de notificar os utilizadores quando forem direcionados para o chat do bot depois de selecionar o botão de ação, uma vez que não existe nenhuma indicação visual. Isto ajuda a gerir as expectativas, uma vez que pode haver um atraso antes de o bot devolver uma resposta devido à latência da rede e ao tempo de processamento. Por exemplo, o bot pode enviar uma série de atividades para manter o utilizador informado sobre o progresso:

    await context.sendActivities([
  {
    type: ActivityTypes.Message,
    text: "Continuing conversation from copilot...",
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 1000 },
  {
    type: ActivityTypes.Message,
    text: `Fetching more details using the continuation token passed: ${continuationToken}`,
  },
  { type: ActivityTypes.Typing },
  { type: "delay", value: 4000 },
  {
    type: ActivityTypes.Message,
    text: `Handoff successful!`,
  }
]);

  • Recomendamos que faça a gestão do ciclo de vida do token de continuação para garantir que expira após um período razoável e processe cenários em que o utilizador reproduz o pedido de token de continuação. Por exemplo, se for apresentado o mesmo token, informe o utilizador de que precisa de iniciar uma nova conversa com o bot porque a entrega do copilot não pode continuar.

Exemplos de código

Nome do exemplo Descrição Node.js
Extensão de mensagem de inventário da Northwind Este exemplo é uma extensão de mensagem do Teams que funciona como um plug-in para o Microsoft 365 Copilot. Inclui o handoff copilot e permite que os utilizadores transitem o chat do Copilot para a Base de Dados da Northwind. View