Building an Agentic NLU agent

Use this guide to create and configure a working Agentic NLU Virtual Assistant (VA), from initial agent setup to a fully designed conversation flow.

Prerequisite

Agentic NLU is a gated feature and must be enabled for your account. For more information, see the Agnetic NLU AI engine page.

The process covers two phases:

1. Create the agent. Complete the setup wizard to configure your agent's basic settings. At the end of this phase, you have an empty agent with no active flow.

2. Design the flow. Define your intents and parameters, then configure your Agentic nodes to build a working conversation flow.

Create the agent

1

Choose the right agent type

Selecting the Telephony agent type to begin the creation process.

When creating an agent, you are prompted to select an agent type. To access the features described on this page, choose Telephony as your agent type.

Limited availability

Currently, Agentic NLU is only available for voice agents.

2

Choose the right AI engine

Choosing the Agentic NLU engine to enable autonomous decision-making and context-based goals.

When prompted to select an AI engine, select Agentic NLU.

No backward compatibility

If you create an agent with the Agentic NLU AI engine, you cannot change it to Hybrid NLU/ Traditional NLU by editing or duplicating the agent, and vice versa.

3

Fill in the Details page

The following fields are available for configuration:

Field	Options	Description
Region	List of available options	Select the geographical data center where your agent’s data and traffic will be processed. Available options are the United States and Europe.
Agent Name	Text	A unique internal label used to identify the agent within your dashboard.
Agent Description (Optional)	Text	A summary of the agent’s use case. Provides context to the AI engine to improve goal alignment and serves as an internal reference.
API Key	List of available options	Select the specific Vonage API Key that will be used to authenticate and bill the agent’s activity.
Language	List of available options	Define the primary language the agent will use to communicate and process NLU intents. Currently, only English (United States) is available
Voices	List of available options	Select the Text-to-Speech (TTS) voice profile and accent that best fit your brand's persona.
Time Zone	List of available options	Set the agent's local time zone, which dictates how time-based conditions and scheduling logic are executed.

You can view and edit these details later.

Language

Once selected, you cannot change the agent's language.

4

Choose the right VA template

The Choose Template screen offers the option to start from a blank canvas or use a preconfigured Agentic NLU Template.

You can create an Agentic NLU agent using two different approaches:

• Agentic NLU Template: AI Studio provides a ready-made template that pre-configures the Agentic Classification and Agentic Capture nodes in an optimal "hub-and-branch" model. This is the fastest way to maximize the benefits of the Agentic NLU engine with a proven architectural structure.

• Start from Scratch: For full control over your conversation logic, you can start from a blank canvas and manually add Agentic nodes from the node canvas. This allows you to integrate Agentic reasoning into existing rule-based workflows or create unique hybrid architectures.

5

Choose the right type of Event

To utilize Agentic NLU, you must select either Inbound Call or Outbound Call as your triggering event:

• ​Inbound Call: The most common trigger; the agent activates immediately when a user calls the assigned number.

• ​Outbound Call: Enables the agent to dial a user’s number to start a session proactively.

• ​End Call: A post-session trigger that allows the agent to continue specific background tasks or data processing after the main call has ended.

• ​API Event: Uses 3rd-party integrations to trigger a conversation based on external data or system prompts.

Event Limitation

End Call and API Event are currently unavailable for the Agentic NLU engine.

6

Click Create to finalize the setup

Once you click Create, you are redirected to the Agent canvas. This is your primary workspace for building and managing the agent's logic.

---

Design the flow: Agentic intents, parameters, and nodes

Designing an Agentic NLU flow differs from Traditional or Hybrid NLU flows. Instead of mapping every possible scenario, you provide the agent with the "ingredients" (Agentic Intents and Parameters) and use Agentic nodes to manage the conversation autonomously.

In a typical Agentic flow, all conversation logic is driven by the interaction between these elements:

1. Preparation: Before placing nodes, define your Agentic Intents (to establish context) and Parameters (to identify the data that needs to be collected).

2. Routing (Classification): Start your flow with an Agentic Classification node. This acts as the "hub," evaluating user input against your defined intents to determine the next step.

3. Fulfillment (Capture): Link identified intents to Agentic Capture nodes. These "specialists" handle multi-turn collection and re-confirmation, ensuring all required parameters are accurately gathered.

4. Path Management: Configure all exit paths from these nodes. You must specifically account for Intent Changes (re-routing), Escalation (human handoff), and Failed outcomes.

Pro tip

Always route the Escalation and Failed paths to a dedicated fallback flow. This should include a seamless human handoff or a clear explanation to the user to prevent a "dead-end" experience.

