Pubblicare un agente in applicazioni mobili o personalizzate

Collega un agente pubblicato di Copilot Studio alla tua app mobile o personalizzata così gli utenti possono interagire con l'agente senza uscire dall'app.

Scegli l'integrazione che si adatta alla tua app:

• Codice web embed: Aggiungi l'interfaccia di chat fornita a un'app web.
• Direct Line: invia e ricevi attività in modo programmatico da un'app nativa, un'interfaccia web personalizzata o un adattatore verso un altro servizio.

Per un'integrazione separata basata su SDK, scopri di più in Integrazione di app web o native con Managed Disks.

Prerequisites

• Un agente pubblicato di Copilot Studio. Scopri di più in Pubblica e distribuisci il tuo agente.
• Per gli esempi di C#, un SDK .NET supportato e i pacchetti NuGet Microsoft.Bot.Connector.DirectLine e Microsoft.Rest.ClientRuntime. Questi esempi usano System.Net.Http.Json e System.Text.Json.Serialization per la risposta del token.
• Strumenti di sviluppo appropriati per la tua app. I prerequisiti .NET si applicano solo agli esempi di C#, non a ogni integrazione.

Connettere l'agente a un'app basata sul Web

1. In Copilot Studio, seleziona menu di spostamento, quindi 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.

   

Connettere l'agente a un'app nativa o personalizzata

Per connetterti ai canali di Azure servizio Bot, scopri di più in Pubblicare un agente nei canali di Azure servizio Bot.

References

Le istruzioni in questo articolo utilizzano i seguenti riferimenti:

• Direct Line API di Bot Framework
• Autenticazione Direct Line
• Variabili di contesto disponibili al momento del passaggio
• Attività Microsoft Bot Framework

Recuperare i parametri dell'agente Copilot Studio

Per connettersi all'agente che hai creato, ottenere il nome e l'endpoint del token dell'agente per identificarlo.

1. In Copilot Studio passare alla pagina Panoramica dell'agente e copiare il nome dell'agente.

2. Seleziona Canali>App per dispositivi mobili.

3. Nella pagina App per dispositivi mobili, accanto a Endpoint token, seleziona Copia. Avrai bisogno di questo endpoint per il passaggio Ottenere un token Direct Line.

   

Ottenere un token Direct Line

Per iniziare una conversazione con il tuo agente, ottieni un token Direct Line inviando una richiesta GET all'endpoint del token che hai copiato da Copilot Studio. Questo endpoint è il token endpoint Copilot Studio, non l'endpoint Direct Linetokens/generate. Usa il token restituito per le richieste Direct Line successive.

Un token Direct Line consente l'accesso a una conversazione; non è un token di accesso per l'utente finale. Non mettere un segreto Direct Line nel codice del browser o dell'app mobile. Scopri di più sull'autenticazione Direct Line.

GET <TokenEndpoint>

Se la richiesta ha successo, l'endpoint restituisce un token, la sua durata in secondi in expires_in, e un conversationId. Usa la durata di validità restituita invece di assumere un periodo di scadenza fisso.

{
    "token": "<DirectLineToken>",
    "expires_in": 3600,
    "conversationId": "<ConversationId>"
}

Esempio di codice per il token Direct Line

Aggiungi il seguente metodo e tipo di risposta alla tua classe di applicazione. Importa System.Net.Http.Json e System.Text.Json.Serialization.

Il metodo accetta un HttpClient gestito dal chiamante e genera un'eccezione se l'endpoint non restituisce alcun token utilizzabile. Gli errori HTTP e JSON si propagano al chiamante.

public static async Task<DirectLineToken> GetTokenAsync(
    HttpClient httpClient, string tokenEndpoint)
{
    var response = await httpClient.GetFromJsonAsync<DirectLineToken>(
        tokenEndpoint);

    if (response is null || string.IsNullOrWhiteSpace(response.Token))
    {
        throw new InvalidOperationException(
            "The token endpoint returned no Direct Line token.");
    }

    return response;
}

public sealed class DirectLineToken
{
    [JsonPropertyName("token")]
    public string Token { get; set; } = string.Empty;

