Semantic Kernel 시작하기

몇 단계만 따라 하면 Python, .NET, Java 중 어느 언어로든 첫 AI 에이전트를 만들 수 있어요. 이 가이드에서는 필요한 패키지를 설치하고, AI와 주고받는 대화를 만들고, 에이전트가 여러분의 코드를 실행하게 하고, AI가 즉석에서 계획을 세우는 것까지 확인해 볼 거예요.

출처: 공식문서

SDK 설치하기

Semantic Kernel은 여러 NuGet 패키지를 제공하지만, 대부분의 시나리오에서는 보통 Microsoft.SemanticKernel 하나면 충분해요.

 dotnet add package Microsoft.SemanticKernel

전체 NuGet 패키지 목록은 지원 언어 문서에서 확인할 수 있어요.

Python 패키지는 PyPI에서 받을 수 있는데, 설치가 아주 간단해요.

 pip install semantic-kernel

Java 패키지는 semantic-kernel-java 리포지토리에서 받을 수 있어요.

 <dependencyManagement> <dependencies> <dependency> <groupId>com.microsoft.semantic-kernel</groupId> <artifactId>semantickernel-bom</artifactId> <version>${sk.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement> <dependencies> <dependency> <groupId>com.microsoft.semantic-kernel</groupId> <artifactId>semantickernel-api</artifactId> </dependency> <dependency> <groupId>com.microsoft.semantic-kernel</groupId> <artifactId>semantickernel-aiservices-openai</artifactId> </dependency> </dependencies>

노트북으로 빠르게 시작하기

Python이나 C# 개발자라면 제공되는 노트북으로 바로 시작할 수 있어요. 노트북에는 AI 에이전트를 만드는 과정이 단계별로 정리돼 있어요.

Semantic Kernel 리포지토리를 클론해요
Visual Studio Code에서 열어요
dotnet/notebooks로 이동해요
00-getting-started.ipynb를 열어 환경을 설정하고 첫 AI 에이전트를 만들어요

첫 콘솔 앱 작성하기

새 .NET 콘솔 프로젝트를 만듭니다.

 dotnet new console

필요한 .NET 의존성을 설치해요.

 dotnet add package Microsoft.SemanticKernel dotnet add package Microsoft.Extensions.Logging dotnet add package Microsoft.Extensions.Logging.Console

Program.cs 내용을 아래 코드로 바꿔요. Azure OpenAI 채팅 완성으로 커널을 만들고, 로깅을 추가하고, LightsPlugin을 커널에 등록하고, 자동 함수 호출을 켠 뒤 사용자와 주고받는 대화를 시작해요.

 // Import packages
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.Extensions.Logging;
 using Microsoft.SemanticKernel;
 using Microsoft.SemanticKernel.ChatCompletion;
 using Microsoft.SemanticKernel.Connectors.OpenAI;
 // Populate values from your OpenAI deployment
 var modelId = "";
 var endpoint = "";
 var apiKey = "";
 // Create a kernel with Azure OpenAI chat completion
 var builder = Kernel.CreateBuilder().AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);
 // Add enterprise components
 builder.Services.AddLogging(services => services.AddConsole().SetMinimumLevel(LogLevel.Trace));
 // Build the kernel
 Kernel kernel = builder.Build();
 var chatCompletionService = kernel.GetRequiredService<IChatCompletionService>();
 // Add a plugin (the LightsPlugin class is defined below)
 kernel.Plugins.AddFromType<LightsPlugin>("Lights");
 // Enable planning
 OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
 {
     FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
 };
 // Create a history store the conversation
 var history = new ChatHistory();
 // Initiate a back-and-forth chat
 string? userInput;
 do
 {
     // Collect user input
     Console.Write("User > ");
     userInput = Console.ReadLine();
     // Add user input
     history.AddUserMessage(userInput);
     // Get the response from the AI
     var result = await chatCompletionService.GetChatMessageContentAsync(
         history,
         executionSettings: openAIPromptExecutionSettings,
         kernel: kernel);
     // Print the results
     Console.WriteLine("Assistant > " + result);
     // Add the message from the agent to the chat history
     history.AddMessage(result.Role, result.Content ?? string.Empty);
 } while (userInput is not null);

콘솔에서 보게 될 대화는 대략 아래와 비슷해요. AI가 뒤에서 플러그인을 어떻게 활용하는지 보여 주려고 함수 호출 부분을 함께 표시했어요.

Role	Message
🔵 User	Please toggle the light
🔴 Assistant (function call)	`LightsPlugin.GetState()`
🟢 Tool	`off`
🔴 Assistant (function call)	`LightsPlugin.ChangeState(true)`
🟢 Tool	`on`
🔴 Assistant	The light is now on

