세마틱 커널이란 무엇인가? 마이크로소프트 AI 오케스트레이션용 SDK

Microsoft 스택에서 소프트웨어를 구축하고 Python 서비스를 별도로 추가하지 않고 AI를 통합하고 싶다면 Semantic Kernel은 Microsoft가 여러분을 위해 만든 SDK입니다. 이 SDK는 기존 코드와 API를 대규모 언어 모델에 연결하는 오픈소스 키트로, C#, Python, Java에서 실행됩니다. 이 가이드에서는 Semantic Kernel이 무엇인지, 커널과 플러그인이 어떻게 결합되는지, 그리고 OpenAPI 사양 지원을 통해 모든 REST API가 모델이 호출할 수 있는 형태로 어떻게 전환되는지 설명합니다.

버튼

Semantic Kernel이란 무엇인가

Semantic Kernel (SK)은 Microsoft가 AI 에이전트를 구축하고 모델을 코드베이스에 통합하기 위해 제공하는 경량 오픈소스 개발 키트입니다. Microsoft는 이를 미들웨어라고 설명합니다. 즉, 애플리케이션과 모델 사이에 위치하여 모델의 요청을 실제 함수 호출로 변환하고 실행한 다음 결과를 다시 전달합니다. 여러분은 일반 코드를 작성하고, 모델이 언제 이를 호출할지 결정합니다.

SK가 다른 에이전트 라이브러리 중에서 돋보이는 세 가지 특징이 있습니다.

첫째, 진정한 다국어 지원입니다. SK는 C#/.NET, Python, Java용 공식 SDK를 제공하며, 세 가지 언어 모두에서 버전 1.0+ 안정성을 보장합니다. 대부분의 에이전트 프레임워크는 Python 우선이며 다른 언어는 나중에 고려하는 경향이 있습니다. 백엔드가 .NET인 경우, SK는 네이티브처럼 느껴지는 몇 안 되는 성숙한 옵션 중 하나입니다.

둘째, 모델에 구애받지 않습니다. SK는 커넥터 세트를 통해 OpenAI, Azure OpenAI 및 기타 공급자와 연결됩니다. 모델을 교체하고 싶을 때는 전체 애플리케이션을 변경하는 것이 아니라 구성을 변경합니다.

셋째, 기업의 관심사를 염두에 두고 구축되었습니다. 텔레메트리, 후크, 필터가 최고 수준으로 지원되므로 AI가 수행하는 작업을 로깅하고 감사하며 가로챌 수 있습니다. 이러한 집중 덕분에 Microsoft와 여러 Fortune 500 기업 팀이 이를 채택했습니다.

커널, 플러그인, 그리고 함수

핵심 객체는 커널입니다. AI를 위한 종속성 주입 컨테이너라고 생각하면 됩니다. 모델 커넥터와 플러그인을 커널에 등록한 다음, 커널에 작업을 실행하도록 요청합니다. 커널은 오케스트레이션을 처리합니다: 프롬프트, 모델 호출, 함수 호출, 결과, 반복.

플러그인은 모델에 노출하는 명명된 함수 그룹입니다. 함수는 모델이 호출할 수 있는 단일 기능입니다. 함수에는 두 가지 유형이 있습니다.

