Semantic Kernel Tools

The Semantic Kernel Tools help developers to write semantic plugins for the Semantic Kernel.

Create a Semantic Plugin

1. Once you have installed the Semantic Kernel Tools extension you will see a new Semantic Kernel option in the activity bar
   • We recommend you clone the semantic-kernel repository and open this in your VS Code workspace
2. Click the Semantic Kernel icon to open Semantic Kernel Functions view
3. Click the "Add Semantic Plugin" icon in the Semantic Kernel Functions view title bar
4. You will be prompted to select a folder
   • This will be the location of the Plugin which will contain your new Semantic Function
   • Create a new folder called MyPlugin¹ in this directory <location of your clone>\semantic-kernel\samples\plugins
   • Select this new folder as your Plugin folder
5. You will be prompted for a function name, enter MyFunction¹
6. You will be prompted for a function description²
7. A new prompt text file will be automatically created for your new function
8. You can now enter your prompt. More information on how to write semantic plugins in Semantic Kernel.

1 The name of the plugin folder and function name can contain only latin letters, 0-9 digits, and underscore.

2 The function description is required.

Execute a Semantic Function

First you must configure an AI endpoint to be used by the Semantic Kernel

1. Open the Command Palette i.e., View -> Command Palette or Ctrl+Shift+P
2. If you have access to an Azure subscription that contains the Azure OpenAI resource you want to use:
   • Type "Add Azure OpenAI Endpoint" and you will be prompted for the following information:
     • Endpoint type, select "completion"
     • Allow the extension to sign in to Azure Portal
     • Select the subscription to use
     • Select the resource group which contains the Azure OpenAI resource
     • Select the Azure OpenAI resource
     • Select the Azure OpenAI model
3. If you have the details of an Azure OpenAI endpoint that you want to use
   • Type "Add AI Endpoint" and you will be prompted for the following information:
     • Endpoint type, select "completion"
     • Completion label, the default of "Completion" is fine
     • Completion AI Service, select AzureOpenAI
     • Completion deployment or model id e.g., gpt-4
     • Completion endpoint URI e.g., https://contoso-openai.azure.com/
     • Completion endpoint API key (this will be stored in VS Code secure storage)
4. If you have the details of an OpenAI endpoint that you want to use
   • Type "Add AI Endpoint" and you will be prompted for the following information:
     • Endpoint type, select "completion"
     • Completion label, the default of "Completion" is fine
     • Completion AI Service, select OpenAI
     • Completion deployment or model id e.g., gpt-4
     • Completion endpoint API key (this will be stored in VS Code secure storage)

Once you have a AI endpoint configured proceed as follows:

1. Select the semantic function you want to execute
2. Select the "Run Function" icon which is shown in the Functions view
   • You will be prompted to enter any arguments the semantic function requires
3. The response will be displayed in the Output view in the "Semantic Kernel" section

Troubleshooting

Enabling Trace Level Logs

You can enable trace level logging for the Semantic Kernel using the following steps:

1. Open settings (Ctrl + ,)
2. Type “Semantic Kernel”
3. Select Semantic Kernel Tools -> Configuration
4. Change the log level to “Trace”
5. Repeat the steps to execute a semantic function and this time you should see trace level debugging of the semantic kernel execution

Below is a list of possible errors you might receive and details on how to address them.

Check Developer Tools Console

You can check the developer tools console to get more detailed information if errors occur:

1. Open Help -> Toggle Developer Tools
2. Select the 'Console' tab

Errors creating a Prompt

• Unable to create function prompt file for <name>
  • An error occurred creating the skprompt.txt file for a new semantic function. Check you can create new folders and files in the location specified for the semantic plugin.
• Function <name> already exists. Found function prompt file: <file name>
  • A skprompt.txt file already exists for the semantic function you are trying to create. Switch to the explorer view to find the conflicting file.
• Unable to create function configuration file for <file name>
  • An error occurred creating the config.json file for a new semantic function. Check you can create new folders and files in the location specified for the semantic plugin.
• Configuration file for <file> already exists. Found function config file: <file name>
  • A config.json file already exists for the semantic function you are trying to create. Switch to the explorer view to find the conflicting file.

Errors configuring an AI Endpoint

