A virtual agent is the NLU (natural language understanding) part of a project. It works out what the customer wants by matching their message to an intent you trained with example utterances. It also picks out details from the message, such as a date, an amount or a city (entities), so the intent's action flow can use them. It then runs that action flow.
An AI agent works differently: it reasons with a large language model and calls tools. See Creating an AI Agent. Advanced Conversation Routing lets an LLM help the virtual agent choose an intent.
📝 Note: A Virtual Agent node works only with a trained virtual agent, and a project cannot be published while a Virtual Agent node uses a virtual agent that was never trained. Train it from its intents page, as described in Training and Testing.
Intents, utterances and entities
| Building block | What it is | Example |
|---|---|---|
| Intent | Something the customer wants. Each intent runs its own action flow. | weather |
| Utterance | An example sentence you train an intent with. | "What's the weather like in Istanbul today?" |
| Entity | A detail picked out of the customer's message. | The city Istanbul, picked out by the city entity |
The intent's action flow can use the entity's value as context.entity.<name>. For example, the weather action sends context.entity.city to a weather service. If the customer's message does not include the city, the Ask Missing Slot node asks the customer for it. There are three kinds of entity: ready-made system entities (Date, Number, Currency and so on), list entities and regex entities. See Entities.
One virtual agent per project language
The project wizard creates one virtual agent for each project language and names it after the project and the language (<Project>-<LANG>, for example CustomerCare-EN). Adding a language to the project adds a virtual agent for it. You cannot create, rename, delete or share a virtual agent yourself, and you cannot remove a language from a project after adding it. See Creating a Project and Multilingual Projects.
To open a virtual agent, use the Virtual Agent menu in the project app bar. It takes you to the virtual agent's intents page. In a project with several languages, the menu is called Virtual Agents and lists one virtual agent per language.
How a flow uses it: the Virtual Agent node
A flow hands the customer's message to a virtual agent through a Virtual Agent node.
| Input | What it does | Default |
|---|---|---|
| Virtual Agent | The virtual agent that classifies the message. | Required, no default |
| Utterance | The text to classify. | The customer's last input |
| Try Count | How many fallbacks in a row the node allows before it gives up. | 2 (range 0-10) |
On each turn, one of three things happens:
- One intent matches. The intent's action flow runs. When the action flow ends, the node continues through its
outoutput. - Nothing matches. If the top score is at or below the Confidence Threshold, the message counts as unmatched. The fallback intent's action runs, the attempt counts as a try, and the node waits for the next message. After Try Count fallbacks in a row, the node leaves through its
fallbackoutput. - Several intents match almost equally. If other intents score nearly as high as the top one and are also above the threshold, the customer is asked to choose. With five candidates or fewer, they appear as buttons plus an Other button. With more than five, the customer gets a text question instead. To change the wording, go to Prompts > System Messages and open Multiple Intent Match.
💡 Tip: The choice buttons show the intent names exactly as you wrote them. Name intents the way a customer should read them, for example
Track my orderrather thanORD_STATUS_01.
If you only need to know the intent, use the Intent Recognition node instead. It writes the result to a variable. It does not run an action flow, retry or ask the customer to choose.
You can use the Virtual Agent node in main flows, subflows, surveys and SR fallback flows. You cannot use it inside an intent's action flow.
Virtual agent settings
A virtual agent has one setting, its Confidence Threshold (default 0.5, range 0-1). Open Project Settings > Virtual Agents and select the virtual agent. The same page also offers the prebuilt intent templates for the virtual agent's language. For how to choose a threshold, see Training and Testing; for templates, see Importing Intents.
What a virtual agent is not
- It is not an LLM. It matches messages to the intents you trained. What the customer hears or reads comes from the intent's action flow.
- It only knows the intents you trained. A request that no intent covers ends in fallback, or in the wrong intent if one scores above the threshold.
- It is not shared. Each virtual agent belongs to one project and one language.
Building a virtual agent
- Intents and Utterances: create intents and add example utterances.
- Importing Intents: bring in intents from an FAQ file, from another virtual agent's utterances or from a template.
- Entities: pick out details from the customer's message.
- Intent Actions: design the flow each intent runs.
- Training and Testing: train the virtual agent, test it, tune the threshold and publish.