Condividi tramite

Sovralimentare le interazioni vocali: integrazione di Servizi di comunicazione di Azure con gli agenti di Microsoft Copilot Studio

Questo documento fornisce istruzioni dettagliate su come creare e integrare un agente di Copilot Studio con Servizi di comunicazione di Azure. Questa guida consentirà di creare agenti abilitati per la voce a cui gli utenti possono chiamare.

Scaricare l'esempio

Trovare il progetto per questo esempio in GitHub. È possibile scaricare questo codice ed eseguirlo in locale per provarlo manualmente.

Prerequisiti

Prima di iniziare, assicurarsi di disporre di:

1. Crea il tuo agente in Copilot Studio

Dopo l'accesso o l'iscrizione a Copilot Studio, si accede alla home page. Seleziona Crea nella barra di spostamento sinistra.

Screenshot di come creare un agente.

Nella pagina Crea selezionare Nuovo agente. Utilizza la chat per descrivere l'agente, utilizzando le domande fornite come guida.
Dopo aver specificato tutte le informazioni richieste, fare clic su Crea.

Screenshot di Fare clic per creare.

Per altri dettagli sulla creazione e la personalizzazione dell'agente, vedere l'argomento di avvio rapido di Copilot Studio.

2. Disabilitare l'autenticazione

Dopo aver creato l'agente, è necessario apportare alcuni aggiornamenti in modo che sia possibile integrarlo con il servizio di comunicazione di Azure.

  • Passare alla scheda Impostazioni.

Screenshot di come andare alla scheda delle impostazioni.

  • Fare clic su Sicurezza nel riquadro sinistro.

Screenshot della scheda Sicurezza.

  • Selezionare Autenticazione, selezionare Nessuna autenticazione e fare clic su Salva.

Screenshot del passaggio autenticazione.

3. Ottenere la chiave di sicurezza webchannel

Tornare alla sezione Sicurezza selezionare Sicurezza canale Web. Copiare e salvare la chiave da qualche parte. Questa operazione è necessaria quando si distribuisce l'applicazione.

4. Pubblica agente

Ora che hai aggiornato le impostazioni degli agenti e salvato la chiave dell'agente, puoi pubblicare il tuo agente.

5. Impostazione del codice

Dopo aver creato l'agente, assicurarsi di scaricare l'esempio. Dopo aver scaricato l'esempio, sarà necessario aggiornare alcune delle proprietà.

  • Stringa di connessione: è possibile ottenere la stringa di connessione dalla risorsa di Servizi di comunicazione di Azure.
  • Chiave Direct Line di Microsoft Copilot Studio: che hai salvato nel passaggio 3, la tua chiave di sicurezza del canale web.
  • Endpoint personalizzato di Servizi di intelligenza artificiale di Azure: è possibile ottenere questo endpoint dalla risorsa di Servizi di intelligenza artificiale di Azure.
  • È necessario disporre di una porta in esecuzione per ricevere notifiche degli eventi da Servizi di comunicazione di Azure. È possibile usare strumenti come DevTunnels per configurarne uno.

6. Panoramica del codice

Esistono alcuni concetti di base con cui è necessario familiarizzare e che l'esempio utilizza per costruire questo flusso di lavoro.

Chiamata in arrivo

Registrare un evento di chiamata in ingresso, in modo che l'applicazione sappia quando arriva una chiamata e deve rispondere.

Risposta alla chiamata con trascrizione in tempo reale

Quando si risponde alla chiamata si abilita anche lo streaming della trascrizione in tempo reale, che invia il contenuto convertito da voce a testo che il chiamante sta dicendo quasi in tempo reale.

