Prompt Engineering at Runtime
Introduction
This document explains how to integrate the prompt engineering capabilities of the Agent Commons module into your smart app. It guides you through rebuilding a simplified version of an example that is implemented in the GenAI Showcase App. To follow along, you can use your existing app or start from scratch as described in the Build a Smart App from a Blank GenAI App document.
This document will help you with the following:
- Understand how to implement Agent Commons in your Mendix application.
- Enable AI experts to prompt engineer in your running application.
- Learn how you can call a crafted agent to an LLM of your choice.
Prerequisites
Before integrating Agent Commons into your app, make sure you meet the following requirements:
- An existing app: either an app that you have already built, or one that you can start from scratch using the Blank GenAI App.
- Installation: if not done already, install the AgentCommons module from the Mendix Marketplace.
- Access to an LLM of your choice: in this example, the Mendix Cloud GenAI Resources Packs are used, but you can use any provider with a connector that is compatible with GenAICommons, such as OpenAI or Amazon Bedrock.
- Basic understanding of GenAI concepts: review the Enrich Your Mendix App with GenAI Capabilities page for foundational knowledge, and to familiarize yourself with GenAI Concepts.
- Basic understanding of Mendix: knowledge of simple page building, microflow modeling, and domain model creation.
Use Case
This document shows you how to build a very simple user interface that allows users to generate descriptions for their products. By integrating Generative AI (GenAI), you can leverage a large language model (LLM) to create these descriptions based on a pre-configured prompt as part of an agent. This document also explains how you can integrate Agent Commons capabilities to your app and craft your first agent in the UI at runtime. In the interface, users can input the product name and specify the desired length of the description. This input is dynamically inserted into a prompt previously created by an admin, which is then called. Users can then review the generated response.
This use case is a simplified version of the Generate Product Description (Agent) example in GenAI Showcase App, which you can explore yourself to improve your knowledge.
Integrate Agent Commons
Agent Commons enables users to create powerful agents at runtime, enriching requests to an LLM with tools, knowledge bases, prompts and more. This example focuses mainly on prompt engineering at runtime. The following steps describe how you can add the capabilities to your app and navigation:
-
Open the Security settings of your project and edit the user role that should be able to create agents at runtime. This is typically the admin role, but it may vary depending on your use case.
- Locate the Agent Commons module and assign the AgentAdmin module role.
- Find the Conversational UI module and assign at least the User module role.
- Search Mendix Cloud GenAIConnector module and assign the Administrator module role.
- Save the security settings.
-
Go to Navigation, and add a new Agents item.
- Select a suitable icon, such as
notes-paper-text
, from the Atlas icon set. - Set the
On Click
action toShow Page
. - Search and select the
Agent_Overview
page, located under AgentCommons > USE_ME > Agent Builder folder. Alternatively, you can add a button to a page and connect to the same page.
- Select a suitable icon, such as
-
If you have not started from a GenAI Starter App, you also need to add a navigation item that opens the
Configuration_Overview
page of the MxGenAIConnector. For more details, see Configuration.
You can now run the app, login as administrator, and verify that you can navigate to the Agent_Overview and MxGenAIConnector’s Configuration pages. If you already have a key for a Text Generation resource, you can import it at this stage. For more details, see Mendix Cloud GenAI.
Create Your First Agent
You can now create your first agent in the user interface. The final agent will look like this:
Initial Agent
-
In the running app, open the Agent overview page that you added to your navigation in the previous section.
-
Click New Agent in the top-right corner.
-
Provide a title and description for your agent.
- For the title, you can use
Product Description Generator
. - For the description, which is optional, you can use
Mendix How-To example: let the model generate a product description based on user input
.
- For the title, you can use
-
Select a Usage type to either create a
Single-Call
orConversational
agent. The main difference is that conversational prompts are designed for chat-based interactions, which include the full conversation history, and do not rely on predefined user prompts.Single-Call
prompts, on the other hand, are used for one-time interactions between the user and the LLM. For this example, select theSingle-Call
type and click Save to create the agent. -
On the agent’s details page, where you can perform prompt engineering at runtime, enter the following prompt in the User Prompt field:
Generate a short product description for a chair
. The User Prompt typically represents what the end user would write, although it can be prefilled by our own instructions. -
Click Run in the top-right corner to view the model’s response. However, since no model has been selected yet, you will be prompted to select one before running the test. If no models are available to select, you first need to configure one. For Mendix Cloud GenAI, you need to import a key on the configuration page you added in the previous section.
-
On the Output card, you can see the response from the model. This is already sufficient for the first try.
- Click the Save As button on the Agent card to save this version of the agent.
- For the title, use
Simple product description agent
and save it.
The agent cannot be edited anymore.
Iteration and First Test Case
To further improve your prompts and the user experience for the end users, you can now add some placeholder variables.
-
Next to the version’s dropdown, click the New Agent Version icon ( ) to create a new draft version. Change the User Prompt to
Generate a short product description for a {{ProductName}}. The description should not be longer than {{NumberOfWords}} words.
-
Notice that two variables have been created in the Test Case card on the right. These variables can later be used in your application to allow users to dynamically modify the user prompt without needing to understand what a prompt is, and without requiring any changes or restarts to the application. You can now enter the following values for the variables:
-
30
for NumberOfWords -
chair
for ProductName
Click Run to see how the model adjusts the output based on the updated prompt.
-
-
The values you entered for the variables are only available in the agent builder capability, and are not yet connected to your use case. To make them available for future test runs, use the Save As option.
EnterChair 30 words
as the title for the test case.
System Prompt and Multiple Test Cases
-
Save the agent’s version one more time as described in the Initial Agent section. Enter
Added user input
as the title. -
For the final version, add the additional instructions in the System Prompt field. Enter the following:
You are a sales assistant that can write engaging and inspiring product descriptions for our online marketplace. The user asks you to create a description for various products. You should always respond in {{Language}}.
, and notice that the Language variable is created. -
Add a new test case by clicking the
New Test Case
icon ( ) next to the test case dropdown.- For Language, enter any language, but preferably not English. For this example, use
German
to ensure correct testing. - For the other two variables, reuse the previous values:
30
andchair
.
- For Language, enter any language, but preferably not English. For this example, use
-
Click Run to test the new input, then save the test case with the title:
Chair 30 words German
. -
Now that you have saved at least two test cases, open a dropdown next to the Run button, and click Run All. This will execute both test cases, allowing you to compare the different input values. Note that the Language variable was not set in the first test case, as it did not exist at the time. As a result, the model’s response may be in English or another random language.
-
Once you are satisfied with your agent, you can now save the version one more time with the title
Added system prompt and language
.
You have now successfully created your first agent. A few additional configurations are still required, which will be covered later in this document.
Create User Interface
To connect an agent with the rest of your application, it is helpful to create an entity that contains attributes for capturing user input. This will then be used to fill the prompt variables.
In this section, you will create both the entity and the user interface. The final page will look like this:
-
In Studio Pro, go to your module’s domain model. For new apps, this is MyFirstModule.
-
Create an entity with the name
Product
. -
Add the following attributes to the new entity:
ProductName
as StringNumberOfWords
as IntegerLanguage
as StringProductDescription
as String and set length tounlimited
-
Update the Access rules of the entity to grant read-write access to the attributes
ProductName
,NumberOfWords
, andProductDescription
for both the User and Administrator roles. Ensure that both roles have the Allow creating new objects permission enabled. -
Save the entity to apply the changes.
-
Create a blank responsive web page called Product_NewEdit, and set the layout to Atlas_Default.
-
Add a data view to the page.
- Set the Form orientation to
Vertical
. - Select your newly created entity
Product
as data source Context. - Click OK. Let Studio Pro automatically fill in the content of the data view.
- Set the Form orientation to
-
Remove the
Language
input field, as this will not be provided by users. -
Grant access to the page for both the User and Administrator roles by updating the Visible for property in the Navigation category of the page properties.
-
Add a
Generate product description
button, which will later execute the agent. Place the button right before theProduct Description
input field. -
Open your app’s navigation and add a new menu item called Add product.
- Set the On click action to Create object of the
Product
entity. - Open the
Product_NewEdit
page. - For the icon, you can use
add
from the Atlas icon category.
- Set the On click action to Create object of the
Alternatively, you can add a button to a page and connect to the same page via the Create object event.
Now a user can create a new product in the UI, but the process was not yet enhanced with any AI.
Connect Your Agent to Your App
In this section, you can connect the agent that was already created in the user interface to let an LLM create the product description.
Finalize Your Agent
You first need to configure some additional settings for the agent before it can be used in your app.
-
Run the app and navigate to your agent.
-
Below the user prompt, you can select the context entity. Search for Product and select the entity that was created in the previous section. When starting from the Blank GenAI App, this should be MyFirstModule.Product.
-
In the background, the system checks whether all prompt variables can be matched to attributes in the selected entity. If any variable names do not match the attribute names exactly, a warning message is displayed. Below the list of variables, you may see an informational message indicating that not all attributes are being used as variables. This is simply a helpful reminder in case you unintentionally missed a variable. In this example, the
ProductDescription
attribute is a placeholder for the model’s response, and thus not part of the user or system prompt. -
Navigate back to the Agent Overview through the breadcrumb.
-
Hover over the ellipsis ( ) corresponding to your agent and click Select Version in use. On this page, select a version that you want to set to
In Use
. This means that it is selected for production, and also selectable in your microflow logic. Select the latest versionAdded system prompt and language
, and click Select.
Enable Generation Microflow
Now you will create the microflow that is called when a user clicks the button. This microflow executes a call to the LLM, and sets the ProductDescription
attribute value to the model’s response. The microflow can also be found in the GenAI Showcase App in ExampleMicroflows > Prompt Engineering > ACT_Product_GenerateProductDescription and will look like this:

-
In Studio Pro, go to the
Product_NewEdit
page. -
Open the button and change the On click event to
Call a microflow
. -
Click New to create a new microflow called
ACT_Product_GenerateProductDescription
. -
Click Ok to close the button properties.
-
Open the newly created microflow.
-
Grant the module roles access. Change the
Allowed roles
selection under the Security category and add both roles. -
As a first action in the microflow, add a
Change object
action to change the Language attribute:- Object:
Product
(input parameter) - Member:
Language
- Value:
English
(You can use whatever language. This is just an example to show that you can have input for the prompt that is not defined by your users.)
- Object:
-
Add a
Retrieve
action to the microflow to retrieve the prompt that you created in the UI:- Source:
From database
- Entity:
AgentCommons.Agent
(search for Agent) - XPath constraint:
[Title = 'Product Description Generator']
- Range:
First
- Object name:
Agent
(default)
- Source:
-
Add the
Call Agent Without History
action from the toolbox to execute the LLM call:- Agent:
Agent
(the object that was previously retrieved in step 4) - Optional context object:
Product
(input parameter) - Object name:
Response
(default)
- Agent:
-
Add a
Change object
action to change the ProductDescription attribute:- Object:
Product
(input parameter) - Member:
ProductDescription
- Value:
$Response/ResponseText
(expression)
- Object:
You have now successfully implemented Agent Commons and connected it to a sample use case. Users can now generate a product description using an LLM, based on two input fields and the agent you previously created. Run the app again and you can test the use case by yourself.
Troubleshooting
Model Selection Is Empty
When you want to run your agent from the Agent Commons page, you need to select a model. If the list is empty, you likely have not configured a model yet using one of the platform-supported or other GenAICommons-compatible connectors. Make sure that the model supports SystemPrompt
as well as Text
as output modality.
Context Entity Issues
When you select the Context entity
in the UI, but cannot find the one you are looking for, you might need to restart your application after the entity was added to your domain model.
If the attributes do not match the variables, a warning is displayed in the UI or the Console of your running app. This might happen if you have used inconsistent names for the {{variables}}
inside of your prompts compared to the attribute names. Double check if they are exactly the same, with no whitespace or other characters.
“Owner” of Agent Is Empty
If the Owner
field on the Agent Overview page is empty, you are likely logged in as MxAdmin
, which does not have a name linked to it. For other users, the Owner
field should be populated. This should not change the behavior of this document.