Connect agentic virtual agents to Architect Virtual Agent flows

AI-generated summary

Genesys Cloud enables integration of agentic virtual agents into Architect flows through the Call Agentic Virtual Agent action, supporting both voice and digital bot workflows. Implementation requires Virtual Agent enablement at the organization level, appropriate AI Studio permissions, and agent publication through the Orchestration menu before connection to Architect. The Call Agentic Virtual Agent action operates through a configuration process where users select published agents, specify an action name, and manage input and output variables. Input variables receive starting context values—either literal or expression-based—sent to the agent, while output variables capture end context data returned after interaction completion. The system executes the latest published agent version and provides dynamic message handling capabilities without requiring global prompts for no-match and no-input scenarios. Execution outcomes follow three distinct paths: Success indicates successful agent execution, Failure indicates action errors, and Timeout indicates exceeded execution time. The system tracks four exit reasons (Error, Escalation, TriggeredByUser, and Guardrails) assignable to variables for downstream flow logic. Recommended timeouts remain under 30 seconds to prevent extended user wait times. Key technical features include Dependency Search functionality for identifying flows dependent on specific agentic virtual agents, automatic flow type conversion to Agentic Virtual Agent upon action addition, and seamless agent escalation capabilities. The platform supports hybrid workflows combining conventional flow-based elements with AI-driven components. Agent publishing validates overall definition size, including instructions, guidelines, descriptions, tools, and data types; oversized definitions must be reduced before publishing, as smaller definitions consume fewer tokens at runtime. To optimize agent performance and reduce token consumption, organizations should reuse values through variable linking, mask sensitive data such as authentication tokens and API keys, select only necessary output fields from data actions, and minimize verbose instructions and descriptions. The Architect tool provides a Dependency Search tab for identifying flows with dependencies on agentic virtual agents, facilitating flow management and troubleshooting across the system.

PrerequisitesClick to expand

After you publish an agent in AI Studio, you can connect it to an Architect bot flow or digital bot flow. The bot flow or digital bot flow must be enabled with Virtual Agent using the Call Agentic Virtual Agent action.

Publish an agent in AI Studio

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.
Complete the entire agentic virtual agent setup and click Publish. After you publish the agent, you can now open Architect and connect the agent to a Virtual Agent flow.

Agent size limits for publishing

When you publish an agent, the system validates the overall size of the agent definition, including its instructions, guidelines, descriptions, tools, and data types. If the definition exceeds the size limit, publishing fails and you must reduce its size before publishing again.

A smaller definition also consumes fewer tokens at runtime because the definition is sent to the model on every turn. To reduce the size of an agent and its token consumption, use the following strategies:

Reuse values through linking: When the same value is used in multiple places, such as a tool input that matches a start context variable or a value shared across tools, link to the existing variable instead of defining it again. For more information, see the Set up input variables section in Set up tools for an agentic virtual agent.
Mask values that the agent does not need: Mark non-meaningful or sensitive values, such as authentication tokens, API keys, and internal IDs, as masked. This applies to both start context values and data action output values. Masked values are hidden from the agent and do not count toward size limits.
Select only the output fields that you need: When you configure a tool, include only the data action output fields that the agent actually requires instead of the entire output schema.
Reduce verbosity: Keep instructions, guidelines, and descriptions concise. Verbose or repetitive content increases the size of the agent and is sent to the model on every turn.

Add a Call Agentic Virtual Agent action to a bot flow or digital bot flow in Architect

Use the Call Agentic Virtual Agent action in a bot flow or digital bot flow that is enabled with Virtual Agent to invoke the AI agent. You can solely use the agent or mix and match the agent with conventional flow-based elements as necessary to implement a hybrid workflow.

Notes:

The AI Studio category and the Call Agentic Virtual Agent action are available only when you enable Virtual Agent.
When you add a Call Agentic Virtual Agent action to a flow in Architect, the flow type changes to Agentic Virtual Agent and it is indicated by the following badge at the upper right corner:

Add a Call Agentic Virtual Agent action to a bot flow or digital bot flowClick to expand

To access the Call Agentic Virtual Agent action, follow these steps:

From the Architect home page, click or hover over the Flows menu and select a bot flow or digital bot flow.
Create a new flow or select an existing one. The flow's configuration page opens. Note: The flow must have Virtual Agent enabled.
From the Toolbox, expand the AI Studio category and drag a Call Agentic Virtual Agent action to the wanted location in the flow.
In the Name box, type a meaningful name for the action. This name becomes the name of the Call Agentic Virtual Agent action in the flow.
From the Agentic Virtual Agent list, choose a published agent.
Continue building your flow based on your business needs.

Configure the Call Agentic Virtual Agent actionClick to expand

Field	Description
Name	Type a distinctive name for the Call Agentic Virtual Agent action. The label you enter here becomes the action's name displayed in the flow structure.
Agentic Virtual Agent	Select the name of the agent that the flow must invoke. Click Open Agentic Virtual Agent in New Tab to open the agent in AI Studio. Notes: Only published agents are available for selection.
Version	The flow always executes the latest published version of the agent.
Inputs	Lists the input variables that you defined as part of start context in the selected agentic virtual agent. Assign a value (literal or expression) that you want to send to the selected agentic virtual agent as the starting context.
Outputs	Lists the output variables that you defined as part of end context in the selected agentic virtual agent. These values are outputs that the agentic virtual agent sends to the Architect flow after the interaction ends. Assign a variable name to each output variable for further use in the flow.
Exit Reason	Indicates the reason that caused the agentic virtual agent to exit. Assign a variable name to the exit reason for further use in the flow. The exit reason can be one of the following string values: Error Escalation TriggeredByUser Guardrails

Define success, failure, and timeout pathsClick to expand

Name	Description
Success	This path indicates that the action successfully executed the agentic virtual agent. Drag the appropriate action below the Success path to follow the route you want the interaction to take.
Failure	This path indicates that there was an error in executing the action. Drag the appropriate action below the Failure path to follow the route you want the interaction to take.
Timeout	This path indicates that the action has exceeded the specified amount of time to execute the action. Drag the appropriate action below the Timeout path to follow the route you want the interaction to take. Note: Actions use either the default timeout or the flow author's specified timeout. If the action times out, the flow follows the route specified below the Timeout path. This feature ensures that the user does not wait too long for the path to continue. It is recommended that you set the timeout duration to less than 30 seconds.

Name

Description

Success

This path indicates that the action successfully executed the agentic virtual agent.

Drag the appropriate action below the Success path to follow the route you want the interaction to take.

Failure

This path indicates that there was an error in executing the action.

Drag the appropriate action below the Failure path to follow the route you want the interaction to take.

Timeout

This path indicates that the action has exceeded the specified amount of time to execute the action.

Drag the appropriate action below the Timeout path to follow the route you want the interaction to take.

Note: Actions use either the default timeout or the flow author's specified timeout. If the action times out, the flow follows the route specified below the Timeout path. This feature ensures that the user does not wait too long for the path to continue. It is recommended that you set the timeout duration to less than 30 seconds.

Dependency search

You can use Architect’s Dependency Search tab to search for flows that have dependency on an agentic virtual agent.

[NEXT] Was this article helpful?

Get user feedback about articles.