1

Add Agentic Intents

Agentic Intents define the goals your assistant can recognize. Each intent includes:

• A name (short and descriptive)

• A natural-language description of the intent (similar to an LLM prompt)

You can define Agentic Intents in the Properties panel of your AI Studio agent. Once created, they can be reused across the agent’s flow.

Best practices: Description field

• Separate intents from parameters: Use intents to capture the primary action; use parameters to capture the specific details.

  • Avoid: Order_Pizza, Order_Burger, Order_Salad as separate intents.

  • Recommended: Single Order_Food intent + $Food_Item parameter.

• Keep intents semantically distinct: Overlapping intents cause misclassification.

  • If two intents are too similar, merge them into one (e.g., Reset_Password + Unlock_Account → Account_Access).

  • Use follow-up conversational turns to determine the specific action needed.

• Account for natural language variation: Intent descriptions should cover informal phrasing, abbreviations, and, for voice, common ASR transcription errors.

Pro tip

Use an AI tool (Gemini, ChatGPT, Claude) to draft your Description. Paste these best practices in, describe your intent in plain English, and refine the output based on testing in AI Studio.

Example of the Agentic Intents, where names and descriptions are defined to guide the agent's classification logic.

Best practice

Always add “End conversation” and “Talk to human agent” intents to your agents to improve the performance of the Agentic NLU AI engine.

2

Add Agentic Parameters

Agentic Parameters describe the information your Virtual Assistant needs to collect. Because they do not rely on entities, you can use natural language instructions instead of maintaining complex entity lists.

You can define Agentic Parameters in the Properties panel of your AI Studio agent. Once created, they can be reused across the agent’s flow.

There are three types of these parameters: Custom, System, and User parameters.

Parameter Type	Description	Validity	Editable?	Examples
Custom	Manually created by builders to store session-specific data.	Session-only: Reset once the interaction ends.	Yes: Name and Value.	Booking_ID
System	Automatically generated for every Virtual Agent.	Session-only: Reset once the interaction ends.	No.	Agent_ID
User	Used for data that remains constant across multiple interactions.	Cross-Session: Follows the caller across different VAs in the same account.	Yes: Name and Value.	User_ID, User_Language_Preference

Conditions node: Parameter logic

The Conditions node supports both Custom and User parameters, applying qualitative and quantitative logic across all data types.

Type compatibility:

• Quantitative Logic: Use Number, Date, Time, or DateTime for mathematical or chronological comparisons (e.g., greater than or before).

• Qualitative Logic: The String type is ideal for text-based matching but does not support quantitative operations.

Setting up Custom parameters

Name	Options	Description
Name	Text	A name for your parameter.
Type	List of available options	Defines the data format the system expects to store. Available options are String, Number , DateTime, Date, Time.
Description	Text	Explains the parameter's role to the AI. This provides general context so the agent understands the "job" of this parameter.
Format	Text	The strict logic the AI uses to extract and validate input. This is where you define exactly how the parameter value must be structured.
Value	Text	Allows you to specify a pre-defined value of the parameter.

Date, Time, and DateTime formats

These parameter types are automatically stored in standardized ISO formats:

• Date: YYYY-MM-DDT00:00:00±HH:MM.

• Time: 1970-01-01THH:MM:SS±HH:MM.

• DateTime: YYYY-MM-DDTHH:MM:SS±HH:MM.

Note: When selecting Date, Time, DateTime, or Number, the Format field locks automatically because these types rely on fixed system logic. The Description field remains available for providing context to the AI.

Best practices: Description field

• Focus on the Role: Tell the AI what the information is, not how to get it.

  • Example: "This is the caller's 8-digit bank account number used for identity verification."

• Keep it Concise: Limit this to 1–2 lines.

• Avoid Logic: Do not define extraction rules here; the AI will ignore them in this field. Use the Format field for rules.

Best practices: Format field

The AI relies strictly on this field to pull data from a caller's sentence. To ensure high accuracy, include the following in your instructions:

• Length: State exact, minimum, or maximum character counts.

• Composition: Define allowed characters (e.g., "digits only," "uppercase letters").

• Structure: Describe the sequence (e.g., "starts with two letters followed by four numbers").

• Restrictions: Explicitly state what is forbidden (e.g., "no spaces," "no decimals").

• Examples: Always provide 2–3 correct examples and 2–3 incorrect examples to "prime" the LLM.

Pro Tip

Use an AI tool (Gemini, ChatGPT, Claude) to draft your Format field. Paste these best practices in, describe your intent in plain English, and refine the output based on testing in AI Studio.

Format field examples

