哈囉，各位飢腸轆轆的饕客們！我是 iThome 鐵人賽的頂級廚師——「AI 全餐」的掌勺人。

在前幾天的菜色中，我們學會了如何用自己的程式碼（Native Code）來製作 Plugin，讓我們的 AI 服務生擁有新的技能。但對於企業級的應用來說，很多功能早就已經寫好了，它們以 RESTful API 的形式存在於公司的各個角落，例如查詢庫存、處理訂單、或者管理使用者資料。

難道我們要把這些 API 重新用 C# 或 Python 包裝一遍嗎？當然不用！這就像是廚房裡已經有現成的頂級食材，我們只需要一張標準食譜，讓 AI 廚師能看懂並直接拿來用。

這張「標準食譜」就是我們今天的主角：OpenAPI 規格（舊稱 Swagger）！

🍴 標準食譜登場：OpenAPI 規格是什麼？

想像一下，OpenAPI 規格就是你家餐館裡，用來描述每一道菜（API Endpoints）的詳細說明書。它鉅細靡遺地記載了：

1. 菜名 (Operation ID/Summary)：這個 API 的主要功能是什麼？
2. 配方 (Parameters)：需要提供哪些參數？參數的類型和意義是什麼？
3. 成品 (Responses)：回傳的結果是什麼格式？

Semantic Kernel（SK）這位頂級廚師非常聰明，它能直接讀取這份標準食譜，立刻學會如何調用這些 API，並自動將其轉換為 AI 可理解的 Plugin 函式，省去了我們手動包裝的麻煩！

👨‍🍳 實戰教學：匯入 OpenAPI 的魔法

現在，就讓我們來實戰，看看如何將一個外部 API 透過 OpenAPI 規格匯入到我們的 Kernel 裡。

我們以一個模擬的「燈光控制 API」為例。假設這個 API 的規格放在一個公開的 URL 上，比如 https://example.com/v1/swagger.json。

1. 安裝必要的套件

首先，你需要確保你的專案安裝了 Microsoft.SemanticKernel.Plugins.OpenApi：

dotnet add package Microsoft.SemanticKernel.Plugins.OpenApi --prerelease

2. 使用 ImportPluginFromOpenApiAsync

透過 Kernel 的擴充方法 ImportPluginFromOpenApiAsync，你可以在一行程式碼內完成匯入：

using Microsoft.SemanticKernel;
using Microsoft.SemanticKernel.Connectors.OpenAI;
using System.Net.Http.Headers;

// 假設這是你的 Kernel 已經建構完成
IKernelBuilder builder = Kernel.CreateBuilder()
    .AddOpenAIChatCompletion("your-model", "your-key");
Kernel kernel = builder.Build();

// 這是你的 OpenAPI 規格 URL (請替換為實際可用的 URL)
var openApiUrl = new Uri("https://petstore.swagger.io/v2/swagger.json"); 

// 執行匯入
// PluginName 將會是這個 Plugin 在 Kernel 裡的名字
// 這裡我們用一個更真實的例子：Swagger Petstore API
KernelPlugin petstorePlugin = await kernel.ImportPluginFromOpenApiAsync(
    pluginName: "PetStore",
    uri: openApiUrl,
    // 如果你的 API 需要驗證，可以在這裡提供 AuthCallback
    executionParameters: new OpenApiFunctionExecutionParameters()
    {
        // 範例：這裡假設 API 需要一個 Bearer Token
        AuthCallback = (request, cancellationToken) => 
        {
            // 在每次呼叫前，加入驗證資訊
            request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_API_TOKEN");
            return Task.CompletedTask;
        }
    }
);

Console.WriteLine($"已成功匯入 Plugin: {petstorePlugin.Name}");
Console.WriteLine($"擁有的函式: {string.Join(", ", petstorePlugin.Select(f => f.Name))}");

// ...

🧠 讓食譜更美味：OpenAPI 的 AI 友好調整

OpenAPI 規格主要是為人類和程式設計師設計的。但對 LLM 來說，我們需要「潤飾」一下這份食譜，讓 AI 廚師更容易理解和正確使用：

匯出到試算表

💡 實戰應用：Agent 執行 API 呼叫

當你將 OpenAPI Plugin 匯入 Kernel 後，你就可以像使用原生 Plugin 一樣，讓你的 AI Agent 透過 Function Calling 去執行這些 API 呼叫。

例如，如果你匯入了 PetStore 的 API，你可以這樣要求你的 AI 員工：

使用者：「幫我查查現在寵物店裡有哪些 status 是 sold 的狗狗可以領養？」

1. AI (LLM)： 接收到請求。
2. AI (LLM) 判斷： 發現有 PetStore-findPetsByStatus 函式，並判斷需要 status='sold' 的參數。
3. SK： 收到呼叫請求，執行 PetStore-findPetsByStatus(status: 'sold') 進行實際的 HTTP 呼叫。
4. API 伺服器： 回傳一串 JSON 格式的狗狗清單。
5. SK： 將 API 回應的結果送回給 LLM。
6. AI (LLM)： 根據回傳的清單，用自然的語言回答使用者：「好的！目前有 3 隻 status 是 sold 的狗狗：[...]，編號分別是 1001、1005、1010。」

整個過程全自動化，你的 AI Agent 就像擁有了一位全能的秘書，可以直接與企業的後端服務進行資料交換和業務邏輯操作！