セマンティックカーネルとは？ MicrosoftのAIオーケストレーションSDK

Microsoftスタックでソフトウェアを構築していて、Pythonサービスを別途追加せずにAI機能を組み込みたい場合、Semantic Kernelは有力な選択肢です。Semantic Kernelは、既存のコードやAPIを大規模言語モデルに接続するMicrosoft製のオープンソースSDKで、C#、Python、Javaで利用できます。この記事では、Semantic Kernelの基本構成、カーネル・プラグイン・関数の使い方、そしてOpenAPI仕様を使ってREST APIをモデルから呼び出せるようにする実装パターンを整理します。

今すぐApidogを試す

Semantic Kernelとは

Semantic Kernel (SK) は、Microsoftが提供する軽量なオープンソース開発キットです。アプリケーションとAIモデルの間に入り、モデルからの要求を実際の関数呼び出しに変換し、結果をモデルへ返します。

開発者の視点では、次のように考えると分かりやすいです。

1. 通常のアプリケーションコードを書く
2. モデルに呼び出してよい関数を登録する
3. モデルが必要に応じて関数を選択する
4. Semantic Kernelが実行と結果の受け渡しを担当する

Semantic Kernelの特徴は主に3つあります。

• C#/.NET、Python、Javaに対応
  
  3言語すべてに公式SDKがあり、バージョン1.0以上の安定性保証があります。特に.NETバックエンドでは自然に導入しやすいSDKです。

• モデルに依存しない
  
  OpenAI、Azure OpenAI、その他のプロバイダーへコネクタ経由で接続できます。モデルを切り替える場合も、アプリケーション全体を書き換えるのではなく、設定変更で対応しやすくなります。

• エンタープライズ向けの拡張ポイントがある
  
  テレメトリー、フック、フィルターを使って、AIの動作をログ記録・監査・制御できます。

カーネル、プラグイン、関数の基本構造

Semantic Kernelの中心はカーネルです。カーネルは、AI向けの依存性注入コンテナのような役割を持ちます。

カーネルには次のものを登録します。

• 使用するAIモデル
• モデルに公開するプラグイン
• プラグイン内の関数
• 必要に応じた認証、フィルター、実行設定

用語の整理

用語	役割
カーネル	モデル呼び出し、関数呼び出し、結果の受け渡しを管理する中核オブジェクト
プラグイン	モデルに公開する関数群
関数	モデルが呼び出せる単一の処理

関数には大きく2種類あります。

• ネイティブ関数
  
  C#メソッドやPython関数など、通常のコードで実装する関数です。

• プロンプト関数
  
  テキスト要約、分類、書き換えなど、モデル呼び出し自体をテンプレート化した関数です。

C#でSemantic Kernelをセットアップする

C#では、まずカーネルを作成し、チャットモデルとプラグインを登録します。

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 に定義された関数をモデルが必要に応じて呼び出せます。

例えば LightsPlugin 側では、次のような関数を公開できます。

public class LightsPlugin
{
    [KernelFunction("change_light_state")]
    [Description("Change the state and color of a light")]
    public string ChangeLightState(
        [Description("The room name")] string room,
        [Description("The color to set")] string color
    )
    {
        // 実際のIoT APIや内部サービスを呼び出す
        return $"Changed {room} light to {color}";
    }
}

モデルが「キッチンのライトを青にして」と判断すると、Semantic Kernelは該当する関数を実行し、結果をモデルへ返します。

OpenAPI仕様をプラグインとしてインポートする

Semantic Kernelで特に実用的なのが、OpenAPI仕様からプラグインを生成するパターンです。

既存のREST APIがOpenAPI仕様を持っていれば、ラッパーコードを大量に書かなくても、各APIオペレーションをモデルが呼び出せる関数として公開できます。

C#では ImportPluginFromOpenApiAsync を使います。

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仕様から次の情報を読み取ります。

• パス
• HTTPメソッド
• operationId
• パラメータ名
• パラメータの説明
• 型情報
• リクエスト・レスポンススキーマ

そして、それらをモデルが理解できる関数メタデータとして渡します。モデルは、ユーザーの依頼に応じてどのAPIを呼ぶべきか、どの引数を渡すべきかを推論します。

Semantic KernelはOpenAPI 2.0および3.0をサポートしており、可能な場合は3.1仕様を3.0へダウングレードします。

モデルが呼び出しやすいOpenAPI仕様にする

