Configure Agent Node¶

By default, the Agent Node is disabled. Enable the node from Generative AI Tools > GenAI Features > Dynamic Conversations. Learn more.

Add the node to a dialog task and configure the node's properties and tool calling capabilities.

Add Agent Node to a Dialog Task¶

Steps to add an Agent node to a Dialog Task:

Go to Automation > Dialogs and select the task that you are working with.
You can add the Agent Node just like any other node. You can find it in the main list of nodes.

Configure Agent Node¶

Component Properties¶

The component properties empower you to configure the following settings. The changes made within this section affect this node across all instances and dialog tasks.

It allows you to provide a Name and Display Name for the node. The node name cannot contain spaces.

Model Configuration¶

Adjusting the settings allows you to fine-tune the model’s behavior to meet your needs. The default settings work fine for most cases. You can tweak the settings and find the right balance for your use case. A few settings are common in the features, and a few are feature-specific:

Model: The selected model for which the settings are displayed.
Prompt/Instructions or Context: Add feature/use case-specific instructions or context to guide the model.
Conversation History Length: This setting allows you to specify the number of recent messages sent to the LLM as context. These messages include both user messages and virtual assistant (VA) messages. The default value is 10. This conversation history can be seen from the debug logs. Note: Applicable only if you are using a custom prompt.
Temperature: The setting controls the randomness of the model’s output. A higher temperature, like 0.8 or above, can result in unexpected, creative, and less relevant responses. On the other hand, a lower temperature, like 0.5 or below, makes the output more focused and relevant.
Max Tokens: It indicates the total number of tokens used in the API call to the model. It affects the cost and the time taken to receive a response. A token can be as short as one character or as long as one word, depending on the text.
Fallback Behavior: Fallback behavior lets the system determine the optimal course of action on LLM call failure or the Guardrails are violated. You can select fallback behavior as:
- Trigger the Task Execution Failure Event
- Skip the current node and jump to a particular node. The system skips the node and transitions to the node the user selects. By default, ‘End of Dialog’ is selected.

Pre-Processor Script¶

Note

The pre-processor script does not apply to the custom prompt.

This property helps execute a script as the first step when the Agent Node is reached. Use the script to manipulate data and incorporate it into rules or exit scenarios as required. The Pre-processor Script has the same properties as the Script Node. Learn more.

To define a pre-processor script, click Define Script, add the script you want to execute, and click Save. Enable Auto Save to save your work automatically after one second of inactivity. It must be re-enabled each time you open the editor.

Entities¶

Specify the entities to be collected by LLM during runtime. In the Entities section, click + Add, enter an Entity Name, and select the Entity Type from the drop-down list.

Most entity types are supported. Here are the exceptions: custom, composite, list of items (enumerated and lookup), and attachment. See Entity Types for more information.

System Context¶

Add a brief description of the use case context to guide the model.

Tools¶

Tools allow the Agent Node to interact with external services, fetching or posting data as needed. When called, they let language models perform tasks or obtain information by executing actions linked to Script, Service, or Search AI nodes. Users can add a maximum of 5 tools to each node.

Note

Tool calling is supported only with custom prompts (Javascript) without streaming.

Click + Add to open the New Tool creation window.

Define the following details for tool configuration:

Name: Add a meaningful name that helps the language model identify the tool to call during the conversation.
Description: Provide a detailed explanation of what the tool does to help the language model understand when to call it.
Parameters:Specify the inputs the tool needs to collect from the user. Define up to 10 parameters for each tool and mark them as mandatory or optional.
- Name: Enter the parameter name.
- Description: Enter an appropriate description of the parameter.
- Type: Select the parameter type (String, Boolean, or Integer).
Actions: These are the nodes that the XO Platform executes when the language model requests a tool call with the required parameters. Users can add up to 5 actions for each tool. These actions are chained and executed sequentially, where the output of one action becomes the input for the next.
- Node Type: Select the node type (Service Node, Script Node, Search AI Node) from the dropdown.
- Node Name: Select a new or existing node from the dropdown.
Response Path: The final output from the action nodes is required to be added as a Response Path for the Platform to understand where to look for the actual response in the payload. Choose the specific key or path that defines the output.
Choose transition: Define the behavior after tool execution:
- Default: Send the response back to the LLM. It is mandatory to have a Response Path in this case.
- Exit Node: Follow the transitions defined for the Agent Node.
- Jump to a Node (Coming soon): You can jump to any node defined in the dialog.

Rules¶

Add the business rules that the collected entities should respect. In the rules section, click + Add, then enter a short and to-the-point sentence, such as:

The airport name should include the IATA Airport Code;
The passenger’s name should include the last name.

