Guide · Open source

How to use semantic-kernel: install, set keys and build an agent

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Semantic Kernel is a model-agnostic SDK from Microsoft for connecting large language models, such as OpenAI or Azure OpenAI models, to your own applications. This guide shows you how to install it, set your API key, and run a basic agent with a custom plugin. Note first: the project's README says Semantic Kernel is now succeeded by Microsoft Agent Framework, so check that project before starting something new.

Semantic Kernelmicrosoft/semantic-kernel · ★ 28.7k · MIT Install options & downloads

Quick start

1Check the successor project. Read the README notice that Semantic Kernel is succeeded by Microsoft Agent Framework, and decide which project fits your new work.
2Confirm your runtime. Make sure you have Python 3.10+, .NET 10.0+ or JDK 17+ installed.
3Set your API key. Export AZURE_OPENAI_API_KEY for Azure OpenAI, or OPENAI_API_KEY for OpenAI.
4Install the package. Run pip install semantic-kernel for Python, or dotnet add package Microsoft.SemanticKernel for .NET.
5Run the basic agent. Copy the quickstart code, create a ChatCompletionAgent, and call get_response or InvokeAsync with a message.
6Add a plugin. Mark a method with kernel_function or KernelFunction and a description so the agent can call it.

Check whether Semantic Kernel is the right project

The README states that Semantic Kernel is now Microsoft Agent Framework, described there as the enterprise-ready successor. It points to a migration guide for existing Semantic Kernel code.

Semantic Kernel still suits developers who already use Azure OpenAI or OpenAI and want a structured SDK for agents, or who maintain older Semantic Kernel code.

Existing Semantic Kernel code: follow the migration guide linked in the README.
New projects: evaluate Microsoft Agent Framework first.

What you need before installing

Semantic Kernel is a developer SDK, so you need to write code to use it. The README lists the runtime requirements for each language and an API key from an AI provider.

The README lists Windows, macOS and Linux as supported operating systems.

Python 3.10+, or .NET 10.0+, or JDK 17+
An Azure OpenAI or OpenAI API key

Install Semantic Kernel and set your API key

First, set the environment variable for your AI service. Use the Azure OpenAI variable if you use Azure, or the OpenAI variable if you connect to OpenAI directly.

Then install the package for your language. For Python, the README uses pip. For .NET, it adds the Microsoft.SemanticKernel package and the Agents.Core package. Java builds are described in the project's BUILD.md file.

Python: pip install semantic-kernel
Java: see the semantic-kernel-java build instructions

export AZURE_OPENAI_API_KEY=AAA....

# or OpenAI directly
export OPENAI_API_KEY=sk-...

pip install semantic-kernel

dotnet add package Microsoft.SemanticKernel
dotnet add package Microsoft.SemanticKernel.Agents.Core

Build a basic agent in Python

The README's first quickstart creates a ChatCompletionAgent with an Azure chat service, a name and a system instruction, then asks it for a response. The agent call is asynchronous, so it runs inside an async function started with asyncio.run.

The .NET quickstart follows the same pattern: it builds a kernel, creates a ChatCompletionAgent, and streams responses from InvokeAsync.

import asyncio
from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion

async def main():
    agent = ChatCompletionAgent(
        service=AzureChatCompletion(),
        name="SK-Assistant",
        instructions="You are a helpful assistant.",
    )
    response = await agent.get_response(messages="Write a haiku about Semantic Kernel.")
    print(response.content)

asyncio.run(main())

Add a plugin so the agent can call your code

Plugins extend an agent with tools. In Python, a plain class method marked with the kernel_function decorator becomes a tool the agent can call, and a description tells the model what the function does. The README's example is a menu plugin that returns specials and item prices.

In .NET, the same idea uses the KernelFunction attribute with a Description, and the plugin is registered on the kernel with KernelPluginFactory.CreateFromType.

Plugins can be native code functions, prompt templates, OpenAPI specs, or Model Context Protocol (MCP) tools, according to the README.
The README also shows structured output in Python through a Pydantic model.

from typing import Annotated
from semantic_kernel.functions import kernel_function

class MenuPlugin:
    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"

Next steps: multi-agent systems and other features

The README includes a Multi-Agent System example in Python and describes features for orchestrating several collaborating specialist agents. It also lists vector database connectors, multimodal input, and local deployment options such as Ollama, LMStudio and ONNX.

Read the examples in the repository and the linked documentation for the details of each feature before you build on it.

Vector DB connectors listed: Azure AI Search, Elasticsearch, Chroma
Local deployment options listed: Ollama, LMStudio, ONNX

What people use it for

Building a chatbot-style assistant with a fixed instruction, as shown in the basic agent quickstart
Giving an agent access to your own code, such as a menu plugin that returns prices
Returning structured output in a defined format using a Pydantic model in Python
Orchestrating several specialist agents in a multi-agent workflow
Connecting an agent to vector databases such as Azure AI Search, Elasticsearch or Chroma

Frequently asked questions

Is Semantic Kernel free to use?

Semantic Kernel is released under the MIT licence, as shown in the README and repository. You still need an Azure OpenAI or OpenAI API key, and the provider's usage terms apply to the model calls you make.

What do I need to install Semantic Kernel?

The README lists Python 3.10+, .NET 10.0+ or JDK 17+, and an Azure OpenAI or OpenAI API key. For Python, install it with pip install semantic-kernel.

Is Semantic Kernel the same as Microsoft Agent Framework?

No, but the README says Semantic Kernel is now succeeded by Microsoft Agent Framework. The README describes Agent Framework 1.0 as the production-ready successor, and it links a migration guide for existing Semantic Kernel code.

Can I use Semantic Kernel without OpenAI?

The README says the SDK is model-agnostic and lists support for Hugging Face, NVidia, Ollama, LMStudio and ONNX alongside OpenAI and Azure OpenAI. Check the repository for the exact connectors available in your language.

What is Semantic Kernel compared with LangChain or LlamaIndex?

Semantic Kernel is an SDK for building agents and plugins in C#, Python or Java. LangChain, LlamaIndex and Haystack are comparable projects in this space, and the best choice depends on your language, existing stack and whether you need Agent Framework's newer path.

Why does my Semantic Kernel code fail with a missing key error?

Check that the environment variable is set in the same shell where you run your program. The quickstarts read AZURE_OPENAI_API_KEY, or OPENAI_API_KEY when you use OpenAI directly.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Semantic Kernel suits developers who already use OpenAI or Azure OpenAI and want a structured SDK for agents and plugins in .NET, Python or Java. Teams starting new work, or anyone who wants a no-code tool or a single direct API call, should look at Microsoft Agent Framework or a simpler option instead.

Install options & downloads