OpenAPI仕様は、人間にとって読みやすいだけでは不十分です。モデルが正しくツール呼び出しできるように、仕様そのものを設計する必要があります。

最低限、次を確認してください。

• operationId を具体的にする
• パラメータの説明を省略しない
• 曖昧な string を減らし、enumや型付きパラメータを使う
• 1つのAPIに過剰な責務を持たせない
• レスポンススキーマを正確に定義する
• エラー時のレスポンスも明示する
• 不要なエンドポイントをモデルに公開しない

悪い例です。

paths:
  /items:
    get:
      operationId: get
      parameters:
        - name: q
          in: query
          schema:
            type: string

改善例です。

paths:
  /items:
    get:
      operationId: searchInventoryItems
      summary: Search inventory items
      description: Search inventory items by keyword and optional category.
      parameters:
        - name: keyword
          in: query
          description: Keyword used to search item names and descriptions.
          required: true
          schema:
            type: string
        - name: category
          in: query
          description: Optional item category.
          required: false
          schema:
            type: string
            enum:
              - hardware
              - software
              - accessory

仕様の品質は、エージェントのAPI呼び出し精度に直接影響します。

認証が必要なAPIを呼び出す場合

OpenAPIプラグインとしてインポートするAPIが認証を必要とする場合は、実行時に認証情報を付与する設計が必要です。

典型的には、次のような情報を環境ごとに分離します。

• LLMプロバイダーのAPIキー
• REST APIのアクセストークン
• ステージング・本番のベースURL
• テナントIDやユーザーコンテキスト

APIキーやトークンはコードにハードコードせず、設定ファイル、環境変数、シークレット管理サービスなどで管理してください。

エージェントとプランニング

Semantic Kernelは当初、目標を段階的に分解する明示的なプランナーを提供していました。その後、モデルの関数呼び出し能力を活用する方向へ進化しました。

現在は、モデル自身が次の判断を行う構成が一般的です。

1. ユーザーの要求を理解する
2. 呼び出すべき関数を選ぶ
3. 必要な引数を組み立てる
4. 関数の結果を受け取る
5. 必要なら追加の関数を呼ぶ
6. 最終応答を生成する

Semantic Kernelには、エージェントやマルチエージェントパターンを構築するためのエージェントフレームワーク層もあります。これには、セッションベースのステート、エージェントループ、外部ツールを接続するためのModel Context Protocol（MCP）サポートが含まれます。

他のエージェントSDKとの比較

フレームワーク	主要言語	オーケストレーションモデル	最適な用途
Semantic Kernel	C#/.NET、Python、Java	関数呼び出し + エージェント	.NETおよびエンタープライズチーム
LangGraph	Python、JS	明示的な状態グラフ	複雑で分岐するエージェントフロー
Google ADK	Python	エージェント + ツールモデル	Google CloudおよびGeminiスタック
OpenAI Agents SDK	Python、JS	エージェント + ハンドオフ	OpenAI中心のアプリ

どれか1つが常に優れているわけではありません。選択基準は次の通りです。

• 主言語が.NETかPythonか
• モデルプロバイダーを固定するか
• 実行フローを明示的に制御したいか
• OpenAPIベースで既存APIを使いたいか
• エンタープライズ向けの監査やテレメトリーが必要か

Semantic KernelとMicrosoft Agent Frameworkの位置付け

MicrosoftはMicrosoft Agent Framework（MAF）を導入しており、ドキュメントではSemantic KernelとAutoGenの後継として説明されています。MAFは、AutoGenのエージェント抽象化とSemantic Kernelのエンタープライズ機能を組み合わせ、マルチエージェントオーケストレーション向けのグラフベースワークフローを追加します。

現時点での実務的な判断は次の通りです。

• 既存のSemantic Kernelアプリケーションは継続利用できる
• Semantic Kernelは安定しており、現在もサポートされている
• 1.0以上の後方互換性保証は維持される
• 新規のエージェントプロジェクトではMAFのドキュメントも確認する
• OpenAPI仕様を通じてREST APIをツール化するパターンは両方で重要

既にSemantic Kernelで実装している場合、急いで移行する必要はありません。新規プロジェクトの場合は、Semantic KernelとMAFの両方を比較してから選定するのが安全です。

Semantic Kernelを使うべきケース

Semantic Kernelは、次のようなケースに向いています。

• .NETまたはJava中心のスタックでAIオーケストレーションを追加したい
• Pythonサイドカーを増やしたくない
• 既存のREST APIをOpenAPI仕様経由でモデルに呼び出させたい
• モデルプロバイダーを切り替えられる設計にしたい
• テレメトリー、フック、フィルター、監査性が必要
• エンタープライズ環境でAI機能を段階的に導入したい