• Unable to find any subscriptions. Please log in with a user account that has access to a subscription where OpenAI resources have been deployed.
  • The user account you specified to use when logging in to Microsoft does not have access to any subscriptions. Please try again with a different account.
• Unable to find any resource groups. Please log in with a user account that has access to a subscription where OpenAI resources have been deployed.
  • The user account you specified to use when logging in to Microsoft does not have access to any resource groups in the subscription you selected. Please try again with a different account or a different subscription.
• Unable to find any OpenAI resources. Please log in with a user account that has access to a subscription where OpenAI resources have been deployed.
  • The user account you specified to use when logging in to Microsoft does not have access to any Azure OpenAI resources in the resource group you selected. Please try again with a different account or a different resource group.
• Unable to find any OpenAI model deployments. Please log in with a user account that has access to a subscription where OpenAI model deployments have been deployed.
  • The user account you specified to use when logging in to Microsoft does not have access to any deployment models in the Azure OpenAI resource you selected. Please try again with a different account or a different Azure OpenAI resource.
• Unable to access the Azure OpenAI account. Please log in with a user account that has access to an Azure OpenAI account.
  • The user account you specified to use when logging in to Microsoft does not have access to the Azure OpenAI account in the Azure OpenAI resource you selected. Please try again with a different account or a different Azure OpenAI resource.
• Unable to access the Azure OpenAI account keys. Please log in with a user account that has access to an Azure OpenAI account.
  • The user account you specified to use when logging in to Microsoft does not have access to the Azure OpenAI account keys in the Azure OpenAI resource you selected. Please try again with a different account or a different Azure OpenAI resource.
• Settings does not contain a valid AI completion endpoint configuration. Please run the "Add Azure OpenAI Endpoint" or "Add AI Endpoint" command to configure a valid endpoint.
  • You have not configured an AI endpoint. Please refer to the first part of the Execute a Semantic Function section above.
• Tokenization logic is not available.
  • Tokenization is only available for known models e.g., gpt-4. If you are using an unknown AI model then token counts cannot be computed.
• Setting has invaid type, expected "string". Fix in JSON.
  • The semantic-kernel.completionEndpoint may have been incorrectly set to null. Open the command palette (Ctrl+Shift+P) and select "Open User Settings (JSON)". Remove the line containing semantic-kernel.completionEndpoint: null.

Errors executing a Prompt

• ModelNotAvailable – unable to fetch the list of model deployments from Azure (Unauthorized)

  • This failure happens when calling the Azure OpenAI REST API. Check the AzureOpenAI resource you are using is correctly configured.

• Service not found: '__SK_DEFAULT' text completion service not available - This failure happens if you execute a semantic function using an image generation model and the semantic function references another function which depends on a text completion service. Currently only a single AI service is supported when executing semantic functions.

Using Semantic Kernel Tools with Azure API Management

For information on configuring Azure API Management please refer to Protect your Azure OpenAI API keys with Azure API Management

Instructions to test the Semantic Kernel Tools with your APIM deployment are as follows:

Configure AI Endpoint

1. Open the Command Palette (Ctrl+Shift+P)
2. Execute the “Add AI Endpoint” command
3. Select “AzureOpenAI” as the service type
4. Enter valid deployment name
5. Enter “https://apim...azure-api.net/” as the endpoint URI
6. Enter and empty string as the key (if you have an existing key please delete this)
7. You should get a message “Successfully configured AI endpoint: ”

Configure Request Header

1. Open Settings (Ctrl+,)
2. Search for "Semantic Kernel"
3. Select "Completion Configuration"
4. Enter the "Completion Header Name" (this will be "Ocp-Apim-Subscription-Key")
5. Enter the "Completion Header Value" (this will be "")

Test Function Execution

1. Switch to the Semantic Kernel view
2. Open a Function
3. Click the “Debug Function” action
4. You will be prompted to enter any required parameters
5. Next you will get a message stating “The extension “Semantic Kernel Tools” wants to sign in using Microsoft”, click the Allow button
6. This trigger the flow to authenticate against the APIM endpoint
7. A browser window will open and you can authenticate
8. Once you have authenticated the function execution will proceed and the response form the AI will be displayed in the Output view