API 工具¶
把一個固定的端點包成工具——先設定好網址與 HTTP 方法，Agent 只負責填允許的參數。適合穩定、單一用途的 API。若你要的是由 Agent 自行決定網址與方法的通用呼叫，請改用 HTTP 工具。
這項偏技術
本頁牽涉端點、HTTP 方法、輸入結構、查詢參數、請求內容、HTTP 標頭等技術概念。這些值通常由工程／IT 同事提供，若你不確定要填什麼、從哪裡拿，建議直接請他們協助，照著給的值填即可。
開始前
若 API 需要認證或共用基底網址，建議先建立一個 Connector（連結器）資源，由它提供認證標頭與基底網址；見 Connector 資源。也可不用 Connector，直接在工具填完整網址。
「描述」決定 Agent 會不會用對工具
Agent 是靠每個工具的「描述」（Description）判斷何時、該不該用它。描述寫得越清楚具體，Agent 越能在對的時機正確使用；寫得太籠統，可能該用時沒用、或用錯場合。建議寫明這個 API 端點查什麼、做什麼、什麼情況下該呼叫。
欄位說明¶
把固定端點包成工具，URL 與方法預先設好，Agent 只填參數。
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 名稱（Name） | 是 | （無） | 工具識別名稱，同一 Agent 內不可重複。 |
| 描述（Description） | 是 | （無） | 說明這個 API 做什麼、何時該用。 |
| 方法（Method） | 是 | （無） | HTTP 方法，可選 GET、POST、PUT、PATCH、DELETE。 |
| 連結器（Connector） | 與「網址」二擇一 | （無） | 選一個 API 類型的 Connector，提供基底網址與認證標頭。 |
| 網址（URL） | 與「連結器」二擇一 | （無） | API 端點的完整網址；若同時設了 Connector，這裡的網址會覆蓋其基底網址。 |
| 輸入結構（Input Schema） | 否 | （無） | 定義 Agent 呼叫時可填哪些參數。這是一張逐列填寫的表格（名稱／類型／必填／可空），不是貼 JSON 的大文字框；按 + 新增一列。 |
| 參數（Params） | 否 | （無） | 固定附加在每次請求上的查詢參數，也是逐列填的表格（名稱／值）。 |
| 主體（Body） | 否 | （無） | 固定的請求內容（body），逐列填的表格（鍵／值）。 |
| 逾時（Timeout） | 否 | 30 | 單次請求最長等待秒數，範圍 1–120。 |
進階設定（點「進階設定」展開才看得到）：
| 欄位 | 必填 | 預設 | 說明 |
|---|---|---|---|
| 顯示名稱（Display Name） | 否 | （無） | 介面上顯示的標籤。 |
| HTTP 標頭（HTTP Header） | 否 | （無） | 每次請求都會帶上的 HTTP 標頭。 |
| 標籤（Tags） | 否 | （無） | 自訂分類標記。 |
最小可動範例
最簡單能跑的設定：方法選 GET、網址填一個完整的 API 端點（例如 https://api.example.com/orders），其餘留空即可先建立。需要帶參數或認證時，再回頭補「參數」「HTTP 標頭」或改用 Connector。
實際效果¶
設定好之後，當使用者的問題需要這個端點，Agent 會自動依「輸入結構」填好參數、呼叫固定端點，再用回傳資料作答。下圖是一個包成 API 工具的匯率端點——使用者問貨幣換算，Agent 自動填入來源貨幣、目標貨幣與金額並呼叫：
可展開的卡片會顯示這次呼叫填了哪些參數（上圖的 From、To、Amount）。因為網址與方法是你預先設好的，Agent 只能填你允許的參數，呼叫範圍穩定、可控。
API 還是 HTTP？
端點固定、只想讓 Agent 填參數 → 用 API；網址／方法會變、要 Agent 彈性決定 → 用 HTTP 工具。
下一步¶
- 需要認證或基底網址 → Connector 資源
- 要更彈性的呼叫 → HTTP 工具
- 回到 工具總覽