    [JsonPropertyName("expires_in")]
    public int ExpiresIn { get; set; }

    [JsonPropertyName("conversationId")]
    public string ConversationId { get; set; } = string.Empty;
}

Utilizzare Direct Line per comunicare con l'agente

Dopo aver recuperato un token, usa Direct Line per iniziare una conversazione e inviare e ricevere attività. Scopri di più su Bot Framework Direct Line API.

I seguenti frammenti appartengono allo stesso metodo asincrono nella classe applicazione che contiene GetTokenAsync. Importa Microsoft.Bot.Connector.DirectLine e System.Linq. Sostituisci <TokenEndpoint> e <AgentName> con i valori del tuo agente e fornisci un identificatore utente specifico per l'app al posto di <UserId>.

1. Prendi un token, inizializza un DirectLineClient, e avvia una conversazione. Tieni il client e l'ID della conversazione nel contesto per le seguenti operazioni:

   using var httpClient = new HttpClient();
   var tokenResponse = await GetTokenAsync(httpClient, "<TokenEndpoint>");
   using var directLineClient = new DirectLineClient(tokenResponse.Token);
   
   var conversation =
       await directLineClient.Conversations.StartConversationAsync();
   string conversationId = conversation.ConversationId;
   string? watermark = null;
   string agentName = "<AgentName>";
   

2. Manda un messaggio a quella conversazione:

   string inputMessage = "Hello";
   await directLineClient.Conversations.PostActivityAsync(
       conversationId,
       new Activity
       {
           Type = ActivityTypes.Message,
           From = new ChannelAccount { Id = "<UserId>" },
           Text = inputMessage,
           TextFormat = "plain"
       });
   

3. Recupera le attività utilizzando lo stesso client e lo stesso ID conversazione. Il risultato può contenere sia attività utente che agente. Questo esempio mostra le attività dei messaggi in base al nome agente configurato:

   var response = await directLineClient.Conversations.GetActivitiesAsync(
       conversationId, watermark);
   watermark = response.Watermark ?? watermark;
   
   foreach (var activity in response.Activities.Where(activity =>
       activity.Type == ActivityTypes.Message &&
       string.Equals(activity.From?.Name, agentName, StringComparison.Ordinal)))
   {
       Console.WriteLine(activity.Text);
   }
   

   Ripeti l'operazione di ricezione per raccogliere le attività che arrivano in seguito; una singola richiesta potrebbe non contenere ancora la risposta dell'agente. Passa il watermark più recente su ogni richiesta e conserva il valore precedente se la risposta non ne fornisce uno. Scopri di più in Ricevi attività dal bot.

   Il filtro dei messaggi serve solo per la visualizzazione. La tua app deve gestire separatamente altri tipi di attività, inclusi gli eventi di handoff.

Aggiornare il token Direct Line

Per una conversazione lunga, aggiorna il token prima che scada, usando il valore restituito expires_in per pianificare l'aggiornamento. Un token scaduto non può essere aggiornato. Scopri di più sull'autenticazione Direct Line.

L'esempio seguente aggiorna il token per una conversazione di Copilot Studio esistente:

var refreshedTokenResponse =
    await directLineClient.Tokens.RefreshTokenAsync();
using var refreshedClient = new DirectLineClient(refreshedTokenResponse.Token);

Da usare refreshedClient per operazioni successive con l'esistente conversationId e la filigrana. Elimina i client quando la tua app non ne ha più bisogno.

Analizzare il payload di conversazioni dell'agente

Dopo aver avviato una conversazione con l'agente, il payload JSON della conversazione utilizza l'attività Direct Line Microsoft Bot Framework standard. Scopri di più su Bot Framework Direct Line API.

Gestire l'attività di trasferimento

Se la tua applicazione deve essere consegnata a un provider di operatore umano, gestisci l'attività di handoff inviata quando viene eseguito un nodo Trasferisci a un operatore. Per saperne di più, consulta Esempio di payload del messaggio di handoff.

Attivare un messaggio di benvenuto

Per fare in modo che l'agente invii automaticamente il tema Greeting System quando un utente avvia una conversazione, inviare un'attività con Type=event e Name=startConversation.