Generating API Manifests for Semantic Kernel

Hi everyone!

Today we’re featuring a guest author from another team in Microsoft on our Semantic Kernel blog. Today’s topic will cover how to utilize API’s manifests. An API manifest is a way to store the dependencies that an application has on HTTP APIs. It contains characteristics of those dependencies including links to API descriptions, specifics of the types of HTTP API requests made by the application and related authorization information. We will turn it over to Vincent Biret to dive into Generating API Manifests for Semantic Kernel in a follow up from the blog on Introducing API Manifest Plugins for Semantic Kernel.

In our last blog post, we detailed how you can use semantic kernel and API manifests to build intelligent agents thanks to sematic kernel and a little bit of code. However, building API manifests by hand can be time consuming and cumbersome, it also requires you to have basic level of the OpenAPI specification. In this blog post, we’ll show you how you can use preview features of Kiota, your modern API consumption army knife, to generate semantic kernel API manifests for you.

Getting the Tools

The only tool you’ll need is kiota, there are multiple ways to install kiota on your machine, just make sure you have v1.14.0 or above installed to get the plugins generation capabilities. If you have dotnet installed, the simplest way to get kiota is by running

dotnet tool install -g Microsoft.OpenApi.Kiota

Once you have installed kiota, open a terminal, the plugins generation features are hidden behind a feature flag.

If you’re running in PowerShell run the following command:

$Env:KIOTA_CONFIG_PREVIEW = $true

In Bash, run the following command line:

KIOTA_CONFIG_PREVIEW="true"

In Windows, run the following command line:

set KIOTA_CONFIG_PREVIEW=true

Generating Semantic Kernel Plugins Manifests

Now that you have all the tools you need, let’s generate manifests. We’ll generate manifests for the same APIs that were used in the previous blog post: GitHub and Microsoft Graph.

Finding the Description

The first hurdle you might face while building manifests is the need for an OpenAPI description for the API you want to integrate into semantic kernel. Finding such descriptions can be difficult and time consuming, but thankfully kiota offers a search command. Let’s start by finding the description for GitHub’s API

kiota search github

Which will return:

Let’s take apisguru::github.com:api.github.com and run:

kiota search apisguru::github.com:api.github.com

This will give us the following URL for the description, which we can write down, as we’ll need it for later. https://raw.githubusercontent.com/APIs-guru/openapi-directory/gh-pages/v2/specs/github.com/api.github.com/1.1.4/openapi.json

Finding the Operation

Now that we found the description, let’s try to get the operation that’d allow us to generate markdown. Kiota allows us to easily explore a description through its show command. Running the following command will display the API tree with the matching API paths

kiota show -k apisguru::github.com:api.github.com -i **/markdown

Generating the plugin

Now that we have identified the description and found the right API operation, we’re ready to generate a plugin for sematic kernel. The following command

kiota plugin add -d https://raw.githubusercontent.com/APIs-guru/openapi-directory/gh-pages/v2/specs/github.com/api.github.com/1.1.4/openapi.json -i **/markdown --pn github --type apimanifest -o ./github

Will generate the plugin manifest for GitHub

Generating a manifest for Microsoft Graph

Now that we understand the basics of kiota, let’s fast track through the generation of an API manifest for Microsoft Graph.

kiota search "microsoft graph"
kiota search github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0
# gives us https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml
kiota show -k github::microsoftgraph/msgraph-metadata/graph.microsoft.com/v1.0 -i /me/messages#GET
kiota plugin add -d https://raw.githubusercontent.com/microsoftgraph/msgraph-metadata/master/openapi/v1.0/openapi.yaml -i /me/messages#GET --pn "microsoft.graph" --type apimanifest -o ./graph

Results

Thanks to kiota plugin manifests generation capabilities, you’ll find a graph and a github directory each containing:

A json api manifest file
A sliced API description containing only the selected operations

Example with GitHub

{
  "applicationName": "application",
  "apiDependencies": {
    "github": {
      "apiDescriptionUrl": "https://raw.githubusercontent.com/APIs-guru/openapi-directory/gh-pages/v2/specs/github.com/api.github.com/1.1.4/openapi.json",
      "apiDeploymentBaseUrl": "https://api.github.com/",
      "requests": [
        {
          "method": "POST",
          "uriTemplate": "markdown"
        }
      ]
    }
  }
}

Both files can be fed to semantic kernel in order to build intelligent agents capable of orchestrating multiple API calls.

Future Plans

Thank you for trying kiota to generate semantic kernel API manifests. Don’t hesitate to reach out if you have any feedback about the latest preview features. We’re working to add other plugin manifests type generation support in kiota. We’re also working to update kiota’s Visual Studio Code extension so you can get a rich Graphical User Interface (GUI) to build your manifests. Thanks for reading and stay tuned!

From the Semantic Kernel team, we want to thank Vincent for his time. We’re always interested in hearing from you. If you have feedback, questions or want to discuss further, feel free to reach out to us and the community on the Semantic Kernel GitHub Discussion Channel! We would also love your support, if you’ve enjoyed using Semantic Kernel, give us a star on GitHub.