Pubblica un agente su app mobili o personalizzate

Articolo
12/09/2024

Puoi Connetti il tuo agente in un'app personalizzata in modo che gli utenti dell'app possano interagire con agente direttamente dall'interno della tua 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.

Collegare il tuo agente a un'app basata sul web è relativamente semplice, poiché consiste nel copiare il codice frammento nella tua app. Tuttavia, sia le app basate sul Web che quelle native o personalizzate richiedono comunque notevoli competenze di sviluppo per integrare completamente agente nella tua app. Entrambe le procedure sono descritte in questo articolo.

Prerequisiti

.NET Core SDK versione 2.1.
Pacchetto Nuget Microsoft.Bot.Connector.DirectLine.
Un agente creato in Copilot Studio che vuoi aggiungere Connetti alla tua app.

Connetti il tuo agente in un'app basata sul web

In Copilot Studio, seleziona menu di spostamento, quindi Canali.
Seleziona il riquadro App per dispositivi mobili per aprire la finestra di configurazione.
Copia il codice nella sezione App basate sul Web e forniscilo ai tuoi sviluppatori di app da aggiungere alla tua app basata sul Web.

Connetti il tuo agente in 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 è quello di usare Connetti sui canali Azure servizio Bot, oltre a seguire le istruzioni riportate qui, i tuoi sviluppatori possono saperne di più consultando Pubblica un agente sui canali Azure servizio 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:

Codice di esempio del connettore

Riferimenti

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

Recupera i tuoi parametri agente Copilot Studio

Per Connetti sul agente che hai creato, devi recuperare il nome del tuo agente e il token endpoint per identificarlo.

In Copilot Studio, vai alla pagina Panoramica del tuo agente e copia il nome del tuo agente.
Seleziona Canali>App per dispositivi mobili.
Nella pagina App per dispositivi mobili, accanto a Endpoint token, seleziona Copia. Avrai bisogno di questo endpoint per il passaggio Ottieni token Direct Line.

Ottenere token Direct Line

Per avviare una conversazione con il tuo agente, ti serve un Direct Line token. 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, verrà restituito un token, un tempo di scadenza e un conversationId per l'agente richiesto. Direct Line Esempio:

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

Codice di esempio

L'esempio seguente utilizza campioni dal codice di esempio del connettore per ottenere un Direct Line token per un Copilot Studio agente.

/// <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"
}

Utilizzare Direct Line per comunicare con agente

Dopo aver recuperato il Direct Line token, sei pronto per avere una conversazione con il tuo Copilot Studio agente 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 campioni dal codice di esempio del connettore per avviare una conversazione e inviare e ricevere messaggi da a Copilot Studio agente.

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;
   }

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",
           });
       }
   }

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

   // 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 codice per aggiornare il token Direct Line se l'applicazione ha una lunga conversazione con agente. 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

Analizza il payload della conversazione da agente

Dopo aver avviato una conversazione con agente, il payload JSON della conversazione utilizza l'attività standard. Microsoft Bot Framework Direct Line 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 tuo agente invii automaticamente il saluto argomento di sistema quando un utente avvia una conversazione, puoi inviare un'attività con Type=event e Name=startConversation.

Condividi tramite