HTTP Request
當 Agent 需要在對話中和外部系統交換結構化資料時，就用 HTTP Request。
以 Consultation Desk 為例，這不是第一天就一定要加的工具。先把前段分流流程做順，等你已經能明確說出「現在要做哪一個外部動作」時，再補進來。
常見用法像是：
- 使用者同意回電後，幫他在 CRM 建立一筆 callback lead
- 向排程系統查詢可預約時段
- 把已確認的 intake 資料送到內部流程
什麼情況適合用 HTTP Request
適合：
- 外部系統本來就有穩定的 HTTPS endpoint
- 你需要的是結構化請求或回應，不是自由搜尋
- 你能清楚說明這個 request 應該在什麼時機觸發
不適合：
- 這份資訊其實應該整理進
Knowledge Base - API 合約自己都還沒定清楚
- 這個外部動作本來就應該先由人審核
步驟 1：先定義它只做哪一件事
先把工具的工作縮到一個明確動作。
好的名稱：
Create Callback LeadCheck Appointment Availability
不好的名稱：
CRM Integration
一個工具只做一個明確動作，通常會比一個什麼都想包的 request 更容易測試和除錯。
步驟 2：加入 HTTP Request
在 Editor 的 Tools 裡按 Add Tool，選 HTTP Request。
Display Name 請寫成營運動作，不要只寫成技術名詞。之後回來看設定時，團隊才會一眼知道這個工具到底負責什麼。
步驟 3：先設定 Method 與 URL
先把 HTTP Method 和 Request URL 設好。
- URL 必須是
https:// - 如果 URL 需要帶使用者身分資訊，目前可用
{{user.email}}、{{user.id}}、{{user.external_id}}
endpoint 也要盡量精準。要送 callback lead，就指向 callback lead 的 endpoint，不要丟到一個什麼都能做的通用路徑。
步驟 4：只填真的需要的驗證與 payload
接著補上 endpoint 真正需要的欄位：
AuthenticationHeadersQuery ParametersRequest Body，可用UI Mode或Text Mode
payload 越精簡越好。下游系統不需要的欄位，就不要因為對話裡剛好有資料而一起送出去。
步驟 5：把 When to Use 寫得很窄
這個工具會不會在不該出手的時候被叫起來，關鍵常常不在 API，而在 When to Use。
例如：
Use this request only after the user agrees to a human callback and you have collected their preferred contact details. Send the callback request to the CRM so the operations team can follow up.
這段好用，是因為它同時交代了：
- 對話走到哪一個階段才可以呼叫
- 哪些資料必須先收齊
- 這個外部 request 存在的營運目的
步驟 6：測一條會成功觸發的路，和一條不該觸發的路
先測應該要觸發的情境：
好，請幫我安排明天下午回電。
再測不該觸發的情境：
我還在比較方案。
確認：
- 只有在對的路徑才會送 request
- payload 真的只包含你預期的欄位
- 使用者還沒決定下一步前，Agent 不會太早把資料送出去
操作建議
- 一個 request 專心做一個營運動作。
- 工具名稱寫成動作，不要寫成供應商名稱。
When to Use和 payload 要互相對得起來。前者說「同意回電後」，後者就應該假設資料已經收齊。- 如果這個動作不可逆或風險高，流程裡還是要保留人工確認，不要太早自動送出。
常見錯誤
把 HTTP Request 當成萬用解法
這樣很快就會變脆弱。每個 request 都應該有清楚的目的和合約。
流程都還沒走到位，就先把資料送出去
使用者還在探索階段時，不應該先呼叫外部系統。
什麼欄位都想一起送
欄位越多不代表整合越聰明，通常只是讓除錯變更難。