app.MapPost("/api/incomingCall", async (
    [FromBody] EventGridEvent[] eventGridEvents,
    ILogger<Program> logger) =>
{
    foreach (var eventGridEvent in eventGridEvents)
    {
        logger.LogInformation($"Incoming Call event received : {JsonConvert.SerializeObject(eventGridEvent)}");
        // Handle system events
        if (eventGridEvent.TryGetSystemEventData(out object eventData))
        {
            // Handle the subscription validation event.
            if (eventData is SubscriptionValidationEventData subscriptionValidationEventData)
            {
                var responseData = new SubscriptionValidationResponse
                {
                    ValidationResponse = subscriptionValidationEventData.ValidationCode
                };
                return Results.Ok(responseData);
            }
        }
        var jsonObject = JsonNode.Parse(eventGridEvent.Data).AsObject();
        var incomingCallContext = (string)jsonObject["incomingCallContext"];
        var callbackUri = new Uri(baseUri + $"/api/calls/{Guid.NewGuid()}");
        
        var answerCallOptions = new AnswerCallOptions(incomingCallContext, callbackUri)
        {
            CallIntelligenceOptions = new CallIntelligenceOptions()
            {
                CognitiveServicesEndpoint = new Uri(cognitiveServicesEndpoint)
            },
            TranscriptionOptions = new TranscriptionOptions(new Uri($"wss://{baseWssUri}/ws"), "en-US", true, TranscriptionTransport.Websocket)
            {
                EnableIntermediateResults = true
            }
        };

        try
        {
            AnswerCallResult answerCallResult = await client.AnswerCallAsync(answerCallOptions);

            var correlationId = answerCallResult?.CallConnectionProperties.CorrelationId;
            logger.LogInformation($"Correlation Id: {correlationId}");

            if (correlationId != null)
            {
                CallStore[correlationId] = new CallContext()
                {
                    CorrelationId = correlationId
                };
            }
        }
        catch (Exception ex)
        {
            logger.LogError($"Answer call exception : {ex.StackTrace}");
        }
    }
    return Results.Ok();
});

Stabilire una connessione con copilota

Una volta connessa la chiamata, l'applicazione deve stabilire una connessione all'agente di intelligenza artificiale creato usando le API Direct Line con websocket.

Avviare la conversazione

var response = await httpClient.PostAsync("https://directline.botframework.com/v3/directline/conversations", null);
response.EnsureSuccessStatusCode();
var content = await response.Content.ReadAsStringAsync();
return JsonConvert.DeserializeObject(content);

Ascolta webscket

await webSocket.ConnectAsync(new Uri(streamUrl), cancellationToken);

var buffer = new byte[4096]; // Set the buffer size to 4096 bytes
var messageBuilder = new StringBuilder();

while (webSocket.State == WebSocketState.Open && !cancellationToken.IsCancellationRequested)
{
    messageBuilder.Clear(); // Reset buffer for each new message
    WebSocketReceiveResult result;
    do
    {
        result = await webSocket.ReceiveAsync(new ArraySegment<byte>(buffer), cancellationToken);
        messageBuilder.Append(Encoding.UTF8.GetString(buffer, 0, result.Count));
    }
    while (!result.EndOfMessage); // Continue until we've received the full message
}

Logica integrata di barge-in:

L'applicazione usa i risultati intermedi ricevuti dalla trascrizione in tempo reale per rilevare un barge-in dal chiamante e annulla l'operazione di riproduzione.

if (data.Contains("Intermediate"))
{
    Console.WriteLine("\nCanceling prompt");
    if (callMedia != null)
    {
        await callMedia.CancelAllMediaOperationsAsync();
    }
}
  • Quando l'agente di intelligenza artificiale fornisce risposte, l'applicazione usa l'API Play per convertire il testo nell'audio del servizio Sintesi vocale.
var ssmlPlaySource = new SsmlSource($"{message}");

var playOptions = new PlayToAllOptions(ssmlPlaySource)
{
    OperationContext = "Testing"
};

await callConnectionMedia.PlayToAllAsync(playOptions);
  • Trasferire la chiamata a un livello superiore quando il chiamante chiede di parlare con un rappresentante: quando l'utente chiede di parlare con un rappresentante, l'agente di intelligenza artificiale trasferisce la chiamata a un agente umano.
if (botActivity.Type == "handoff")
{
    var transferOptions = new TransferToParticipantOptions(agentPhoneIdentity)
    {
        SourceCallerIdNumber = acsPhoneIdentity
    };

    await Task.Delay(6000);
    await callConnection.TransferCallToParticipantAsync(transferOptions);
}

7. Esegui

Dovrebbe ora essere possibile effettuare una chiamata e parlare con l'agente.

Suggerimenti

Argomenti

Per ottimizzare per la voce, è consigliabile aggiornare gli argomenti in cui si usa il tipo "Messaggio" di Text-to-Speech, in quanto ottimizza le risposte degli agenti per gli scenari di interazione vocale.

Come gestire gli argomenti di sistema

Per impostazione predefinita, l'agente include Argomenti di sistema predefiniti. È possibile scegliere di disabilitare questi argomenti, ma se si desidera continuare a usarli, l'applicazione deve compilare la logica per gestire questi argomenti. Ad esempio:

  • Inoltra al livello superiore: è necessario integrare il trasferimento agente nell'applicazione per inoltrare la chiamata da questo agente Copilot a un rappresentante umano.