Tools are data actions that provide your agentic virtual agents access to real-time data, enabling them to complete end-to-end actions.

Enter basic details and choose a data action

1. Click Menu > Orchestration > AI Studio > Agentic Virtual Agents.
2. (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.
3. To open an AI agent, click the agent’s tile. The Agent profile view opens.
4. Click the Tools tab. 
5. Click Create. The Create Tool view opens.
6. Under Overview, add a meaningful name. For example, “validate user login code.” Genesys recommends that you add a get prefix when the agent gets something from the tool, for example, “get available hotels given distance.”
7. Add a description that clearly states the tool’s objective. For example, “Sends the user’s login credentials to an API endpoint. If the login credentials are valid, return a session token (aka auth token). Otherwise, return an error message.”
8. In the Source section, select a data action from the Choose a data action list. For more information about creating a custom data action, see Create a custom action for integrations.
9. Click Next to proceed to the Input tab.

Set up inputs

Add pre-instructions

1. Under Pre-instructions in the Input tab, click Add and add any conditions that must be met before this tool is used by the agent. For example, “Obtain only the user’s login code to log in. Once they are authenticated, do not ask for authentication again.”
2. Add as many pre-instructions as needed for the intended tool usage.

Turn pre-instructions into contextual comfort (wait) statements

You can define contextual comfort statements for individual tool calls through pre-instructions. For more information, see the Contextual comfort statements section in Configure the start and exit behavior of an agentic virtual agent.

Define required variables

Link the existing variables that must be collected before the tool is actioned. 

To mark a variable as required, follow these steps:

1. Under Required variables in the Input tab, click Add. The Required variables dialog box opens.
2. In the Name field, enter a meaningful name for the variable linkage. 
3. Under Link variable, click Select. The Link existing dialog box opens.
4. Select a variable from one of the following tabs:
   • Tool Input
   • Tool Output
   • Start context
5. Click Select to confirm the variable selection.
6. Click Add.

These linked variables are now available for further use in the validation rules which you can configure in the Validation checks section. 

Add validation checks

Define strict validation rules that the agent must pass before the tool is actioned. The system offers two flexible ways to create your preconditions:

• Builder: Use the guided interface to build the validation logic to meet your requirements. This mode is recommended for common rules and regular format checks.
• Code: Use the code editor to write custom logic for advanced or unsupported validation checks.

Considerations

• In Builder mode, you can add up to five groups. Each group can contain up to five checks. Also, Builder mode does not support nested grouping.
• Builder mode supports standard conditions. To work with arrays or create more complex groupings, use Code mode.

To create an out, follow these steps:

1. Under Validation checks in the Input tab, click Add and add any validations that must pass before this tool is used by the agent.
2. Select either the Building or Code mode for building your validation logic:
3. If you chose the Builder mode, follow these steps:
   1. Use the toggle switch to select between the AND and OR operator.
   2. From the Select input list, select one of the required input variables.
   3. From the Select condition list, select the required condition.

      Condition	Description
      is null	Returns true if the value is empty or not set.
      is not null	Returns true if the value is present.
      equals	Returns true if the value exactly matches the specified value.
      does not equal	Returns true if the value does not exactly match the specified value.
      in	Returns true if the value matches any value in the specified list.
      not in	Returns true if the value does not match any value in the specified list.
      contains	Returns true if the value includes the specified text.
      doesn't contain	Returns true if the value does not include the specified text.
      begins with	Returns true if the value starts with the specified text.
      ends with	Returns true if the value ends with the specified text.
      less than	Returns true if the value is less than the specified value.
      less than or equal to	Returns true if the value is less than or equal to the specified value.
      greater than	Returns true if the value is greater than the specified value.
      greater than or equal to	Returns true if the value is greater than or equal to the specified value.

   4. In the Enter value field, enter the value that must match against the selected condition. 
   5. Click Add check to more validation checks.
   6. Click Add group to add a separate group of checks along with its own conditional operator. 
4. If you chose the Code mode, enter your custom validation logic.
5. In the Failure instruction field, enter the instruction that the agent must follow when the check is not met. Include the next action, such as asking the participant to correct or provide the required information, or end the conversation if necessary.
6. Click Create to add the validation check.

Edit or delete validation checks

Under Validation checks in the Input tab, hover over the validation check that you want to edit or delete, and then click Edit or Delete.

Reorder validation checks

1. Under Validation checks in the Input tab, hover over the validation check that you want to reorder, and then click More.
2. Select the appropriate option to move the validation check up or down in the list. You can also add a new validation check above or below the current one.

Set up input variables

The input variables are pulled from the data action. To ensure that they are set up for the tool, follow these steps:

1. To set up the input variables for the tool, follow these steps:
   1. Under Inputs in the Input tab, select one of the following options:
      • Create new: This option allows you to create a new input variable to use with the tool.
      • Link existing: This option allows you to link to an existing variable from another tool or start context from outside the agent.
   2. If you selected Create new in the previous step, enter these details:
      1. In the Name field, enter a variable name.
      2. In the Description field, provide a clear description about the variable. For example, “8-digit login code that is used to authorize a user into the system.”
      3. From the Advanced type list, select one of the following options:
         • Exact user input: Use this option if you want the agent to capture the value exactly as provided by the participant. This option works best for direct identifiers such as names, email addresses, and physical addresses. Genesys recommends that you avoid using this feature when the agent needs to infer, transform, correct, or summarize the user input.
         • List: Use this option to add a comma-separated list of values if you want the agent to accept only those values.
   3. If you selected Link existing, do these steps:
      1. Click Select to view all available variables on the right pane.
      2. Select the required variable or create the relevant start context and click Select. 
         Notes:

         • When a value is already defined elsewhere, such as in a start context variable or another tool, link to it instead of defining it again. Duplicate definitions increase the agent’s size and are sent to the model on every turn.
         • If the system masks an output variable value from the agent, the masking state is indicated by the icon, which appears next to the variable name.
2. Click Next to proceed to the Output tab.

Set up the output object

1. Under Output fields, enter the following details:
   1. In the Name field, enter an output object name. For example, “PaymentRecord.”
   2. In the Description field, provide a clear description about the output object. For example, “Record of a processed payment transaction.”
   3. Select the output fields to include in the output object. Then, modify the output field descriptions, if needed.
      Notes:

      • The system automatically retrieves the field names and descriptions from the chosen data action.
      • Select only the output fields that the agent needs. Every selected field contributes to the agent’s size, so including unused fields increases token consumption unnecessarily.
   4. (Optional) Enable the Mask value from agent toggle, which prevents the agentic virtual agent from reading the raw value. This option is unavailable for mandatory (required) output fields. 
2. (Optional) Add output instructions.
3. Click Next to proceed to the Summary tab. 
   Note: If the system masks an output variable value from the agent, the masking state is indicated by the icon, which appears next to the variable name.

Add output instructions

Define how the agent behaves after receiving the tool’s output. The system offers two flexible ways to create your output conditions:

• Builder: Use the guided interface to build the validation logic to meet your requirements. This mode is recommended for common rules and regular format checks.
• Code: Use the code editor to write custom logic for advanced or unsupported validation checks.

Considerations

• In Builder mode, you can add up to five groups. Each group can contain up to five checks. Also, Builder mode does not support nested grouping.
• Builder mode supports standard conditions. To work with arrays or create more complex groupings, use Code mode.
• In Code mode, the tool response is available through the result object. Write a bare Python expression that returns True or False, such as result.temp > 30, instead of a lambda function such as lambda result: result.temp > 30.

Code mode examplesClick to expand

To build an output validation logic, follow these steps:

1. Under output Instructions in the Output tab, click Add and add any validations that must pass before the agent follows the output instruction.
2. Under Conditions, select either Builder mode or Code mode to define your validation logic.
3. If you chose the Builder mode, follow these steps:
   1. Use the toggle to select either the AND or OR operator.
   2. From the Select output list, select one of the available output variables.
   3. From the Select condition list, select the required condition.

      Condition	Description
      is null	Returns true if the value is empty or not set.
      is not null	Returns true if the value is present.
      equals	Returns true if the value exactly matches the specified value.
      does not equal	Returns true if the value does not exactly match the specified value.
      in	Returns true if the value matches any value in the specified list.
      not in	Returns true if the value does not match any value in the specified list.
      contains	Returns true if the value includes the specified text.
      doesn’t contain	Returns true if the value does not include the specified text.
      begins with	Returns true if the value starts with the specified text.
      ends with	Returns true if the value ends with the specified text.
      less than	Returns true if the value is less than the specified value.
      less than or equal to	Returns true if the value is less than or equal to the specified value.
      greater than	Returns true if the value is greater than the specified value.
      greater than or equal to	Returns true if the value is greater than or equal to the specified value.

   4. In the Enter value field, enter the value that must be matched against the selected condition. 
   5. Click Add check to more conditions.
   6. Click Add group to add a separate group of conditions along with its own logical operator. 
4. If you chose the Code mode, enter your custom validation logic.
   Tip: In Code mode, you can enter the value “True” to ensure that the agent always follows the output instruction.
5. In the Instruction field, enter the instruction that the agent must follow when the condition is met. Include the next action, such as acknowledging the participant that the authentication worked.
6. Click Create to add the output validation logic.

Edit or delete output instructions

Under output Instructions in the Output tab, hover over the output instruction tile that you want to edit or delete, and then click Edit or Delete.

Reorder output instructions

1. Under output Instructions in the Output tab, hover over the output instruction tile that you want to reorder, and then click More.
2. Select the appropriate option to move the output instruction up or down in the list. You can also add a new output instruction above or below the current one.

Mask variable values from the agent

If the Mask value from agent toggle is enabled for an output variable, the agent knows 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.

Considerations for data action output schema

When you define the data action for your agentic virtual agents, consider these schema restrictions.

Agentic virtual agents do not support the following schema features:

• Schema combinators: oneOf, anyOf, allOf
• Conditional keywords: if, then, else
• Schema dependencies: dependencies
• References: $ref
• Negation: not
• Constants: const
• Structural restriction:
  • Empty objects (objects without properties)
  • Tuple validation (multiple schemas defined in items)
  • Nested arrays (items cannot be of type array)

Configure error handling

Create error cases

1. In the Errors tab, click Create. The Create error case panel appears.
2. In the Error name field, enter a meaningful name for the error case. Use a name that indicates the cause of the error or resolution such as ServerError, Re-authenticate, and Wait-Then-Retry. Also, the name must not contain spaces. 
3. In the Description field, explain when this error must be triggered. 
4. In the Error codes list, choose one or more system status codes that you want to map to the specific error. Once you map an error code to an error, the code becomes unavailable for use in subsequent error case additions.
   Note: If the system returns a matching status code (any of the mapped codes in case of multiple mapped codes), the agent runs the configured instruction.
5. In the Default instruction field, instruct the agent to how to respond if the specific error occurs. The instruction works best when it is direct, with the suggested content provided in quotation marks. For example, Tell the customer, "An error has occurred; please contact the branch." is better than "Ask the customer to contact the branch."
6. Click Create. By default, the newly created error handling instruction is enabled.

(Optional) Override the default error handling instruction

Under Error cases, hover your mouse on the (Default) field of an error case and click Edit. Then, add your new instruction and click Confirm. 

Disable error handling instructions

Whenever you create an error case, the system enables it by default. You can disable (or enable) it using the toggle button on the error case tile.

Review and save the tool

1. In the Summary tab, review all the parameters of the tool.
2. To edit the parameters, click Edit. 
3. Click Create.

Navigate the agentic virtual agent profile

The profile contains the following sections and a preview widget:

• Agent
• Tools
• Knowledge
• A2A
• Configuration
• Guardrails

Show meClick to expand

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.