Impulsa tus interacciones de voz: Integración de los Servicios de Comunicación de Azure con agentes de Microsoft Copilot Studio

En este documento se proporcionan instrucciones paso a paso sobre cómo crear e integrar un agente de Copilot Studio con Azure Communication Services. Esta guía le permitirá crear agentes habilitados para voz a los que los usuarios puedan llamar.

Descargar el ejemplo

Busque el proyecto de este ejemplo en GitHub. Puede descargar este código y ejecutarlo localmente para probarlo usted mismo.

Prerrequisitos

Antes de comenzar, asegúrese de que tiene:

• Cuenta de Azure con una suscripción activa: consulte Crear una cuenta gratuita.
• Recurso de Azure Communication Services, consulte Creación de un nuevo recurso de Azure Communication Services. Debe registrar la cadena de conexión del recurso para este ejemplo.
• Cree una nueva aplicación de servicio web mediante el SDK de automatización de llamadas.
• Un recurso multiservicio de Azure AI y un dominio personalizado.
• Conecte Azure Communication Services y Azure AI.
• Una licencia de Copilot Studio para que pueda crear y publicar un agente.

1. Creación del agente en Copilot Studio

Después de iniciar sesión o registrarse en Copilot Studio, llegará a la página principal. Seleccione Crear en la navegación de la izquierda.

En la página Crear, seleccione Nuevo agente. Utilice el chat para describir a su agente, utilizando las preguntas proporcionadas como guía.
Una vez que haya proporcionado toda la información solicitada, haga clic en Crear.

Para obtener más información sobre cómo crear y personalizar el agente, puede ver el inicio rápido de Copilot Studio.

2. Deshabilitar la autenticación

Una vez que haya creado el agente, debe realizar algunas actualizaciones para que pueda integrarla con Azure Communication Service.

• Vaya a la pestaña Configuración.

• Haga clic en Seguridad en el panel izquierdo.

• Seleccione Autenticación, seleccione Sin autenticación y haga clic en Guardar.

3. Obtención de la clave de seguridad de Webchannel

Al volver a la sección Seguridad , seleccione Seguridad del canal web. Copie y guarde esta clave en algún lugar. Necesita esto cuando implemente la aplicación.

4. Publicar agente

Ahora que tiene la configuración de los agentes actualizada y guardada la clave del agente, puede publicar el agente.

5. Configurar código

Ahora que ha creado el agente, asegúrese de descargar el ejemplo. Después de descargar el ejemplo, deberá actualizar algunas de las propiedades.

• Cadena de conexión: puede obtener la cadena de conexión del recurso de Azure Communication Services.
• Clave de Direct Line de Microsoft Copilot Studio: que guardó en el paso 3, la clave de seguridad de webchannel.
• Punto de conexión personalizado de Azure AI Services: puede obtener este punto de conexión del recurso de Azure AI Services.
• Debe tener un puerto en ejecución para recibir notificaciones de eventos de Azure Communication Services. Puede usar herramientas como DevTunnels para ayudar a configurar una.

6. Información general del código

Hay algunos conceptos básicos con los que debe estar familiarizado con que el ejemplo usa para crear este flujo de trabajo.

Llamada entrante

Registre un evento de llamada entrante para que la aplicación sepa cuándo entra una llamada y necesita responder.

Llamada de respuesta con transcripción en tiempo real

Al responder a la llamada también se habilita el streaming de transcripción en tiempo real, que envía el contenido convertido de voz a texto que el autor de la llamada está diciendo casi en tiempo real.

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

Establecimiento de una conexión de copilot

Una vez conectada la llamada, la aplicación debe establecer una conexión con el agente de IA que creó mediante las API de Direct Line con websockets.

Iniciar conversación

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

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

Lógica integrada de barras:

La aplicación usa los resultados intermedios recibidos de la transcripción en tiempo real para detectar la barra de acceso desde el autor de la llamada y cancela la operación de reproducción.

if (data.Contains("Intermediate"))
{
    Console.WriteLine("\nCanceling prompt");
    if (callMedia != null)
    {
        await callMedia.CancelAllMediaOperationsAsync();
    }
}

• Cuando el agente de IA proporciona respuestas, la aplicación usa Play API para convertir ese texto en audio del servicio Text-to-Speech.

var ssmlPlaySource = new SsmlSource($"{message}");

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

await callConnectionMedia.PlayToAllAsync(playOptions);

• Escala la llamada cuando el autor de la llamada solicita a un representante: cuando el usuario pide que hable con un representante, el agente de IA transfiere la llamada a un agente humano.

if (botActivity.Type == "handoff")
{
    var transferOptions = new TransferToParticipantOptions(agentPhoneIdentity)
    {
        SourceCallerIdNumber = acsPhoneIdentity
    };

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

7. Ejecute

Ahora debería poder realizar una llamada y hablar con el agente.

Consejos

Temas

Para optimizar la voz, le recomendamos que actualice los temas en los que usa el tipo "Mensaje" de Text to Speech, ya que optimiza las respuestas de los agentes para escenarios de voz.

Cómo gestionar temas del sistema

El agente tiene temas del sistema integrados de manera predeterminada. Puede optar por deshabilitar estos temas, pero si desea seguir usándolas, la aplicación debe crear lógica para controlar estos temas. Por ejemplo:

• Escalado: debe compilar la transferencia del agente a la aplicación para escalar la llamada de este agente copilot a un representante humano.