네이티브 함수는 커널이 모델에 설명할 수 있도록 어노테이션을 추가하는 코드의 일반 메서드(C# 메서드, Python 함수)입니다.
프롬프트 함수는 모델 자체를 호출하는 템플릿화된 프롬프트로, 텍스트 요약, 분류 또는 재작성에 유용합니다.

다음은 C#에서의 모습입니다. 커널을 구축하고, 채팅 모델을 등록하고, 플러그인을 추가한 다음, 모델이 필요할 때 함수를 호출하도록 합니다.

var builder = Kernel.CreateBuilder();
builder.AddOpenAIChatCompletion("gpt-4o", apiKey);
builder.Plugins.AddFromType<LightsPlugin>("Lights");
Kernel kernel = builder.Build();

// The model can now invoke LightsPlugin functions during a chat
var result = await kernel.InvokePromptAsync("Turn the kitchen light blue");

모델이 반환되고 커널이 change_light_state를 호출하려는 것을 감지하면, 커널은 여러분의 코드를 실행하고, 결과를 캡처하여 모델에 다시 전달합니다. 이 루프가 SK의 핵심입니다.

OpenAPI-투-플러그인 패턴

이것은 가장 주목할 만한 기능이며, 기존 서비스로의 가장 깔끔한 다리입니다. SK는 OpenAPI 사양을 가져와 모든 작업을 호출 가능한 함수로 자동 전환할 수 있습니다. 래퍼 코드를 작성할 필요가 없습니다. SK에 사양을 지정하면 각 경로/작업이 모델이 호출할 수 있는 함수가 됩니다.

C#에서는 호출이 ImportPluginFromOpenApiAsync입니다. Python에서는 add_plugin_from_openapi입니다. Java에도 동등한 임포터가 있습니다. 다음은 URL에서 사양을 로드하는 C# 버전입니다.

await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "lights",
    uri: new Uri("https://example.com/v1/swagger.json"),
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        EnablePayloadNamespacing = true
    }
);

내부적으로 SK는 사양을 파싱하고, 모든 매개변수의 이름, 설명, 유형 및 스키마를 추출하여 해당 메타데이터를 모델에 전달합니다. 모델은 어떤 작업을 호출하고 어떤 인수를 전달할지 추론합니다. 그런 다음 SK는 HTTP 요청을 구성하고, 인증 콜백을 적용하고, 이를 전송하며, 응답을 다시 읽습니다. SK는 OpenAPI 2.0 및 3.0을 지원하며, 가능한 경우 3.1 사양을 3.0으로 다운그레이드합니다.

문제는 사람을 위해 작성된 사양이 모델에게 항상 명확하지는 않다는 것입니다. Microsoft의 자체 지침은 설명적인 작업 ID를 추가하고, 유용한 매개변수 설명을 작성하며, 엔드포인트 수를 적게 유지하고, 느슨한 문자열보다는 열거형 및 형식화된 매개변수를 선호하라는 것입니다. 사양의 품질은 에이전트가 API를 얼마나 잘 호출하는지에 직접적인 영향을 미칩니다. 이는 사양 자체가 나중에 생각할 것이 아니라 신중하게 설계하고 테스트할 가치가 있는 요소임을 의미합니다.

에이전트 및 플래닝

SK는 목표를 단계별로 분해하는 명시적인 플래너로 시작했습니다. 그 이후 프레임워크는 함수 호출 방식으로 전환되었는데, 이는 모델 자체가 어떤 함수를 어떤 순서로 호출할지 결정하는 방식으로, 최신 모델에서는 더 안정적입니다. 이 외에도 SK는 에이전트 및 다중 에이전트 패턴 구축을 위한 에이전트 프레임워크 레이어를 추가했으며, 세션 기반 상태, 에이전트 루프 및 외부 도구 연결을 위한 모델 컨텍스트 프로토콜(MCP) 지원을 제공합니다.

접근 방식을 비교한다면, 이 블로그에서 다룬 다른 에이전트 SDK와 SK가 어떻게 비교되는지 살펴보겠습니다.

프레임워크	주요 언어	오케스트레이션 모델	최적의 활용처
Semantic Kernel	C#/.NET, Python, Java	함수 호출 + 에이전트	.NET 및 엔터프라이즈 팀
LangGraph	Python, JS	명시적 상태 그래프	복잡하고 분기되는 에이전트 흐름
Google ADK	Python	에이전트 + 도구 모델	Google Cloud 및 Gemini 스택
OpenAI Agents SDK	Python, JS	에이전트 + 핸드오프	OpenAI 중심 앱

이들 중 어느 것도 절대적으로 더 좋다고 할 수는 없습니다. 올바른 선택은 사용하는 언어, 모델 공급자, 그리고 실행에 대한 얼마나 명시적인 제어를 원하는지에 따라 달라집니다.

