真人交接

Human Handoff 讓 Agent 在不適合繼續由 AI 回覆時，停止回答並把 live 使用者交給真人處理。

它適合用在 Agent 能判斷需要升級處理，但下一則回覆應該由你的團隊接手的情境。

設定交接前，先選擇回覆模式

在 Agent Editor 打開 Advanced → Response mode，決定如何處理外部使用者訊息：

模式	實際行為	適用情境
`AI replies`	Agent 正常回答；啟用 `Human Handoff` 後，可以把特定對話交給真人。	AI 應處理已核准範圍，只把例外交接真人。
`Human replies only`	所有外部訊息都會保存並等待真人處理。Agent 不會自動回答，也不會傳送交接訊息或交接通知。	團隊要由真人回答每一則外部訊息，只用 Codeer 接收與營運對話。

Human replies only 是這個 Agent 的整體營運選擇，不是由 Agent 判斷後觸發的交接，也不會把 Live Test 變成真人待辦清單。修改回覆模式後，請按 Apply、發布新版 Agent，再用真實或 staging Channel 驗證結果。

什麼時候適合使用

好的交接規則通常會涵蓋這些情境：

使用者要求找真人
案件緊急、敏感，或超出允許範圍
Agent 已經收集到足夠脈絡，下一步需要人工跟進
對話在反覆釐清後仍然卡住

不要把 Human Handoff 當成一般分流工具。如果另一個 Agent 能接手，請用 Call Agent。如果只是需要在後續跟進前收集結構化資料，請用 Request Form。

在 Agent Editor 裡設定

打開 Agent 的 Editor，找到 Human Handoff，設定：

Enable human handoff：允許 Agent 針對 live 使用者進入 human-only mode。
Idle timeout (minutes)：選填。設定後，使用者閒置這麼多分鐘後會自動回到 AI mode。留空代表需要真人手動切回 AI。
Handoff instructions：告訴 Agent 什麼情境應該停止回答並交給真人。

修改設定後，請按 Apply 存成新版本。只有在交接路徑測過之後，才把這個版本發布出去。

交接功能在哪裡可用

Handoff 工具只會在 Codeer 能辨識外部使用者的 live end-user 對話中啟用。它和 Editor 裡的 Live Test 不同。

交接時通知團隊

Agent Editor 裡的 Handoff notifications 只會顯示此 Agent 目前通知模式與生效目的地的唯讀摘要，不會直接建立、編輯或刪除目的地。

選擇 管理工作區通知，即可在工作區通知直接打開 Agent 真人接手 事件與此 Agent。沒有個別設定的 Agent 會自動使用工作區規則；只有需要下列例外行為時，才新增個別設定：

自訂目的地：為此 Agent 選取既有且相容的目的地。
不發送通知：此 Agent 交接時不通知團隊。

將既有設定改成 不發送通知 時，系統會移除原本選取的自訂目的地。之後若要恢復自訂通知，請編輯個別設定並重新選取目的地。

刪除個別設定後，Agent 會改用工作區規則。如果刪除的是 不發送通知 設定，工作區規則可用時會恢復發送通知。自訂目的地 只會改變此 Agent 使用哪些既有目的地。若要新增、編輯、測試、驗證、啟用、停用或刪除目的地，請使用工作區通知的 目的地 分頁。

生效目的地摘要會排除已停用、尚未驗證或不相容的目的地。如果工作區規則不存在、已停用，或沒有可用目的地，使用預設設定的 Agent 不會發送通知；工作區規則恢復可用後會自動恢復傳送。

Webhook URL 請保密

Slack webhook URL 是 secret。只在工作區通知中建立與管理，不要貼到公開文件、issue comment、截圖或 source code 裡。

把交接指令寫窄

交接指令要明確說出 Agent 什麼時候該停下來交接。避免只寫「需要時交接」這種太廣的規則。

範例：

Request human handoff when the user asks for a person, reports an urgent billing or safety concern, or has already answered the qualification questions and wants a callback. Before handing off, summarize the reason in one sentence and do not continue troubleshooting.

使用者會看到什麼

當 Agent 觸發交接時，平台會送出一段簡短訊息，告訴使用者這段對話已經交給真人隊友。之後，對同一位使用者與同一個 Agent，Agent 會停止產生 AI 回覆。

Human-only mode 啟用期間：

使用者的新訊息仍然會保存到對話紀錄
Agent 不會回覆這些訊息
檔案附件仍會附在已記錄的使用者訊息上
如果有設定 idle timeout，每一則新訊息都會延長 timeout 時間

Timeout 到期後，使用者下一則訊息可以重新由 AI 處理。如果沒有設定 timeout，就需要 operator 手動切回 AI mode。

從客戶頁面管理交接

使用者和 Agent 互動過之後，可以從客戶打開該使用者。使用者詳情頁會顯示 Agent 分流資訊，包括目前互動模式、變更原因，以及真人模式何時到期。

有編輯權限的 operator 可以：

把某個 Agent 的互動從 AI 切到 Human
把啟用中的真人互動切回 AI
查看目前 human mode 是由 Agent、自行在 CRM 手動切換，還是自動 timeout 造成

手動切到 Human 只會在該 Agent 已發布，而且已啟用 handoff 時可用。

發布前先測

盡量用真實 channel 或 staging 體驗測試，因為 Human Handoff 依賴 end-user identity。確認這些路徑：

Agent 在設定條件出現時會交接
交接訊息清楚
後續使用者訊息會被記錄，但不會由 AI 回覆
使用者會在 timeout 後回到 AI，或能被手動切回 AI