moenv_openapi_agent 是一個基於 Agent Development Kit (ADK) 的範例代理程式，旨在展示如何將台灣環境部 (MOENV) 的真實世界 OpenAPI 規範整合到一個代理程式中。此專案的最終目標是建立一個能夠使用自然語言查詢環境部開放資料的智慧代理程式。
此檔案定義了 LlmAgent，並整合了 OpenAPI 工具。它配置了代理程式的名稱、使用的語言模型 (LiteLlm)，並包含詳細的指令，指導代理程式根據使用者的自然語言查詢，判斷何時以及如何使用環境部 API 工具。環境部 API 所需的 api_key 會從環境變數傳遞給 OpenAPIToolset。
此檔案負責運行 moenv_openapi_agent 的設定。它處理環境變數的載入、代理程式的實例化、運行器的設定，並提供一個互動迴圈，用於模擬使用者互動，向代理程式發送訊息並列印其回應。
此檔案包含了台灣環境部環境資料開放平台開放資料 API 的 OpenAPI 3.0.0 規範。它定義了各種用於環境資料的 GET 端點，每個端點都需要一個 api_key 查詢參數。
此工具腳本用於修正 moenv_openapi.yaml 檔案中的特定格式問題。它會將 responses: { 200: { description: OK } } 替換為 responses: { '200': { description: OK } }，以確保 YAML 結構的正確性，避免解析錯誤。
此工具腳本用於自動化修改 moenv_openapi.yaml 檔案，為所有 GET 操作添加安全定義 (security: [{'ApiKeyAuth': []}])，並從參數列表中移除 api_key。這有助於將 API 金鑰的處理與 ADK 代理程式的安全性機制整合，確保 API 呼叫的安全性與一致性。
main.py 預期在專案根目錄中存在一個 .env 檔案，其中包含以下配置：
LITELLM_MODEL_NAME="您偏好的 litellm 模型" # 例如：openai/gpt-3.5-turbo, gemini-pro
LITELLM_API_KEY="您的 litellm api 金鑰"
MOENV_API_KEY="您的環境部 api 金鑰" # 請從 https://data.moenv.gov.tw.tw/api-term 取得
- 環境設定：
- 確保
moenv_openapi.yaml檔案位於專案根目錄。 - 在專案根目錄建立一個
.env檔案，並填入上述所需的 API 金鑰和模型名稱。
- 確保
- 運行代理程式：
- 執行
main.py。
- 執行
- 互動：
- 透過提出可使用環境部 API 回答的問題來與代理程式互動（例如：「查詢酸雨監測值」）。
當以下條件滿足時，此範例將被視為成功：
- 代理程式能夠初始化並運行而沒有錯誤。
- 環境部 API 工具在收到適當的使用者查詢後，能被代理程式成功調用。
- 代理程式的回應能夠反映從環境部 API 檢索到的資料。
results/ 目錄中包含了代理程式與使用者互動的範例日誌，展示了其查詢環境部開放資料的能力。
此日誌展示了代理程式處理多種環境資料查詢的能力，包括：
- 酸雨監測值（歷史資料）：查詢並摘要最新的酸雨監測記錄。
- 空氣品質預報資料：提供最新的空氣品質預報，包含 AQI 及污染物資訊。
- 全國細懸浮微粒手動監測資料：查詢並摘要全國 PM2.5 手動監測數據。
- 環境部職員官等性別統計資料：提供環境部職員依官等和性別的統計數據。
- 環境教育活動數量：概覽環境教育活動的年度與季度數量及趨勢分析。 這些範例突顯了代理程式理解自然語言查詢、利用相關 OpenAPI 工具、並以結構化格式呈現數據的能力。
此日誌記錄了使用者查詢「垃圾／廢棄物」相關資料集的互動。代理程式列出了多個與廢棄物管理相關的 API 資料集（例如廢棄物流向統計、回收量、回收率、清運機具資料等），並提供了每個資料集的簡要說明和 API 使用範例。這展示了代理程式能夠引導使用者探索特定主題下的可用資料資源。
此日誌聚焦於「資源回收」及「回收量／回收率」相關的查詢。代理程式詳細列出了與資源回收相關的 API，並針對「電池回收量」和「廢乾電池回收量」提供了具體的查詢結果和歷史數據分析。日誌中也包含了 API 的使用說明，例如如何取得 API-Key、發送 HTTP GET 請求，以及如何根據年份、回收項目或材質進行篩選。這證明了代理程式在特定環境議題上提供深入數據分析和精確查詢的能力。
如需更詳細的設計說明和技術規範，請參閱 docs/moenv_openapi_agent_spec.md。