Aggiungere un copilota ad app per dispositivi mobili e personalizzate

  • Articolo

Importante

Le capacità e funzionalità di Power Virtual Agents ora fanno parte di Microsoft Copilot Studio a seguito di investimenti significativi nell'intelligenza artificiale generativa e integrazioni migliorate in Microsoft Copilot.

Alcuni articoli e schermate potrebbero fare riferimento a Power Virtual Agents durante l'aggiornamento della documentazione e dei contenuti per il training.

Puoi connettere il tuo copilota a un'app personalizzata in modo che gli utenti dell'app possano interagire con il copilota direttamente dall'app.

Nella maggior parte dei casi, l'app personalizzata sarà un'app per dispositivi mobili che è un'app basata sul Web o un'app nativa o un adattatore per altri servizi richiesti dalla tua azienda.

Esistono diverse procedure per la connessione all'app per dispositivi mobili, a seconda che l'app sia un'app basata sul Web o un'app nativa.

La connessione del copilota a un'app basata sul Web è relativamente semplice in quanto comporta la copia di un frammento di codice nella tua app. Tuttavia, sia le app basate sul Web che le app native o personalizzate richiedono ancora una notevole competenza degli sviluppatori per integrare completamente il copilota nella tua app. Entrambe le procedure sono descritte in questo articolo.

Prerequisiti

Connettere il copilota a un'app basata sul Web

  1. In Copilot Studio, nel menu di navigazione, in Impostazioni, seleziona Canali.

  2. Seleziona il riquadro App per dispositivi mobili per aprire la finestra di configurazione.

  3. Copia il codice nella sezione App basate sul Web e forniscilo ai tuoi sviluppatori di app da aggiungere alla tua app basata sul Web.

    Aggiungere il copilota all'applicazione basata sul Web.

Connettere il copilota a un'app nativa o personalizzata

Suggerimento

Sebbene questa sezione descriva come connettersi a un'app per dispositivi mobili, lo stesso processo può essere applicato per app personalizzate o native, come le app IoT (Internet delle cose).

Se il tuo obiettivo è connetterti ai canali del servizioAzure Bot, oltre a seguire le istruzioni in questo argomento, i tuoi sviluppatori possono scoprire di più in Connettere il bot ai canali del servizio Azure Bot.

Importante

Le istruzioni in questa sezione richiedono lo sviluppo del software da parte tua o degli sviluppatori. È destinato a professionisti IT esperti, come amministratori IT o sviluppatori che hanno una solida conoscenza di strumenti di sviluppo, utilità e IDE.

Esempi di codice

I frammenti di codice utilizzati in questo documento provengono da:

Riferimenti

Le istruzioni in questo documento fanno riferimento al materiale di origine seguente:

Recuperare i parametri del copilota Copilot Studio

Per connetterti al copilota che hai creato, sarà necessario recuperare il nome del copilota e l'endpoint del token per identificarlo.

  1. Copia il nome del tuo copilota in Copilot Studio.

    Ottieni il nome del copilota.

  2. Nel menu di navigazione, in Impostazioni seleziona Canali.

  3. Seleziona App per dispositivi mobili.

    Canale dell'app per dispositivi mobili.

  4. Accanto a Endpoint token, seleziona Copia. Avrai bisogno di questo endpoint per il passaggio Ottieni token Direct Line.

    Ottenere i parametri del copilota.

Ottenere token Direct Line

Per iniziare una conversazione con il tuo copilota hai bisogno di un token Direct Line. Questo token può essere ottenuto effettuando una richiesta GET all'endpoint indicato nella schermata di Copilot Studio. Questo token deve quindi essere utilizzato come intestazione per le chiamate successive all'API directline.

Esempio:

GET <BOT TOKEN ENDPOINT>

Se la richiesta ha esito positivo, un token Direct Line, il tempo di scadenza e un conversationId per il copilota richiesto. Esempio:

{
    "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
    "expires_in": 3600,
    "conversationId": "abc123"
}

Codice di esempio

L'esempio seguente utilizza esempi di Codice di esempio del connettore per ottenere un token Direct Line per un copilota Copilot Studio.

/// <summary>
/// Get directline token for connecting bot
/// </summary>
/// <returns>directline token as string</returns>
public async Task<DirectLineToken> GetTokenAsync(string url)
{
    try
    {
        return await _httpClient.GetFromJsonAsync<DirectLineToken>(url);
    }
    catch (HttpRequestException ex)
    {
        throw ex;
    }        
}

/// <summary>
/// class for serialization/deserialization DirectLineToken
/// </summary>
public class DirectLineToken
{
  public string Token { get; set; }
  public int Expires_in { get; set; }
  public string ConversationId { get; set; }
}

L'oggetto di risposta è lo stesso della richiesta GET che abbiamo visto in precedenza.

