實作課程 01 — 環境設定¶
目標： 使用 Agent HQ 的示範 app 作為 SDK 工作階段、串流和範例的可執行載體，設定 Copilot SDK 的 Python 學習路線
時間： ~15 分鐘
必要條件¶
你只需要為實驗使用一個實作的學習路線。此頁面使用的是 .NET 學習路線下的 Python 同層目錄 src/AgentOrchestrator-python/; .NET 學習路線仍保持在
src/AgentOrchestrator/.
安裝這些在開始之前:
- Python 3.11 或更高版本
- uv 用於相依套件管理和命令執行
- GitHub Copilot CLI，並已登入
git,curl，以及jq
⚠️ 你 不 需要為此學習路線安裝 .NET SDK。Python SDK 包為
github-copilot-sdk 版本 1.0.9，匯入名稱為 copilot，專案在其中固定了其版本：
pyproject.toml.
第1步 — 複製並檢查¶
Python 實作與 .NET 實作位於同一目錄中：
當您想獲取完整的地圖時，請閱讀Python學習路線概述。
src/AgentOrchestrator-python/README.md
它與.NET應用功能相匹配：相同的API合同、相同的種子資料、相同的故意程式碼氣味和相同的Copilot SDK學習路徑。
⚠️ 請選擇一個學習路線。 您可以不安裝兩者，同時執行它們，因為埠不重疊：.NET使用5050和5051，而Python使用 5070 API和UI。
第2步 — 恢復相依套件¶
從存放庫根目錄：
uv sync 建立虛擬環境並安裝應用相依套件、開發相依套件、FastAPI、SQLModel、pytest、ruff以及Copilot SDK。
⚠️ 請稍後執行Python命令。 src/AgentOrchestrator-python 除非命令明確改變您所在的目錄，否則沒有解決方案檔案和沒有根級別的Python包執行。
第3步 — 執行測試¶
進行緊湊的CI風格檢查：
預期：30個測試透過。一個驗證執行產生了：
這是14個領域測試和12個MCP伺服器測試——兩者匹配.NET套件——再加上4個僅保護瀏覽器/API請求形狀的Python測試。
記得那個數字。稍後實驗30個測試會要求你不破壞這些。
第4步 — 執行程式碼檢查器¶
預期結果：
linter 設定檔案位於 pyproject.toml.
第5步 — 啟動API和UI¶
在你的第一個終端:
開啟 http://localhost:5070. 你應該看到空的聊天 UI:
⚠️ 與.NET 學習路線不同，這裡沒有 單獨的 UI 伺服器. FastAPI 從同一個程序的埠 5070 服務
💡 為什麼不是 5060 而是 5070? Chrome、Edge、Firefox拒絕開啟埠5060
—這是SIP埠，位於瀏覽器的封鎖埠清單中，因此頁面失敗 ERR_UNSAFE_PORT 儘管 curl 但工作正常。如果更改埠，請避免5060、5061和6000。
在編輯-重新整理開發中，新增 --reload:
⚠️ 埠已佔用？ 一個來自之前執行的伺服器可能仍然在監聽5070上並提供過時的程式碼。在重新啟動之前停止監聽5070的程序。
第6步 — 驗證健康端點¶
在第二個終端，仍然來自 src/AgentOrchestrator-python:
預期結果：
{"status":"healthy","service":"CopilotChat","availableModels":["claude-haiku-4.5","gpt-4.1","gpt-5","claude-sonnet-4.5","claude-opus-4.5","gemini-2.5-pro"]}
這個端點不呼叫模型。它證明應用程式是執行的，並顯示如果即時模型探索失敗時使用的靜態備用目錄。
第7步 — 驗證REST API¶
Python API保持與.NET相同的駝峰式JSON合同，這意味著
customerId, productCategory，以及 topFeatures，而不是Python內部的
customer_id, product_category，以及 top_features.
執行:
curl -s http://localhost:5070/api/transactions | jq 'length'
curl -s http://localhost:5070/api/segments | jq 'length'
curl http://localhost:5070/api/segments/predict/C003
預期事實:
GET /api/transactions傳回10行GET /api/segments傳回4行- 預測呼叫傳回:
{"customerId":"C003","predictedSegment":"High Value","confidence":0.89,"topFeatures":["high_total_spend","multi_category","total_1700"]}
camelCase合同在
app/models.py
所以 curl 範例在兩個學習路線上都有效。
第8步 — 驗證串流¶
這證明了Copilot SDK已連線，CLI已登入，API可以串流模型輸出到瀏覽器或終端。
curl -sN -X POST http://localhost:5070/api/chat/stream \
-H 'Content-Type: application/json' \
-d '{"prompt":"Reply with exactly: streaming works","model":"claude-haiku-4.5"}'
預期流的形狀:
三件事很重要：每個事件都以 data:, 每個事件後面跟著一個空行，流的結束以 data: [DONE].
⚠️ 欄位是 prompt，而不是 message一個未識別的鍵被無聲地忽略，因此一個拼寫錯誤會傳送一個空的提示詞並傳回一個通用的問候，而不是一個錯誤。
⚠️ 如果你看到 data: {"error": "..."} 相反，伺服器已到達SDK但SDK無法完成請求。常見原因可能是未在Copilot CLI中籤入或選擇您帳戶無法使用的模型。
第9步 — 驗證SDK實驗範例¶
每個後續的Python SDK實驗都使用 sdk_labs 模組。現在執行一個真實的範例:
預期結果：
== Lab 03: tools ==
Model: claude-haiku-4.5
Prompt: How much has customer C003 spent in total?
[tool] get_customer_total(C003) -> $1,700.00
Assistant: Customer C003 has spent a total of **$1,700.00** across 2 transactions.
命令排程器位於
sdk_labs/__main__.py.
後來的實驗使用 uv run python -m sdk_labs events,
uv run python -m sdk_labs sessions，以及 uv run python -m sdk_labs mcp.
第10步 — 試用UI¶
回到瀏覽器中，在 http://localhost:5070, 開啟 模型 下拉選單併傳送一條訊息以檢視串流渲染路徑。
💡 請求體使用 prompt匹配 ChatRequest一個早期修訂
已釋出 message 在這裡；因為Pydantic會丟棄未知鍵，UI串流了一個回覆到一個空的提示詞，沒有任何錯誤聲張。 tests/test_chat_contract.py
現在斷言欄位 app.js 傳送的是欄位，API讀取。
✅ 檢查點¶
你應該現在有：
- [x] Python相依套件恢復
uv sync - [x] 30/30測試透過
- [x] Ruff透過
- [x] API和UI在埠5070上執行
- [x] REST端點傳回種子駝峰資料
- [x] 從真實模型串流的即時回應
- 可執行載體上的SDK樣品
uv run python -m sdk_labs ...
💡 延伸挑戰¶
查詢模型端點並計數您的帳戶提供:
然後檢查在
app/routers/chat.py的備用目錄中。