Skip to content

Agents Commons v1.2 #9544

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: development
Choose a base branch
from
Open

Agents Commons v1.2 #9544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7b4c4c4
SAS-1289 new call agent without history of operation
tinaengel May 15, 2025
e99a942
SAS-1289 call agent with and without history actions
tinaengel May 16, 2025
0d461d2
SAS-1289: changes during PR (include refrence to default preprocessing)
tswarmerdam-mx May 16, 2025
1b5f691
Merge branch 'mendix:development' into agents-1.1
tinaengel May 16, 2025
06c7b48
SAS-1289 fixed two typos
tinaengel May 16, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 32 additions & 24 deletions ...ntent/platform-supported-content/modules/genai/reference-guide/agent-commons.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,14 @@ In addition, install the following modules:
If you are starting from a blank app or adding agent-building functionality to an existing project, you need to manually install the [Agent Commons](https://marketplace.mendix.com/link/component/239450) module from the Mendix Marketplace.
Before proceeding, ensure your project includes the latest versions of the required [dependencies](#dependencies). Follow the instructions in [How to Use Marketplace Content](/appstore/use-content/) to install the Agent Commons module.

## Configuration
## Configuration {#configuration}

To use the Agent Commons functionalities in your app, you must perform the following tasks in Studio Pro:

1. Assign the relevant [module roles](#module-roles) to the applicable user roles in the project **Security**.
2. Add the [Agent Builder UI to your app](#ui-components) by using the pages and snippets as a basis.
3. Ensure that a [deployed model](#deployed-models) is configured.
4. [Define](#define-prompt) the prompts, add functions, knowledge bases, and test the agent.
4. [Define](#define-agent) the prompts, add functions, knowledge bases, and test the agent.
5. Add the agent to the app [logic](#app-logic) of your specific use case.
6. Improve and [iterate on agent versions](#improve-agent).

Expand Down Expand Up @@ -96,19 +96,19 @@ To interact with LLMs using Agent Commons, you need at least one GenAI connector
* For [Amazon Bedrock](https://marketplace.mendix.com/link/component/215042), the creation of Bedrock Deployed Models is part of the [model synchronization mechanism](/appstore/modules/aws/amazon-bedrock/#sync-models).
* For [OpenAI](https://marketplace.mendix.com/link/component/220472), the configuration of OpenAI Deployed Models is part of the [configuration](/appstore/modules/genai/reference-guide/external-connectors/openai/#general-configuration).

### Defining the Agent {#define-prompt}
### Defining the Agent {#define-agent}

When the app is running, a user with the `AgentAdmin` role can set up agents, write prompts, link microflows as tools, and provide access to knowledge bases. Once an agent is associated with a deployed model, it can be tested in an isolated environment, separate from the rest of the app’s logic, to validate its behavior effectively.

Users can create two types of agents:

* Conversational Agent: Intended for scenarios where the end user interacts through a chat interface, or where the agent is called conversationally by another agent.
* **Conversational Agent**: Intended for scenarios where the end user interacts through a chat interface, or where the agent is called conversationally by another agent.

* Single-Call Agent: Designed for isolated agentic patterns such as background processes, subagents in an Agent-as-Tool setup, or any use case that doesn't require a conversational interface with historical context.
* **Single-Call Agent**: Designed for isolated agentic patterns such as background processes, subagents in an Agent-as-Tool setup, or any use case that doesn't require a conversational interface with historical context.

{{< figure src="/attachments/appstore/platform-supported-content/modules/genai/agentcommons/agentbuilderUI.png" >}}

#### Defining Context Entity
#### Defining Context Entity {#define-context-entity}

If your agent's prompt includes variables, your app must define an entity with attributes that match the variable names. An object of this entity serves as the context object, which holds the context data that will be passed when the **call agent** operation is triggered. For more details, see the [Use the agent in the app logic](#app-logic) section below.

Expand Down Expand Up @@ -147,37 +147,45 @@ After a few quick iterations, the first version of the agent is typically ready

New agents will be created in the draft status by default, meaning they are still being worked on and can be tested using the agent commons module only. Once an agent is ready to be integrated into the app logic (i.e., logic triggered by end users), it must be saved as a version. This will store a snapshot of the prompt texts and the configured microflows as tools and knowledge bases. To select the active version for the agent, use the three-dot ({{% icon name="three-dots-menu-horizontal" %}}) menu option on the agent overview and click **Select Version in use**.

#### Calling the Agent from a Microflow
#### Calling the Agent from a Microflow {#call-agent-microflow}

For most use cases, the `Call Agent` microflow activity can be used. You can find this operation in Studio Pro **Toolbox**, under the **Agents Kit** category while editing a microflow.
For most use cases, a `Call Agent` microflow activity can be used. You can find these actions in Studio Pro **Toolbox**, under the **Agents Kit** category while editing a microflow. Take a look at the table below if you're unsure which action to use based on your [agent type](#define-agent):

To use it:

1. Create a Request object using either the [GenAI Commons operation](/appstore/modules/genai/genai-for-mx/commons/#chat-create-request) or the [Default Preprocessing from ConversationalUI](/appstore/modules/genai/conversational-ui-module/).
2. Ensure the Agent object is in scope, for example, retrieve it from the database by name.
3. Pass both the Request and Agent objects to the `Call Agent` activity.

This action calls the Agent using the specified Request and executes a `Chat Completions (With History)` operation based on a defined agent. It uses all defined settings, including the selected model, system prompt, tools, knowledge base, and model parameters. The operation returns a Response object containing the assistant’s final message, in the same fashion as the chat completions operations from GenAI Commons.

For more specific use cases, where a context object is required for variable replacement, use the `Get Prompt for Context Object`. You can find this in Studio Pro **Toolbox**, under the **Agents Kit** category while editing a microflow.


This operation returns both the system prompt and user prompt as string attributes within a combined `PromptToUse` object. These prompt strings can then be passed to a Chat Completions operation.
| Toolbox action name | Supported agent types | Description |
|---|---|---|
| [Call Agent with History](#call-agent-with-history) | Single-Call, Conversational | This action returns the assistant response for a single user message or based on a conversation history. The user message or an alternating chat history of user and assistant message need to be added to the request before calling this action. See [Add Message to Request](/appstore/modules/genai/genai-for-mx/commons/#chat-add-message-to-request) <br> This operation is designed for conversational agents, but will work for single-call agents as well; note that in that case the user prompt defined on the agent version is ignored. |
| [Call Agent without History](#call-agent-without-history) | Single-Call | This action returns the assistant response for a single user message. For Single-Call agents, the user message is already part of the agent version and thus doesn't need to be passed explicitly or added to the optional request. |

To use this setup:
##### Call Agent with History {#call-agent-with-history}

1. Retrieve the relevant Agent one more time (for example, by name) and pass it with your custom context object to the operation.
This action uses all defined settings, including the selected model, system prompt, tools, knowledge base, and model parameters to call the Agent using the specified Request and execute a `Chat Completions` operation. If a context entity was configured, the corresponding context object must be passed so that variables in the system prompt can be replaced. The operation returns a Response object containing the assistant’s final message, in the same fashion as the chat completions operations from GenAI Commons.

2. In a similar way to the Call Agent activity, use the `Request_AddAgentCapabilities` microflow to apply the agent's properties to the request.
To use it:

3. Finally, place the required Chat Completions operation (with or without history) after this step to invoke the agent.
1. Create a Request object using the [Create Request](/appstore/modules/genai/genai-for-mx/commons/#chat-create-request), [Default Preprocessing](/appstore/modules/genai/conversational-ui-module/conversational-ui/#chatcontext-operations) or the [Create Request with Chat History](/appstore/modules/genai/conversational-ui-module/conversational-ui/#request-operations) action. You can set optional attributes (such as temperature) directly on the request, if you want to overwrite those from the agent version. You can also [add additional knowledge bases or tools to the request](/appstore/modules/genai/genai-for-mx/commons/#add-function-to-request) that are not already defined with the agent version.
2. Add at least one user message to the request using the [GenAI Commons operation](/appstore/modules/genai/genai-for-mx/commons/#chat-add-message-to-request). You can alternate between user and assistant messages if you want to send a whole conversation history to the model. If you used [Create Request with Chat History](/appstore/modules/genai/conversational-ui-module/conversational-ui/#request-operations) or [Default Preprocessing](/appstore/modules/genai/conversational-ui-module/conversational-ui/#chatcontext-operations) and your Chat Context contained messages, you can ignore this step.
3. Ensure the Agent object is in scope, for example, retrieve it from the database by name.
4. Optional: For more specific use cases, a context object can be passed for variable replacement. This object needs to be of the entity that was selected while [defining the agent](#define-context-entity).
5. Pass both the Request, Agent and optionally the context object to the `Call Agent with History` activity.

For a conversational agent, the chat context can be created based on the agent in one convenient operation. Use the `New Chat for Agent` operation from the **Toolbox** under the **Agents Kit** category. Retrieve the agent (for example, by name) and pass it with your custom context object to the operation. Note that this sets the system prompt for the chat context, making it applicable to the entire (future) conversation. Similar to other chat context operations, an [action microflow needs to be selected](/appstore/modules/genai/conversational-ui-module/conversational-ui/#action-microflow) for this microflow action.

{{% alert color="info" %}}
Download the [Agent Builder Starter App](https://marketplace.mendix.com/link/component/240369) from the Marketplace for a detailed example of how to use the **Call Agent** activity in an action microflow of a chat interface.
{{% /alert %}}

##### Call Agent without History {#call-agent-without-history}

This action is only supported by Single-Call agents which have a user prompt defined as part of the agent version. It uses all defined settings, including the selected model, system prompt, user prompt, tools, knowledge base, and model parameters to call the Agent by executing a `Chat Completions` operation. If any of such parameters should be overwritten or you want to pass a knowledge base or tool that is not already defined with the agent, you can do this by creating a request and adding these properties before passing it as OptionalRequest to the operation. If a context entity was configured, the corresponding context object must be passed so that variables in the system prompt can be replaced. The operation returns a Response object containing the assistant’s final message, in the same fashion as the chat completions operations from GenAI Commons.

To use it:

1. Ensure the Agent object is in scope, for example, retrieve it from the database by name.
2. Optional: Create a Request object using the [GenAI Commons operation](/appstore/modules/genai/genai-for-mx/commons/#chat-create-request) to set optional attributes (such as temperature), if you want to overwrite those from the agent version. You can also [add additional knowledge bases or tools to the request](/appstore/modules/genai/genai-for-mx/commons/#add-function-to-request) that are not already defined with the agent version.
3. Optional: For more specific use cases, a context object can be passed for variable replacement. This object needs to be of the entity that was selected while [defining the agent](#define-context-entity).
4. Optional: You can [create a file collection and add file(s)](/appstore/modules/genai/genai-for-mx/commons/#initialize-filecollection) to it that can be sent along with the user message to the model. Check the documentation of the underlying LLM connector for support of files and images.
5. Pass Agent and, if relevant, the optional request and context objects to the `Call Agent without History` activity.

#### Transporting the Agent to Other Environments

With the above microflow logic, the agent version is ready to be tested within the end-user flow, either in a local or test environment. Additionally, the agent can be exported and imported for transport to other environments when needed.
Expand Down
4 changes: 2 additions & 2 deletions ...ed-content/modules/genai/reference-guide/conversational-ui/conversational-ui.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -137,7 +137,7 @@ The following additional snippets can be used to give the user more control over

See the [AI Bot Starter App](https://marketplace.mendix.com/link/component/227926) or the [GenAI Showcase App](https://marketplace.mendix.com/link/component/220475) on how to use those snippets.

### Providing the ChatContext {#chat-context}
### Providing the Chat Context {#chat-context}

The `ChatContext` is the central entity in the pages and snippets above and represents a chat conversation with potentially many messages. It functions as the input for the action microflow, which contains the logic for LLM interaction and is executed when the user clicks the **Send** button. The `ChatContext` is visible only to its owner (see [Module Roles](#module-roles) for exceptions).

Expand Down Expand Up @@ -190,7 +190,7 @@ If you want to create your custom action microflow, keep the following considera
* Use the [chat context](#chatcontext-operations) and [request operations](#request-operations) to facilitate the interaction between the chat context and the model.
* The custom action microflow can only be triggered if it is set as an action microflow for the `ProviderConfig` using one of the operations mentioned before.

##### ChatContext operations {#chatcontext-operations}
##### Chat Context operations {#chatcontext-operations}

The following operations can be found in the toolbox for changing the [ChatContext](#chat-context) in a (custom) action microflow:

Expand Down