{
  "token": "RCurR_XV9ZA.cwA.BKA.iaJrC8xpy8qbOF5xnR2vtCX7CZj0LdjAPGfiCpg4Fv0y8qbOF5xPGfiCpg4Fv0y8qqbOF5x8qbOF5xn",
  "expires_in": 3600,
  "conversationId": "abc123"
}

Usa Direct Line per comunicare con il copilota

Dopo aver recuperato il token Direct Line, sei pronto per avere una conversazione con il tuo copilota di Copilot Studio con Direct Line. Per avviare una conversazione e inviare e ricevere messaggi, segui le istruzioni in API Direct Line Bot Framework.

L'esempio seguente utilizza esempi dal codice di esempio del connettore per iniziare una conversazione e inviare e ricevere messaggi da un copilota Copilot Studio.

  1. Inizializza un'istanza DirectLineClient con il token Direct Line e avvia una conversazione:

       // Use the retrieved token to create a DirectLineClient instance
   using (var directLineClient = new DirectLineClient(token))
   {
       var conversation = await directLineClient.Conversations.StartConversationAsync();
       string conversationtId = conversation.ConversationId;
   }

  2. Una volta avviata, ogni conversazione può essere identificata e connessa usando la combinazione di token e conversationtId. Invia un messaggio utente a una conversazione esistente:

       // Use the retrieved token to create a DirectLineClient instance
   // Use the conversationId from above step
   // endConversationMessage is your predefined message indicating that user wants to quit the chat
   while (!string.Equals(inputMessage = /*Get_User_Input()*/, endConversationMessage, StringComparison.OrdinalIgnoreCase))
   {
       using (var directLineClient = new DirectLineClient(token))
       {
           // Send user message using directlineClient
           // Payload is a Microsoft.Bot.Connector.DirectLine.Activity
           await directLineClient.Conversations.PostActivityAsync(conversationtId, new Activity()
           {
               Type = ActivityTypes.Message,
               From = new ChannelAccount { Id = "userId", Name = "userName" },
               Text = inputMessage,
               TextFormat = "plain",
               Locale = "en-Us",
           });
       }
   }

  3. Recupera la risposta del copilota usando lo stesso token e conversationId. Le attività di risposta Direct Line recuperate contengono sia i messaggi dell'utente che quelli del copilota. Puoi filtrare le attività di risposta in base al nome del copilota per ottenere solo il messaggio di risposta del copilota.

       // Use the same token to create a directLineClient
   using (var directLineClient = new DirectLineClient(token))
   {
       // To get the first response set string watermark = null
       // More information about watermark is available at
       // https://learn.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-direct-line-1-1-receive-messages?view=azure-bot-service-4.0

       // response from bot is of type Microsoft.Bot.Connector.DirectLine.ActivitySet
       ActivitySet response = await directLineClient.Conversations.GetActivitiesAsync(conversationtId, watermark);

       // update watermark from response
       watermark = response?.Watermark;

       // response contains set of Activity from both user and bot
       // To display bot response only, filter Activity.From.Name equals to your bot name
       List<Activity> botResponses = response?.Activities?.Where(x =>
                 x.Type == ActivityTypes.Message &&
                   string.Equals(x.From.Name, /*Bot_Name*/, StringComparison.Ordinal)).ToList();

       // Display botResponses
   }

Aggiornare il token Direct Line

Potrebbe essere necessario aggiungere del codice per aggiornare il token Direct Line se la tua applicazione ha una lunga conversazione con il copilota. Il token scade ma può essere aggiornato prima della scadenza; scopri ulteriori informazioni in Autenticazione Direct Line.

L'esempio seguente utilizza esempi del codice di esempio del connettore per aggiornare il token per una conversazione Copilot Studio esistente.

  // DirectLine provides a token refresh method
  // Requires the currentToken valid when refreshing
  string refreshToken = new DirectLineClient(currentToken).Tokens.RefreshToken().Token;
  // create a new directline client with refreshToken
  directLineClient = new DirectLineClient(refreshToken);
  // use new directLineClient to communicate to your bot

Analizzare il payload di conversazioni dal copilota

Dopo aver avviato una conversazione con il copilota, il payload JSON della conversazione utilizza l'attività Direct Line di Microsoft Bot Framework standard. Puoi saperne di più in API Direct Line Bot Framework.

Gestire l'attività di passaggio

Se l'applicazione deve essere distribuita a un fornitore di agenti live, è necessario gestire l'attività di distribuzione. L'attività di passaggio viene inviata quando viene selezionato il nodo "Trasferisci all'agente". Puoi leggere ulteriori informazioni sul payload dell'attività di passaggio.

Attivare un messaggio di benvenuto

Se vuoi che il copilota invii automaticamente l'argomento di sistema di saluto quando un utente inizia una conversazione, puoi inviare un'attività con Type=event e Name=startConversation.