The following examples cover common String-type Custom Parameters. Each includes a breakdown of the rules and a ready-to-copy text for the Format field.

Date

Format	YYYY-MM-DD
Length	Exactly 10 characters.
Structure	Four digits (year), hyphen, two digits (month), hyphen, two digits (day).
Restrictions	No slashes. No spelled-out month names. Leading zeros required.
Correct	2024-05-14 1999-12-01 2025-01-31
Incorrect	05/14/2024 (slashes) May 14th 2024 (spelled-out month) 2024-5-14 (missing leading zero)

📋 Example prompt

The value must represent a date exactly in the YYYY-MM-DD format. It must be exactly 10 characters long. It must consist of four digits for the year, a hyphen, two digits for the month, a hyphen, and two digits for the day. Do not use slashes or spell out the month. Correct Examples: 2024-05-14, 1999-12-01, 2025-01-31 Incorrect Examples: 05/14/2024, May 14th 2024, 2024-5-14 (missing leading zero).

Time (24-hour)

Format	HH:MM
Length	Exactly 5 characters.
Structure	Two digits (00-23), colon, two digits (00-59).
Restrictions	No AM/PM designations.
Correct	08:30 14:00 23:59
Incorrect	8:30 (missing leading zero) 02:00 PM (AM/PM) 24:00 (invalid hour)

📋 Example prompt

The value must represent a time in the 24-hour format (HH:MM). It must be exactly 5 characters long. The first two characters must be digits between 00 and 23. This is followed by a colon ":". The last two characters must be digits between 00 and 59. No AM/PM designations are allowed. Correct Examples: 08:30, 14:00, 23:59. Incorrect Examples: 8:30 (missing leading zero), 02:00 PM (contains AM/PM), 24:00 (invalid hour).

Currency (USD)

Format	$X,XXX.XX
Structure	$ symbol, digits, thousands separated by commas, decimal point, exactly two cent digits.
Restrictions	No spaces.
Correct	$1,250.00, $50.75, $1,000,000.99
Incorrect	1250 USD (missing symbol) $50.7 (missing cent digit) $1000.00 (missing comma)

📋 Example prompt

The value must represent a monetary amount in US Dollars. It must start with a "$" symbol, followed by digits. Thousands must be separated by commas. It must end with a decimal point and exactly two digits for the cents. No spaces are allowed. Correct Examples: $1,250.00, $50.75, $1,000,000.99. Incorrect Examples: 1250 USD, $50.7, $1000.00 (missing comma).

Email address

Structure	Local part, @ symbol, domain name, valid top-level domain (e.g., .com, .org, .co.uk).
Restrictions	No spaces.
Correct	[e-mail] [e-mail] [e-mail]
Incorrect	user.name @ domain.com (spaces) user@domain (missing TLD) www.website.com (not an email)

📋 Example prompt

The value must be a valid email address structure. It must contain a local part, an "@" symbol, and a domain name. It must not contain any spaces. It must end with a valid top-level domain (e.g., .com, .org, .co.uk). Correct Examples: [e-mail], [e-mail], [e-mail]. Incorrect Examples: user.name @ domain.com (contains spaces), user@domain (missing top-level domain), www.website.com (not an email).

Booking ID

Length	Exactly 6 characters.
Structure	First 3 characters: letters A–Z or a–z. Last 3 characters: digits 0–9.
Correct	ABC123, MNO456, XYZ009, abc123, mno321

📋 Example prompt

The value must be exactly six characters long. The first three characters must be letters between A to Z (uppercase) OR a to z (lowercase). The last three characters must be digits between 0 and 9. Correct Examples: ABC123, MNO456, XYZ009, abc123, mno321.

Example of a Booking ID configuration, differentiating the Description (context) from the Format (logic).

System Parameters

Below is the list of System parameters available in the Agentic NLU AI engine:

Name	Type	Description
CALLER_PHONE_NUMBER	String	The caller's telephone number.
CALL_START_DATE	DateTime	The date of the call.
CALL_START_TIME	DateTime	The time when the agent picked up the call.
CALL_DIRECTION	String	Categorizes the interaction as 'Inbound' or 'Outbound'. Used to enforce call-type restrictions and ensure the agent only executes tasks relevant to the current call direction.
CALL_TRANSCRIPTION	String	Stores the transcription of the interaction.
TRIGGERED_BY_SESSION_ID	String	Identifies the specific session that initiated or "triggered" the current interaction.
VAPI_CALL_ID	String	The Call ID from the Voice API in the dashboard. This allows you to match calls between the Studio log and the Voice API dashboard log.
SESSION_ID	String	A sequence of numbers and letters to identify the specific session.
AGENT_ID	String	The agent's ID.
CONVERSATION_ID	String	The Conversation ID/UUID sent from Vonage API.
AGENT_PHONE_NUMBER	String	The agent's virtual phone number.
CALL_START_DATETIME	DateTime	The date and time that the interaction started.

