OakXgen 使用手冊

外觀

沒有 MCP 的系統，怎麼讓 AI 即時查：用 HTTP API 接政府開放資料

這篇用一個只有 REST API、沒有 MCP 的政府開放資料服務，示範怎麼自己定義 HTTP 動作，讓 AI 在對話當下查即時資料。完成後，你可以在對話裡用統一編號或公司名稱查公司登記狀態，並從工具呼叫紀錄確認 AI 帶入的參數值。

開始前 ​

你需要能管理工具庫與建立 Skill Agent 的工作區權限，以及一個可供 agent 使用的AI 引擎。

本例使用經濟部商工登記公示資料的開放 API，服務位址是 https://data.gcis.nat.gov.tw。這個 API 不需要註冊或金鑰，驗證方式選不需驗證；查詢條件用 OData 格式的查詢參數 $filter 傳送，查不到資料時會回傳空白內容。資料由政府機關提供，欄位與服務狀態可能變動。

同一個需求會用到五個設定，先分清楚它們在哪裡，之後 AI 沒查到資料時才知道要回頭檢查哪一個。

項目在哪裡設定在這個例子裡的作用
連線工具庫儲存服務位址、驗證方式，以及每次請求都附加的 $format=json
動作該連線的操作分頁自己建立兩個動作：用統一編號查公司登記、用公司名稱查統一編號
模型參數動作視窗的模型會看到的參數由 {tax_id}、{company_name} 推導，補上說明讓 AI 知道該填什麼值
AI 代理AI 代理的知識與工具分頁建立「公司登記查詢助理」，把兩個動作加入這個 agent
對話對話選「公司登記查詢助理」提問，查看工具呼叫紀錄裡的參數

如果你的 API 需要金鑰 ​

很多政府開放資料 API 要求在網址帶金鑰，例如環境部環境資料開放平臺的 API 使用 api_key 查詢參數。這種情況請在連線設定把驗證方式選查詢參數，參數名稱填 api_key，Token 填 <你的 API 金鑰>。不要把金鑰寫在動作的查詢參數或系統提示詞裡；連線層的憑證會套用到底下的每個動作，存檔後也不會再顯示原值。

MCP 和 HTTP API 的差別 ​

〈用 MCP 做一個政府標案助理〉接的是 MCP 伺服器：按探索工具後，工具名稱、說明與參數都由伺服器提供。HTTP API 沒有這一步，每個動作、每個參數的意思都要自己寫。下表比較兩者在設定上的差異。

比較項目MCP 伺服器HTTP API
動作從哪裡來按探索工具向伺服器取得清單在操作分頁按新增動作逐一建立
參數定義伺服器提供的遠端參數定義，只能開關與改描述路徑、查詢參數、Header 或本文裡的 {參數名}，由系統推導
參數說明由伺服器提供自己在告訴模型這個參數是什麼填寫
模型看到的函式名稱伺服器的工具名稱，例如 search_tenders由 HTTP 方法與路徑組成，路徑不好讀時名稱也不好讀
測試連線檢查什麼伺服器是否可連通只對服務位址送出一次 GET，不會執行任何動作
適合的情況對方已提供 MCP 伺服器對方只有 REST API 文件

HTTP API 的好處是可控：AI 只能填你開出來的參數，查詢條件的其他部分固定不變。代價是參數說明寫得好不好，會直接影響 AI 填入的值。

建立 HTTP API 連線 ​

  1. 在工具庫按新增連線，選 HTTP API。
  2. 連線名稱填「公司登記查詢（經濟部開放資料）」，描述寫明資料來源與用途。
  3. 服務位址填 https://data.gcis.nat.gov.tw，只填到主機；各 API 的路徑之後填在動作裡。
  4. 驗證方式保持不需驗證。
  5. 在預設查詢參數按新增一列，左欄填 $format，右欄填 json，讓每個動作都取得 JSON 格式的回應。
  6. 按測試連線，確認右上角出現 HTTP 200。

下面的動畫示範填入服務位址，並在預設查詢參數新增 $format=json。

接著按測試連線，下面的動畫顯示成功時右上角出現 HTTP 200。

HTTP API 的測試連線只檢查服務位址是否回應，不會帶入任何動作的路徑與參數。所以出現 HTTP 200 只代表主機可連通；動作的路徑或查詢條件寫錯，要到對話實測時才看得出來。