Semantic Kernel과 Microsoft Agent Framework의 관계

이 분야는 빠르게 변화하므로, 현재 상황을 솔직하게 말씀드리겠습니다. Microsoft는 Microsoft Agent Framework (MAF)를 도입했으며, 문서에서는 이를 Semantic Kernel과 AutoGen의 직접적인 후속작으로, 동일한 팀이 구축했다고 설명합니다. MAF는 AutoGen의 에이전트 추상화와 SK의 엔터프라이즈 기능을 결합하고, 다중 에이전트 오케스트레이션을 위한 그래프 기반 워크플로우를 추가합니다.

실제 의미는 다음과 같습니다.

Semantic Kernel은 안정적이며 여전히 지원됩니다. 기존 SK 애플리케이션은 계속 작동하며, 1.0+ 버전의 호환성 보장이 유지됩니다.
새로운 에이전트 프로젝트의 경우, Microsoft는 Agent Framework를 권장하며 SK 코드를 이전하기 위한 마이그레이션 가이드를 발행합니다.
OpenAPI-투-플러그인 아이디어는 계속 이어집니다. 사양을 통해 에이전트가 REST API에 액세스하도록 하는 것은 두 프레임워크가 공유하는 패턴입니다.

따라서 SK는 여전히 유지 관리되는 견고하고 프로덕션 검증된 선택으로 간주하되, 최신 투자는 MAF로 향하고 있음을 알아두십시오. 오늘 결정하고 여러분의 코드가 이미 SK에 있다면, 서두를 필요는 없습니다. 새로 시작하고 최신 방향을 원한다면, 결정하기 전에 MAF 문서를 읽어보십시오.

Semantic Kernel을 사용해야 할 때

다음과 같은 경우 SK를 활용하세요.

스택이 .NET 또는 Java이고 Python 사이드카 대신 네이티브하게 느껴지는 AI 오케스트레이션을 원할 때.
기존 REST API 포트폴리오를 보유하고 있으며 모델이 OpenAPI 사양을 통해 이를 호출하도록 하려 할 때.
텔레메트리, 필터, 후크, 그리고 AI가 수행한 작업을 감사할 수 있는 기능과 같은 엔터프라이즈 기반 시설이 필요할 때.
모델에 구애받지 않고 앱을 다시 작성하지 않고도 공급자를 교체하고 싶을 때.

팀이 Python만 사용하고 최신 다중 에이전트 기능을 원한다면 다른 대안을 찾아보세요. 이 경우 MAF 또는 그래프 우선 라이브러리가 더 적합할 수 있습니다.

Semantic Kernel 에이전트 뒤의 API 테스트

여기서 API 툴링이 중요하며, Apidog가 깔끔하게 들어맞는 부분입니다. SK는 API를 구축하거나 대체하지 않습니다. SK는 API를 호출합니다. SK 에이전트는 두 종류의 엔드포인트에 의존합니다. 하나는 통신하는 LLM 엔드포인트이고, 다른 하나는 OpenAPI 플러그인으로 가져오는 REST API입니다. 두 가지 모두 올바르고, 잘 설명되어 있으며, 신뢰할 수 있어야 합니다. 그렇지 않으면 에이전트가 잘못된 호출을 할 수 있습니다.

몇 가지 실용적인 작업:

OpenAPI 사양을 가져오기 전에 설계하고 테스트하십시오. SK는 각 작업을 함수로 변환하고 모델에 매개변수 설명을 제공하므로, 부실한 사양은 부실한 도구 호출을 초래합니다. 사양을 검증하고, 모든 엔드포인트를 실행하며, 응답이 스키마와 일치하는지 확인하십시오. 깔끔한 계약은 더 나은 에이전트를 만듭니다.
개발 중에 종속성을 모의(Mock)하십시오. 아직 구축되지 않은 엔드포인트를 위해 모의 API를 설정하거나, 오케스트레이션 루프를 디버깅하는 동안 토큰 소모 및 호출 제한에 도달하는 것을 피하기 위해 LLM 엔드포인트를 모의할 수 있습니다. 패턴에 대한 자세한 내용은 API 호출 모의 방법을 참조하십시오.
응답 형태를 단언(Assert)하십시오. API 단언을 사용하여 에이전트가 호출하는 도구 엔드포인트가 모델이 예상하는 구조를 정확히 반환하는지 확인하십시오. 이렇게 하면 백엔드 변경이 에이전트 동작을 예기치 않게 손상시키는 것을 방지할 수 있습니다.
환경별 키를 관리하십시오. LLM 및 API 자격 증명을 하드코딩하는 대신 개발, 스테이징, 프로덕션 환경별로 분리하여 관리하십시오.

이것은 에이전트 대신이 아니라, 에이전트 이전과 주변에서 수행되는 일반적인 API 작업입니다. 더 깊이 있는 설명을 원하시면 Apidog로 에이전트의 도구 호출 테스트하기에서 하네스에 대해 자세히 다룹니다.

자주 묻는 질문

Semantic Kernel은 무료이며 오픈소스인가요?

네, 그렇습니다. Semantic Kernel은 오픈소스이며 Microsoft가 GitHub에 관대한 라이선스 하에 게시했으며, C#/.NET, Python, Java용 SDK를 제공합니다. SK 자체에는 비용이 들지 않지만, 모델 사용(OpenAI, Azure OpenAI 등)에 대한 비용은 지불해야 합니다.

Semantic Kernel은 어떤 언어를 지원하나요?

C#/.NET, Python, Java를 지원하며, 모두 버전 1.0+ 안정성을 보장합니다. C# SDK가 가장 성숙하지만, Python 및 Java SDK도 핵심 커널, 플러그인, OpenAPI 가져오기 기능을 포함합니다.

Semantic Kernel은 OpenAPI 사양을 어떻게 사용하나요?

ImportPluginFromOpenApiAsync (C#) 또는 add_plugin_from_openapi (Python)를 사용하여 사양을 가져올 수 있습니다. SK는 사양을 파싱하고, 각 작업을 매개변수 메타데이터가 포함된 호출 가능한 함수로 전환하며, 모델이 해당 작업을 호출하도록 합니다. 모델이 여러분의 설명에 의존하므로, 먼저 사양을 검증하는 것이 중요합니다. Apidog를 사용하여 이 작업을 수행하고 실시간 엔드포인트를 테스트할 수 있습니다.

Semantic Kernel을 사용해야 하나요, 아니면 Microsoft Agent Framework를 사용해야 하나요?

이미 SK 애플리케이션을 사용 중이라면 계속 사용하세요. 지원되고 안정적입니다. 새로운 프로젝트의 경우 Microsoft는 Agent Framework를 후속작으로 제시하며 마이그레이션 가이드를 제공합니다. 이 분야는 빠르게 변화하고 있으므로, 새로 시작하기 전에 현재 MAF 문서를 확인하십시오. 둘 중 하나가 호출하는 API를 테스트하려면, Apidog로 ChatGPT API를 테스트하는 방법을 참조하십시오.

마무리

Semantic Kernel은 Microsoft 스택 팀에게 AI를 오케스트레이션하는 깔끔한 방법을 제공합니다. 모델을 코드에 연결하는 커널, 모델이 호출할 수 있는 플러그인과 함수, 그리고 기존 REST API를 에이전트 도구로 노출하는 OpenAPI 가져오기 경로가 그것입니다. 이는 안정적이고 프로덕션 검증되었으며, 이제 Agent Framework가 최신 방향을 이끌고 있습니다. 어떤 것을 선택하든, 기반이 되는 API는 여전히 견고해야 합니다. 에이전트가 호출하기 전에 에이전트가 의존하는 사양과 엔드포인트를 설계하고, 모의하며, 테스트하려면 Apidog를 다운로드하여 계약을 구축하십시오.