Troubleshooting ServiceNow Virtual Agent: A Practical Guide

Virtual Agent problems usually come from one of four places: dialog flow, intent training, routing, or the service connections behind fulfillment actions. This guide sorts each symptom by where the conversation stopped, so the search starts at the right layer rather than the whole configuration.

Recognizing Virtual Agent problems

Virtual Agent issues manifest as broken conversations, missed handoffs to humans, or consistently incorrect responses. These symptoms point to different root causes: the agent training, the dialog models, the routing configuration, or the underlying service connections. A Virtual Agent that never resolves a conversation probably has a routing failure or missing fulfillment action. An agent that gives wrong answers or gets stuck in loops likely needs training data updates or dialog flow repair.

Dialog flow and conversation routing

A conversation in ServiceNow Virtual Agent moves through dialog flows that must be correctly defined. Check the Dialog Task or Bot Step configuration to ensure the conversation follows an intended sequence. When a conversation gets stuck or repeats the same question, the dialog has a loop or missing transition. Look at the conversation history in the Virtual Agent workspace to see exactly what the user asked and what the agent responded. If the response is nonsensical, the dialog does not have a handler for that input.

Routing to human agents fails when the Routing Rule is misconfigured or when the target queue is unavailable. Virtual Agent sends conversations to the target queue defined in the Dialog Task or Routing Rule. If humans never receive routed conversations, verify that the queue exists and that agents are assigned to it. Test the routing by creating a conversation that triggers the rule and checking whether an Incident or Task is created in the target queue. Monitor queue depth to ensure routed conversations are not accumulating faster than agents can handle them.

Training and intent recognition

Virtual Agent relies on training to recognize user intents. If the agent frequently misunderstands what users are asking, the training model lacks sufficient examples of user language for that intent. Add more training phrases to the intent to cover variations of how users phrase the same request. Use real customer conversations from the conversation history to build training examples, not invented phrasing. The training model improves over time as conversations accumulate and are tagged with intents.

Intent confusion arises when two intents have overlapping training phrases. Review your intent definitions to find conflicts, and make training phrases more specific to each intent. Test intent recognition using the Test Intent feature in the Virtual Agent workspace before pushing changes to production. Use a holdout test set—conversation examples not used in training—to validate model performance.

Fulfillment actions and service integration

A conversation that asks questions correctly but never completes is usually blocked by a fulfillment action. Fulfillment actions call back-end services such as REST APIs, ServiceNow table queries, or webhooks. When a fulfillment action fails silently, the conversation stalls. Enable debug logging in the Virtual Agent configuration and rerun the conversation to see which fulfillment action failed and why. Check whether the target service is reachable, whether the request payload is correctly formatted, and whether credentials are valid.

The Response Entity Mapping tells Virtual Agent how to extract data from the service response. If the response is received but the agent gives users an unhelpful reply, the mapping may be incorrect. Validate the service response payload and ensure the mapping extracts the right fields. Test fulfillment actions in isolation before integrating them into the dialog.

Analytics and user feedback

The Virtual Agent Analytics dashboard shows conversation success rates, handoff rates, and common failure points. Use Success Rate as the primary health metric; if it drops below your baseline, investigate which intents have the lowest success. Handoff Rate tells you how often conversations escalate to humans; increasing handoff rates indicate the agent is not handling conversations effectively. Review conversations marked as Abandoned or Failed to find patterns in what the agent cannot handle. Track conversation satisfaction scores if they are collected from users.

Configuration validation and testing

Before pushing Virtual Agent changes to production, validate the configuration in a test environment. Test each dialog flow using real user scenarios. Check that all referenced APIs, queues, and integrations exist. Verify that credentials and authentication are correctly configured. Run the Virtual Agent Configuration Checker if available in your release to identify missing dependencies or broken references. Use conversation transcripts from test execution to verify the agent behaves as expected for common use cases and edge cases.

Sort the Problem by Where the Conversation Stopped

Every failed conversation stops at one of a few points: the bot did not recognize the intent, it recognized the intent but did not run the right action, the action returned something unusable, or the handoff never reached a person. Find the stopping point first. Diagnosing a stalled conversation by reading the topic from the top wastes time, because the fault is usually at one point in the path.

1. Open the conversation history for one failed session and note the last message the user sent.
2. Check whether the bot’s reply to that message matched the intent the user meant.
3. If the intent was right, check the action that followed and whether it completed.
4. If the action completed, check the reply that was built from its result.
5. If the reply was wrong, check the handoff rule and the routed record.

Intent Failures and What They Look Like

Recognition faults show up as replies that answer a neighboring question. Users rephrase two or three times, then leave or ask for a person. The cause is usually one of two things: the training phrases are too narrow, or two intents share so much vocabulary that the model cannot separate them. Narrow phrases are easy to fix by adding real examples from the conversation history. Overlap is harder, and the fix is to rename or split one intent so its purpose is distinct.

Action Failures That Never Report an Error

A conversation that asks the right questions and then falls silent usually has an action that failed without telling the dialog. The reply branch then waits for a result that never arrives. Look at the action’s own log for the session, not the conversation log, because that is where the response code or the timeout appears. Confirm the payload the action sent matches the format the other system expects, and check that the mapping reads the fields the response actually contains. A mapping written against a sample response can fail quietly when the live response adds or renames a field.

When to Stop Tuning and Redesign

Tuning means small changes to phrases, branches and mappings. Redesign means changing the topic’s purpose or its steps. Tuning is the right response when a topic resolves most conversations and fails in a few predictable places. It is the wrong response when the topic’s success rate has stayed low through several rounds of tuning, because each round then masks a design that no longer fits the request. A short test of the topic’s original purpose, run with three people from the team that owns the request, usually settles which path to take.

Testing a Fix Before It Reaches Users

Test every change in a non-production copy with conversations taken from the failure log, not with phrases invented for the test. Run each old failing case, then a set of cases that the change should not affect, since a new phrase can pull a neighboring intent away from its own requests. Record which tests passed and which were intentionally left failing because they belong to a different topic.

Frequently asked questions

Why does a topic work in testing and fail for real users?

Test phrases are usually cleaner than real requests. Real users abbreviate, misspell and mix two requests in one message. Build the test set from the failure log so it reflects that wording.

Is the analytics success rate enough to judge a topic?

It is a starting signal. A high success rate can hide a topic that resolves easy cases and hands difficult ones to people. Read a sample of handed-over conversations before deciding the topic is healthy.

What should a support engineer collect before raising a platform issue?

The conversation identifier, the intent that was matched, the action name and its response, the time of the failure and the topic version. Those five items let the platform team reproduce the path without reading the whole conversation.

Can we disable a faulty topic while investigating?

Yes, if the topic can be deactivated without breaking other entry points. Replace it with a clear message that a person will help, so users are not left in a dead end while the fix is underway.

Action failures usually trace back to the connections the channel depends on. The integration patterns guide describes how those connections are usually organised, and the natural language model concept page covers the recognition side. For the handoff fields, read the escalation handoff article.

The virtual agent topic concept page sets out the parts of a topic that most of these checks depend on.