User Parameters

There are two preconfigured user parameters available in AI Studio:

• Account_Name for storing the business account name related to the call.

• Phone_Number for storing the caller's phone number.

Limitation

User parameters do not have Description and Format fields and cannot be used with the Agentic nodes. Instead, user parameters need to be set by using the “Set Parameter” node.

3

Add an Agentic Classification node

The node drawer is divided into three functional sections:

• Setup: Define the inputs, the scope of intents, and escalation thresholds.

• Configuration: Fine-tune the Communication Layer and LLM response behavior.

• Test: Perform isolated testing of your classification logic.

Setup

Field	Options	Description
User Input	List of parameters	A parameter that stores the caller's response and serves as the primary input for the Agentic Classification node.
Agentic Intents	List of options	A list of intents in scope for this node. The node will only search for matches within this list.
Maximum Number of Attempts	1-6	The maximum number of attempts the node makes to identify an intent during a live conversation. If the number is exceeded, the node triggers the Escalation path. The default value is 3.
Detected Intent	List of parameters	A parameter that stores the intent identified by the engine.
Agentic Response	List of parameters	A parameter that stores the response generated by the engine, particularly useful when no intent is initially detected.
Escalation Reason	List of options	A parameter that stores why an escalation was triggered. The available reasons are: A parameter that stores why an escalation was triggered. The available reasons are: “ATTEMPTS_EXCEEDED”: the number of attempts exceeded the defined maximum. “USER_DENIAL”: a caller refused to provide a valid response. “USER_INFORMATION_GAP”: a caller either did not have the required information, cannot find it, or needs clarification about what is being asked. “HUMAN_HANDOFF”: a caller explicitly requests a human, support agent, or other channel. “USER_INITIATED_TERMINATION”: a caller expresses emotional frustration, dissatisfaction, or explicitly indicates a desire to stop or end the conversation.

Configuration

Communication Layer

The Communication Layer is a permanent background flow of Speak and Listen nodes that manages the autonomous conversation loop. It automatically delivers the agent's responses and captures user input at each stage of the interaction.

• Always Active: To ensure consistent interaction, the Communication Layer cannot be disabled.

• Fixed Audio Settings: The Speak node settings within this layer are pre-configured and cannot be modified.

Within the Agentic Classification node configuration, you can adjust the following Listen node settings for this layer:

Communication Layer

Field	Options	Description
Detect Silence	0.4-5 seconds	The amount of time the agent waits after the user stops speaking to determine whether the parameter is filled and to continue the flow. The default value is 0.4 seconds.
No input	1-60 seconds	The amount of time the agent waits for a caller's input. If the time limit is exceeded, the agent triggers the Retry logic until it reaches the last retry, then moves to the No Input flow. The default value is 10 seconds.
Context keywords	Text	Context keywords improve recognition quality if certain words are expected from the user.
Enable Node Noise Sensitivity	On/Off 10-100	When no value is provided here, the agent-level sensitivity settings will apply to the node as well. When a value is provided for the Node noise sensitivity, these settings will override the agent-level sensitivity settings. The default value is 40.

Other configuration settings

Field	Options	Description
Waiting Time	3-10 seconds	The maximum time to wait for the NLU engine response. If the time is exceeded, the Failed exit path is triggered. The default value is 5 seconds.
Agentic Response Guidelines	Text	An optional field for providing natural language instructions (LLM prompting) that give limited control over how the node phrases its responses. Empty by default.

Best practices: Agentic Response Guidelines

• Only use this field after optimizing the Description field of your Agentic Intents and the Format field of your Agentic Parameters. Those have a far greater impact on accuracy.

• Use it only to define tone, brand terminology, and Text-to-Speech nuances.

• Do not use this field to override logic that is pre-configured by the platform:

  • Redefine the node's role, e.g., "You are a virtual agent for XYZ handling ABC."

  • Script exit path responses, e.g., "In case of escalation, say XYZ."

  • Set exit path conditions, e.g., "If the caller asks for ABC, trigger escalation."

• Start with no guidelines and add them only when testing reveals a specific gap. Keep to a maximum of 4.

• Where possible, include correct and incorrect response examples to improve accuracy, for example:

  • Correct: support at a-b-c dot org.

  • Incorrect: [e-mail].

Test

You can click Test to test your configured Agentic Classification node without linking it to other nodes. In this section, you can:

