Incorporación de actividades de seguimiento al bot

SE APLICA A: SDK v4

Una actividad de seguimiento es una actividad que el bot puede enviar a Bot Framework Emulator. Puede usar las actividades de seguimiento para depurar un bot de forma interactiva, ya que permiten ver información sobre el bot mientras se ejecuta localmente.

Las actividades de seguimiento solo se envían al emulador y no a ningún otro cliente o canal. El emulador las muestra en el registro, pero no en el panel principal de chats.

• Las actividades de seguimiento enviadas mediante el contexto del turno se envían a través de los controladores de actividad de envío registrados en el contexto del turno.
• Las actividades de seguimiento enviadas mediante el contexto del turno se asocian a la actividad de entrada aplicando la referencia de la conversación, en caso de que haya alguna. En el caso de un mensaje proactivo, el identificador Responder a será un nuevo GUID.
• Independientemente de cómo se envíe, una actividad de seguimiento nunca establece la marca responded.

Nota:

Los SDK de JavaScript, C# y Python de Bot Framework seguirán siendo compatibles, pero el SDK de Java se va a retirar con la compatibilidad final a largo plazo que finaliza en noviembre de 2023.

Los bots existentes creados con el SDK de Java seguirán funcionando.

Para la nueva compilación de bots, considere la posibilidad de usar Microsoft Copilot Studio y lea sobre cómo elegir la solución de copilot adecuada.

Para obtener más información, consulte El futuro de la construcción de bots.

Para utilizar una actividad de seguimiento

Para ver una actividad de seguimiento en el emulador, necesita un escenario en el que el bot enviará una actividad de seguimiento, como generar una excepción y enviar una actividad de seguimiento desde el controlador de errores del turno del adaptador.

Para enviar una actividad de seguimiento desde el bot:

1. Cree una nueva actividad.
   • Establezca su propiedad type requerida en "trace".
   • Opcionalmente, puede establecer sus propiedades name, label, value y value type, según corresponda para el seguimiento.
2. Use el método send activity del objeto del contexto del turno para enviar la actividad de seguimiento.
   • Este método agrega los valores de las restantes propiedades necesarias de la actividad, en función de la actividad de entrada. Estas propiedades incluyen las propiedades channel ID, service URL, from y recipient.

Para ver una actividad de seguimiento en el emulador:

1. Ejecute el ejemplo localmente en la máquina.
2. Pruébelo con el emulador.
   • Interactúe con el bot y siga los pasos del escenario para generar la actividad de seguimiento.
   • Cuando el bot emite la actividad de seguimiento, la actividad de seguimiento se muestra en el registro del emulador.

Esta es una actividad de seguimiento que puede ver si ejecutó el bot básico sin configurar primero la base de conocimiento de QnAMaker en la que se basa el bot.

Incorporación de una actividad de seguimiento al controlador de errores del adaptador

El controlador de errores del turno del adaptador captura cualquier excepción no detectada de otro modo que se produzca en el bot durante un turno. El controlador de errores es un buen lugar para una actividad de seguimiento, ya que puede enviar un mensaje descriptivo al usuario y enviar información de depuración sobre la excepción al emulador.

Este código de ejemplo procede del ejemplo Bot básico. Vea el ejemplo completo en C#, JavaScript, Python, o Java.

C#

El controlador OnTurnError del adaptador crea la actividad de seguimiento para incluir la información de la excepción y la envía al emulador.

AdapterWithErrorHandler.cs

    {
        // Log any leaked exception from the application.
        // NOTE: In production environment, you should consider logging this to
        // Azure Application Insights. Visit https://aka.ms/bottelemetry to see how
        // to add telemetry capture to your bot.
        logger.LogError(exception, $"[OnTurnError] unhandled error : {exception.Message}");

        // Send a message to the user
        var errorMessageText = "The bot encountered an error or bug.";
        var errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.IgnoringInput);
        await turnContext.SendActivityAsync(errorMessage);

        errorMessageText = "To continue to run this bot, please fix the bot source code.";
        errorMessage = MessageFactory.Text(errorMessageText, errorMessageText, InputHints.ExpectingInput);
        await turnContext.SendActivityAsync(errorMessage);

        if (conversationState != null)
        {
            try
            {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a Web pages.
                await conversationState.DeleteAsync(turnContext);
            }
            catch (Exception e)
            {
                logger.LogError(e, $"Exception caught on attempting to Delete ConversationState : {e.Message}");
            }
        }

        // Send a trace activity, which will be displayed in the Bot Framework Emulator
        await turnContext.TraceActivityAsync("OnTurnError Trace", exception.Message, "https://www.botframework.com/schemas/error", "TurnError");
    };
}

