From 4d80ebb67f06ef52767ca8fb20bda8b91eef8833 Mon Sep 17 00:00:00 2001 From: Tom Warmerdam Date: Fri, 1 May 2026 10:27:20 +0200 Subject: [PATCH 1/4] SAS-1751: chat-type agents --- .../genai/reference-guide/agent-editor.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md index 53770a040ee..03b9bb829c0 100644 --- a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md +++ b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md @@ -131,16 +131,12 @@ Defining an agent is also document-based and can be configured using the Agent e * Add an Agent document from the **App Explorer** at the module level. Right-click on the module or folder where you want to create your Model document, select **Add other** and find Agent in the bottom section. * Select a Module document for an agent to call a text generation resource. -* Configure the **System prompt** and **User prompt** for task-style execution. In these prompts, define placeholders with double braces (for example, `{{variable}}`). +* Configure the **System prompt** and, additionally for task-style execution, the **User prompt**. In these prompts, define placeholders with double braces (for example, `{{variable}}`). * When placeholders are used, select a **Context entity** to resolve values at runtime. The placeholders used within the prompts need to match with the attribute names of the entity selected, so that attribute values can be inserted instead of the placeholders at runtime. * Optionally, adjust the **Model settings** as needed (maximum tokens, temperature, and TopP), based on the supported ranges of the model provider. You can also check out template agents in the **USE_ME** folder of the **AgentEditorCommons** module. -{{% alert color="info" %}} -Both **System prompt** and **User prompt** are currently mandatory, as the Agent Editor supports only task-based agents at this time. Support for chat-based agents will be introduced in a future release. -{{% /alert %}} - For more information about prompts and prompt engineering, see [Prompt Engineering](/appstore/modules/genai/prompt-engineering/). Selecting a model is mandatory. You can save the document without it, but if the model configuration is incomplete, Studio Pro will show consistency errors. These errors block running the app locally, cloud deployment, and agent testing in later steps. @@ -228,14 +224,18 @@ If a call fails during testing, a generic error message is shown in the Agent ed ### Including the Agent in the App Logic {#call-agent} -You can include an agent in the app logic by calling it from a microflow. To do so, the Agent Editor provides the **Call Agent** toolbox action in the **Agent Editor** category. This action is currently focused on single-call, task-style execution. +You can include an agent in the app logic by calling it from a microflow. To do so, the Agent Editor provides the **Call Agent** toolbox actions in the **Agent Editor** category. The **Call Agent without History** action is currently focused on single-call, task-style execution, where **Call Agent with History** supports conversational scenarios with multiple messages. When configuring the action, select the Agent document so that the right agent is called. If your prompts use variable placeholders, pass a context object to the action. This object must be of the selected context entity type so that placeholders can be resolved at runtime. -Optionally, you can pass a `Request` object to set request-level values, and a `FileCollection` object with files to send along with the user message to make use of vision or document chat capabilities. Support for files and images depends on the underlying large language model. Refer to the documentation of the specific connector. +For **Call Agent without History**, you can optionally pass a `Request` object to set request-level values, and a `FileCollection` object with files to send along with the user message to make use of vision or document chat capabilities. For **Call Agent with History** the `Request` object is mandatory, as it contains any previous messages from the conversation. Support for files and images depends on the underlying large language model. Refer to the documentation of the specific connector. The output is a `GenAICommons.Response` object, aligned with the GenAI Commons and Agent Commons domain models and actions, which can be used for further logic. Additionally, all agents created via the Agent Editor extension are seamlessly integrated with other Mendix offerings, such as the [Token consumption monitor](/appstore/modules/genai/genai-for-mx/conversational-ui/#snippet-token-monitor) or the [Traceability](/appstore/modules/genai/genai-for-mx/conversational-ui/#traceability) feature from [ConversationalUI](/appstore/modules/genai/genai-for-mx/conversational-ui/). +### Including the Agent in a Conversational User Interface (#conversational-ui) + +Pages and Snippets as building blocks for chat-type UI patterns exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext` which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, you can use the **New Chat for Agent** action in the microflow that opens your chat page and pass the Agent document. Read more about the conversational UI patterns in the [documentation](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). + ### Deploying the Agent to Cloud Environments {#deploy-agent} Agents created with the Agent Editor are documents in the app model. This means they are packaged and deployed together with the rest of the app whenever a deployment is performed. @@ -253,7 +253,7 @@ To return to historical agent versions, use version control to inspect previousl ## Known Limitations {#limitations} * Currently, the Agent Editor supports only Mendix Cloud GenAI as a provider for text generation models and knowledge bases. Support for other providers, such as (Azure) OpenAI and Amazon Bedrock, is planned for a future release. -* Agent Editor currently supports task-based agents only, which require both **System prompt** and **User prompt** to be configured. Chat-based agents will be supported in a future release. +* Support for Mac users is limited: some functionalities might not work, such as doing a test call for Model documents. Mendix recommends using Studio Pro on Windows to use all features of the Agent Editor smoothly. * MCP tool support is limited to whole-server integration. Selecting individual tools from a consumed MCP service to be added to an agent is not yet supported. That also means that the tool choice option `Tool` can only refer to a microflow tool currently. * If a document that is referenced by an Agent document is excluded, Studio Pro shows a consistency error accordingly. In the current version, these consistency errors may not be resolved automatically when the excluded document is included again. You can resolve it by synchronizing the project directory (F4) or by making a small change in any agent-related document (for example, add a character to a system prompt and remove it again). * The extension creates a `/agenteditor` log folder in the app directory. This is not excluded from version control automatically upon including the module from the Marketplace. This folder should be added to `.gitignore` manually as described in the [First-time setup](#setup) section. @@ -262,7 +262,7 @@ To return to historical agent versions, use version control to inspect previousl ### Testing the Agent From Studio Pro Results in an Error -This error is typically due to incorrect model configuration or an exception originating from the API call of the large language model. Check the **Console** pane in Studio Pro for detailed logs. Additionally, verify that the `ASU_AgentEditor` microflow was added to your after-startup logic as described in the [First-time setup](#setup) section. +This error is typically due to incorrect model configuration or an exception originating from the API call of the large language model. Check the **Console** pane in Studio Pro for detailed logs. Additionally, verify that the `ASU_AgentEditor` microflow was added to your after-startup logic as described in the [First-time setup](#setup) section, and that the app startup has completed fully. ### Testing the Agent From Studio Pro Is Disabled From 2160388c929484e475fb8eeaa2f26485f0372810 Mon Sep 17 00:00:00 2001 From: Karuna-Mendix Date: Mon, 4 May 2026 18:40:10 +0530 Subject: [PATCH 2/4] Proofreading --- .../marketplace/genai/reference-guide/agent-editor.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md index 03b9bb829c0..30495c8c700 100644 --- a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md +++ b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md @@ -131,7 +131,7 @@ Defining an agent is also document-based and can be configured using the Agent e * Add an Agent document from the **App Explorer** at the module level. Right-click on the module or folder where you want to create your Model document, select **Add other** and find Agent in the bottom section. * Select a Module document for an agent to call a text generation resource. -* Configure the **System prompt** and, additionally for task-style execution, the **User prompt**. In these prompts, define placeholders with double braces (for example, `{{variable}}`). +* Configure the **System prompt**, and additionally define a **User prompt** for task-style execution. In both prompts include placeholders with double braces, for example, `{{variable}}`. * When placeholders are used, select a **Context entity** to resolve values at runtime. The placeholders used within the prompts need to match with the attribute names of the entity selected, so that attribute values can be inserted instead of the placeholders at runtime. * Optionally, adjust the **Model settings** as needed (maximum tokens, temperature, and TopP), based on the supported ranges of the model provider. @@ -228,13 +228,13 @@ You can include an agent in the app logic by calling it from a microflow. To do When configuring the action, select the Agent document so that the right agent is called. If your prompts use variable placeholders, pass a context object to the action. This object must be of the selected context entity type so that placeholders can be resolved at runtime. -For **Call Agent without History**, you can optionally pass a `Request` object to set request-level values, and a `FileCollection` object with files to send along with the user message to make use of vision or document chat capabilities. For **Call Agent with History** the `Request` object is mandatory, as it contains any previous messages from the conversation. Support for files and images depends on the underlying large language model. Refer to the documentation of the specific connector. +For **Call Agent without History**, you can optionally pass a `Request` object to set request-level values, and a `FileCollection` object with files to send along with the user message to make use of vision or document chat capabilities. For **Call Agent with History** the `Request` object is mandatory, as it contains the previous messages from the conversation. Support for files and images depends on the underlying large language model. Refer to the documentation of the specific connector. The output is a `GenAICommons.Response` object, aligned with the GenAI Commons and Agent Commons domain models and actions, which can be used for further logic. Additionally, all agents created via the Agent Editor extension are seamlessly integrated with other Mendix offerings, such as the [Token consumption monitor](/appstore/modules/genai/genai-for-mx/conversational-ui/#snippet-token-monitor) or the [Traceability](/appstore/modules/genai/genai-for-mx/conversational-ui/#traceability) feature from [ConversationalUI](/appstore/modules/genai/genai-for-mx/conversational-ui/). ### Including the Agent in a Conversational User Interface (#conversational-ui) -Pages and Snippets as building blocks for chat-type UI patterns exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext` which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, you can use the **New Chat for Agent** action in the microflow that opens your chat page and pass the Agent document. Read more about the conversational UI patterns in the [documentation](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). +Pages and Snippets are building blocks for chat-type UI patterns exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext` which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, use the **New Chat for Agent** action in the microflow that opens your chat page and passes the Agent document. For more details, refer to the [Conversational UI patterns](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). ### Deploying the Agent to Cloud Environments {#deploy-agent} @@ -253,7 +253,7 @@ To return to historical agent versions, use version control to inspect previousl ## Known Limitations {#limitations} * Currently, the Agent Editor supports only Mendix Cloud GenAI as a provider for text generation models and knowledge bases. Support for other providers, such as (Azure) OpenAI and Amazon Bedrock, is planned for a future release. -* Support for Mac users is limited: some functionalities might not work, such as doing a test call for Model documents. Mendix recommends using Studio Pro on Windows to use all features of the Agent Editor smoothly. +* Support for Mac users is limited. Some functionalities might not work, such as doing a test call for Model documents. Mendix recommends using Studio Pro on Windows to use all features of the Agent Editor smoothly. * MCP tool support is limited to whole-server integration. Selecting individual tools from a consumed MCP service to be added to an agent is not yet supported. That also means that the tool choice option `Tool` can only refer to a microflow tool currently. * If a document that is referenced by an Agent document is excluded, Studio Pro shows a consistency error accordingly. In the current version, these consistency errors may not be resolved automatically when the excluded document is included again. You can resolve it by synchronizing the project directory (F4) or by making a small change in any agent-related document (for example, add a character to a system prompt and remove it again). * The extension creates a `/agenteditor` log folder in the app directory. This is not excluded from version control automatically upon including the module from the Marketplace. This folder should be added to `.gitignore` manually as described in the [First-time setup](#setup) section. From 3a15e51e2c1682b7d67fbb677c0e94a1f70a4e3e Mon Sep 17 00:00:00 2001 From: Karuna-Mendix Date: Mon, 4 May 2026 18:46:56 +0530 Subject: [PATCH 3/4] Fix small issues --- .../marketplace/genai/reference-guide/agent-editor.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md index 30495c8c700..a0c0d0d7045 100644 --- a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md +++ b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md @@ -131,7 +131,7 @@ Defining an agent is also document-based and can be configured using the Agent e * Add an Agent document from the **App Explorer** at the module level. Right-click on the module or folder where you want to create your Model document, select **Add other** and find Agent in the bottom section. * Select a Module document for an agent to call a text generation resource. -* Configure the **System prompt**, and additionally define a **User prompt** for task-style execution. In both prompts include placeholders with double braces, for example, `{{variable}}`. +* Configure the **System prompt**, and additionally define a **User prompt** for task-style execution. In both prompts, include placeholders with double braces, for example, `{{variable}}`. * When placeholders are used, select a **Context entity** to resolve values at runtime. The placeholders used within the prompts need to match with the attribute names of the entity selected, so that attribute values can be inserted instead of the placeholders at runtime. * Optionally, adjust the **Model settings** as needed (maximum tokens, temperature, and TopP), based on the supported ranges of the model provider. @@ -224,17 +224,17 @@ If a call fails during testing, a generic error message is shown in the Agent ed ### Including the Agent in the App Logic {#call-agent} -You can include an agent in the app logic by calling it from a microflow. To do so, the Agent Editor provides the **Call Agent** toolbox actions in the **Agent Editor** category. The **Call Agent without History** action is currently focused on single-call, task-style execution, where **Call Agent with History** supports conversational scenarios with multiple messages. +You can include an agent in the app logic by calling it from a microflow. To do so, the Agent Editor provides the **Call Agent** toolbox actions in the **Agent Editor** category. The **Call Agent without History** action is currently focused on single-call, task-style execution, where the **Call Agent with History** supports conversational scenarios with multiple messages. When configuring the action, select the Agent document so that the right agent is called. If your prompts use variable placeholders, pass a context object to the action. This object must be of the selected context entity type so that placeholders can be resolved at runtime. -For **Call Agent without History**, you can optionally pass a `Request` object to set request-level values, and a `FileCollection` object with files to send along with the user message to make use of vision or document chat capabilities. For **Call Agent with History** the `Request` object is mandatory, as it contains the previous messages from the conversation. Support for files and images depends on the underlying large language model. Refer to the documentation of the specific connector. +For **Call Agent without History**, you can optionally pass a `Request` object to set request-level values, and a `FileCollection` object with files to send along with the user message to utilize vision or document chat capabilities. For the **Call Agent with History** the `Request` object is mandatory, as it contains the previous messages from the conversation. Support for files and images depends on the underlying large language model. Refer to the documentation of the specific connector. The output is a `GenAICommons.Response` object, aligned with the GenAI Commons and Agent Commons domain models and actions, which can be used for further logic. Additionally, all agents created via the Agent Editor extension are seamlessly integrated with other Mendix offerings, such as the [Token consumption monitor](/appstore/modules/genai/genai-for-mx/conversational-ui/#snippet-token-monitor) or the [Traceability](/appstore/modules/genai/genai-for-mx/conversational-ui/#traceability) feature from [ConversationalUI](/appstore/modules/genai/genai-for-mx/conversational-ui/). ### Including the Agent in a Conversational User Interface (#conversational-ui) -Pages and Snippets are building blocks for chat-type UI patterns exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext` which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, use the **New Chat for Agent** action in the microflow that opens your chat page and passes the Agent document. For more details, refer to the [Conversational UI patterns](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). +Pages and Snippets are building blocks for chat-type UI patterns that exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext`, which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, use the **New Chat for Agent** action in the microflow that opens your chat page and passes the Agent document. For more details, refer to the [Conversational UI patterns](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). ### Deploying the Agent to Cloud Environments {#deploy-agent} @@ -262,7 +262,7 @@ To return to historical agent versions, use version control to inspect previousl ### Testing the Agent From Studio Pro Results in an Error -This error is typically due to incorrect model configuration or an exception originating from the API call of the large language model. Check the **Console** pane in Studio Pro for detailed logs. Additionally, verify that the `ASU_AgentEditor` microflow was added to your after-startup logic as described in the [First-time setup](#setup) section, and that the app startup has completed fully. +This error is typically due to incorrect model configuration or an exception originating from the API call of the large language model. Check the **Console** pane in Studio Pro for detailed logs. Additionally, verify that the `ASU_AgentEditor` microflow is added to your after-startup logic as described in the [First-time setup](#setup) section, and that the app startup has completed fully. ### Testing the Agent From Studio Pro Is Disabled From 85fa33aac7ba115ad3774110463e6ad290bd58c9 Mon Sep 17 00:00:00 2001 From: Karuna-Mendix Date: Tue, 5 May 2026 11:51:11 +0530 Subject: [PATCH 4/4] Incorporate the feedback --- .../en/docs/marketplace/genai/reference-guide/agent-editor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md index a0c0d0d7045..30c409175ef 100644 --- a/content/en/docs/marketplace/genai/reference-guide/agent-editor.md +++ b/content/en/docs/marketplace/genai/reference-guide/agent-editor.md @@ -234,7 +234,7 @@ The output is a `GenAICommons.Response` object, aligned with the GenAI Commons a ### Including the Agent in a Conversational User Interface (#conversational-ui) -Pages and Snippets are building blocks for chat-type UI patterns that exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext`, which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, use the **New Chat for Agent** action in the microflow that opens your chat page and passes the Agent document. For more details, refer to the [Conversational UI patterns](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). +Pages and Snippets are building blocks for chat-type UI patterns that exist in the [ConversationalUI module](/appstore/modules/genai/genai-for-mx/conversational-ui/). The central entity here is the `ChatContext`, which represents a user-agent chat session. When using the Agent Editor, in order to instantiate a new `ChatContext`, use the **New Chat for Agent** action in the microflow to open the chat page and pass the Agent document. Configure the Agent document as the input parameter for this action. For more details, refer to [Conversational UI patterns](/appstore/modules/genai/genai-for-mx/conversational-ui/#chat-context-operations). ### Deploying the Agent to Cloud Environments {#deploy-agent}