Configuration of a Generative AI chat control

Use Generative AI chat control to send requests to the AI provider to get information. You can submit the prompt using a Generative AI provider or perform a search using an AI knowledge base provider. You can configure these AI providers within the Integration menu.

You can include case data for analysis when using Generative AI or an AI knowledge base. This enables you to utilize the case data to gather the information you need through natural language queries, while ensuring that the actual case data remains hidden from view.

Configuration to search using Generative AI

Configure the following settings to perform search using Generative AI.

Header label

Enter the header label to be displayed at runtime. (Default: Generative AI Chat)

Search type

To execute the search based on Generative AI, select Generative AI.

Provider

Select the Generative AI provider to use, such as ChatGPT, OpenAI, or AI Agent. (Default: Tungsten)

The Provider list includes the AI providers configured in Integration > Generative AI. See Integrate Generative AI with TotalAgility.

If a Generative AI provider is not already configured, a warning message appears when you add the Generative AI chat control to a form.

When you select an AI Agent provider, lists of additionally added input and output variables appear. You can set a static value or select a dynamic variable (form control, form variable, global variable, and copilot insights) for the input and output variables.

Source

Select one of the following options.

None (default)	The response from the AI provider is based on the input provided (plain text or variables).
Image	On the Document list, select a form control (Web capture control), form variable, or global variable of type String, and on the Mime type list, select a file type. The following mime types are supported: GIF, JPEG, and PNG. Mime type is not supported for form variables. When using images, make sure that your selected provider supports the use of images. Black and white GIF files are not supported. We recommend that you convert the GIF image to JPG or PNG. When you select an AI Agent or Custom LLM as the provider, at runtime: Document Content variable uses the content of the document as a base64 string. Document variable uses the instance ID of the document.
Text	The OCR text of the document is returned in a more logical reading order, resembling how a narrator would read it aloud. Instead of being presented in the "top-left to the bottom-right" order returned by OCR, the text is arranged more clearly and coherently. A document with layout text, such as an invoice, a purchase order, or other semi-structured document, or a fixed form, can provide better results than those returned using a Custom LLM provider. If the document has layout text, such as a semi-structured document (invoice, purchase order, and more) or a fixed form, the document text can provide better results when compared to the results returned using a Custom LLM provider. On the Document list, select the form control, form variable, or global variable. The response is generated based on the text passed as input. When you select an AI Agent or Custom LLM as the provider, at runtime: Input Prompt variable: Adds content of the image at the end of the input prompt. Document variable: Uses the instance ID of the document. The following file types are supported in the Transformation Designer for text source format in TotalAgility at runtime: TIFF (.tif), JPEG (.jpg), PNG (*.png), and PDF. When you set the source format as Text, the standard model configuration is used.
Inline image	Click the attachment icon  available at runtime to upload an image and ask a question about it. The thumbnail of the uploaded image is displayed. The response is generated based on the image provided at runtime. When you select an agent or Custom LLM as the provider, the Document Content variable uses content of the document as base64 string at runtime.

Persist conversation

If selected, allows the context to persist for the duration of the conversation. (Default: Clear)

Persisting the conversation increases the token usage that may result in exceeding the token limit. When the prompt exceeds the token limit, the earlier conversation history is removed to manage the token limit automatically.

Use response profile

If selected, lets you add a response profile that can be used at runtime because you may want your responses to take a specific word count or style. (Default: Clear)

Response profile

Provide an inline value, such as "Summarize the response in 20 words or less." or select a global variable, form variable, or form control.

Use seed

If selected, lets you specify the seed value. (Default: Clear)

The seed value increases the likelihood of obtaining more consistent results from the AI provider across repeated requests, though not guaranteed.

Seed

Provide an inline value or select a numeric variable. (Default: 0 and Maximum: 32,767)

Include case data

If selected, lets you include case data for analysis when using Generative AI. (Default: Clear)

When you include case data, you are prompted to enhance your experience by providing descriptions for both the process and activities to achieve optimal results.

The "Include case data" option is not available when using a Custom LLM provider.

For Case identifier, select a variable (global variable, form variable, or form control) or provide an inline value for Case ref or Case ID.
A list of case data is displayed. By default, Key Case Details, History (full), Variables, and Notes options are selected. You can select the items from the list as needed.

At runtime, the case details are included in the information available to search and in the response.

Override default message

If selected, enables the Welcome message and Input help text boxes where you can enter a customized welcome message and help text to be displayed in the Chat control at runtime. (Default: Clear)

Welcome message

You can provide static or dynamic value (form control, form variable, or global variable) or a combination of both for a welcome message.

For example, if you enter "Good day!" as the message, and a form variable called Name that contains the value "John Doe", the default "Hello <username>, how can I help you today?" is replaced with "Good day! John Doe" at runtime.

Input help text

Enter the help text to be displayed in the Chat window at runtime.

Response format

Select either option for response format.

HTML (default): Returns the response with HTML formatting, such as bullet points, headings, and bold text, to present structured content clearly and enhance readability.
None: Returns the response as plain text with no formatting.

On upgrading TotalAgility to 2025.2, the Response format is set to None.
This setting is not available when using Custom LLM or AI Agent AI providers.

When you submit a prompt in a Generative AI Chat control on a form using Generative AI as the search type, an entry is recorded in the audit log.

When you view the Generative AI chat control at runtime:

The Copilot chat window appears with a welcome message, "Hello <username>, how can I help you today?". You can modify the welcome message and input help text, customize the appearance of the chat window, such as modify the header color of the Copilot chat window, set an icon for Copilot, and more. See Generative AI chat control style.
When you enter any input, the response is streamed before it is displayed. You can click the Cancel button  to cancel the request. If you add an image or text as part of the input, such as upload an image of car registration, and request the AI provider to get the registration number, the response is returned accordingly.
To clear the current conversation (including the context if Persist conversation is turned on in Search using Generative AI) and start a new conversation, click the New chat icon  in the top right corner of the Chat box.
The prompt within the control is executed based on the search type (Generative AI or AI knowledge base) configured.

Configuration to search using AI knowledge base

Configure the following settings to search using both TotalAgility document and non-TotalAgility documents with the AI knowledge base in a Generative AI chat control.

Access to the knowledge base is available only to Enterprise tier customers. For users on the Standard and Advanced tiers, this feature is restricted and indicated by a lock icon.

Header label	Enter the header label to be displayed at runtime. (Default: Generative AI Chat)
Search type	To execute the search based on the AI knowledge base, select AI Knowledge Base.
AI Knowledge Base	Select the configured AI knowledge base provider. (Default: Tungsten) See Integrate with AI knowledge base. The list of indexes from the selected AI knowledge base integration appears.
Index	Select an index.
Override max number of matches	If selected, allows you to override the maximum number of documents configured when configuring the AI knowledge base integration. (Default: Clear) See Integrate TotalAgility with AI Knowledge Base.
Max number of matches	Specify the maximum number of documents to override. (Default: 5) This property is available only if "Override max number of matches" is enabled.
Index Fields	The source identifier in the AI knowledge base determines relevant sources, formulates queries to retrieve information, and ranks the retrieved information based on relevance and reliability to ensure a well-informed response. You can add one or more source identifiers. Click . On the Name list, select a source identifier type and enter an inline value or provide a global variable, form variable, or form control. Available identifier types are Job ID, Case ID, Case Ref, and Tag. For example, if you select a Job ID, the knowledge base search is performed based on documents associated with that job ID. The data object fields are not supported in an AI knowledge base search filter. In the Value box, provide an inline value or select a global variable, form variable or a form control. Click Add.
Persist conversation	If selected, allows the context to persist for the duration of the conversation. (Default: Clear) Persisting the conversation increases the token usage that may result in exceeding the token limit. When the prompt exceeds the token limit, the earlier conversation history is removed to manage the token limit automatically.
Use response profile	If selected, lets you add a response profile that can be used at runtime because you may want your responses to take a specific word count or style. (Default: Clear)
Response profile	Provide an inline value, such as "Summarize the response in 20 words or less." or select a global variable, form variable, or form control.
Use seed	If selected, lets you specify the seed value. (Default: Clear) The seed value increases the likelihood of obtaining more consistent results from the AI provider across repeated requests, though not guaranteed.
Seed	Provide an inline value or select a numeric variable. (Default: 0 and Maximum: 32,767)
Include case data	If selected, lets you include case data for analysis when using the AI knowledge base. (Default: Clear) When you include case data, you are prompted to enhance your experience by providing descriptions for both the process and activities to achieve optimal results. The "Include case data" option is not available when using a Custom LLM provider. For Case identifier, select a variable (global variable, form variable, or form control) or provide an inline value for Case ref or Case ID. A list of case data is displayed. By default, Key Case Details, History (full), Variables, and Notes options are selected. You can select the items from the list as needed. At runtime, the case details are included in the information available to search and also included in the response.
Override default message	If selected, overrides the default welcome message and input help text with custom text at runtime. (Default: Clear) Enter the text for the Welcome message and Input help text to be displayed in the Chat window at runtime. For example, if you enter "Good day!" for the Welcome message, the default "Hello <username>, how can I help you today?" text in the chat window is replaced with "Good day!" at runtime.
Response format	Select either option for response format. HTML (default): Returns the response with HTML formatting, such as bullet points, headings, and bold text, to present structured content clearly and enhance readability. None: Returns the response as plain text with no formatting. On upgrading TotalAgility to 2025.2, the Response format is set to None. This setting is not available when using Custom LLM or AI Agent AI providers.
Events	Add one or more actions for the Document clicked event. Within the action, you must get access to the document ID of the document clicked. For example, add a Same page event to display the document in a Web capture control. Save the event.

At runtime, when you search the knowledge base for results based on TotalAgility and non-TotalAgility document data:

The response is streamed before it is displayed. You can click the Cancel button  to cancel the search.
The number of documents returned in a search depends on the integration setting or the AI knowledge base configuration. The number specified in the "Override max number of matches" setting takes precedence over the integration setting.
The TotalAgility documents added to the knowledge base appear as references with hyperlinks. Clicking these hyperlinks triggers the associated actions.
The documents used for the search are from all added sources; if no sources are added, all documents in the knowledge base are used. You can perform the search within the control only if you have search access (configured in the AI knowledge base integration).
The search results display both TotalAgility and non-TotalAgility document data along with relevant references. In the text response, references are indicated using numbers, such as [1]. At runtime, for TotalAgility document references, the names of documents are displayed as hyperlinks that direct you to the respective documents; for non-TotalAgility document references, the text specified for the reference property is displayed without hyperlinks. Additionally, non-TotalAgility document references do not trigger any document click events.
When you select a reference in the search results, the corresponding section of the document is highlighted. If the reference is configured to display the document in a Web capture control, that specific section is highlighted and focused within the control. The same document may appear multiple times in the search results, and clicking the document can highlight different sections each time.