Claire_Conant
ServiceNow Employee
Options
- Post History
- Subscribe to RSS Feed
- Mark as New
- Mark as Read
- Bookmark
- Subscribe
- Printer Friendly Page
- Report Inappropriate Content
4 hours ago
Your topics are published. NLU is trained. The handoff is wired up. Everything passed in Designer. Then you go live, and something still isn't right.
That's because go-live depends on four separate layers: topics, NLU, portal configuration, and the live agent handoff. And Designer testing only covers part of each one. The rest only shows up once real users are in the system. The good news: these gaps cluster in predictable places and each one has a clear fix once you know where to look.
If your Virtual Agent is already live and something isn't working, start by identifying which configuration layer the problem is in instead.
1. Activating a topic requires a role to be assigned during setup
When you create and publish a Virtual Agent topic, the expectation is that it's ready for users. But if the topic has role restrictions on the Properties tab and no role is assigned, users who need the topic won't find it.
Before publishing, check the Properties tab on the topic and confirm that the role assignments match the users you're targeting. If the topic should be available to unauthenticated users (for example, in an external embed), it needs the Public role specifically.
2. NLU models need training and publication before they work in Virtual Agent
The gap here is in the sequence and what "published" actually means. You can create a Natural Language Understanding (NLU) model, add intents and utterances, assign the model to a topic, and test in the Designer without the model being fully published. The Designer test may even return partial results, which makes it look like NLU is working when it isn't fully deployed.
For NLU to work reliably in production, the model needs to be trained on your utterance data and then explicitly published. An unpublished or draft model won't appear in the NLU model selector on Virtual Agent topics. If you've added intents or changed utterances since the last publish, those changes aren't live until you retrain and republish.
Important: Each intent belongs to exactly one NLU model and cannot be shared across models. If you created an intent in one model but assigned a different model to your topic, the intent won't appear in the Associated Intent list. There is no error message for this. The intent simply doesn't show up.
3. The Service Portal Virtual Agent widget requires configuration beyond embedding
After adding the Virtual Agent widget to a Service Portal page, you also need to match the widget configuration to the portal scope. Topic visibility depends on how both are set up.
If you're embedding Virtual Agent in a scoped portal like the Employee Service Center (ESC), topics created in the Global application scope won't appear. The Virtual Agent panel loads and looks normal, but some or all topics are missing from the conversation. To fix this, create topics in the matching application scope for that portal.
If you're embedding Virtual Agent in an external website via iframe, each topic needs the Public role assigned individually. Without it, the topic is invisible to external users even though it's active and published in the Designer. The result looks the same: the panel appears, but topics are missing.
4. Live agent handoff requires three separate configurations that work together
Getting Virtual Agent to hand off to a live agent involves more setup than the topic flow itself. Three configuration layers need to align, and a gap in any one of them can cause the handoff to fail without a visible error.
The Live Agent Support topic needs to be active and published.
This is the base system topic that handles the handoff. If it's inactive or unpublished, the transfer has nowhere to go. Go to sys_cs_topic.list and confirm that both the Active and Published fields are checked.
The Fulfiller UI on the chat setup record needs to be set to Agent Workspace.
If it's set to Connect instead, live agent routing fails. You may see an invalid queue message in the logs but no error visible to the user. Go to sys_cs_live_agent_setup.list and verify the setting.
The Advanced Work Assignment (AWA) queue needs a routing condition that matches how interactions are created.
Interactions are created in a Work in Progress state. If the AWA queue Work Item Routing Condition filters on a different state (like New), no work items are created, and agents never see the request. Check the queue under Advanced Work Assignment > Settings > Queues.
These three checks cover the most common failures of live agent handoff. If the handoff is still not connecting after verifying all three, review the additional root causes in the companion article: Virtual Agent not working after setup: find the layer that's broken
5. The Virtual Agent Designer test console does not replicate a full production environment
Treating the Designer test as the final validation step can lead to issues that only surface after go-live. The built-in test console is useful for verifying topic flow logic, but it doesn't cover everything that happens in a production deployment.
Several things behave differently in the Designer than in a Service Portal or Microsoft Teams deployment. Role and condition restrictions on topics aren't evaluated the same way as they are in an actual end user session. NLU predictions may return partial results if the model isn't fully published. Topics that rely on portal-specific context or channel-specific rendering (like file attachments or carousel images in Teams) may pass the Designer test but fail in the deployment channel.
After validating topic logic in the Designer, test in the actual portal or channel where users will interact with Virtual Agent. If you're deploying to Microsoft Teams, test in Teams. If you're embedding in an external portal, test in that portal with an external user session. This second stage of testing surfaces the issues that the Designer doesn't catch.
Where to go from here
Every one of these gaps has a fix once you know where to look. Assign the role, publish the model, match the scope, align the three handoff settings, and what passed in Designer becomes what your users experience at go-live. If you're already past setup and need to identify which configuration layer the problem is in, see Virtual Agent not working after setup: find the layer that's broken.
Note: Licensing, usage, and entitlements can vary by release, setup, and contract. Always confirm the specifics for your environment.
