跳至主要内容

工具呼叫授權

當 Bot Provider 設定了需要使用者授權的 Toolset，Agent 呼叫工具前 SDK 會自動彈出授權 Modal， 請使用者對每筆工具呼叫做出決策，才繼續執行。

整合方無需額外接線 — ToolCallConsentGate 已內建於 <Chatbot> 元件中。

載入中…

三種決策​

決策（按鈕文字）對應結果說明
本次對話皆允許ALLOW_ALWAYS核准此次呼叫，並在本次對話中自動核准後續所有相同工具的呼叫
僅此次允許ALLOW_ONCE僅核准此次呼叫
拒絕DENY_ONCE拒絕此次呼叫；可選填原因讓 Agent 知道為什麼被拒絕

自動略過規則​

兩種情況下 SDK 不會彈 Modal，直接處理：

  1. alreadyAllowed: true — 後端標記為已授權（例如前一輪對話已 Allow for This Chat），自動 ALLOW_ONCE
  2. 本批次 Allow for This Chat — 同一批次中已對某工具選擇 Allow for This Chat，後續同 toolset / toolName 自動 ALLOW_ALWAYS

使用方式​

不需要任何設定，只要 Bot Provider 的 Toolset 啟用了 consent，SDK 即自動處理：

<Chatbot
  config={{
    apiKey: 'your-api-key',
    botProviderEndpoint: 'https://api.asgard-ai.com/ns/{namespace}/bot-provider/{botProviderId}',
  }}
  customChannelId="your-channel-id"
/>

Deny 兩步確認​

為避免誤按，拒絕採兩步送出：

  1. 第一次按 拒絕 — 展開拒絕原因輸入框，按鈕變為 送出拒絕
  2. 第二次按 送出拒絕 — 才送出拒絕（原因可留空）

等待授權時，其他回合會被拒絕​

授權 Modal 掛著的時候，channel 在伺服器端是暫停狀態，只認得授權回覆；其他回合一律被回絕 （「use RespondToolCallConsent」）。所以 sendMessage() 與 nudge() 會在本地就先拒絕， 丟出 ChannelAwaitingConsentError：

import { isChannelAwaitingConsentError } from "@asgard-js/core";

try {
  await channel.sendMessage({ text: "算了，改問別的" });
} catch (error) {
  if (isChannelAwaitingConsentError(error)) {
    // 先回覆授權才有辦法繼續
  }
}
為什麼需要這道本地防線

「有 run 佔住 channel」那道 busy 防線擋不住這個情境：授權事件比 run 的終止事件還早抵達， 等 Modal 出現在畫面上時 run 已經結束，channel 看起來是閒置的。本地攔下來，才不會讓一個註定失敗 的回合先推出樂觀的使用者泡泡、再把後端錯誤寫進對話串——被拒絕的回合不會在對話串留下任何痕跡。

唯一的出路是 replyToolCallConsents()；答完之後防線自動解除。錯誤上的 processId 是暫停批次的 process id，但重新連線後會是空字串（後端從持久化的暫停狀態重建提示時刻意留白），只能當診斷 提示，不要拿來當 key。

用內建 <Chatbot> 的話不必自己接：輸入框與 Nudge 入口在等待授權期間都會被鎖住，使用者按不到。 這道防線是給headless／自訂外殼準備的。

授權回覆本身失敗時，pending 狀態會被還原，Modal 留在原地讓使用者重試，不會兩頭落空。

主題客製化​

Modal 預設跟隨 Chatbot 的 --asg-color-* 設計 token，無需額外設定。

此外，自 0.2.61 起，Modal 的強調色（工具名稱高亮、主要按鈕、focus ring）會自動跟隨你用 theme 設定的品牌色 —— 解析順序為 chatbot.primaryComponent.mainColor → chatbot.mainColor → userMessage.backgroundColor，按鈕上的文字色取自對應的 secondaryColor。因此只要用 theme 設好品牌色，consent modal 通常就無需再手動覆寫下列 CSS 變數。

若仍需覆寫個別顏色，可在任意父層設定 CSS 變數：

.my-chatbot-wrapper {
  --asgard-consent-modal-bg: #0f172a;
  --asgard-consent-modal-accent: #6366f1;
  --asgard-consent-modal-danger: #ef4444;
}
CSS 變數用途Fallback
--asgard-consent-modal-bgModal 背景色--asg-color-surface
--asgard-consent-modal-border邊框顏色--asg-color-border
--asgard-consent-modal-headlineModal 標題色（「允許使用工具…？」）--asg-color-text-primary
--asgard-consent-modal-title內文 / 強調文字色（工具資訊、拒絕原因、輸入框文字）--asg-color-text-primary
--asgard-consent-modal-muted次要文字色--asg-color-text-secondary
--asgard-consent-modal-accent主色（Allow for This Chat 按鈕）--asg-color-primary
--asgard-consent-modal-danger危險色（Deny 按鈕）--asg-color-error
--asgard-consent-modal-input-bgDeny Reason 輸入框背景--asg-color-bg