코드 이해하기

Semantic Kernel로 기업용 앱을 만들기 쉽도록, 커널을 만들고 AI 서비스와 상호작용하는 과정을 단계별로 정리했어요. 아래 단계들이 전체 흐름이에요.

패키지 가져오기 (Import packages)
AI 서비스 추가 (Add AI services)
엔터프라이즈 컴포넌트 (Enterprise components)
커널 만들기 (Build the kernel)
메모리 추가 (Add memory — 이 샘플에서는 건너뜀)
플러그인 추가 (Add plugins)
커널 인자 만들기 (Create kernel arguments — 건너뜀)
프롬프트 만들기 (Create prompts — 건너뜀)
플래닝 (Planning)
호출 (Invoke)

AI 서비스 추가하기

커널에서 가장 중요한 부분은 사용할 AI 서비스예요. 이 예제에서는 Azure OpenAI 채팅 완성 서비스를 커널 빌더에 추가했어요. Azure OpenAI 대신 다른 채팅 완성 서비스를 써도 돼요. 지원 서비스 전체 목록은 지원 언어 문서, 서비스 생성 방법은 AI 서비스 문서에서 확인할 수 있어요.

 // Create kernel
 var builder = Kernel.CreateBuilder()
 builder.AddAzureOpenAIChatCompletion(modelId, endpoint, apiKey);

플러그인 추가하기

플러그인을 추가하면 AI 에이전트가 외부 소스에서 정보를 가져오거나 동작을 수행하도록 여러분의 코드를 실행할 수 있어요. 위 예제에서는 에이전트가 전구(light bulb)를 조작하도록 하는 플러그인을 추가했어요. 네이티브 플러그인을 만드는 것은 클래스 하나를 만드는 것만큼 간단해요. 아래는 C#으로 만든 LightsPlugin이에요.

 using System.ComponentModel;
 using System.Text.Json.Serialization;
 using Microsoft.SemanticKernel;

 public class LightsPlugin
 {
     // Mock data for the lights
     private readonly List<LightModel> lights = new()
     {
         new LightModel { Id = 1, Name = "Table Lamp", IsOn = false },
         new LightModel { Id = 2, Name = "Porch light", IsOn = false },
         new LightModel { Id = 3, Name = "Chandelier", IsOn = true }
     };

     [KernelFunction("get_lights")]
     [Description("Gets a list of lights and their current state")]
     public async Task<List<LightModel>> GetLightsAsync()
     {
         return lights;
     }

     [KernelFunction("change_state")]
     [Description("Changes the state of the light")]
     public async Task<LightModel?> ChangeStateAsync(int id, bool isOn)
     {
         var light = lights.FirstOrDefault(light => light.Id == id);
         if (light == null)
         {
             return null;
         }
         // Update the light with the new state
         light.IsOn = isOn;
         return light;
     }
 }

 public class LightModel
 {
     [JsonPropertyName("id")]
     public int Id { get; set; }
     [JsonPropertyName("name")]
     public string Name { get; set; }
     [JsonPropertyName("is_on")]
     public bool? IsOn { get; set; }
 }

플래닝 활성화하기

Semantic Kernel은 대부분의 LLM이 기본 지원하는 function calling을 활용해 플래닝을 제공해요. 자동 함수 호출을 켜려면, AI 에이전트가 함수를 요청했을 때 커널이 알아서 호출하도록 실행 설정(execution settings)을 만들어야 해요.

 OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
 {
     FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
 };

 execution_settings = AzureChatPromptExecutionSettings()
 execution_settings.function_choice_behavior = FunctionChoiceBehavior.Auto()

 // Enable planning
 InvocationContext invocationContext = new InvocationContext.Builder()
     .withReturnMode(InvocationReturnMode.LAST_MESSAGE_ONLY)
     .withToolCallBehavior(ToolCallBehavior.allowAllKernelFunctions(true))
     .build();

호출하기

마지막으로 플러그인과 함께 AI 에이전트를 호출해요. 아래 코드는 비스트리밍 응답을 만드는 예시예요. GetStreamingChatMessageContentAsync 메서드를 쓰면 스트리밍 응답도 만들 수 있어요.

 // Create chat history
 var history = new ChatHistory();
 // Get the response from the AI
 var result = await chatCompletionService.GetChatMessageContentAsync(
     history,
     executionSettings: openAIPromptExecutionSettings,
     kernel: kernel
 );

 dotnet run

더 알아보기 (Learn more)

심화 샘플 — 더 복잡한 AI 에이전트를 만드는 예제
AI 서비스 문서 — 다양한 서비스 추가하기
플러그인이란? — 네이티브 코드로 플러그인 만들기