實作課程 01 — 環境設定

目標： 已設定為搭配 Copilot SDK 使用，並以 Agent HQ 示範應用程式作為 SDK 工作階段、串流與範例的可執行載體。

時間： 約 15 分鐘

必要條件

請參閱 實作課程 README。簡而言之：.NET 10 SDK、已登入的 GitHub Copilot CLI，以及 curl 以及 jq.

步驟 1 — 複製並檢視

git clone https://github.com/vicperdana/aigenius-copilotsdk-s5ep2.git
cd aigenius-copilotsdk-s5ep2

花點時間查看四周：

ls

此版面配置遵循 Microsoft Build 工作階段存放庫慣例 — .NET 實作位於 src/AgentOrchestrator/，其中包含兩個專案與測試。

⚠️ 存放庫根目錄沒有方案檔。 其位置為 src/AgentOrchestrator/AgentHQDemo.slnx，因此建置與測試命令會明確指定它。若直接在根目錄執行 dotnet build ，則從根目錄執行會失敗並顯示 MSB1003.

步驟 2 — 還原並建置

dotnet restore src/AgentOrchestrator/AgentHQDemo.slnx
dotnet build   src/AgentOrchestrator/AgentHQDemo.slnx

預期結果：

Build succeeded.
    0 Warning(s)
    0 Error(s)

⚠️ 如果您遇到 MSB3923: Failed to download file ... registry.npmjs.org，表示您的網路封鎖了 npm 套件登錄庫。Copilot SDK 會在建置時下載相符的 CLI 二進位檔。請改為全域安裝 CLI，然後重新建置 — Directory.Build.props 會偵測並重複使用：

npm install -g @github/copilot

請參閱 疑難排解 取得完整覆寫項目清單。

步驟 3 — 執行測試

dotnet test src/AgentOrchestrator/AgentHQDemo.slnx

預期結果：

Passed!  - Failed: 0, Passed: 26, Skipped: 0, Total: 26

記住這個數字。實作課程 05 會要求您新增測試，而且不能破壞這些測試。

步驟 4 — 啟動 API

在第一個終端機中：

dotnet run --project src/AgentOrchestrator/AgentHQDemo.Api --urls "http://localhost:5050"

第一次執行時，系統會自動建立 SQLite 資料庫並植入資料 — 您會看到 EF Core CREATE TABLE 以及 INSERT 陳述式，接著：

Now listening on: http://localhost:5050
Application started.

步驟 5 — 啟動 Blazor UI

在一個 第二個 終端機：

dotnet run --project src/AgentOrchestrator/AgentHQDemo.Web --urls "http://localhost:5051"

接著開啟 http://localhost:5051。您應該會看到空白的聊天 UI：

⚠️ 連接埠已在使用中？ 先前執行的伺服器可能仍在運作，並悄悄提供過期程式碼。請找到並停止它：

lsof -ti:5050        # prints a PID if something is listening
kill <PID>

步驟 6 — 驗證 REST API

在第三個終端機中：

curl -s http://localhost:5050/api/chat/health | jq
curl -s http://localhost:5050/api/transactions | jq 'length'
curl -s http://localhost:5050/api/segments | jq '.[].name'
curl -s http://localhost:5050/api/segments/predict/C003 | jq

預期結果：健康情況回報 "status":"healthy"、10 筆交易、四個客群區隔名稱（High Value、Regular、At Risk、New），以及如下的預測：

{
  "customerId": "C003",
  "predictedSegment": "High Value",
  "confidence": 0.89,
  "topFeatures": ["high_total_spend", "multi_category", "total_1700"]
}

步驟 7 — 驗證串流是否運作

這才是真正的測試 — 它能證明 Copilot SDK 已正確接線並完成驗證：

curl -N -X POST http://localhost:5050/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Reply with just the word OK","model":"claude-haiku-4.5"}'

預期結果 — 區塊逐步送達，最後以終止符結束：

data: {"content":"OK"}

data: [DONE]

⚠️ 如果您看到 data: {"error":"..."} 改為，表示 SDK 已連上 CLI，但某個環節失敗。常見原因有兩個：

• Model "..." is not available — 您的帳戶無法使用該模型識別碼。請向 API 查詢您實際可用的模型： curl -s http://localhost:5050/api/chat/models | jq '.[].id'
• JSON-RPC 或還原序列化錯誤 — 您的 SDK 與 CLI 版本已不一致。請執行 copilot --version 並檢查 疑難排解.

步驟 8 — 驗證 SDK 實作課程範例

後續每個 SDK 實作課程都會使用範例專案，因此請先建置一次，並確認可存取 CLI 進入點：

dotnet build src/AgentOrchestrator/samples/SdkLabs
dotnet run --project src/AgentOrchestrator/samples/SdkLabs

預期結果：建置成功，接著在不帶引數執行時，會列印使用方式橫幅並列出五個範例命令：

tools
events
permissions
sessions
mcp

這可確認 SDK 已載入、專案可以執行，而且後續步驟可以使用實作課程命令。

步驟 9 — 試用 UI

回到瀏覽器中的 http://localhost:5051:

1. 開啟 模型 下拉式選單 — 內容會在執行階段從您的帳戶載入，因此清單只會包含您確實可以使用的模型
2. 提問： 「哪個客群區隔的留存率最低？」
3. 逐一觀察權杖送入回應串流

✅ 檢查點

您現在應該具備：

• [x] 乾淨建置，26/26 項測試通過
• [x] API 位於 5050，UI 位於 5051
• [x] REST 端點會傳回種子資料
• [x] 從真實模型取得即時串流回應
• [x] SDK 實作課程範例專案可成功建置並列印命令橫幅

💡 延伸練習

查詢模型端點，並計算您的帳戶提供多少個模型：

curl -s http://localhost:5050/api/chat/models | jq 'length'

請將它與以下位置的靜態備援清單比較： ChatController.AvailableModels。即時清單才是正確資料來源 — 實作課程 02 會說明其重要性。

相關內容

• 下一步： 實作課程 02 — 第一次對話
• 示範：Copilot SDK 整合
• 疑難排解