{"id":3965,"date":"2025-01-09T14:43:35","date_gmt":"2025-01-09T22:43:35","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/semantic-kernel\/?p=3965"},"modified":"2025-02-10T10:18:17","modified_gmt":"2025-02-10T18:18:17","slug":"empowering-ai-agents-with-tools-via-openapi-a-hands-on-guide-with-microsoft-semantic-kernel-agents","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/agent-framework\/empowering-ai-agents-with-tools-via-openapi-a-hands-on-guide-with-microsoft-semantic-kernel-agents\/","title":{"rendered":"Empowering AI Agents with Tools via OpenAPI: A Hands-On Guide with Microsoft Semantic Kernel Agents"},"content":{"rendered":"

Today the Semantic Kernel team is happy to welcome back our guest author, Akshay Kokane<\/a>. We will turn it over to him to dive into his recent Medium article on Semantic Kernel.<\/p>\n

As we advance towards an Agentic Approach in the AI world, I would like to share my insights on how Semantic Kernel can assist in building AI agents and leveraging existing APIs to create intelligent agents.<\/span>\u00a0<\/span><\/p>\n

In a previous <\/span>article<\/span><\/a>, I discussed how Semantic Kernel can develop a multi-agent system that fosters a collaborative environment for these agents to interact and deliver results. In this new blog post, I am pleased to share that by using the OpenAPI specification, we can utilize existing APIs to integrate with agents. These are referred to as tools or plugins, which AI agents can call upon to obtain contextual data.<\/span>\u00a0<\/span><\/p>\n

Using Semantic Kernel, adding plugins via the OpenAPI specification is simplified. Furthermore, these plugins are automatically triggered as and when required using the OpenAI Tool Calling. Semantic Kernel eliminates the complexities associated with tool invocation, streamlining the development of AI agents by removing the need to focus on these intricacies.\u00a0<\/span>\u00a0<\/span><\/p>\n

In this blog post, I will showcase how to create a chat-based application for an e-commerce platform that manages customer payments through the integration of their existing Payment Service APIs. Here are high level steps to import plugin through OpenApi:<\/span>\u00a0<\/span><\/p>\n

To add a plugin to your kernel:<\/span><\/p>\n

1. Add the following NuGet Reference:<\/span>\u00a0<\/span><\/p>\n

<PackageReference Include=\"Microsoft.SemanticKernel.Plugins.OpenApi\" Version=\"1.32.0-preview\" \/><\/code><\/pre>\n
2. Import the Plugin to the Kernel:<\/span><\/p>\n
await kernel.ImportPluginFromOpenApiAsync( \r\n\r\n   pluginName: \"paymentProcessor\", \r\n\r\n   uri: new Uri(\"localhost:8080\/swagger\/v1\/swagger.json\"), \r\n\r\n   executionParameters: new OpenApiFunctionExecutionParameters() { \r\n\r\n       EnablePayloadNamespacing = true \r\n\r\n   } \r\n\r\n); <\/code><\/pre>\n
This approach is transformative for enterprises aiming to leverage their existing APIs without reinventing the wheel. Additionally, the OpenAPI spec enables microservice architecture for your AI agents, facilitating easy scalability and resource management at the plugin level.<\/span>\u00a0<\/span><\/p>\n
Semantic Kernel offers several methods for calling APIs. The blog includes a simple example of non-Auth APIs, but it is also possible to call Auth-based APIs. For more information, refer to the documentation on <\/span>Give agents access to OpenAPI APIs | Microsoft Learn<\/span><\/a>\u00a0<\/span>For more details, please read the full article<\/a> below.\u00a0\u00a0<\/span><\/p>\n
Empowering AI Agents with Tools via OpenAPI: A Hands-On Guide with Microsoft Semantic Kernel Agents<\/span><\/h3>\n
<\/p>\n
I recently explored how the OpenAPI Specification can be utilized to give actionable capabilities to AI agents. In this blog, I aim to share my insights and demonstrate the process.<\/p>\n
Understanding the OpenAPI Specification<\/h1>\n
TThe\u00a0OpenAPI Specification<\/strong>\u00a0(formerly known as Swagger) is a standardized, language-agnostic framework for defining HTTP APIs. It allows both humans and machines t discover a service\u2019s capabilities without needing access to its source code or documentation. Properly defined OpenAPI specs enable consumers to interact with services using minimal implementation logic..\u00a0Learn more here<\/a>.<\/p>\n
Why Use OpenAPI with AI Agents?<\/h1>\n
Many enterprises already have robust APIs in place. With the growing demand for AI-enabled applications, using OpenAPI-based plugins simplifies the process of empowering AI agents with existing APIs. Semantic Kernel, when integrated with OpenAPI, provides AI agents with detailed API semantics, including endpoint descriptions, data types, and expected responses.<\/p>\n
For instance, imagine an e-commerce platform launching a new feature called\u00a0ShopChat.AI<\/strong>, where customers can interact with an AI agent to find and purchase products. The AI agent can handle payments and check order statuses by leveraging the existing\u00a0Payment Service APIs<\/strong>\u00a0through OpenAPI specs.<\/p>\n
Key Benefits of Combining OpenAPI with Semantic Kernel<\/h1>\n
Integrating OpenAPI specs with Semantic Kernel and Azure OpenAI provides numerous advantages:<\/p>\n
1. Simplified AI Integration<\/h2>\n
OpenAPI specs offer a standardized method for AI agents to understand and interact with existing APIs, eliminating the need for complex custom integrations.<\/p>\n
2. Enhanced Agent Functionality<\/h2>\n
By leveraging existing APIs, AI agents can handle a wide range of tasks, such as inventory management and payment processing, resulting in more versatile applications.<\/p>\n
3. Improved Scalability<\/h2>\n
As your application grows, integrating new APIs becomes easier with OpenAPI. This ensures that your AI agents can evolve alongside your platform.<\/p>\n
Building an AI-Powered Application with OpenAPI and Semantic Kernel<\/h1>\n
\n
\n
\"\"<\/picture><\/div>\n<\/div>
Example Agent based Application<\/figcaption><\/figure>\n
Let\u2019s consider an example: Suppose you have a payment service for your e-commerce platform already in use. The service exposes two APIs:<\/p>\n
    \n
  1. payment\/accept<\/strong><\/code>: This API accepts credit card information, processes the payment, and returns a\u00a0transactionId<\/code>.<\/li>\n
  2. payment\/status<\/strong><\/code>: This API uses the\u00a0transactionId<\/code>\u00a0to retrieve the payment status.<\/li>\n<\/ol>\n
    Now the e-commerce website is planning to launch new feature \u201cShopeChat.AI\u201d where you can interact with AI agent like you interact with actual shopkeeper to find best product and buy that product.<\/p>\n
    Step 1: Exposing OpenAPI Specs for Your Service<\/h2>\n
    Make sure your Payment Service is exposing the OpenAPI Spec. I am doing it in .net, so in .net you can expose the OpenAPI Spech by using Swagger. Complete guide can be found here\u00a0https:\/\/learn.microsoft.com\/en-us\/aspnet\/core\/tutorials\/web-api-help-pages-using-swagger?view=aspnetcore-8.0<\/a><\/p>\n
    This is using SwagsBuckler package, I will add this service<\/p>\n
    builder.Services.AddSwaggerGen(options =>\r\n{\r\n    var<\/span> xmlFile = $\"{System.Reflection.Assembly.GetExecutingAssembly().GetName().Name}<\/span>.xml\"<\/span>;\r\n    var<\/span> xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);\r\n    options.IncludeXmlComments(xmlPath);\r\n});<\/span><\/pre>\n
    Learn more about configuring Swagger\/OpenAPI at https:\/\/aka.ms\/aspnetcore\/swashbuckle<\/a><\/p>\n
    This should create output\u00a0http:\/\/localhost:5272\/swagger\/v1\/swagger.json<\/a>.<\/p>\n
    {\r\n\"openapi\": \"3.0.1\",\r\n\"info\": {\r\n\"title\": \"PaymentProcessor\",\r\n\"version\": \"1.0\"\r\n},\r\n\"paths\": {\r\n\"\/api\/Payments\/status\": {\r\n\"get\": {\r\n\"tags\": [\r\n\"Payments\"\r\n],\r\n\"summary\": \"Retrieves the status of a specific payment.\",\r\n\"responses\": {\r\n\"200\": {\r\n\"description\": \"Success\"\r\n}\r\n}\r\n}\r\n},\r\n\"\/api\/Payments\/process\": {\r\n\"post\": {\r\n\"tags\": [\r\n\"Payments\"\r\n],\r\n\"summary\": \"Processes a payment request.\",\r\n\"requestBody\": {\r\n\"description\": \"The payment request details.\",\r\n\"content\": {\r\n\"application\/json\": {\r\n\"schema\": {\r\n\"$ref\": \"#\/components\/schemas\/PaymentRequest\"\r\n}\r\n},\r\n\"text\/json\": {\r\n\"schema\": {\r\n\"$ref\": \"#\/components\/schemas\/PaymentRequest\"\r\n}\r\n},\r\n\"application\/*+json\": {\r\n\"schema\": {\r\n\"$ref\": \"#\/components\/schemas\/PaymentRequest\"\r\n}\r\n}\r\n}\r\n},\r\n\"responses\": {\r\n\"200\": {\r\n\"description\": \"Success\"\r\n}\r\n}\r\n}\r\n}\r\n},\r\n\"components\": {\r\n\"schemas\": {\r\n\"PaymentRequest\": {\r\n\"required\": [\r\n\"transactionId\"\r\n],\r\n\"type\": \"object\",\r\n\"properties\": {\r\n\"transactionId\": {\r\n\"minLength\": 1,\r\n\"type\": \"string\"\r\n},\r\n\"amount\": {\r\n\"minimum\": 0.01,\r\n\"type\": \"number\",\r\n\"format\": \"double\"\r\n}\r\n},\r\n\"additionalProperties\": false\r\n}\r\n}\r\n}\r\n}<\/code><\/pre>\n
    To ensure the Payment Service APIs are invoked correctly, I\u2019ve added a constant static transaction ID for verification purposes:<\/h1>\n
    TransactionId = \u201cTestService123\u201d<\/strong><\/p>\n
    \n
    \n
    \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
    Step 2: Optional Deployment to Azure<\/h2>\n
    While optional, deploying your service to Azure ensures accessibility and scalability. You can follow Microsoft\u2019s official guide on deploying ASP.NET Core apps to Azure App Services for a smooth cloud integration.If you plan to host your application in the cloud, deploy it to Azure for accessibility and scalability. While optional, this step ensures seamless integration and availability for testing and deployment.<\/p>\n
    \n
    \n
    \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
    Step 3:\u00a0<\/strong>Configuring a Semantic Kernel Agent.\u00a0We will call this agent as \u201cSalesAgent\u201d.<\/strong><\/h2>\n
    We\u2019ll set up a Semantic Kernel agent, which we\u2019ll refer to as\u00a0\u201cSalesAgent\u201d<\/strong>\u00a0Here\u2019s how to configure it:<\/p>\n
      \n
    1. Add the required package reference in your project<\/li>\n
    2. Import the paymentProcessor plugin from your OpenAPI specification:<\/li>\n<\/ol>\n
      <PackageReference Include=\"Microsoft.SemanticKernel.Plugins.OpenApi\" Version=\"1.32.0-preview\" \/><\/span><\/pre>\n
      await<\/span> kernel.ImportPluginFromOpenApiAsync(\r\n               pluginName: \"paymentProcessor\"<\/span>,\r\n               uri: new<\/span> Uri(\"http:\/\/payment-backend-f4bjgseugsdhddb4.eastus-01.azurewebsites.net\/swagger\/v1\/swagger.json.\"<\/span>),\r\n               executionParameters: new<\/span> OpenApiFunctionExecutionParameters()\r\n                {\r\n                      EnablePayloadNamespacing = true<\/span>\r\n                }\r\n            );<\/span><\/pre>\n
      Once your application is launched, the\u00a0Kernel<\/code>\u00a0object should display the\u00a0paymentProcessor<\/strong>\u00a0plugin. This confirms the successful integration of the APIs.<\/p>\n
      If you want to learn how to define kernel, checkout my previous\u00a0<\/em>blogs<\/em><\/a><\/p>\n
      \n
      \n
      \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
      Step 4: Run the app<\/strong><\/p>\n
      Now that everything is set up, deploy your application and begin interacting with the Semantic Kernel agent. The system is designed to handle various tasks seamlessly.<\/p>\n
      Sample Application Overview<\/h1>\n
      Here\u2019s a quick summary of the sample application I\u2019ve created. It includes two key plugins:<\/p>\n
        \n
      1. Inventory Plugin<\/strong>\nRetrieves the latest inventory details. This plugin resides inside SalesAgent service<\/li>\n
      2. PaymentProcessor Plugin<\/strong>\nThis plugin is hosted on another service. Makes API calls hosted on the PaymentProcessor service for handling transactions.<\/li>\n<\/ol>\n
        \n
        \n
        \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
        \n
        \n
        \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
        \n
        \n
        \"\"<\/picture><\/div>\n<\/div>\n<\/figure>\n
        Transaction id confirms that InventoryService\u2019s both APIs were called successfully by our AI Agent!!<\/strong><\/h2>\n
        Conclusion: A Powerful Combination for Streamlined AI Integration<\/h1>\n
        The OpenAPI Specification, along with Semantic Kernel and Azure OpenAI, presents a compelling solution for empowering AI agents with real-world capabilities. This combination offers several key benefits:<\/p>\n
          \n
        • Simplified AI Integration:<\/strong>\u00a0OpenAPI specs provide a standardized way for AI agents to understand and interact with existing APIs, eliminating the need for complex custom integrations.<\/li>\n
        • Enhanced Agent Functionality:<\/strong>\u00a0By leveraging existing APIs, AI agents can perform a wider range of tasks, such as processing payments or managing inventory. This leads to more versatile and helpful AI experiences.<\/li>\n
        • Improved Scalability:<\/strong>\u00a0As your application grows, you can easily integrate new APIs using the OpenAPI, allowing your AI agents to keep pace with evolving functionalities.<\/li>\n<\/ul>\n
          This blog has provided a step-by-step guide on utilizing OpenAPI specs with Semantic Kernel Agents and Azure OpenAI. By following these steps and embracing this powerful combination, you can empower your AI agents to deliver a more comprehensive and valuable user experience.<\/p>\n
          \n
          \n