From 5cc8ea96fdc336abd22210ef5d89d4dd5acc7b91 Mon Sep 17 00:00:00 2001 From: Tom Warmerdam Date: Fri, 17 Jul 2026 17:04:36 +0200 Subject: [PATCH 1/9] SAS-1850: update for Azure AI in SP model document --- .../genai/v2/reference-guide/agent-editor.md | 25 ++++++++++++++----- .../external-platforms/openai.md | 16 +++++++----- 2 files changed, 29 insertions(+), 12 deletions(-) diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index ba42b4be9bf..c27c6416346 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -62,10 +62,14 @@ The following modules are required dependencies for the supported capabilities o * [Encryption](https://marketplace.mendix.com/link/component/1011) * [GenAI Commons](https://marketplace.mendix.com/link/component/239448) * [MCP Client](https://marketplace.mendix.com/link/component/244893) -* [Mendix Cloud GenAI Connector](https://marketplace.mendix.com/link/component/239449) * [Nanoflow Commons](https://marketplace.mendix.com/link/component/109515) * [Web Actions](https://marketplace.mendix.com/link/component/114337) +Depending on the LLM and Knowledge bases used in your setup, you need to install the corresponding provider module for the app logic to work. + +* [Mendix Cloud GenAI Connector](https://marketplace.mendix.com/link/component/239449) for **Mendix Cloud GenAI** resources (text generation and knowledge bases) +* [OpenAI Connector](https://marketplace.mendix.com/link/component/220472) for ** Azure AI Foundry** resources (text generation model deployments supporting chat completions) + In addition, ensure the following widgets are available in your app: * [Events Widget](https://marketplace.mendix.com/link/component/224259) @@ -113,17 +117,26 @@ For a step-by-step tutorial, see [Create an Agent with Agent Editor](/agents/age With Agent Editor, you can define the model as a document in your app model. You can link this model to one or more agents in your app. Defining a Model document is mandatory. Without a Model document, the agent you configure in the next steps cannot run. -Currently, only models provided by Mendix Cloud GenAI are supported. +Currently, text generation models provided by Mendix Cloud GenAI and Azure AI Foundry are supported. Model configuration is document-based and can be managed directly in Studio Pro: * Add a Model document from the **App Explorer** at the module level. Right-click the module or folder where you want to create your Model document, select **Add other**, and find Model in the bottom section. +* Select the provider. Then follow the provider specific configuration: + +#### For Mendix Cloud GenAI {#define-model-mendix} * Configure the **Model key** with a String constant that contains the key for a Text Generation resource. Obtain this key from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com). * After you select the key, model metadata is imported and shown in the editor. -* Validate the connectivity in the **Connection** section by clicking **Test**. +* Click **List Models** to validate the connectivity. A table shows the available models in the resource. + + +#### For Azure AI Foundry {#define-model-azure} +* Configure the **Project endpoint** and **API Key** fields, each with a String constant that contains the project endpoint and the API key respecively. Obtain the Project Endpoint and the API key from the [Azure AI Foundry Portal](https://ai.azure.com/home). Read more in the documentation of the [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/#azure-resource-name). +* Click **List Deployments** to validate the connectivity. A table shows the available model deployments in the Azure resource. + {{% alert color="info" %}} -The value you use for the constant in Studio Pro can be different from the value used in cloud environments. Constant values can be overridden per environment during deployment. For example, you can locally connect to a text generation resource using a different key than the one used for production. +The value you use for a constant in Studio Pro can be different from the value used in cloud environments. Constant values can be overridden per environment during deployment. For example, you can locally connect to a text generation resource using a different key than the one used for production. {{% /alert %}} ### Defining the Agent With a Prompt, Context Entity, and Model Settings {#define-agent} @@ -133,7 +146,7 @@ After defining the model, define the Agent document and configure the prompts an Defining an agent is also document-based and can be configured using Agent Editor: * Add an Agent document from the **App Explorer** at the module level. Right-click the module or folder where you want to create your Agent document, then select **Add other** > **Agent**. -* Select a Model document for an agent to call a text generation resource. +* Select a **Model** document and model version for the agent to call a text generation resource. * Configure the **System prompt**. Additionally, define a **User prompt** for task-style execution. In both prompts, include placeholders with double braces (for example, `{{variable}}`). * When you use placeholders, select a **Context entity** to resolve values at runtime. The placeholders used within the prompts must match the attribute names of the selected entity 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. @@ -260,7 +273,7 @@ Use version control to view and restore previous agent versions. This lets you i ## Known Limitations {#limitations} -* Currently, 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. +* Currently, Agent Editor supports only Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and knowledge bases. Support for other providers, such as 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 Agent Editor. * 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 referenced by an Agent document is excluded, Studio Pro shows a consistency error. These consistency errors may not be resolved automatically when you include the excluded document again. Resolve this by synchronizing the app 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). diff --git a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md index 7b1826dfe0e..16edf3ea9aa 100644 --- a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md +++ b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md @@ -87,17 +87,21 @@ Microsoft Foundry configuration requires the following inputs: | Azure key type | The type of token entered in the API key field. For Azure OpenAI, two types of keys are currently supported: Microsoft Entra token and API key.
For details on generating a Microsoft Entra access token, see [How to Configure Azure OpenAI Service with Managed Identities](https://learn.microsoft.com/en-gb/azure/ai-services/openai/how-to/managed-identity). Alternatively, if your organization allows it, you can use the Azure `api-key` authentication mechanism. For details on obtaining an API key, see the [Obtaining API Keys](#azure-api-keys) section below. For more information, see the [Technical Reference](#technical-reference) section. | | Token / API key | The access token to authorize your API call. | -##### Obtaining the Resource Name {#azure-resource-name} +The following steps are written to be used with the new Foundry portal (released in 2026). Read more on the [Microsoft Documentation](https://learn.microsoft.com/en-us/azure/foundry/how-to/upgrade-azure-openai?tabs=portal) about how to switch from older versions. + +##### Obtaining the Project Endpoint and Resource Name {#azure-resource-name} 1. Sign in to the [Microsoft Foundry portal](https://ai.azure.com/). -2. In the upper-right corner, select the resource. -3. On the home page, go to **Resource configuration** to find the **Microsoft Foundry endpoint**. -4. Click **Copy** ({{% icon name="copy" %}}) and use it as your resource name in the endpoint URL. +2. In some cases this brings you to the resource page directly. If this is not the case, select the correct Azure resource, which should be of type "Project". +3. On the resource page, the Project Endpoint is shown. This URL has the following structure: +`https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}`. +4. If you use the Agent Editor in Studio Pro, you need the full project endpoint. +5. If you use the configuration page of the connector in the running app, extract the resource name and use it to construct the requested URL format as mentioned in the instruction on the page in the app. ##### Obtaining API Keys {#azure-api-keys} -1. On the same page where the resource name is located, find your API key information. -2. View ({{% icon name="view" %}}) and copy ({{% icon name="copy" %}}) the value of the **key1** or **key2** field as your API key while setting up the configuration. Note that these keys might not be visible for everyone in the portal, depending on your organization's security settings. +1. On the same page where the Project Endpoint is located, find your API key information. +2. Copy the API key and use it while setting up the configuration. Note that these keys might not be visible for everyone in the portal, depending on your organization's security settings. ##### Adding Azure AI Search Resources {#azure-ai-search} From 41a26fb3046f01eca1e08fce5da5fff69a4f8ea8 Mon Sep 17 00:00:00 2001 From: Tom Warmerdam Date: Mon, 20 Jul 2026 17:28:03 +0200 Subject: [PATCH 2/9] SAS-1850: Azure AI as additional provider --- content/en/docs/genai/v2/reference-guide/agent-editor.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index c27c6416346..09ed5101b80 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -273,7 +273,7 @@ Use version control to view and restore previous agent versions. This lets you i ## Known Limitations {#limitations} -* Currently, Agent Editor supports only Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and knowledge bases. Support for other providers, such as OpenAI and Amazon Bedrock, is planned for a future release. +* Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and Mendix Cloud GenAI as provider for knowledge bases. Support for other providers, such as 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 Agent Editor. * 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 referenced by an Agent document is excluded, Studio Pro shows a consistency error. These consistency errors may not be resolved automatically when you include the excluded document again. Resolve this by synchronizing the app 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). From 16f0b6f6f152f7391549ddcf84c194df9d21fcc1 Mon Sep 17 00:00:00 2001 From: Tina Engel Date: Mon, 20 Jul 2026 17:34:34 +0200 Subject: [PATCH 3/9] SAS-1850 small additions in agent editor how to --- .../how-to/creating-agents/create-agent-with-agent-editor.md | 3 ++- content/en/docs/genai/v2/reference-guide/agent-editor.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md b/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md index 41d0fa4bf22..7d6bacae438 100644 --- a/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md +++ b/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md @@ -12,7 +12,8 @@ aliases: This approach uses [Agent Editor](https://marketplace.mendix.com/link/component/257918) in Studio Pro to create and manage agents as part of your app model. You define agents as documents in your app, alongside related resources such as models, knowledge bases, and consumed MCP services. This is the recommended approach for most use cases because it leverages existing platform capabilities. -Currently, Agent Editor supports only [Mendix Cloud GenAI](/agents/mx-cloud-genai/) as a provider for models and knowledge bases. The steps below use the Mendix Cloud GenAI provider type, text generation resource keys, and knowledge base resource keys from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com/). +Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and Mendix Cloud GenAI as provider for knowledge bases. +The steps below use the Mendix Cloud GenAI provider type, text generation resource keys, and knowledge base resource keys from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com/). ## Prerequisites diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index 09ed5101b80..9e49a1373b3 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -20,7 +20,7 @@ Agent Editor is compatible with the Agent Commons module. Using this module, you The Agent Editor module includes a Studio Pro extension that you can use to define GenAI agents as documents in the app model. The Agent Editor Commons module, which is installed as part of the same package, includes logic and activities to call these agents from microflows in a running app. {{% alert color="info" %}} -Agent Editor supports only Mendix Cloud GenAI as a provider. Support for other providers, such as (Azure) OpenAI and Amazon Bedrock, is planned for future releases. +Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and Mendix Cloud GenAI as provider for knowledge bases. Support for other platforms, such as OpenAI and Amazon Bedrock, is planned for future releases. {{% /alert %}} ### Typical Use Cases {#use-cases} From a54ffc76607a6566a2ed81e199db7ae209813b30 Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Tue, 21 Jul 2026 14:07:00 +0530 Subject: [PATCH 4/9] Proofreading --- .../create-agent-with-agent-editor.md | 5 ++-- .../genai/v2/reference-guide/agent-editor.md | 29 ++++++++++--------- .../external-platforms/openai.md | 25 ++++++++-------- 3 files changed, 30 insertions(+), 29 deletions(-) diff --git a/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md b/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md index 7d6bacae438..03b63c2f1b1 100644 --- a/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md +++ b/content/en/docs/genai/v2/how-to/creating-agents/create-agent-with-agent-editor.md @@ -12,8 +12,9 @@ aliases: This approach uses [Agent Editor](https://marketplace.mendix.com/link/component/257918) in Studio Pro to create and manage agents as part of your app model. You define agents as documents in your app, alongside related resources such as models, knowledge bases, and consumed MCP services. This is the recommended approach for most use cases because it leverages existing platform capabilities. -Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and Mendix Cloud GenAI as provider for knowledge bases. -The steps below use the Mendix Cloud GenAI provider type, text generation resource keys, and knowledge base resource keys from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com/). +Currently, Agent Editor supports two providers for text generation models: Mendix Cloud GenAI and Azure AI Foundry. For knowledge bases, it currently supports only Mendix Cloud GenAI. + +The steps below use Mendix Cloud GenAI. You need the text generation resource keys, and knowledge base resource keys from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com/). ## Prerequisites diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index 9e49a1373b3..85d6f9cd900 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -20,7 +20,8 @@ Agent Editor is compatible with the Agent Commons module. Using this module, you The Agent Editor module includes a Studio Pro extension that you can use to define GenAI agents as documents in the app model. The Agent Editor Commons module, which is installed as part of the same package, includes logic and activities to call these agents from microflows in a running app. {{% alert color="info" %}} -Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and Mendix Cloud GenAI as provider for knowledge bases. Support for other platforms, such as OpenAI and Amazon Bedrock, is planned for future releases. + +Currently, Agent Editor supports two providers for text generation models: Mendix Cloud GenAI and Azure AI Foundry. For knowledge bases, it currently supports only Mendix Cloud GenAI. Support for other platforms, such as OpenAI and Amazon Bedrock, is planned for future releases. {{% /alert %}} ### Typical Use Cases {#use-cases} @@ -67,8 +68,8 @@ The following modules are required dependencies for the supported capabilities o Depending on the LLM and Knowledge bases used in your setup, you need to install the corresponding provider module for the app logic to work. -* [Mendix Cloud GenAI Connector](https://marketplace.mendix.com/link/component/239449) for **Mendix Cloud GenAI** resources (text generation and knowledge bases) -* [OpenAI Connector](https://marketplace.mendix.com/link/component/220472) for ** Azure AI Foundry** resources (text generation model deployments supporting chat completions) +* [Mendix Cloud GenAI Connector](https://marketplace.mendix.com/link/component/239449) for Mendix Cloud GenAI resources (text generation and knowledge bases) +* [OpenAI Connector](https://marketplace.mendix.com/link/component/220472) for Azure AI Foundry resources (text generation model deployments supporting chat completions) In addition, ensure the following widgets are available in your app: @@ -117,23 +118,23 @@ For a step-by-step tutorial, see [Create an Agent with Agent Editor](/agents/age With Agent Editor, you can define the model as a document in your app model. You can link this model to one or more agents in your app. Defining a Model document is mandatory. Without a Model document, the agent you configure in the next steps cannot run. -Currently, text generation models provided by Mendix Cloud GenAI and Azure AI Foundry are supported. +Currently, the Agent Editor supports text generation models provided by Mendix Cloud GenAI and Azure AI Foundry. Model configuration is document-based and can be managed directly in Studio Pro: * Add a Model document from the **App Explorer** at the module level. Right-click the module or folder where you want to create your Model document, select **Add other**, and find Model in the bottom section. -* Select the provider. Then follow the provider specific configuration: +* Select the provider and follow the provider-specific configuration: #### For Mendix Cloud GenAI {#define-model-mendix} -* Configure the **Model key** with a String constant that contains the key for a Text Generation resource. Obtain this key from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com). + +* Configure the **Model key** with a String constant that contains the key for a text generation resource. Obtain this key from the [Mendix Cloud GenAI Portal](https://genai.home.mendix.com). * After you select the key, model metadata is imported and shown in the editor. * Click **List Models** to validate the connectivity. A table shows the available models in the resource. - #### For Azure AI Foundry {#define-model-azure} -* Configure the **Project endpoint** and **API Key** fields, each with a String constant that contains the project endpoint and the API key respecively. Obtain the Project Endpoint and the API key from the [Azure AI Foundry Portal](https://ai.azure.com/home). Read more in the documentation of the [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/#azure-resource-name). -* Click **List Deployments** to validate the connectivity. A table shows the available model deployments in the Azure resource. +* Configure the **Project endpoint** and **API key**, each with a String constant. Obtain the **Project endpoint** and **API key** from the [Azure AI Foundry Portal](https://ai.azure.com/home). For more information, refer to [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/#azure-resource-name). +* Click **List Deployments** to validate the connectivity. A table shows the available model deployments in the Azure resource. {{% alert color="info" %}} The value you use for a constant in Studio Pro can be different from the value used in cloud environments. Constant values can be overridden per environment during deployment. For example, you can locally connect to a text generation resource using a different key than the one used for production. @@ -229,7 +230,7 @@ Testing is available when the following conditions are met: * The app model has no consistency errors in Studio Pro (as shown in the **Errors** pane). * The app is running locally. -* The after-startup logic (mentioned in the [First-time Setup](#setup) section) has run successfully. +* The after-startup logic (mentioned in the [First-Time Setup](#setup) section) has run successfully. * The text generation resource configured in the Model document is reachable. You can verify this by clicking **Test** on the Model document. If you change the agent definition (for example, by updating the system prompt or adding or removing tools), restart the local app runtime before testing again. Agent Editor provides a UI indication for this, but Mendix recommends accounting for it explicitly while iterating. @@ -273,17 +274,17 @@ Use version control to view and restore previous agent versions. This lets you i ## Known Limitations {#limitations} -* Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry as a provider for text generation models and Mendix Cloud GenAI as provider for knowledge bases. Support for other providers, such as OpenAI and Amazon Bedrock, is planned for a future release. +* Currently, Agent Editor supports Mendix Cloud GenAI and Azure AI Foundry for text generation models and Mendix Cloud GenAI for knowledge bases. Support for other providers, such as 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 Agent Editor. * 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 referenced by an Agent document is excluded, Studio Pro shows a consistency error. These consistency errors may not be resolved automatically when you include the excluded document again. Resolve this by synchronizing the app 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 folder is not excluded from version control automatically when you include the module from Marketplace. Add this folder to `.gitignore` manually, as described in the [First-time setup](#setup) section. +* The extension creates a `/agenteditor` log folder in the app directory. This folder is not excluded from version control automatically when you include the module from Marketplace. Add this folder to `.gitignore` manually, as described in the [First-Time Setup](#setup) section. ## Troubleshooting {#troubleshooting} ### 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 is 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 @@ -299,7 +300,7 @@ This is a known issue caused by internal timeouts. It is more likely to occur if ### Agent Documents Are Not Visible in Agent Commons UI -Agent documents created in Studio Pro are imported through after-startup logic. Verify that `ASU_AgentEditor` is configured as the after-startup microflow, or included in your existing after-startup microflow as described in the [First-time setup](#setup) section. After these configuration changes, restart the app. +Agent documents created in Studio Pro are imported through after-startup logic. Verify that `ASU_AgentEditor` is configured as the after-startup microflow, or included in your existing after-startup microflow as described in the [First-Time Setup](#setup) section. After these configuration changes, restart the app. ### MCP Tools Cannot Be Listed or Called diff --git a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md index 16edf3ea9aa..1e8ca2bd399 100644 --- a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md +++ b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md @@ -68,12 +68,12 @@ After installing the OpenAI connector, you can find it in the **Marketplace Modu OpenAI configuration requires the following inputs: -| Parameter | Value | -| ----------- | ------------------------------------------------------------ | -| Display name | The name identifier of a configuration (for example, *MyConfiguration*). | -| API type | Select `OpenAI`. | -| Endpoint | The API endpoint (for example, `https://api.openai.com/v1`). | -| Token | The access token to authorize your API call.
To get an API key, follow these steps:
  1. Create an account and sign in at [OpenAI](https://platform.openai.com/).
  2. Go to the [API key page](https://platform.openai.com/account/api-keys) to create a new secret key.
  3. Copy the API key and save this somewhere safe.
| +| Parameter | Value | +| ----------- | ------ | +| Display name | The name identifier of a configuration (for example, *MyConfiguration*). | +| API type | Select `OpenAI`. | +| Endpoint | The API endpoint (for example, `https://api.openai.com/v1`). | +| Token | The access token to authorize your API call.
To get an API key, follow these steps:
  1. Create an account and sign in at [OpenAI](https://platform.openai.com/).
  2. Go to the [API key page](https://platform.openai.com/account/api-keys) to create a new secret key.
  3. Copy the API key and save this somewhere safe.
| #### Microsoft Foundry Configuration {#azure-openai-configuration} @@ -87,21 +87,20 @@ Microsoft Foundry configuration requires the following inputs: | Azure key type | The type of token entered in the API key field. For Azure OpenAI, two types of keys are currently supported: Microsoft Entra token and API key.
For details on generating a Microsoft Entra access token, see [How to Configure Azure OpenAI Service with Managed Identities](https://learn.microsoft.com/en-gb/azure/ai-services/openai/how-to/managed-identity). Alternatively, if your organization allows it, you can use the Azure `api-key` authentication mechanism. For details on obtaining an API key, see the [Obtaining API Keys](#azure-api-keys) section below. For more information, see the [Technical Reference](#technical-reference) section. | | Token / API key | The access token to authorize your API call. | -The following steps are written to be used with the new Foundry portal (released in 2026). Read more on the [Microsoft Documentation](https://learn.microsoft.com/en-us/azure/foundry/how-to/upgrade-azure-openai?tabs=portal) about how to switch from older versions. - ##### Obtaining the Project Endpoint and Resource Name {#azure-resource-name} +The steps below are intended for the Microsoft Foundry portal (released in 2026). If you are using an older version, see the [Microsoft Documentation](https://learn.microsoft.com/en-us/azure/foundry/how-to/upgrade-azure-openai?tabs=portal) for guidance on upgrading. + 1. Sign in to the [Microsoft Foundry portal](https://ai.azure.com/). -2. In some cases this brings you to the resource page directly. If this is not the case, select the correct Azure resource, which should be of type "Project". -3. On the resource page, the Project Endpoint is shown. This URL has the following structure: -`https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}`. +2. In some cases this brings you to the resource page directly. If this is not the case, select the correct Azure resource of type "Project". +3. On the resource page, **Project endpoint** is shown. The URL has the following structure: `https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}`. 4. If you use the Agent Editor in Studio Pro, you need the full project endpoint. 5. If you use the configuration page of the connector in the running app, extract the resource name and use it to construct the requested URL format as mentioned in the instruction on the page in the app. ##### Obtaining API Keys {#azure-api-keys} -1. On the same page where the Project Endpoint is located, find your API key information. -2. Copy the API key and use it while setting up the configuration. Note that these keys might not be visible for everyone in the portal, depending on your organization's security settings. +1. On the same page where the **Project endpoint** is located, find your **API key** information. +2. Copy the **API key** and use it while setting up the configuration. Note that these keys might not be visible for everyone in the portal, depending on your organization's security settings. ##### Adding Azure AI Search Resources {#azure-ai-search} From 31ce5dad09c7af33c46ec3b6e5528c1600900a30 Mon Sep 17 00:00:00 2001 From: Tom Warmerdam Date: Tue, 21 Jul 2026 15:36:32 +0200 Subject: [PATCH 5/9] SAS-1850: small tweak --- content/en/docs/genai/v2/reference-guide/agent-editor.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index 85d6f9cd900..c8211baeb9a 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -134,7 +134,7 @@ Model configuration is document-based and can be managed directly in Studio Pro: #### For Azure AI Foundry {#define-model-azure} * Configure the **Project endpoint** and **API key**, each with a String constant. Obtain the **Project endpoint** and **API key** from the [Azure AI Foundry Portal](https://ai.azure.com/home). For more information, refer to [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/#azure-resource-name). -* Click **List Deployments** to validate the connectivity. A table shows the available model deployments in the Azure resource. +* Click **List Deployments** to validate the connectivity. A table shows all the available model deployments in the Azure AI resource. Note that only deployments that support chat completions are currently usable by Agents in a Mendix app. {{% alert color="info" %}} The value you use for a constant in Studio Pro can be different from the value used in cloud environments. Constant values can be overridden per environment during deployment. For example, you can locally connect to a text generation resource using a different key than the one used for production. @@ -147,7 +147,7 @@ After defining the model, define the Agent document and configure the prompts an Defining an agent is also document-based and can be configured using Agent Editor: * Add an Agent document from the **App Explorer** at the module level. Right-click the module or folder where you want to create your Agent document, then select **Add other** > **Agent**. -* Select a **Model** document and model version for the agent to call a text generation resource. +* Select a **Model** document for the agent to call a text generation resource. Depending on the platform chosen, an additional dropdown will appear to select a model version (Mendix Cloud GenAI) or deployment (Azure AI Foundry). Make the agent is set up to use a text generation model. * Configure the **System prompt**. Additionally, define a **User prompt** for task-style execution. In both prompts, include placeholders with double braces (for example, `{{variable}}`). * When you use placeholders, select a **Context entity** to resolve values at runtime. The placeholders used within the prompts must match the attribute names of the selected entity 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. From 5e863d33cac03252a0630d1e5ad05d609e070490 Mon Sep 17 00:00:00 2001 From: Tom Warmerdam Date: Tue, 21 Jul 2026 15:43:59 +0200 Subject: [PATCH 6/9] SAS-1850: include cross-link --- .../docs/genai/v2/reference-guide/external-platforms/openai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md index 1e8ca2bd399..c3465276525 100644 --- a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md +++ b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md @@ -94,7 +94,7 @@ The steps below are intended for the Microsoft Foundry portal (released in 2026) 1. Sign in to the [Microsoft Foundry portal](https://ai.azure.com/). 2. In some cases this brings you to the resource page directly. If this is not the case, select the correct Azure resource of type "Project". 3. On the resource page, **Project endpoint** is shown. The URL has the following structure: `https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}`. -4. If you use the Agent Editor in Studio Pro, you need the full project endpoint. +4. If you use the Agent Editor in Studio Pro, you need the full project endpoint. Refer to the [Agent editor](/agents/reference-guide/agent-editor/#define-model-azure) documentation for more information. 5. If you use the configuration page of the connector in the running app, extract the resource name and use it to construct the requested URL format as mentioned in the instruction on the page in the app. ##### Obtaining API Keys {#azure-api-keys} From ad97b0e3d643dc2f16346d1755b10c4b9e4b48a8 Mon Sep 17 00:00:00 2001 From: Tom Warmerdam Date: Tue, 21 Jul 2026 15:58:33 +0200 Subject: [PATCH 7/9] SAS-1850: bump latest released versions --- content/en/docs/genai/v2/_index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/content/en/docs/genai/v2/_index.md b/content/en/docs/genai/v2/_index.md index d0f54047a8f..3daf8df6301 100644 --- a/content/en/docs/genai/v2/_index.md +++ b/content/en/docs/genai/v2/_index.md @@ -36,10 +36,10 @@ The following components are available in Agents Kit 2. | Module | Description | Latest Released Version | | --- | --- | --- | -| [Agent Commons](/agents/agents-kit-2/reference-guide/agent-commons/) | Build agentic functionality by defining, testing, and evaluating agents at runtime. Iterate on prompts and agent configurations without app redeployment through the integrated Agent Builder UI. | 4.0.0 | -| [Agent Editor](/agents/agents-kit-2/reference-guide/agent-editor/) | Define agents as version-controlled documents in Studio Pro at design time. Author prompts, configure tools and knowledge bases, test locally, and deploy agents as part of your app model. | 2.0.0 | -| [Conversational UI](/agents/agents-kit-2/reference-guide/conversational-ui/) | Create chat interfaces for full-screen, sidebar, or modal GenAI conversations. Monitor token consumption and trace interactions with UI features built on GenAI Commons. | 7.0.0 | -| [GenAI Commons](/agents/agents-kit-2/reference-guide/commons/) | Integrate GenAI connectors with other modules using common capabilities provided by this base module. Required dependency for both core and connector modules. You can also implement your own connector based on this module. | 7.0.0 | +| [Agent Commons](/agents/agents-kit-2/reference-guide/agent-commons/) | Build agentic functionality by defining, testing, and evaluating agents at runtime. Iterate on prompts and agent configurations without app redeployment through the integrated Agent Builder UI. | 4.1.0 | +| [Agent Editor](/agents/agents-kit-2/reference-guide/agent-editor/) | Define agents as version-controlled documents in Studio Pro at design time. Author prompts, configure tools and knowledge bases, test locally, and deploy agents as part of your app model. | 2.1.0 | +| [Conversational UI](/agents/agents-kit-2/reference-guide/conversational-ui/) | Create chat interfaces for full-screen, sidebar, or modal GenAI conversations. Monitor token consumption and trace interactions with UI features built on GenAI Commons. | 7.1.0 | +| [GenAI Commons](/agents/agents-kit-2/reference-guide/commons/) | Integrate GenAI connectors with other modules using common capabilities provided by this base module. Required dependency for both core and connector modules. You can also implement your own connector based on this module. | 7.1.0 | ### Connector Modules {#connectors} @@ -49,17 +49,17 @@ All connectors depend on GenAI Commons and can be used with the other [core modu | --- | --- | --- | | [Amazon Bedrock Connector](/agents/agents-kit-2/reference-guide/external-connectors/bedrock/) | Connect to Amazon Bedrock. | 11.0.0 | | [Google Gemini Connector](/agents/agents-kit-2/reference-guide/external-connectors/gemini/) | Connect to Google Gemini. | 2.0.0 | -| [Mendix Cloud GenAI Connector](/agents/agents-kit-2/mx-cloud-genai/mxgenai-connector/) | Connect to Mendix Cloud and use Mendix Cloud GenAI resource packs directly within your Mendix application. | 7.0.0 | +| [Mendix Cloud GenAI Connector](/agents/agents-kit-2/mx-cloud-genai/mxgenai-connector/) | Connect to Mendix Cloud and use Mendix Cloud GenAI resource packs directly within your Mendix application. | 7.1.0 | | [Mistral Connector](/agents/agents-kit-2/reference-guide/external-connectors/mistral/) | Connect to Mistral AI. | 2.0.0 | -| [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/) | Connect to OpenAI and Microsoft Foundry. | 9.0.0 | +| [OpenAI Connector](/agents/agents-kit-2/reference-guide/external-connectors/openai/) | Connect to OpenAI and Microsoft Foundry. | 9.1.0 | | [PgVector Knowledge Base](/agents/agents-kit-2/reference-guide/external-connectors/pgvector/) | Manage and interact with a PostgreSQL PgVector knowledge base. | 7.0.0 | ### MCP Modules {#mcp-modules} | Module | Description | Latest Released Version | | --- | --- | --- | -| [MCP Client](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-client/) | Access tools and prompts available via MCP inside your Mendix app and add them to LLM requests. | 4.0.0 | -| [MCP Server](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-server/) | Make your Mendix business logic available to any agent in your enterprise landscape. Expose reusable prompts, including the ability to use prompt variables. List and run actions implemented in the application as a tool. | 5.0.0 | +| [MCP Client](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-client/) | Access tools and prompts available via MCP inside your Mendix app and add them to LLM requests. | 4.1.0 | +| [MCP Server](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-server/) | Make your Mendix business logic available to any agent in your enterprise landscape. Expose reusable prompts, including the ability to use prompt variables. List and run actions implemented in the application as a tool. | 5.1.0 | ## Documents in This Section From 7f6af6198ef2d1080393895d97738e76ab0796d4 Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Thu, 23 Jul 2026 11:11:42 +0530 Subject: [PATCH 8/9] Add small changes --- content/en/docs/genai/v2/reference-guide/agent-editor.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/genai/v2/reference-guide/agent-editor.md b/content/en/docs/genai/v2/reference-guide/agent-editor.md index c8211baeb9a..dfc110c9c70 100644 --- a/content/en/docs/genai/v2/reference-guide/agent-editor.md +++ b/content/en/docs/genai/v2/reference-guide/agent-editor.md @@ -147,7 +147,7 @@ After defining the model, define the Agent document and configure the prompts an Defining an agent is also document-based and can be configured using Agent Editor: * Add an Agent document from the **App Explorer** at the module level. Right-click the module or folder where you want to create your Agent document, then select **Add other** > **Agent**. -* Select a **Model** document for the agent to call a text generation resource. Depending on the platform chosen, an additional dropdown will appear to select a model version (Mendix Cloud GenAI) or deployment (Azure AI Foundry). Make the agent is set up to use a text generation model. +* Select a **Model** document for the agent to call a text generation resource. Depending on the platform chosen, an additional dropdown will appear to select a model version (Mendix Cloud GenAI) or deployment (Azure AI Foundry). Make sure the agent is set up to use a text generation model. * Configure the **System prompt**. Additionally, define a **User prompt** for task-style execution. In both prompts, include placeholders with double braces (for example, `{{variable}}`). * When you use placeholders, select a **Context entity** to resolve values at runtime. The placeholders used within the prompts must match the attribute names of the selected entity 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. @@ -304,7 +304,7 @@ Agent documents created in Studio Pro are imported through after-startup logic. ### MCP Tools Cannot Be Listed or Called -If **List tools** fails, verify the consumed MCP service configuration: endpoint constant value, protocol version, and credentials microflow (when authentication is required). For technical details, the log files in the `/agent-editor` folder of the app directory can be inspected. +If **List tools** fails, verify the consumed MCP service configuration: endpoint constant value, protocol version, and credentials microflow (when authentication is required). For technical details, the log files in the `/agenteditor` folder of the app directory can be inspected. If possible, confirm that the target endpoint is reachable from the running app runtime. You can do this, for example, by temporarily configuring it manually in the [MCP Client module](/agents/agents-kit-2/reference-guide/mcp-modules/mcp-client/) and checking the **Console** pane in Studio Pro for logs. From 994b296db11181d09ec1b4c1f28cfe32d9ea8492 Mon Sep 17 00:00:00 2001 From: Karuna Vengurlekar Date: Thu, 23 Jul 2026 11:30:19 +0530 Subject: [PATCH 9/9] Fix the broken link --- .../docs/genai/v2/reference-guide/external-platforms/openai.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md index c3465276525..7f460e3fc4d 100644 --- a/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md +++ b/content/en/docs/genai/v2/reference-guide/external-platforms/openai.md @@ -94,7 +94,7 @@ The steps below are intended for the Microsoft Foundry portal (released in 2026) 1. Sign in to the [Microsoft Foundry portal](https://ai.azure.com/). 2. In some cases this brings you to the resource page directly. If this is not the case, select the correct Azure resource of type "Project". 3. On the resource page, **Project endpoint** is shown. The URL has the following structure: `https://{your-resource-name}.services.ai.azure.com/api/projects/{your-project-name}`. -4. If you use the Agent Editor in Studio Pro, you need the full project endpoint. Refer to the [Agent editor](/agents/reference-guide/agent-editor/#define-model-azure) documentation for more information. +4. If you use the Agent Editor in Studio Pro, you need the full project endpoint. Refer to the [Agent editor](/agents/agents-kit-2/reference-guide/agent-editor/#define-model-azure) documentation for more information. 5. If you use the configuration page of the connector in the running app, extract the resource name and use it to construct the requested URL format as mentioned in the instruction on the page in the app. ##### Obtaining API Keys {#azure-api-keys}