There is a 250-character limit to the Rules field, and you can add a maximum of 5 rules.

Exit Scenarios¶

Specify the scenarios that should terminate entity collection and return to the dialog task. This means the node ends interaction with the generative AI model and returns to the dialog flow within the XO Platform.

Click Add Scenario, then enter short, clear, and to-the-point phrases that specifically tell the generative AI model when to exit and return to the dialog flow. For example, Exit when the user wants to book more than 5 tickets in a single booking and return "max limit reached".

There is a 250-character limit to the Scenarios field, and you can add a maximum of 5 scenarios.

Post-Processor Script¶

Note

The post-processor script does not apply to the custom prompt.

This property initiates the post-processor script after processing every user input as part of the Agent Node. Use the script to manipulate the response captured in the context variables just before exiting the Agent Node for both the success and exit scenarios. The Post-processor Script has the same properties as the Script Node. Learn more.

Important Considerations

If the Agent Node requires multiple user inputs, the post-processor is executed for every user input received.

To define a post-processor script, click Define Script and add the script you want to execute.

Instance Properties¶

Configure the instance-specific fields for this node. These apply only for this instance and will not affect this adaptive dialog node when used in other tasks. You must configure Instance Properties for each task where this node is used.

User Input¶

Define how user input validation occurs for this node:

Mandatory: This entity is required and must be provided before proceeding.
Allowed Retries: Configure the maximum number of times a user is prompted for a valid input. You can choose between 5-25 retries in 5-retries increments. The default value is 10 retries.
Behavior on Exceeding Retries: Define what happens when the user exceeds the allowed retries. You can choose to either End the Dialog or Transition to a Node – in which case you can select the node to transition to.

Auto Correct¶

Toggle enable/disable the Auto Correct for spelling and other common errors.

Advanced Controls¶

Configure advanced controls for this node instance as follows:

Intent Detection

This applies only to String and Description entities: Select one of these options to determine the course of action if the VA encounters an entity as a part of the user utterance:

Accept input as entity value and discard the detected intent: The VA captures the user entry as a string or description and ignores the intent.
Prefer user input as intent and proceed with Hold & Resume settings: The user input is considered for intent detection, and the VA proceeds according to the Hold & Resume settings.
Ask the user how to proceed: Allow the user to specify if they meant intent or entity.

Interruptions Behavior

To define the interruption handling at this node. You can select from the below options:

Use the task level ‘Interruptions Behavior’ setting: The VA refers to the Interruptions Behavior settings set at the dialog task level.
Customize for this node: You can customize the Interruptions Behavior settings by selecting this option and configuring it. You can choose whether to allow interruptions or not, or to allow the end user to select the behavior. You can further customize Hold and Resume behavior. Read the Interruption Handling and Context Switching article for more information.

Custom Tags

Add Custom Meta Tags to the conversation flow to profile VA-user conversations and derive business-critical insights from usage and execution metrics. You can define tags to be attached to messages, users, and sessions. See Custom Meta Tags for details.

Connections Properties¶

Note

If the node is at the bottom of the sequence, then only the connection property is visible.

Define the transition conditions from this node. These conditions apply only to this instance and will not affect this node’s use in any other dialog. For a detailed setup guide, See Adding IF-Else Conditions to Node Connections for a detailed setup guide.

All the entity values collected are stored in context variables. For example, {{context.genai_node.bookflight_genainode.entities.entity_1}}. You can define transitions using the context variables.

This node captures entities in the following structure:

{
    "bookflight_genainode": {
        "entities": {
            "entity_1": "value 1",
            "entity_2": "value 2",
            "entity_3": "value 3"
        },
        "exit_scenario": {
            "conv_status": "ended"
        },
        "bot_response": {
            "bot": "Thank you for choosing us, your flight ticket details will be shared over email."
        }
    }
}

Custom Prompt for Agent Node¶

The Platform lets you create a custom prompt tailored to your use case, for both system and custom integrations. This also supporrs a JavaScript mode that enables you to create prompts using JavaScript. It will process the JavaScript and any variables in the prompt to generate a JSON object. The users can preview and validate the scripts by seeing the key-value pairs of the resulting JSON object, similar to a message node. Finally, the system will send the generated JSON object to the configured model.

Note

The Prompts and Requests Library offers reference template prompts and the custom prompts you have created. While template prompts provide a solid starting point, we recommend reviewing and adjusting them as necessary to suit your business needs.

Sample JavaScript

