Debug a Virtual Agent topic

Investigate and resolve unexpected behavior in your custom Virtual Agent topics.

Duplicate a topic before debugging and changing it

Duplicate a topic rather than update a live topic. The unmodified original topic can serve as both a reference and a backup, and retaining the original enables you to quickly restore the topic. Remember to deactivate the original topic before publishing the duplicate.

Debug a topic while previewing your conversations

As you create or update a topic in Virtual Agent Designer, use the Preview button to test a conversation. The preview pop-up window shows the conversation as it appears within Service Portal. Elements in your conversation might appear differently in third-party messaging applications. Test your conversations in any third-party applications where you intend to deploy Virtual Agent.

Conversation preview logs shown in the topic preview window

Use the conversation preview logs to view errors and messages logged while previewing a topic. The following steps describe how to access the conversation preview logs. Use gs.log, gs.print, and gs.warn statements in your scripts to output information in this log.

In Virtual Agent Designer, click Preview to begin previewing a topic.
In the topic preview window, select the Show Logs check box.

Note: The logs record information only after you select the Show Logs check box. Be sure to select this option immediately after the topic preview loads to ensure that all logging information is available.

Watch for warnings on controls within your topic

Warnings appear as red icons in the upper left corner of the designer and on the individual controls.

Controls that are missing necessary information show a red icon in the upper left corner of the control. The icon shows a number indicating the number of issues in that control. Point to this icon to see a list of the issues in the control.

Another icon appears in the upper left corner of the designer to indicate the number of issues within the entire topic.

Check for errors when a topic preview does not run

Additional information appears under the Virtual Agent Designer canvas when an error prevents the topic from running. Use the information provided to correct any errors in your conversation.

Common Virtual Agent issues


Issue	Possible resolution
Cannot see module designer under collaboration	User might not have the virtual_agent_admin role. Virtual Agent plugin might not be activated.
Cannot edit a topic	Logged-in user must be in the same application scope as the topic.
Cannot preview topic	Make sure that all required fields are filled in on the node properties. Ensure that your browser is configured to permit pop-ups from your instance.
Web client stuck at Connecting...	One or more of your topics might be missing. Check the Topics page to ensure that topics are present on the instance and in the Active state.

Review topics that run in a conversation flow

During a conversation session, Virtual Agent captures the conversation "tasks" that occur during the conversation. A conversation task is the runtime execution of a topic during the conversation. For a given conversation session, Virtual Agent records the various topics run, such as the topics that a user requests or selects. Also recorded are the setup and any small talk topics that run during the conversation.

To see which tasks were run during the session, check the Conversation [sys_cs_conversation] table. In the navigation filter, enter sys_cs_conversation.list to view the Conversation table. For each conversation, you can view two related tables:

Conversation Tasks [sys_cs_conversation_task] table — Lists all the tasks for a conversation. The relevant fields in each record include: Topic (name of the topic that was executed at runtime) and State.
Conversation Messages [sys_cs_message] table — The Payload field in each record contains the message string displayed for the conversation task (runtime topic executed).

Check NLU prediction information in the Open NLU Predict Logs

When reviewing or debugging topics that use Natural Language Understanding, use the Open NLU Predict Logs [open_nlu_predict_log] table to view the NLU prediction records for topics. Each record in the log identifies the utterance and corresponding intents (topics) and entities determined by the NLU service. Each record also includes the NLU prediction scores calculated during topic discovery (intent matching) and entity extraction.

To view the log, enter open_nlu_predict_log.list in the navigation filter.

The log information includes:

Table 1.
Field	Description
Created	Date and time the NLU prediction record was created.
Utterance	User statement recognized by the bot, which maps to an intent defined in an NLU model.
Request	NLU prediction parameter that contains the utterance and NLU model for the recognized intent.
Response	NLU prediction results, which contain 0 (none) or more scored intents and scored entities.
Duration	Length of processing time for the prediction to return intent and entity values.
Level	Type of message: Information level
Message	Prediction results returned: Number of intents and entities.
Source	Process or area: OpenNLU - Predict.
Async	Indicator for asynchronous prediction processing: True or false. True indicates that the prediction was performed asynchronously, allowing Virtual Agent worker threads to continue.

Review NLU model information using the Open NLU Resource API

If you are debugging or reviewing NLU topics, you can review NLU model information for a specified NLU service provider by using the Open NLU Resource API. You can view the intents, entities, and utterances bound to published NLU models, outside of the Virtual Agent platform.

Contents