定義第一個動作：用統一編號查公司登記 ​

  1. 切到操作，按新增動作。
  2. 工具名稱填「用統一編號查公司登記」。描述寫清楚這個動作查什麼、會回傳哪些欄位、查不到時會怎樣，例如「用 8 碼統一編號查詢公司登記基本資料，包括公司名稱、登記狀態、資本額、代表人、所在地與核准設立日期。查無資料時回應是空白。」
  3. 確認開放給 Agent 使用已開啟，方法保持 GET，路徑填 /od/data/api/5F64D864-61CB-4D0D-8AD9-492047CC1EA6。
  4. 在查詢參數按三次新增一列，填入下表的三組參數。
  5. 按模型會看到的參數右側的重新推導，確認出現 tax_id。
  6. 在 tax_id 旁填寫參數說明，再按確定。

第一個動作的查詢參數如下；只有 $filter 裡的 {tax_id} 由 AI 填寫，其他值固定。

參數名稱值作用
$filterBusiness_Accounting_NO eq {tax_id}用統一編號篩選，{tax_id} 由 AI 填入
$skip0從第一筆開始
$top1只取一筆；同一個統編只對應一家公司

下面的動畫示範在查詢參數輸入含 {tax_id} 的條件後，按重新推導，tax_id 才出現在模型會看到的參數。路徑與 JSON 本文修改後會自動推導，查詢參數與 Header 的值則要手動按重新推導。

下圖是完成的動作設定：方法與路徑、三組查詢參數，以及 tax_id 的說明「公司的 8 碼統一編號，只能是數字，例如 22099131。使用者只給公司名稱時，不要猜統編，改用「用公司名稱查統一編號」。」

用統一編號查公司登記的動作設定，含 $filter 查詢參數與 tax_id 參數說明

這段說明寫了三件事：值的格式、一個實際例子，以及資訊不足時該改用哪個動作。這個 API 的路徑是一串代碼，AI 只能從工具名稱、描述與參數說明判斷用途，所以這三個欄位不能留白。

定義第二個動作：用公司名稱查統一編號 ​

使用者常常只知道公司名稱，因此再建立一個動作，用名稱查統一編號。

  1. 在操作再按一次新增動作，工具名稱填「用公司名稱查統一編號」。
  2. 描述填「用公司名稱查詢核准設立中的公司，回傳統一編號、公司名稱、資本額、代表人與所在地，最多 10 筆。適合使用者只知道公司名稱、不知道統編時使用。」
  3. 路徑填 /od/data/api/6BBA2268-1367-4B42-9CCA-BC17499EBE8C，查詢參數填下表三組，按重新推導後確認出現 company_name。
  4. 替 company_name 填寫說明，按確定，最後按頁面右上角的儲存。
參數名稱值作用
$filterCompany_Name like {company_name} and Company_Status eq 01用名稱比對，只保留核准設立中的公司
$skip0從第一筆開始
$top10最多取 10 筆，避免回應過長

下圖顯示第二個動作的設定。company_name 的說明要求使用正式登記名稱，並說明原因：用簡稱「台積電」直接查時，會比對到名稱剛好含這三個字的其他公司，例如「台積電機有限公司」。

用公司名稱查統一編號的動作設定，含 company_name 參數說明

儲存後回到工具庫，這條連線會顯示 2 個動作，狀態為正常。

建立 Skill Agent 並加入動作 ​

  1. 在 AI 代理按新增代理，選 Skill Agent。
  2. AI Agent 名稱填「公司登記查詢助理」。系統提示詞寫明：公司登記問題一定先用工具查；有統編用「用統一編號查公司登記」，只有名稱先用「用公司名稱查統一編號」；簡稱要換成正式名稱再查；工具回應空白代表查無資料，不要編造；回答最後註明資料來源。
  3. 選擇AI 引擎，切到知識與工具。
  4. 在可用動作按加入動作，在「公司登記查詢（經濟部開放資料）」分組勾選兩個動作，再按視窗中的加入動作。
  5. 確認可用動作列出兩個動作及所屬連線，按頁面右上角的儲存。

下面的動畫示範在加入動作視窗勾選兩個 HTTP 動作，並帶回 agent 表單。同一個視窗中，MCP 工具顯示伺服器提供的長說明，HTTP 動作則顯示你自己寫的描述。

下圖是儲存後的知識與工具分頁，兩個動作都標示所屬連線「公司登記查詢（經濟部開放資料）」。下方的允許自由連外預設為開啟，開啟時 AI 可以自行呼叫其他 API 或網頁；如果要讓 AI 只能使用你設定的工具，請關閉它。本次實測保留預設值，四題都透過自訂動作查詢。

