{"id":2601,"date":"2024-05-03T14:51:57","date_gmt":"2024-05-03T21:51:57","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/semantic-kernel\/?p=2601"},"modified":"2024-05-06T08:09:20","modified_gmt":"2024-05-06T15:09:20","slug":"generating-api-manifests-for-semantic-kernel","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/agent-framework\/generating-api-manifests-for-semantic-kernel\/","title":{"rendered":"Generating API Manifests for Semantic Kernel"},"content":{"rendered":"

Hi everyone!<\/span>\u00a0<\/span><\/p>\n

Today we\u2019re 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<\/a> 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.<\/a><\/p>\n

In <\/span>our last blog post<\/span><\/a>, 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.<\/span>\u00a0<\/span>However, building API manifests by hand can be time consuming and cumbersome, it also requires you to have basic level of the OpenAPI specification.<\/span>\u00a0<\/span>In this blog post, we\u2019ll show you how you can use preview features of <\/span>Kiota<\/span><\/a>, your modern API consumption army knife, to generate semantic kernel API manifests for you.<\/span>\u00a0<\/span><\/p>\n

Getting the Tools\u00a0<\/strong><\/p>\n

The only tool you\u2019ll need is kiota, there are multiple <\/span>ways to install kiota<\/span><\/a> on your machine, just make sure you have v1.14.0 or above installed to get the plugins generation capabilities.<\/span>\u00a0<\/span>If you have dotnet installed, the simplest way to get kiota is by running<\/span>\u00a0<\/span><\/p>\n

dotnet tool install -g Microsoft.OpenApi.Kiota\u00a0<\/span><\/p>\n

Once you have installed kiota, open a terminal, the plugins generation features are hidden behind a feature flag.<\/span>\u00a0<\/span><\/p>\n

If you\u2019re running in PowerShell run the following command:<\/span><\/p>\n

$Env:KIOTA_CONFIG_PREVIEW = $true <\/code><\/pre>\n
In Bash, run the following command line:<\/p>\n
KIOTA_CONFIG_PREVIEW=\"true\"<\/code><\/pre>\n
In Windows, run the following command line:<\/p>\n
set KIOTA_CONFIG_PREVIEW=true<\/code><\/pre>\n
Generating Semantic Kernel Plugins Manifests<\/strong><\/p>\n
Now that you have all the tools you need, let\u2019s generate manifests. We\u2019ll generate manifests for the same APIs that were used in the previous blog post: GitHub and Microsoft Graph.<\/p>\n
Finding the Description<\/strong><\/p>\n
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.\nLet\u2019s start by finding the description for GitHub\u2019s API<\/p>\n
kiota search github<\/code><\/pre>\n
Which will return:<\/p>\n
\"Image<\/a><\/p>\n
Let\u2019s take apisguru::github.com:api.github.com and run:<\/p>\n
kiota search apisguru::github.com:api.github.com<\/code><\/pre>\n
This will give us the following URL for the description, which we can write down, as we\u2019ll need it for later.\nhttps:\/\/raw.githubusercontent.com\/APIs-guru\/openapi-directory\/gh-pages\/v2\/specs\/github.com\/api.github.com\/1.1.4\/openapi.json<\/a><\/p>\n
Finding the Operation<\/strong><\/p>\n
Now that we found the description, let\u2019s try to get the operation that\u2019d allow us to generate markdown. Kiota allows us to easily explore a description through its show command.\nRunning the following command will display the API tree with the matching API paths<\/p>\n
kiota show -k apisguru::github.com:api.github.com -i **\/markdown<\/code><\/pre>\n
\"Image<\/a><\/p>\n
Generating the plugin<\/strong><\/p>\n
Now that we have identified the description and found the right API operation, we\u2019re ready to generate a plugin for sematic kernel.\nThe following command<\/p>\n
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<\/code><\/pre>\n
Will generate the plugin manifest for GitHub<\/p>\n
Generating a manifest for Microsoft Graph<\/strong><\/p>\n
Now that we understand the basics of kiota, let\u2019s fast track through the generation of an API manifest for Microsoft Graph.<\/p>\n
kiota search \"microsoft graph\"\r\nkiota search github::microsoftgraph\/msgraph-metadata\/graph.microsoft.com\/v1.0\r\n# gives us https:\/\/raw.githubusercontent.com\/microsoftgraph\/msgraph-metadata\/master\/openapi\/v1.0\/openapi.yaml\r\nkiota show -k github::microsoftgraph\/msgraph-metadata\/graph.microsoft.com\/v1.0 -i \/me\/messages#GET\r\nkiota 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<\/code><\/pre>\n
Results<\/strong><\/p>\n
Thanks to kiota plugin manifests generation capabilities, you\u2019ll find a graph and a github directory each containing:<\/p>\n