Microsoft 스택에서 AI 기능을 추가해야 하지만 별도의 Python 서비스를 운영하고 싶지 않다면, Semantic Kernel은 현실적인 선택지입니다. Semantic Kernel은 기존 코드와 API를 대규모 언어 모델에 연결하는 Microsoft의 오픈소스 SDK이며, C#, Python, Java에서 사용할 수 있습니다. 이 글에서는 Semantic Kernel의 핵심 구조, 커널과 플러그인의 동작 방식, 그리고 OpenAPI 사양을 통해 REST API를 모델이 호출 가능한 도구로 바꾸는 방법을 구현 관점에서 정리합니다.
Semantic Kernel이란 무엇인가
Semantic Kernel은 Microsoft가 AI 에이전트를 구축하고 LLM을 애플리케이션 코드에 연결하기 위해 제공하는 경량 오픈소스 SDK입니다.
실무적으로는 다음 역할을 합니다.
- 애플리케이션 코드와 LLM 사이에 위치합니다.
- 모델이 사용할 수 있는 함수 목록을 제공합니다.
- 모델이 함수를 호출하면 실제 코드를 실행합니다.
- 실행 결과를 다시 모델에 전달합니다.
즉, 개발자는 일반적인 메서드나 API를 작성하고, Semantic Kernel은 이를 모델이 호출할 수 있는 도구로 노출합니다.
Semantic Kernel이 특히 유용한 이유는 세 가지입니다.
C#/.NET, Python, Java 공식 지원
Python 중심 에이전트 프레임워크와 달리 .NET 백엔드에서도 자연스럽게 사용할 수 있습니다.모델 공급자에 덜 종속됨
OpenAI, Azure OpenAI 등 커넥터를 통해 모델을 연결합니다. 모델을 교체할 때 애플리케이션 전체를 다시 작성하기보다 설정을 변경하는 방식에 가깝습니다.엔터프라이즈 환경을 고려한 구조
텔레메트리, 필터, 후크를 통해 AI 호출 흐름을 로깅하고 감사하거나 중간에 가로챌 수 있습니다.
커널, 플러그인, 함수 구조
Semantic Kernel의 핵심 객체는 Kernel입니다. AI 기능을 위한 종속성 주입 컨테이너처럼 생각하면 됩니다.
기본 흐름은 다음과 같습니다.
- 커널을 생성합니다.
- LLM 커넥터를 등록합니다.
- 모델이 호출할 수 있는 플러그인을 등록합니다.
- 프롬프트를 실행합니다.
- 모델이 필요하다고 판단하면 플러그인의 함수를 호출합니다.
- 함수 실행 결과를 다시 모델에 전달합니다.
플러그인과 함수
플러그인은 모델에 노출할 함수들의 묶음입니다. 함수는 모델이 호출할 수 있는 단일 기능입니다.
Semantic Kernel에서 함수는 크게 두 종류입니다.
네이티브 함수
C# 메서드나 Python 함수처럼 실제 코드로 작성된 함수입니다. 어노테이션이나 설명을 통해 모델이 이해할 수 있게 만듭니다.프롬프트 함수
텍스트 요약, 분류, 재작성처럼 모델 호출 자체를 템플릿화한 함수입니다.
C#에서 Semantic Kernel 시작하기
아래 예시는 커널을 만들고, OpenAI 채팅 모델을 등록한 뒤, LightsPlugin을 모델이 호출할 수 있도록 추가하는 기본 구조입니다.
var builder = Kernel.CreateBuilder();
builder.AddOpenAIChatCompletion(
modelId: "gpt-4o",
apiKey: apiKey
);
builder.Plugins.AddFromType<LightsPlugin>("Lights");
Kernel kernel = builder.Build();
var result = await kernel.InvokePromptAsync(
"Turn the kitchen light blue"
);
이제 모델은 프롬프트를 해석하다가 조명 상태 변경이 필요하다고 판단하면 LightsPlugin 안의 함수를 호출할 수 있습니다.
예를 들어 플러그인은 다음과 같은 형태가 될 수 있습니다.
public class LightsPlugin
{
[KernelFunction("change_light_state")]
[Description("Changes the state or color of a light")]
public string ChangeLightState(
[Description("The name of the light")] string lightName,
[Description("The target color")] string color
)
{
// 실제 조명 API 호출 또는 내부 서비스 호출
return $"{lightName} light changed to {color}";
}
}
핵심은 함수명과 파라미터 설명입니다. 모델은 이 메타데이터를 보고 어떤 함수를 어떤 인자로 호출할지 결정합니다.
OpenAPI-투-플러그인 패턴
Semantic Kernel의 실무 활용에서 가장 중요한 기능 중 하나는 OpenAPI 사양을 플러그인으로 가져오는 기능입니다.
이미 REST API가 있고 OpenAPI 문서가 있다면, 별도의 래퍼 코드를 많이 작성하지 않아도 됩니다. Semantic Kernel이 OpenAPI 사양을 읽고 각 엔드포인트를 모델이 호출 가능한 함수로 변환합니다.
C#에서 OpenAPI 플러그인 가져오기
await kernel.ImportPluginFromOpenApiAsync(
pluginName: "lights",
uri: new Uri("https://example.com/v1/swagger.json"),
executionParameters: new OpenApiFunctionExecutionParameters
{
EnablePayloadNamespacing = true
}
);
Python에서는 add_plugin_from_openapi를 사용하고, Java에도 동등한 임포터가 있습니다.
Semantic Kernel은 내부적으로 다음 작업을 수행합니다.
- OpenAPI 사양을 파싱합니다.
- 각 path와 operation을 함수로 변환합니다.
- 파라미터 이름, 타입, 설명, 스키마를 추출합니다.
- 해당 메타데이터를 모델에 전달합니다.
- 모델이 함수를 선택하면 HTTP 요청을 생성합니다.
- 인증 콜백을 적용하고 요청을 전송합니다.
- 응답을 다시 모델에 전달합니다.
Semantic Kernel은 OpenAPI 2.0 및 3.0을 지원하며, 가능한 경우 3.1 사양을 3.0으로 다운그레이드합니다.
모델이 잘 호출하는 OpenAPI 사양 작성법
OpenAPI 사양은 사람만 읽는 문서가 아닙니다. Semantic Kernel에서는 모델이 읽는 도구 설명이 됩니다.
따라서 사양 품질이 낮으면 모델의 함수 호출 품질도 떨어집니다.
다음 항목을 우선 점검하세요.
1. operationId를 명확하게 작성하기
좋지 않은 예:
operationId: update
더 나은 예:
operationId: updateKitchenLightColor
모델은 operationId를 보고 함수의 목적을 추론합니다. 짧고 모호한 이름보다 행동과 대상을 포함한 이름이 좋습니다.
2. 파라미터 설명 추가하기
parameters:
- name: lightId
in: path
required: true
description: The unique identifier of the light to update.
schema:
type: string
- name: color
in: query
required: true
description: The target color name, such as blue, red, or warm_white.
schema:
type: string
설명이 없으면 모델은 인자를 추측해야 합니다.
3. 가능한 경우 enum 사용하기
느슨한 문자열보다 enum이 더 안전합니다.
schema:
type: string
enum:
- blue
- red
- warm_white
- cool_white
4. 엔드포인트 수를 과도하게 늘리지 않기
모델에 너무 많은 도구를 한 번에 노출하면 선택 오류가 늘어날 수 있습니다. 에이전트가 실제로 필요한 API만 플러그인으로 가져오는 편이 좋습니다.
에이전트 및 플래닝
Semantic Kernel은 초기에는 목표를 단계별로 분해하는 명시적 플래너 중심으로 시작했습니다. 이후 최신 모델의 함수 호출 성능이 좋아지면서, 프레임워크도 모델이 직접 어떤 함수를 어떤 순서로 호출할지 결정하는 방식으로 이동했습니다.
현재 Semantic Kernel은 다음 기능도 제공합니다.
- 에이전트 패턴
- 다중 에이전트 패턴
- 세션 기반 상태 관리
- 에이전트 루프
- 외부 도구 연결을 위한 MCP 지원
다른 에이전트 SDK와 비교하면 다음과 같습니다.
| 프레임워크 | 주요 언어 | 오케스트레이션 모델 | 최적의 활용처 |
|---|---|---|---|
| Semantic Kernel | C#/.NET, Python, Java | 함수 호출 + 에이전트 | .NET 및 엔터프라이즈 팀 |
| LangGraph | Python, JS | 명시적 상태 그래프 | 복잡하고 분기되는 에이전트 흐름 |
| Google ADK | Python | 에이전트 + 도구 모델 | Google Cloud 및 Gemini 스택 |
| OpenAI Agents SDK | Python, JS | 에이전트 + 핸드오프 | OpenAI 중심 앱 |
절대적으로 더 좋은 프레임워크는 없습니다. 선택 기준은 다음입니다.
- 현재 사용하는 언어
- 모델 공급자
- 실행 흐름을 얼마나 명시적으로 제어해야 하는지
- 기존 API와 OpenAPI 사양의 품질
- 엔터프라이즈 감사 및 로깅 요구사항
Semantic Kernel과 Microsoft Agent Framework의 관계
Microsoft는 Microsoft Agent Framework, 즉 MAF를 도입했습니다. 문서에서는 이를 Semantic Kernel과 AutoGen의 직접적인 후속작으로 설명하며, 동일한 팀이 구축했다고 설명합니다.
MAF는 다음 방향을 가집니다.
- AutoGen의 에이전트 추상화
- Semantic Kernel의 엔터프라이즈 기능
- 다중 에이전트 오케스트레이션을 위한 그래프 기반 워크플로우
실무적으로는 다음처럼 판단하면 됩니다.
- 이미 Semantic Kernel로 만든 애플리케이션이 있다면 계속 사용해도 됩니다. SK는 안정적이고 지원됩니다.
- 새로운 에이전트 프로젝트라면 Microsoft Agent Framework 문서를 함께 검토하세요.
- OpenAPI 사양을 통해 REST API를 에이전트 도구로 노출하는 패턴은 두 프레임워크 모두에서 중요한 방향입니다.
즉, Semantic Kernel은 여전히 프로덕션에서 사용할 수 있는 안정적인 선택지입니다. 다만 Microsoft의 최신 에이전트 투자는 MAF 쪽으로 이동하고 있다는 점은 고려해야 합니다.
Semantic Kernel을 사용해야 할 때
다음 조건에 해당하면 Semantic Kernel을 검토할 만합니다.
- .NET 또는 Java 기반 백엔드에서 AI 오케스트레이션을 구현해야 한다.
- Python 사이드카 서비스를 추가하고 싶지 않다.
- 기존 REST API를 OpenAPI 사양으로 관리하고 있다.
- 모델이 REST API를 도구처럼 호출하게 만들고 싶다.
- 텔레메트리, 필터, 후크, 감사 로그가 필요하다.
- OpenAI, Azure OpenAI 등 모델 공급자를 교체할 가능성이 있다.
반대로 다음 경우에는 다른 선택지도 검토하세요.
- 팀이 Python 중심이고 최신 다중 에이전트 기능이 최우선이다.
- 복잡한 상태 그래프와 분기 흐름을 명시적으로 제어해야 한다.
- Microsoft의 최신 에이전트 방향을 바로 따라가고 싶다.
이 경우 MAF 또는 그래프 우선 에이전트 프레임워크가 더 적합할 수 있습니다.
Semantic Kernel 에이전트 뒤의 API 테스트
Semantic Kernel은 API를 대체하지 않습니다. API를 호출합니다.
따라서 에이전트 품질은 다음 두 가지에 크게 의존합니다.
- LLM 엔드포인트가 안정적으로 동작하는가
- OpenAPI 플러그인으로 가져온 REST API가 정확하게 설계되고 테스트되었는가
여기서 Apidog 같은 API 도구가 유용합니다.
1. OpenAPI 사양을 먼저 검증하기
Semantic Kernel은 OpenAPI의 각 operation을 함수로 바꿉니다. 따라서 사양이 모호하면 모델 호출도 모호해집니다.
가져오기 전에 다음을 확인하세요.
- 모든 엔드포인트가 실제로 호출 가능한가
- 요청 파라미터 설명이 충분한가
- 응답이 스키마와 일치하는가
- 인증 방식이 명확한가
- 불필요한 엔드포인트가 플러그인에 포함되어 있지 않은가
2. 개발 중에는 Mock API 사용하기
백엔드가 아직 완성되지 않았거나 LLM 호출 비용을 줄이고 싶다면 Mock API를 사용할 수 있습니다.
예를 들어 아직 구현되지 않은 조명 API를 다음처럼 모의할 수 있습니다.
{
"lightId": "kitchen",
"state": "on",
"color": "blue"
}
관련 내용은 모의 API와 API 호출 모의 방법을 참고할 수 있습니다.
3. 응답 형태를 단언하기
에이전트는 API 응답 구조에 민감합니다. 백엔드 응답 필드가 바뀌면 모델의 후속 추론이 달라질 수 있습니다.
API 단언을 사용해 다음을 확인하세요.
- 필수 필드가 존재하는가
- 타입이 스키마와 일치하는가
- 에러 응답 형식이 일관적인가
- 모델이 기대하는 데이터 구조를 유지하는가
4. 환경별 키 분리하기
LLM API 키와 내부 API 자격 증명을 코드에 하드코딩하지 마세요.
최소한 다음 환경을 분리하는 것이 좋습니다.
- 개발
- 스테이징
- 프로덕션
Semantic Kernel 설정에서도 환경별로 모델 엔드포인트, API 키, 플러그인 URL을 분리해 관리하는 것이 안전합니다.
자세한 하네스 구성은 Apidog로 에이전트의 도구 호출 테스트하기에서 확인할 수 있습니다.
자주 묻는 질문
Semantic Kernel은 무료이며 오픈소스인가요?
네. Semantic Kernel은 Microsoft가 GitHub에 공개한 오픈소스 SDK입니다. C#/.NET, Python, Java SDK를 제공합니다.
Semantic Kernel 자체는 무료로 사용할 수 있지만, OpenAI, Azure OpenAI 같은 모델 사용 비용은 별도로 발생합니다.
Semantic Kernel은 어떤 언어를 지원하나요?
C#/.NET, Python, Java를 지원합니다. 세 언어 모두 1.0+ 안정성을 보장합니다.
C# SDK가 가장 성숙하지만, Python과 Java SDK도 커널, 플러그인, OpenAPI 가져오기 같은 핵심 기능을 제공합니다.
Semantic Kernel은 OpenAPI 사양을 어떻게 사용하나요?
C#에서는 ImportPluginFromOpenApiAsync, Python에서는 add_plugin_from_openapi를 사용해 OpenAPI 사양을 가져올 수 있습니다.
Semantic Kernel은 사양을 파싱하고 각 operation을 호출 가능한 함수로 변환합니다. 모델은 operation 설명, 파라미터 설명, 스키마 정보를 보고 어떤 함수를 호출할지 결정합니다.
따라서 사양을 먼저 검증하는 것이 중요합니다. Apidog를 사용하면 OpenAPI 사양 검증과 실시간 엔드포인트 테스트를 함께 수행할 수 있습니다.
Semantic Kernel을 사용해야 하나요, 아니면 Microsoft Agent Framework를 사용해야 하나요?
이미 Semantic Kernel 애플리케이션을 운영 중이라면 계속 사용해도 됩니다. Semantic Kernel은 안정적이고 지원됩니다.
새 프로젝트라면 Microsoft Agent Framework 문서를 함께 검토하는 것이 좋습니다. Microsoft는 MAF를 Semantic Kernel과 AutoGen의 후속 방향으로 제시하고 있습니다.
어떤 프레임워크를 선택하든, 에이전트가 호출하는 API를 테스트해야 합니다. 관련 예시는 Apidog로 ChatGPT API를 테스트하는 방법을 참고하세요.
마무리
Semantic Kernel은 Microsoft 스택에서 AI 기능을 구현하는 실용적인 방법입니다. 커널은 모델과 코드를 연결하고, 플러그인은 모델이 호출할 수 있는 기능을 제공하며, OpenAPI 가져오기는 기존 REST API를 에이전트 도구로 노출합니다.
이미 .NET, Java, 또는 엔터프라이즈 API 기반 시스템을 운영하고 있다면 Semantic Kernel은 여전히 안정적인 선택입니다. 다만 새 프로젝트에서는 Microsoft Agent Framework의 방향도 함께 확인하는 것이 좋습니다.
무엇을 선택하든 에이전트가 호출하는 API 계약은 견고해야 합니다. 에이전트에 연결하기 전에 사양을 설계하고, Mock API로 검증하고, 응답을 테스트하려면 Apidog를 다운로드해 API 계약을 먼저 정리하세요.
Top comments (0)