公司登記查詢助理的知識與工具分頁，可用動作列出兩個 HTTP 動作

在對話中核對 AI 帶的參數 ​

  1. 打開對話，按新增對話，選「公司登記查詢助理」。
  2. 先問有統編的問題，再問只有公司名稱、不存在的統編，以及只說簡稱的問題。四題可以放在同一段對話。
  3. 每則回覆上方都會出現工具呼叫紀錄，格式是「動作名稱：參數=值」。逐題核對 AI 用了哪個動作、填了什麼值。
  4. 正式用途仍要以官方查詢結果為準。

下面的動畫示範選好「公司登記查詢助理」並送出第一個問題。查詢需要一點時間，回覆會在 API 回應後出現。

下表是四題實測的結果，第三欄列出回答時要核對的界線。

問題2026 年 10 月 4 日實測呼叫與參數回答時要核對的界線
統一編號 22099131 是哪一家公司？目前登記狀態、資本額和代表人是誰？用統一編號查公司登記：tax_id=22099131API 同時有資本總額與實收資本額兩個欄位；這次回答標明採用資本總額
那中華電信股份有限公司的統一編號是多少？公司所在地在哪裡？用公司名稱查統一編號：company_name=中華電信股份有限公司這個動作的條件只保留核准設立中的公司，已解散的公司查不到
統編 12345678 是哪一家公司？用統一編號查公司登記：tax_id=12345678API 回應空白；AI 回答查無資料並請使用者核對，沒有編造公司
台積電的統編是多少？用公司名稱查統一編號：company_name=台灣積體電路製造股份有限公司AI 改用正式名稱查詢，符合提示詞與參數說明的要求，沒有直接拿簡稱查

下圖是後三題的工具呼叫紀錄與回答。第三題帶入的統編確實送出查詢，結果為空，AI 據此回答查無資料；第四題的參數顯示 AI 已把「台積電」換成正式名稱。

對話中的工具呼叫紀錄，顯示 company_name 與 tax_id 的實際參數值

AI 怎麼決定填什麼值 ​

儲存後，每個 HTTP 動作都會變成一個 AI 可呼叫的函式。系統把「[連線名稱] 工具名稱：描述」當作函式說明，每個 {參數名} 都是必填的文字參數，參數說明會一起送給 AI。AI 就是依這些文字，加上系統提示詞與使用者的問題，決定要呼叫哪個動作、填入什麼值。

呼叫時，AI 填入的值會原樣取代 {參數名}，再和固定值一起組成查詢。下表整理呼叫過程中各情況的處理方式。

情況系統怎麼處理對設定的影響
必填參數沒有值不送出請求，回覆 AI 缺少哪個參數，並提示先向使用者詢問參數說明要寫清楚值從哪裡來
API 回應 HTTP 400 以上把狀態碼與回應內容交給 AI，提示檢查參數後重試格式限制寫進參數說明，例如「只能是 8 碼數字」
API 回應成功但內容空白AI 收到空白結果在描述註明「查無資料時回應是空白」，讓 AI 正確判讀
回應內容很長只取前 30,000 個字元交給 AI用 $top 這類參數限制筆數

AI 不一定每題都會使用工具。對需要即時資料的問題，要在系統提示詞明確要求先查工具，並在對話中查看有沒有工具呼叫紀錄；沒有紀錄的回答不能當成已查過資料。

常見問題 ​

HTTP 401：憑證被拒絕，請確認 token 或帳密 ​

這是 API 拒絕請求時，測試連線顯示的訊息。確認驗證方式與 API 文件一致；用查詢參數帶金鑰時，參數名稱要與文件相同，例如 api_key。更換金鑰時直接輸入新值，留白代表沿用原值。

測試連線顯示 HTTP 200，AI 為什麼還是查不到？ ​

測試連線只檢查服務位址，不會執行動作。請依序確認：動作的路徑與查詢參數是否符合 API 文件；{參數名} 是否已出現在模型會看到的參數；動作已加入 agent 並儲存。接著從對話的工具呼叫紀錄確認 AI 填入的值，再用相同的值對照 API 文件。

查詢參數寫了 {tax_id}，模型會看到的參數卻沒有出現 ​

查詢參數與 Header 的值修改後不會自動推導，請按重新推導。若仍未出現，確認大括號完整，且大括號內沒有空格或連字號這類符號。

延伸閱讀 ​