一方、Pythonのみのチームで、最新のマルチエージェント機能やグラフベースの制御を最優先する場合は、MAFやLangGraphのような選択肢も検討してください。

Semantic Kernelエージェントの背後にあるAPIをテストする

Semantic KernelはAPIを置き換えるものではありません。モデルが呼び出すAPIをオーケストレーションする仕組みです。そのため、エージェントが依存するAPIの品質が重要になります。

ここでAPIツールとしてApidogを使うと、OpenAPI仕様の設計、モック、テスト、アサーションをまとめて扱えます。

Semantic Kernelエージェントが依存する主なエンドポイントは2種類です。

1. LLMプロバイダーのエンドポイント
2. OpenAPIプラグインとしてインポートするREST API

どちらも正しく記述され、期待通りに応答し、環境ごとに安定している必要があります。

1. OpenAPI仕様をインポート前に検証する

Semantic KernelはOpenAPI仕様をもとに関数メタデータを生成します。仕様が曖昧だと、モデルのツール選択も曖昧になります。

インポート前に確認する項目は次の通りです。

• スキーマが正しいか
• 必須パラメータが明示されているか
• レスポンスが定義と一致しているか
• operationIdが具体的か
• モデルに公開すべきでないAPIが含まれていないか

2. 開発中はAPIをモックする

まだ実装されていないAPIがある場合は、モックAPIを使うと、エージェント側の実装を先に進められます。

また、LLMエンドポイントや外部APIをモックすることで、次の問題を避けられます。

• トークン消費の増加
• レート制限
• 外部サービス障害の影響
• 開発環境での予期しない課金

具体的なパターンは、API呼び出しをモックする方法も参考になります。

3. レスポンス形状をアサートする

モデルは、APIレスポンスの構造に依存して次の判断を行います。バックエンド変更でレスポンス形状が変わると、エージェントの動作が壊れる可能性があります。

APIアサーションを使って、次のような項目を検証してください。

• HTTPステータスコード
• 必須フィールドの存在
• 型の一致
• enum値の範囲
• エラー時レスポンスの形式
• モデルが参照するフィールド名

4. 環境ごとにキーとURLを分離する

LLMとREST APIの認証情報は、開発・ステージング・本番で分離してください。

最低限、次の値は環境ごとに管理します。

OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
INTERNAL_API_BASE_URL=
INTERNAL_API_TOKEN=

コード内に直接埋め込むのではなく、環境変数やシークレット管理サービスから読み込む構成にします。

エージェントのツール呼び出しをより詳しく検証したい場合は、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でもカーネル、プラグイン、OpenAPIインポートなどの主要機能を利用できます。

Semantic KernelはOpenAPI仕様をどのように使いますか？

C#では ImportPluginFromOpenApiAsync、Pythonでは add_plugin_from_openapi を使ってOpenAPI仕様をインポートします。Semantic Kernelは仕様内の各オペレーションを、モデルが呼び出せる関数に変換します。

モデルは仕様内の説明に依存するため、事前に仕様を検証することが重要です。Apidogを使えば、OpenAPI仕様の確認とライブエンドポイントのテストを行えます。

Semantic KernelとMicrosoft Agent Frameworkのどちらを使うべきですか？

既にSemantic Kernelアプリケーションがある場合は、そのまま使い続けて問題ありません。Semantic Kernelは現在もサポートされており、安定しています。

新規プロジェクトの場合、Microsoft Agent Frameworkが後継として位置づけられているため、最新ドキュメントを確認してから選定してください。どちらを使う場合でも、エージェントが呼び出すAPIのテストは必要です。LLM APIの検証には、ApidogでChatGPT APIをテストする方法も参考になります。

まとめ

Semantic Kernelは、MicrosoftスタックのチームがAI機能を既存アプリケーションに組み込むための実用的なSDKです。カーネルにモデルとプラグインを登録し、ネイティブ関数やOpenAPI仕様から生成した関数をモデルに呼び出させることで、既存のREST APIをエージェントツールとして活用できます。

導入時は、コードだけでなくOpenAPI仕様とAPIテストも重視してください。仕様が曖昧だと、モデルのツール呼び出しも不安定になります。エージェントが依存するAPIを設計、モック、検証するには、Apidogをダウンロードして、モデルに公開する前にAPI契約を固めておきましょう。