API 工具¶
把一個固定的端點包成工具——先設定好網址與 HTTP 方法，Agent 只負責填允許的參數。適合穩定、單一用途的 API。若要的是由 Agent 自行決定網址與方法的通用呼叫，請改用 HTTP 工具。
這項偏技術
本頁牽涉端點、HTTP 方法、輸入結構、查詢參數、請求內容、HTTP 標頭等技術概念。這些值通常由工程／IT 同事提供，若不確定要填什麼、從哪裡拿，建議直接請他們協助，照著給的值填即可。
開始前
若 API 需要共用的認證標頭，建議先建立一個 HTTP 類型的連結器資源，由它集中提供標頭；見 連結器資源。也可不用連結器，由工具自行帶上標頭。端點網址一律在工具的「網址」欄填寫。
「描述」決定 Agent 會不會用對工具
Agent 是靠每個工具的「描述」（Description）判斷何時、該不該用它。描述寫得越清楚具體，Agent 越能在對的時機正確使用；寫得太籠統，可能該用時沒用、或用錯場合。建議寫明這個 API 端點查什麼、做什麼、什麼情況下該呼叫。
欄位說明¶
把固定端點包成工具，URL 與方法預先設好，Agent 只填參數。
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 名稱（Name） | 是 | （無） | 工具識別名稱，同一 Agent 內不可重複。 |
| 描述（Description） | 是 | （無） | 說明這個 API 做什麼、何時該用。 |
| 方法（Method） | 是 | （無） | HTTP 方法，可選 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS。 |
| 連結器（Connector） | 否 | （無） | 選一個 HTTP 類型的連結器，提供每次請求套用的共用認證標頭。可清除。 |
| 網址（URL） | 否 | （無） | API 端點的完整網址（http／https 開頭）。表單雖未強制，但少了網址這個工具無法運作，實務上一定要填。連結器只提供標頭、不含端點，端點一律在此填。 |
| 輸入結構（Input Schema） | 否 | （無，沒有任何一列） | 定義 Agent 呼叫時可以填哪些參數。這是一張有「名稱」「類型」「必填」「可空」四欄的表格，不是貼 JSON 的大文字框。點表格下方的紫色 + 會跳出「新增屬性」對話框，填完存檔才會多一列（步驟見下方 warning，對話框的逐欄說明見「輸入結構」是什麼、怎麼加一列）。 |
| 參數（Params） | 否 | （無） | 固定附加在每次請求上的查詢參數，是逐列填的表格（名稱／值），按 + 會跳出「新增參數」對話框（不是直接在表格裡多一列），在對話框填好名稱與值再儲存；對話框裡的「值」還帶一個 JSONPath 開關。下方的「主體」「標籤」也是同一種對話框式的表格。與「輸入結構」的差別：這裡的值每次都一樣、由使用者寫死，「輸入結構」的值是 Agent 每次自己決定。 |
| 主體（Body） | 否 | （無） | 固定的請求內容（body），逐列填的表格（鍵／值），同樣是每次都帶一樣的值。 |
| 逾時（Timeout） | 是 | 30 | 單次請求最長等待秒數，範圍 1–120 的整數。清空後離開欄位會自動填回預設值 30。 |
進階設定（點「進階設定」展開才看得到）：
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 顯示名稱（Display Name） | 否 | （無） | 介面上顯示的標籤。 |
| HTTP 標頭（HTTP Header） | 否 | （無） | 每次請求都會帶上的 HTTP 標頭。 |
| 標籤（Tags） | 否 | （無） | 自訂分類標記。 |
最小可動範例
最簡單能跑的設定：方法選 GET、網址填一個完整的 API 端點（例如 https://api.example.com/orders），其餘留空即可先建立。這樣建出來的工具 Agent 已經可以呼叫，只是每次都固定打同一個網址、不帶任何參數。
要讓 Agent 自己帶參數，一定要先加「輸入結構」的列
「輸入結構」表格預設是空的（沒有任何一列），而 Agent 只能填這裡列出來的參數——沒加列，它就一個參數都送不出去。這是最容易漏掉的一步。以下圖的匯率工具為例，要讓 Agent 能回答「100 美元換多少歐元」，就得先加三列：
- 點「輸入結構」表格下方的紫色 +，跳出「新增屬性」對話框。
- 「類型」選「字串」、「名稱」填
From、打開「必填」，按「儲存」——表格上就多出一列。 - 重複兩次，加出
To（字串、必填）與Amount（數字、必填）。
這三個名稱要與該 API 端點實際接受的參數名稱一致（向提供 API 的同事確認）。加好之後，Agent 才會像下方「實際效果」那樣自動把 From=USD、To=EUR、Amount=100 填進去。
實際效果¶
設定好之後，當使用者的問題需要這個端點，Agent 會自動依「輸入結構」填好參數、呼叫固定端點，再用回傳資料作答。下圖是一個包成 API 工具的匯率端點——使用者問貨幣換算，Agent 自動填入來源貨幣、目標貨幣與金額並呼叫：
可展開的卡片會顯示這次呼叫填了哪些參數（上圖的 From、To、Amount，正是上方「輸入結構」加的那三列）。「接收 …的查詢結果」卡片保持收合，點一下標題即可展開，看到 API 原始回傳的內容。因為網址與方法是預先設好的，Agent 只能填允許的參數，呼叫範圍穩定、可控。
API 還是 HTTP？
端點固定、只想讓 Agent 填參數 → 用 API；網址／方法會變、要 Agent 彈性決定 → 用 HTTP 工具。