Microsoft AI Foundry

On this page

Alloy Navigator can use AI models from two providers: OpenAI and Azure. Microsoft AI Foundry, formerly Azure OpenAI Service, is served by the Azure provider. To use a model deployed there, you set Alloy Navigator's AI provider to the Azure type and enter the endpoint, the API key, and one deployment name per model. With the Azure type, Alloy Navigator connects through Azure OpenAI, using your endpoint URL and the deployment name of each model.

Alloy Navigator has exactly one AI provider for the whole system: the choice of provider is not made per application. The master switch, Enabled AI Features in the Settings App and Enable AI features in the Admin Center, is a system setting that turns AI on or off. The AI features themselves and the rest of their settings are described in AI Configuration.

Before you begin

  • In the Settings App, you need the AI Integration administrative permission ("Allows managing AI Integration"). It covers the whole AI Integration branch, including AI Configuration.
  • In the Admin Center, the AI Configuration page opens for either of two permissions: AI Integration or Administrative Access.

See Permissions Reference.

Prepare Microsoft AI Foundry

In Microsoft AI Foundry, collect the following:

  • The endpoint URL of your Azure resource: the resource's base address, with no path to a deployment and no API version.
  • An API key of the resource.
  • One deployment name for each model Alloy Navigator uses: the name of the model's deployment in Azure, not the name of the model. A chat completion deployment is required whenever AI is used. Deployments for text-to-speech, transcription, and embeddings are needed for the capabilities you turn on.

To create the resource and the deployments and find these values:

  1. Go to https://ai.azure.com and sign in with your Microsoft account.
  2. Click Create new, select Microsoft Foundry Resource, enter a Project name, and confirm to create the resource.
  3. Open the resource and deploy the models you need, one deployment per model. For the deployment itself, see Microsoft's instructions for deploying Foundry models.
  4. After deployment, note down the Deployment Name of each model.
  5. Go to Foundry > <your resource name> > My Assets > Models + Endpoints. This page shows your deployment names.
  6. Copy the Azure AI Services Endpoint and the API Key.

In Alloy Navigator, paste the Azure AI Services Endpoint into the Endpoint URL field, the API key into the API Key field, and each deployment name into the deployment name field of its model, as described below.

The provider record

The AI provider record holds the following values:

Value What to enter for Microsoft AI Foundry
Provider type Azure. The other type is OpenAI.
API key Your Azure API key.
Endpoint URL The URL of your Azure resource. It is required for Azure and not used for OpenAI.
Chat completion model The deployment name of your chat completion model. It is required whenever AI is used. Chat completion has no switch of its own.
Text-to-speech A switch and a deployment name. Used to read text aloud.
Transcription A switch and a deployment name. Used for voice input.
Embeddings A switch and a deployment name. Used for the vector index and for retrieval.

Each of the three switches turns its capability on.

In the Settings App

In the Settings App, Provider offers two options, OpenAI API and Azure OpenAI Service. To use Microsoft AI Foundry:

  1. Open AI Integration > AI Configuration.
  2. Select Enabled AI Features at the top of the page. While it is clear, the API Key field, the model fields, and the three capability checkboxes are unavailable. Provider and the Endpoint URL field stay available.
  3. Under Provider, select Azure OpenAI Service. The model lists are cleared, every model field is labeled Deployment name, and the Endpoint URL field appears and becomes required.
  4. Enter the API Key, the Endpoint URL, and the deployment name of your chat completion model in the Deployment name field with the hint "Enter the deployment name of your completion model."
  5. For text-to-speech, transcription, and embeddings, either select Enable Text-to-Speech, Enable speech recognition, or Allow AI to access internal knowledge and enter the capability's deployment name, or clear it.
  6. Click Save on the toolbar of the main window, or select File > Save (Ctrl+S). The page has no button of its own.

The Endpoint URL and the completion deployment name are required, and the Settings App refuses to save while a capability is selected and its model or deployment name is empty. The API Key field is not required. An empty required field shows a message such as "Endpoint URL is a required field" or "Completion deployment name is a required field". For a provider that has never been saved, all three capabilities start selected. The Settings App has no connection test; only the Admin Center has one.

In the Admin Center

IMPORTANT: If the provider was first saved in the Settings App, the first time the Admin Center's AI Configuration page or a portal instance's AI Assistant page is opened, the Admin Center replaces the provider record with an empty one. The API key, the endpoint URL, and the model and deployment names are removed, and while AI features are enabled the Web App shows AI as disabled. The new record has the OpenAI type, text-to-speech and transcription switched on, and embeddings switched off. If no provider record exists yet, the first visit creates one, and later saves in the Settings App edit that same record.

In the Admin Center, AI Provider offers OpenAI API and Azure OpenAI Service. To use Microsoft AI Foundry:

  1. Open AI Integration > AI Configuration.
  2. Select Enable AI features. While it is clear, every other control on the page is disabled.
  3. Under AI Provider, select Azure OpenAI Service. An Endpoint URL field appears, and the model fields become text fields labeled Completion deployment name, Text-to-Speech deployment name, Transcription deployment name, and Embeddings deployment name.
  4. Enter the API Key, the Endpoint URL, and the Completion deployment name.
  5. Select Enable Text-to-Speech, Enable speech recognition, and Allow AI to access internal knowledge as needed. Each one enables its own field: enter the Text-to-Speech deployment name, the Transcription deployment name, or the Embeddings deployment name for each one you select. If Embeddings deployment name still holds an OpenAI model name, such as text-embedding-3-large, replace it with the name of your embeddings deployment.
  6. Optionally, click Test Connection.
  7. Click Save.

Save and Cancel appear only once you change the form. With Enable AI features selected, the Completion deployment name and the Endpoint URL are required, and each other deployment name is required while its checkbox is selected. A missing value shows "The "<field>" field is mandatory, it can't be left blank", naming the field as it is labeled. With Enable AI features clear, nothing is required. The API Key field is never required.

When you switch AI Provider, the page clears its validation errors, resets the API Key field, and exchanges the completion, text-to-speech, and transcription values with the ones last entered under the other provider type. The first switch in a visit empties them. The embeddings value stays as it is, so after a switch from OpenAI API to Azure OpenAI Service, Embeddings deployment name keeps the OpenAI embedding model name it held.

The API key:

  • The page never shows the stored key. The API Key field shows that a key exists only while the selected provider type is the saved one.
  • A save with the API Key field empty keeps the stored key. Nothing on the page removes a stored key. After a successful save, the field is empty again.

Test Connection sends one short chat request built from the values in the form, saved or not, and saves nothing. For Azure, the request goes to your endpoint URL, addressed to the completion deployment, with the API version 2024-10-21. The test checks only the completion deployment, not the text-to-speech, transcription, or embeddings deployments. While it runs, the button reads Testing.... It is disabled while Enable AI features is clear, a test is running, the Completion deployment name or the Endpoint URL is empty, or no key is available: none is typed, and there is no stored key, or the stored key cannot be used because the selected provider type differs from the saved one or the key field was edited. The request times out after 30 seconds and does not follow redirects.

On success, the page shows "Connection test successful!". On failure, a dialog headed "Error" shows "Connection test failed.", the message, and "Recommendation:" followed by a recommendation. When the provider answers HTTP 404, the recommendation is "Verify the model/deployment name matches your provider configuration." For the other failure messages, see Test the connection.