JavaScript

El controlador onTurnError del adaptador crea la actividad de seguimiento para incluir la información de la excepción y la envía al emulador.

index.js

    // Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.sendTraceActivity(
        'OnTurnError Trace',
        `${ error }`,
        'https://www.botframework.com/schemas/error',
        'TurnError'
    );

    // Send a message to the user
    let onTurnErrorMessage = 'The bot encountered an error or bug.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    onTurnErrorMessage = 'To continue to run this bot, please fix the bot source code.';
    await context.sendActivity(onTurnErrorMessage, onTurnErrorMessage, InputHints.ExpectingInput);
    // Clear out state
    await conversationState.delete(context);
};

// Set the onTurnError for the singleton CloudAdapter.
adapter.onTurnError = onTurnErrorHandler;

// Define a state store for your bot. See https://aka.ms/about-bot-state to learn more about using MemoryStorage.
// A bot requires a state store to persist the dialog and user state between messages.

// For local development, in-memory storage is used.

Java

En el SDK de Java, se incluye una clase AdapterWithErrorHandler como parte del SDK en el paquete com.microsoft.bot.integration. El controlador onTurnError del adaptador crea la actividad de seguimiento para incluir la información de la excepción y la envía al emulador. A continuación se muestra el código fuente del adaptador predeterminado.

AdapterWithErrorHandler.java

setOnTurnError((turnContext, exception) -> {
    LoggerFactory.getLogger(AdapterWithErrorHandler.class).error("onTurnError", exception);


    return turnContext.sendActivities(
        MessageFactory.text(ERROR_MSG_ONE), MessageFactory.text(ERROR_MSG_TWO)
    ).thenCompose(resourceResponse -> sendTraceActivity(turnContext, exception))
        .thenCompose(stageResult -> {
            if (withConversationState != null) {
                // Delete the conversationState for the current conversation to prevent the
                // bot from getting stuck in a error-loop caused by being in a bad state.
                // ConversationState should be thought of as similar to "cookie-state" in a
                // Web pages.
                return withConversationState.delete(turnContext)
                    .exceptionally(deleteException -> {
                        LoggerFactory.getLogger(AdapterWithErrorHandler.class)
                            .error("ConversationState.delete", deleteException);
                        return null;
                    });
            }
            return CompletableFuture.completedFuture(null);
        });
});

Python

El controlador on_error del adaptador crea la actividad de seguimiento para incluir la información de la excepción y la envía al emulador.

adapter_with_error_handler.py

# This check writes out errors to console log
# NOTE: In production environment, you should consider logging this to Azure
#       application insights.
print(f"\n [on_turn_error] unhandled error: {error}", file=sys.stderr)
traceback.print_exc()

# Send a message to the user
await context.send_activity("The bot encountered an error or bug.")
await context.send_activity(
    "To continue to run this bot, please fix the bot source code."
)
# Send a trace activity if we're talking to the Bot Framework Emulator
if context.activity.channel_id == "emulator":
    # Create a trace activity that contains the error object
    trace_activity = Activity(
        label="TurnError",
        name="on_turn_error Trace",
        timestamp=datetime.utcnow(),
        type=ActivityTypes.trace,
        value=f"{error}",
        value_type="https://www.botframework.com/schemas/error",
    )
    # Send a trace activity, which will be displayed in Bot Framework Emulator
    await context.send_activity(trace_activity)

Pasos siguientes

• Cómo depurar un bot con middleware de inspección describe cómo agregar middleware que emite actividades de seguimiento.
• Para depurar un bot implementado, puede utilizar Application Insights. Para más información, consulte Adición de telemetría al bot.
• Para más información acerca de cada tipo de actividad, consulte el Esquema de actividades de Bot Framework.