const jsonRepresentation = {
  messages: [
    {
      role: "system",
      content: `You are a virtual assistant representing an enterprise business. Act professionally at all times and do not engage in abusive language or non-business-related conversations. ${System_Context} Your task is to collect entities from user input and conversation history. Entities to collect: ${Required_Entities} Entities already collected: ${JSON.stringify(Collected_Entities)}. Business rules for entity collection: ${Business_Rules}. Instructions: - Capture all mentioned entities. - Do not prompt for entities that have already been provided. - Generate appropriate prompts to collect unfulfilled entities only in ${Language} Language and keep the entities collected in the Original Language. - Keep prompts and messages voice-friendly. Output format: STRICTLY RETURN A JSON OBJECT WITH THE FOLLOWING STRUCTURE: {"bot": "prompt to collect unfulfilled entities", "conv_status": "ongoing" or "ended", "entities": [{key1: value1, key2: value2, ...}]} Always ensure that the entities collected SHOULD be in an array of one object. Conversation status: Mark conv_status as 'ended' when all entity values are captured or if any of the following scenarios are met: ${Exit_Scenarios} - Otherwise, set conv_status as 'ongoing'.`
    },
    ...Conversation_History,
    {
        "role": "user",
        "content": `${User_Input}`
    }
  ],
  model: "gpt-4",
  temperature: 0.73,
  max_tokens: 300,
  top_p: 1,
  frequency_penalty: 0,
  presence_penalty: 0
};

context.payloadFields = jsonRepresentation;

Add Custom Prompt¶

This step involves adding a custom prompt to the Agent node to tailor its behavior or responses according to specific requirements. By customizing the prompt, you can guide the AI to generate outputs that align more closely with the desired outcomes of your application.

For more information on Custom Prompt, see Prompts and Requests Library.

To add an Agent node prompt using JavaScript, follow the steps:

Go to Generative AI Tools > Prompts Library.
On the top right corner of the Prompts Library section, click + New Prompt.
Enter the prompt name. In the feature dropdown, select Agent Node and select the model.
The Configuration section consists of End-point URLs, Authentication, and Header values required to connect to a large language model. These are auto-populated based on the input provided while model integration and are not editable.
In the Request section, click Start from Scratch. Learn more.
Click JavaScript. The Switch Mode pop-up is displayed. Click Continue.
Enter the JavaScript, click Preview.
On the Preview pop-up, enter the Variable Value and click Test. This will convert the JavaScript to a JSON object and send it to the LLM. You can view the JSON object in the JSON Preview section. The success message is displayed. Click Close.
You can view the JSON object in the JSON Preview section. Click Close.
In the request section, click Test. This will make a call to the LLM.
If the request values are correct, the response from the LLM is displayed. If not, an error message is displayed.
In the Actual Response section, double-click the Key that should be used to generate the text response path. For example, double-click the Content key and click Save.
The Response Path is displayed.
The Expected Response are displayed.
Enter the Exit Scenario Key-Value fields, Virtual Assistance Response Key, Collected Entities, and Tool Call Request.The Exit Scenario Key-Value fields help identify when to end the interaction with the Agent model and return to the dialog flow. A Virtual Assistance Response Key is available in the response payload to display the VA’s response to the user. The Collected Entities is an object within the LLM response that contains the key-value of pairs of entities to be captured. The tool call request key in the LLM response payload enables the Platform to execute the tool-calling functionality.
Click Test. The Key Mapping pop-up appears. Make any necessary corrections and close it.
Click Save. The request is added and displayed in the Prompts and Requests Library section.

Dynamic Variables¶

The Dynamic Variables like Context, Environment, and Content variables can now be used in pre-processor scripts, post-processor scripts, and custom prompts.

Learn more.

Keys	Description
{{User_Input}}	The latest input by the end-user.
{{Model}} Optional	This specifies the LLM tagged to the Agent Node in the Dialog Task.
{{System_Context}} Optional	This contains the initial instructions provided in the Agent Node that guide how the LLM should respond.
{{Language}} Optional	The language in which the LLM will respond to the users
{{Business_Rules}} Optional	Rules mentioned in the Agent Node are used to understand the user input and identify the required entity values.
{{Exit_Scenarios}} Optional	Scenarios mentioned in the Agent Node should terminate entity collection and transition to the next node based on Connection Rules.
{{Conversation_History_String}} Optional	This contains the messages exchanged between the end-user and the virtual assistant.
{{Conversation_History_Length}} Optional	This contains a maximum number of messages that the conversation history variable can hold.
{{Required_Entities}} Optional	This contains the list of entities (comma-separated values) mentioned in the Agent Node to be captured by the LLM.
{{Conversation_History}} Optional	Past messages in the conversation are exchanged between the end-user and the virtual assistant. This is an array of objects with role and content as keys.
{{Collected_Entities}} Optional	List of entities and their values collected by the LLM. This is an object with an entity name as the key and the value as LLM collected value.