--- url: >- https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/http-api-open-data-assistant.md description: >- 以經濟部商工登記公示資料的公開 API 為例，自己定義 HTTP 動作與參數說明，掛到 Skill Agent 後，在對話中用統一編號或公司名稱即時查公司登記，並從工具呼叫紀錄核對 AI 帶入的參數。 --- 這篇用一個只有 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 做一個政府標案助理](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/mcp-tender-assistant)〉接的是 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`。 [動畫（MP4）](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-01-base-url.mp4) 接著按**測試連線**，下面的動畫顯示成功時右上角出現 **HTTP 200**。 [動畫（MP4）](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-02-test-connection.mp4) 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 填寫，其他值固定。 | 參數名稱 | 值 | 作用 | |---|---|---| | `$filter` | `Business_Accounting_NO eq {tax_id}` | 用統一編號篩選，`{tax_id}` 由 AI 填入 | | `$skip` | `0` | 從第一筆開始 | | `$top` | `1` | 只取一筆；同一個統編只對應一家公司 | 下面的動畫示範在**查詢參數**輸入含 `{tax_id}` 的條件後，按**重新推導**，`tax_id` 才出現在**模型會看到的參數**。路徑與 JSON 本文修改後會自動推導，查詢參數與 Header 的值則要手動按**重新推導**。 [動畫（MP4）](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-03-derive-parameter.mp4) 下圖是完成的動作設定：方法與路徑、三組查詢參數，以及 `tax_id` 的說明「公司的 8 碼統一編號，只能是數字，例如 22099131。使用者只給公司名稱時，不要猜統編，改用「用公司名稱查統一編號」。」 ![用統一編號查公司登記的動作設定，含 $filter 查詢參數與 tax\_id 參數說明](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-06-action-tax-id.png) 這段說明寫了三件事：值的格式、一個實際例子，以及資訊不足時該改用哪個動作。這個 API 的路徑是一串代碼，AI 只能從**工具名稱**、**描述**與參數說明判斷用途，所以這三個欄位不能留白。 ## 定義第二個動作：用公司名稱查統一編號 使用者常常只知道公司名稱，因此再建立一個動作，用名稱查統一編號。 1. 在**操作**再按一次**新增動作**，**工具名稱**填「用公司名稱查統一編號」。 2. **描述**填「用公司名稱查詢核准設立中的公司，回傳統一編號、公司名稱、資本額、代表人與所在地，最多 10 筆。適合使用者只知道公司名稱、不知道統編時使用。」 3. 路徑填 `/od/data/api/6BBA2268-1367-4B42-9CCA-BC17499EBE8C`，查詢參數填下表三組，按**重新推導**後確認出現 `company_name`。 4. 替 `company_name` 填寫說明，按**確定**，最後按頁面右上角的**儲存**。 | 參數名稱 | 值 | 作用 | |---|---|---| | `$filter` | `Company_Name like {company_name} and Company_Status eq 01` | 用名稱比對，只保留核准設立中的公司 | | `$skip` | `0` | 從第一筆開始 | | `$top` | `10` | 最多取 10 筆，避免回應過長 | 下圖顯示第二個動作的設定。`company_name` 的說明要求使用正式登記名稱，並說明原因：用簡稱「台積電」直接查時，會比對到名稱剛好含這三個字的其他公司，例如「台積電機有限公司」。 ![用公司名稱查統一編號的動作設定，含 company\_name 參數說明](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-07-action-company-name.png) 儲存後回到**工具庫**，這條連線會顯示 **2 個動作**，狀態為**正常**。 ## 建立 Skill Agent 並加入動作 1. 在 **AI 代理**按**新增代理**，選 **Skill Agent**。 2. **AI Agent 名稱**填「公司登記查詢助理」。**系統提示詞**寫明：公司登記問題一定先用工具查；有統編用「用統一編號查公司登記」，只有名稱先用「用公司名稱查統一編號」；簡稱要換成正式名稱再查；工具回應空白代表查無資料，不要編造；回答最後註明資料來源。 3. 選擇**AI 引擎**，切到**知識與工具**。 4. 在**可用動作**按**加入動作**，在「公司登記查詢（經濟部開放資料）」分組勾選兩個動作，再按視窗中的**加入動作**。 5. 確認**可用動作**列出兩個動作及所屬連線，按頁面右上角的**儲存**。 下面的動畫示範在**加入動作**視窗勾選兩個 HTTP 動作，並帶回 agent 表單。同一個視窗中，MCP 工具顯示伺服器提供的長說明，HTTP 動作則顯示你自己寫的**描述**。 [動畫（MP4）](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-04-attach-actions.mp4) 下圖是儲存後的**知識與工具**分頁，兩個動作都標示所屬連線「公司登記查詢（經濟部開放資料）」。下方的**允許自由連外**打開時，AI 可以自行呼叫其他 API 或網頁；關閉時只能使用你設定的工具。新建 agent 預設是關閉的（2026 年 10 月 4 日起）；圖中的示範 agent 建立時預設還是開啟，所以開關是開著的，四題實測仍然都透過自訂動作查詢。要讓 AI 只用你設定的工具，保持關閉即可。 ![公司登記查詢助理的知識與工具分頁，可用動作列出兩個 HTTP 動作](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-08-agent-actions.png) ## 在對話中核對 AI 帶的參數 1. 打開**對話**，按**新增對話**，選「公司登記查詢助理」。 2. 先問有統編的問題，再問只有公司名稱、不存在的統編，以及只說簡稱的問題。四題可以放在同一段對話。 3. 每則回覆上方都會出現工具呼叫紀錄，格式是「動作名稱：參數=值」。逐題核對 AI 用了哪個動作、填了什麼值。 4. 正式用途仍要以官方查詢結果為準。 下面的動畫示範選好「公司登記查詢助理」並送出第一個問題。查詢需要一點時間，回覆會在 API 回應後出現。 [動畫（MP4）](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-05-ask.mp4) 下表是四題實測的結果，第三欄列出回答時要核對的界線。 | 問題 | 2026 年 10 月 4 日實測呼叫與參數 | 回答時要核對的界線 | |---|---|---| | 統一編號 22099131 是哪一家公司？目前登記狀態、資本額和代表人是誰？ | 用統一編號查公司登記：`tax_id=22099131` | API 同時有資本總額與實收資本額兩個欄位；這次回答標明採用資本總額 | | 那中華電信股份有限公司的統一編號是多少？公司所在地在哪裡？ | 用公司名稱查統一編號：`company_name=中華電信股份有限公司` | 這個動作的條件只保留核准設立中的公司，已解散的公司查不到 | | 統編 12345678 是哪一家公司？ | 用統一編號查公司登記：`tax_id=12345678` | API 回應空白；AI 回答查無資料並請使用者核對，沒有編造公司 | | 台積電的統編是多少？ | 用公司名稱查統一編號：`company_name=台灣積體電路製造股份有限公司` | AI 改用正式名稱查詢，符合提示詞與參數說明的要求，沒有直接拿簡稱查 | 下圖是後三題的工具呼叫紀錄與回答。第三題帶入的統編確實送出查詢，結果為空，AI 據此回答查無資料；第四題的參數顯示 AI 已把「台積電」換成正式名稱。 ![對話中的工具呼叫紀錄，顯示 company\_name 與 tax\_id 的實際參數值](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/images/http-api-open-data-assistant-09-tool-call-params.png) ## 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 的值修改後不會自動推導，請按**重新推導**。若仍未出現，確認大括號完整，且大括號內沒有空格或連字號這類符號。 ## 延伸閱讀 * [網站客服機器人要怎麼即時查詢訂單狀態，不是每次都要人工查系統](https://docs.oakxgen.ai/zh-Hant-TW/article/website-chatbot-order-status-lookup) * [用 MCP 做一個政府標案助理：接上連線、掛到 AI 代理、開始提問](https://docs.oakxgen.ai/zh-Hant-TW/guide/scenarios-tutorials/mcp-tender-assistant) * [接 REST API：憑證、預設 Header、動作怎麼填](https://docs.oakxgen.ai/zh-Hant-TW/guide/connections/http-connection) * [怎麼幫 agent 掛工具庫的動作](https://docs.oakxgen.ai/zh-Hant-TW/guide/agents/actions) * [怎麼從一則回覆確認 AI 真的查到了什麼](https://docs.oakxgen.ai/zh-Hant-TW/guide/chats/verify-ai-answers)