Configure the start and exit behavior of an agentic virtual agent - Genesys Cloud Resource Center
Configure the start and exit behavior of an agentic virtual agent
AI-generated summary
Genesys Cloud enables configuration of agentic virtual agent start and exit behaviors through the AI Studio interface, providing comprehensive control over agent initialization, data handling, and interaction termination. Starting context originates from Architect Virtual Agent flows and allows administrators to pass participant data and variables to agents at interaction initiation through the Configuration tab, where starting variables are defined by specifying name, data type, and description.
The platform supports masking variable values from agents to prevent access to sensitive data such as authentication tokens, UUIDs, and internal IDs. Masked values reduce token consumption, lower latency, and limit unnecessary data exposure while allowing agents to function normally. Variable names support up to in length, and start context size management is critical for optimal performance. Genesys recommends maintaining small, relevant start contexts to prevent excessive token consumption and runtime failures. If the total size of unmasked start context values exceeds platform limits, the Call Agentic Virtual Agent action returns an exit reason of "request.too.large." Masked values do not count toward this size limit.
Start context variables should use clear, specific naming conventions and include descriptive explanations of their purpose. Sensitive data such as credit card numbers should not be transmitted, and only primitive data types are supported. End context configuration enables agents to send data to external targets upon interaction completion, with agents able to transmit up to 50 output variables with names up to and string values up to Published agents cannot have previously selected output variables deselected, though additional variables can be added in subsequent publications.
Exit behavior is configured through the Configuration tab's Session end section, where administrators define the Exit response message and Escalation response message for transfers to human agents. Two built-in tools—end_conversation and escalate_to_human_agent—enable interaction termination and are referenced through agent guidelines rather than configured as editable tools. Agent escalation settings allow agentic virtual agents to transfer interactions to human agents upon participant request, with escalation enablement inherited from the bot flow's event handling settings.
Comfort statements can be enabled under Wait Experience settings to display reassurance messages during processing pauses. Contextual comfort statements deliver action-specific messages tied to tool calls, referencing the actual operation being performed rather than providing generic placeholder statements. These statements are supported only on agent model v2 for voice interactions and are unavailable on agent model v1 or for digital interactions.
Advanced configuration settings provide enhanced control over agent behavior through repetition handling, which enables preset checks to detect when agents or customers send repeated or nearly identical messages. Two preset checks are available: agent repetition and customer repetition, with configuration options including sensitivity levels and the number of prior messages to evaluate. Users can add up to two scenarios each for customer and agent repetition with custom instructions explaining how the agent should handle each scenario.
The agentic virtual agent profile contains five main sections: Agent Tools, Knowledge, A2A, Configuration, and Guardrails, accessible through a navigation interface with a preview widget. Incomplete sections are marked with an icon, and agents can be saved with incomplete sections but cannot be published until all sections are fully completed. Prerequisites include Virtual Agent enablement in the organization and appropriate AI Studio permissions for agentic virtual agents
Virtual Agent enabled in your organization. For more information, contact your designated Customer Success Manager.
AI Studio permissions for agentic virtual agents. For more information about all the required permissions, see AI Studio permissions.
You can provide any starting context that helps the agentic virtual agent at the start of an interaction. Then, define how the agent behaves when ending a session on the Configuration tab.
The start context originates from the Architect Virtual Agent flow. For example, if the flow author wants to pass some Participant Data to the agentic virtual agent.
Configure starting context
Click Menu > Orchestration > AI Studio > Agentic Virtual Agents.
(Optional) To search for a specific agent, start typing the name of the agent in the search box. As you type, the matching agents are shown.
To open an AI agent, click the agent’s tile. The Agent profile view opens.
Select the Configuration tab.
Under Start context, click Add. The right pane expands.
In the right pane, enter these details:
Name: The name of the variable. For example, “customer_name.”
Type: The data type of the variable.
Description: A short description about the variable.
(Optional) Enable the Mask value from agent toggle, which prevents the agentic virtual agent from reading the raw value. This option is available for string variables only.
Click Create.
Add as many starting variables as needed for your agent.
Note: If the system masks a starting context value from the agent, the masking state is indicated by the icon, which appears next to the variable name.
Mask variable values from the agent
If the Mask value from agent toggle is enabled for a starting context variable, the agent is aware that the variable exists but cannot view or use its actual value. This option is recommended for sensitive or non-meaningful values such as authentication tokens, UUIDs, and internal IDs.
Benefits include:
Reduced exposure: Limits the agent’s access to sensitive or unnecessary values
Improved performance: Reduces context size, which can help lower latency
The agent continues to function as expected, but it does not reference or reproduce the masked value.
Start context size limits
Genesys recommends keeping the start context small and relevant. An excessively large start context increases token consumption and can cause the agent to fail at runtime.
Variable name length: Each start context variable name can be up to 200 characters long. If you add a new variable whose name exceeds this limit, you cannot save the agent until you shorten the name.
Variable value size: The total size of the start context values that are sent to the agent at runtime is limited. Values that are masked from the agent by using the Mask value from agent option do not count toward this limit.
If the total size of the values exceeds the limit, the agent cannot process the interaction. In Architect, the Call Agentic Virtual Agent action follows the Failure path and returns the exit reason request.too.large. To avoid this issue, reduce the size of the start context values and ensure that any values the agent does not require, such as authentication tokens, API keys, and internal IDs, are masked.
Tip: Pass only the start context that the agent needs. Reuse existing values through linking and mask values that are not meaningful to the agent to help keep the start context within the size limit.
Do / Don’t
Example
Explanation
customer_name
customer_phone_number
Be clear and specific.
in_person_banking_available
(Boolean)
Provide any previously gathered information associating with the brand.
credit card number
Data too sensitive to transmit. It also does not contain underscores.
list of orders
The agent can only handle primitive data (string, number, and so on).
Do / Don’t
Example
Explanation
The user’s firstname, which you should use when addressing them throughout the conversation.
Explains what it is and how to use it. For example, when referring to the customer’s name.
The user’s phone number. It is eight digits long and is used to verify that you are speaking to the correct user.
Explains what it is and how to use it. Provides enough context. For example, when referring to the customer’s phone number.
This does stuff.
Too vague and no context.
Configure the ending context
The end context configuration allows you to send data from the agentic virtual agent to an external target such as an Architect Virtual Agent flow, when an interaction ends.
For example, the configured output variables appear in the Call Agentic Virtual Agent action in Architect when the linked agentic virtual agent contains end context variables. The flow author can then use these output variables in the calling flow for further processing. For more information about the Call Agentic Virtual Agent action, see Call Agentic Virtual Agent action.
Set up output variables
Optionally select the variables that you want to send to the calling flow in Architect from the tool input, tool output, or start context tab.
Under End context in the Configuration tab, click Select. The End context panel appears.
In the Tool Input tab, select the input variables that you want to send to the calling flow in Architect.
In the Tool Output tab, select the output variables that you want to send to the calling flow in Architect.
In the Start Context tab, select the start context parameters that you want to send to the calling flow in Architect.
Click Update.
Notes:
After you publish an agent, you cannot cancel the selection the output variables that you previously selected. However, you can add more variables and publish the agent again.
An agent can send up to 50 output variables by default, with names up to 200 characters. Both limits are configurable: use end.context.properties.max to change the number of output variables and end.context.properties.name.length.max to change the maximum name length. Strings exceeding 2000 characters are truncated, which is indicated by an ellipsis. For more information, see Limits for agentic virtual agents.
If the system masks the value of an output variable or starting context variable from the agent, the masking state is indicated by the icon, which appears next to the variable name.
Enable comfort statements
Under Wait Experience, toggle Comfort statements on or off. Use this setting to control how your agent behaves during processing pauses. When enabled, the agent plays reassurance messages to maintain engagement and reduce perceived delays while the customer is waiting.
Contextual comfort statements
In addition to the general comfort statement rotation controlled by this setting, individual tool calls can define their own contextual comfort statement through pre-instruction. Unlike the standard rotation, which plays a randomly selected, generic message (for example, “One moment please”) regardless of what the agent is doing, a contextual comfort statement is tied to a specific tool call and references the actual action being performed (for example, “I’m submitting that refund request now, one moment”).
To implement contextual comfort statements, you must define tool-level pre-instructions.
If the Comfort statements setting is on, and a contextual comfort statement is defined for the tool, both are played.
If the Comfort statements setting is off, and a contextual comfort statement is defined for the tool, only the contextual statement is played on that tool call.
Before calling this tool, let the user know you are checking their order now.
The comfort statement names the actual object being acted on (“their order”) instead of a vague “that” — so it feels grounded and specific to what the user just asked about.
Before calling this tool, let the user know that you are submitting a refund request so the user knows the request is in progress.
The comfort statement describes exactly what the tool call is doing — not a vague filler, and not an overstatement.
Before calling this tool, say to the user “I am checking your order now, please wait.”
It specifies the exact wording rather than describing the intent. Instead of leaving the agent to generate its own phrasing, a scripted line in quotes gives the agent a fixed sentence to say, with only slight variation allowed, making the output predictable and consistent.
Note: Contextual comfort statements are only supported on agent model v2 and for voice interactions. They are not available on agent model v1 or for digital interactions.
Define exit behavior
Under Session end in the Configuration tab, configure the following options:
In the Exit response field, enter the message that the agent sends when the participant ends the interaction or if an error occurs.
In the Escalation response field, enter the message that the agent sends while it transfers the interaction to a human agent.
Note: If you do not want the agent to send any message and want to configure the response message exclusively in Architect, leave the Exit response and Escalation response fields empty.
Click Save.
Built-in exit tools
Every agent includes two built-in tools for ending an interaction: end_conversation and escalate_to_human_agent. These tools are not shown as editable tools in the Tools tab, as they are part of the agent’s core behavior rather than configurable integrations.
To have the agent call these tools, reference them in agent guidelines, tool pre-instructions, or tool post-instructions. For example, you can instruct the agent to call escalate_to_human_agent after a specific tool fails, or to call end_conversation once a specific goal is confirmed complete.
Note: Use targeted instructions that describe a specific condition for ending the interaction. Avoid blanket instructions such as “end the conversation whenever possible”, since these can cause the agent to exit prematurely or unpredictably.
Agent escalation settings
The agent escalation feature allows the agentic virtual agent to transfer the interaction to a human agent when the participant requests to speak to a human agent. The voice bot or digital bot flow that calls the agentic virtual agent dictates whether the agent escalation is enabled or not.
The following inheritance rules apply:
If you enable agent escalation in the bot flow’s event handling settings, the agentic virtual agent also enables it.
If you disable agent escalation in the bot flow’s event handling settings, the agentic virtual agent also disables it. Regardless of the bot flow’s event handling settings, the Preview widget in agentic virtual agent always enables agent escalation.
Also, if the bot flow has escalation handling set to Exit the flow, the agentic virtual agent uses the escalation exit response that is set in the Configuration tab of the agent. If the bot flow has escalation handling set to Jump to Reusable Task, then the escalation exit response from the agentic virtual agent is not used. For more information about agent escalation in bot flows, see Agent escalation in voice and digital bot flows.
Do / Don’t
Example
Explanation
Thanks for contacting us, have a great day!
Clear and neutral positive example.
It was a pleasure talking to you. We look forward to helping you again!
You can bring branding into your response.
An exit function response that we are exiting.
It is not helpful.
Do / Don’t
Example
Explanation
Sorry I cannot answer that. Is there anything else I can help you with?
It is clear and neutral.
I am afraid I cannot answer that. Let me know if you have any other questions.
Keeps the neutral tone while using a different phrasing.
A violation of XYZ.
It is not within the context. Also, it is not a good experience.
Note: The exit instructions are not mandatory requirements but recommendations for the agent. They are not delivered verbatim but are paraphrased based on the conversational context.
Advanced configuration
Advanced configuration settings offer greater control but can significantly affect agent performance. Use them only when standard instructions are not sufficient.
Set up repetition handling
Repetition handling lets you enable preset checks that detect when the agent or the customer sends repeated or nearly identical messages during a conversation. When a message meets a check’s condition, the platform injects your configured instruction into the agent’s guidance for that turn only — it does not persist for the rest of the session.
The following preset checks are available:
The agent repetition check applies if the agent produces repeated or near-identical responses.
The customer repetition check applies if the customer sends repeated or near-identical messages.
Detection logic and thresholds (such as sensitivity level and number of messages evaluated) are platform-defined; you cannot customize the detection criteria itself. Instead, you enable a check and choose from the available presets, then edit the instruction text that runs when the check is triggered.
To set up repetition handling, follow these steps:
In the Configuration tab, click Advanced Configuration to expand it.
On the Repetition handling tile, click Manage. The Repetition handling dialog box appears.
Next to Customer repetition or Agent repetition, click Add.
Configure the repetition detection settings and handling instruction:
Under Sensitivity similarity, select one of the following options:
Moderate: Detects clearly similar messages with normal variation. Recommended for most use cases.
Very strict: Detects only messages that are nearly identical. Triggers least often.
Under Messages to evaluate, enter the number of prior messages the agent checks for repetition.
In the Agent instruction field, explain how the agent must handle the repetition scenario. For example, you can ask the agent to verify whether the participant understood the requested information correctly, or ask for clarification.
Click Add.
Repeat steps 3 and 4 to add up to two scenarios each for Customer repetition and Agent repetition.
Click Close. If at least one scenario is configured, the Repetition handling tile displays the number of configured scenarios.
To edit or delete repetition scenarios, open the Repetition handling dialog box, hover over the scenario, and click Edit or Delete.
Navigate the agentic virtual agent profile
The profile contains the following sections and a preview widget:
You can switch to any of the sections of the agentic virtual agent while creating a new agent, editing an existing agent, or viewing an agent. Any incomplete section is indicated by the icon preceding the section name. You can save an agent with an incomplete section but you cannot publish the agent until all sections are complete.
After you have completed all necessary sections of the agent setup, you can click Publish to publish the flow.