1. Provide a value for “User Input”.

2. Check the generated “Detected Intent” and “Agentic Response”.

If you are unhappy with the results, you can update:

• the Intent Description field from the Agentic Intents tab

• the Agentic Response Guidelines field for a given Agentic Classification node

Using the Test console to verify how the Agentic Classification node responds to user inputs that fall outside the defined intents.

Agentic Classification node exit paths

• Intent: This path is triggered when the Agentic Classification node successfully detects an intent. Every intent selected under the Agentic Intents of an Agentic Classification node will have a unique exit path.

• Escalation: This path is triggered when an escalation scenario is detected based on the caller's response.

• Failed: This path is triggered when the node fails to run due to an internal error.

Pro tip

If the Failed exit path is triggered frequently, it likely indicates an Agentic NLU timeout. To resolve this, increase the Waiting time from the default 5 seconds up to a maximum of 10 seconds.

4

Add Agentic Capture nodes

The node drawer is divided into two functional sections:

• Setup: Define the inputs, parameter scope, and escalation thresholds.

• Configuration: Fine-tune the "Communication Layer" and Agentic response behavior.

Setup

Field	Options	Descriptions
User Input	List of parameters	A parameter that stores the caller's response and serves as the primary input for the Agentic Capture node.
Current Intent	List of options	The active goal for the node; critical for detecting if a caller switches topics mid-flow.
Agentic Parameters	List of options	The list of specific parameters this node is tasked with filling.
Maximum Number of Attempts	1-3	The maximum number of attempts the node makes to capture a parameter during a live conversation. If the number is exceeded, the node triggers the Escalation path. Every parameter has its own Maximum Number of Attempts. The default value is 3.
Reconfirm the captured parameter value with the end user	Selected/ unselected	Whether the agent should repeat the captured value back to the caller. You can use this option to ensure accuracy against potential ASR (Automatic Speech Recognition) transcription errors.
Agentic Response	List of parameters	This parameter stores the response from Agentic Capture and is useful when the parameter capture task is ongoing or an escalation scenario is detected.
Escalation Parameter	List of parameters	This stores the parameter name which caused the escalation path to be triggered in Agentic Capture node.
Escalation Reason	List of options	A parameter that stores why an escalation was triggered. The available reasons are: “ATTEMPTS_EXCEEDED”: the number of attempts exceeded the defined maximum “USER_DENIAL”: a caller denied to provide a valid response “USER_INFORMATION_GAP”: a caller either did not have the required information, cannot find it, or needs clarification about what is being asked “HUMAN_HANDOFF”: a caller explicitly requests a human, support agent, or other channel “USER_INITIATED_TERMINATION”: a caller expresses emotional frustration, dissatisfaction, or explicitly indicates a desire to stop or end the conversation

Configuration

Communication Layer

The Communication Layer is a permanent background flow of Speak and Listen nodes that manages the autonomous conversation loop. It automatically delivers the agent's responses and captures user input at each stage of the interaction.

• ​Always Active: To ensure consistent interaction, the Communication Layer cannot be disabled.

• Fixed Audio Settings: The Speak node settings within this layer are pre-configured and cannot be modified.

Within the Agentic Capture node configuration, you can adjust the following Listen node settings for this layer:

Communication Layer

Field	Options	Description
Detect Silence	0.4-5 seconds	The amount of time the system waits after the caller stops speaking to determine whether the parameter is filled and to continue the flow. The default value is 0.4 seconds.
No input	1-60 seconds	The amount of time the agent waits for a caller's input. If the time limit is exceeded, the agent triggers the retry logic until it reaches the last retry, then moves to the No Input flow. The default value is 10 seconds.
Context keywords	Text	Context keywords improve recognition quality if certain words are expected from the caller.
Enable Node Noise Sensitivity	On/Off 10-100	If no value is provided here, the agent-level sensitivity settings will also apply to the node. When a value is provided for the Node noise sensitivity, these settings will override the agent-level sensitivity settings The default value is 40.

Other Configurations

Field	Options	Description
Waiting Time	3-10 seconds	The maximum time to wait for the NLU engine. The default value is 5 seconds.
Agentic Response Guidelines	Text	An optional field for providing natural language instructions (LLM prompting) that give limited control over how the node phrases its responses. Empty by default.

Agentic Capture node exit paths

• User input: This path is triggered once all assigned parameters within the node have been successfully captured.

• Intent Change: This is triggered when an intent change is detected within the caller's response.

• Escalation: This is triggered when an escalation scenario is detected based on the caller's response.

• Failed: This is triggered when the node fails to run due to an internal error.