跳至主要内容

工具呼叫

當 Agent 在生成回答前呼叫了多個工具（例如查資料庫、打外部 API）， SDK 會自動把連續的 tool-call 訊息分組為 Tool Call Group， 並提供展開檢視每筆工具的 parameter 與 result。

下方切換不同情境，觀察 pending、completed、error 三種狀態的呈現。

工具呼叫狀態

Agent 在回答前往往會呼叫多個工具。SDK 內建的 Tool Call Group 會把連續的工具呼叫分組顯示，並支援展開檢查每一筆的參數與結果。使用 renderToolCallGroup 可以隱藏或自訂呈現方式。

使用範例

// 不需要設定 — 使用內建 UI
<Chatbot
  config={{ botProviderEndpoint: '...' }}
  customChannelId="my-channel"
/>
聊天機器人載入中…

訊息結構​

Tool Call 不是 Template，而是獨立的 ConversationMessage 類型：

type ConversationToolCallMessage = {
  type: "tool-call";
  messageId: string; // `${processId}-${callSeq}`
  eventType: EventType.TOOL_CALL_START | EventType.TOOL_CALL_COMPLETE;
  processId: string;
  callSeq: number;
  toolName: string;
  reason?: string; // 後端提供的呼叫原因；Tool Call Group 標題與授權 Modal 標題會優先顯示 reason || toolName
  toolsetName: string;
  parameter: Record<string, unknown>;
  result?: Record<string, unknown>;
  isError?: boolean; // 後端回報的失敗旗標（0.3.x / F-009），complete 前為 undefined
  toolUseId?: string; // 此工具呼叫的關聯 id；Agent 類工具的 toolUseId 會成為子代理的 key（F-012）
  parentToolUseId?: string; // 非空代表這筆屬於某個子代理（F-012）
  isComplete: boolean;
  time: Date;
  traceId?: string;
};

實際情境下，這些訊息由 EventType.TOOL_CALL_START / EventType.TOOL_CALL_COMPLETE 兩個事件自動寫入 Conversation， 你完全不需要手動處理。

狀態判斷​

狀態條件
pendingisComplete === false
completedisComplete === true && !(isError || result?.error)
errorisComplete === true && (isError || result?.error)
0.3.x 起以後端 isError 為主

失敗判定改以後端回報的 isError 旗標為主要依據（F-009），result.error 僅作為舊版相容的後備。

內建工具呈現（標籤、圖示、diff）​

0.3.x 起，Tool Call Group 會為內建工具合成人類可讀的標籤並配上識別圖示（variant）：

工具標籤範例
Read / Write / EditRead {file} / Wrote {file} / Edited {file}
SkillRan skill {skill}
WebFetch / WebSearchFetched {host} / Searched "{query}"
  • Write / Edit 會在展開時額外呈現 +/- 行 diff（對應 items[].diff，F-007）。
  • 標籤、群組摘要（{n} steps · …）與展開後的 Initial / Result 標題都會依 locale prop 本地化（en-US / ja-JP / zh-TW，F-004 / F-005 / F-008）：
<Chatbot locale="zh-TW" config={{ botProviderEndpoint: '...' }} customChannelId="my-channel" />

自訂 Tool Call Group 顯示​

透過 renderToolCallGroup prop 可以完全控制 Tool Call Group 的渲染方式。

隱藏​

<Chatbot
  renderToolCallGroup={() => null}
  ...
/>

自訂標題​

<Chatbot
  renderToolCallGroup={({ renderDefaultContent }) =>
    renderDefaultContent({ title: 'AI 正在思考中...' })
  }
  ...
/>

自訂 UI​

<Chatbot
  renderToolCallGroup={({ items }) => {
    const completed = items.filter((i) => i.status === "completed").length;
    return (
      <div>✅ {completed} / {items.length} steps completed</div>
    );
  }}
  ...
/>

API​

renderToolCallGroup?: (props: {
  items: ToolCallItemData[];
  time?: Date;
  renderDefaultContent: (overrides?: { title?: string }) => ReactNode;
}) => ReactNode;
參數說明
items該組 tool call 的資料陣列（id、label、status、initial、result，以及 0.3.x 新增的 variant 內建工具識別與 diff Write/Edit 行差異）
time第一筆 tool call 的時間戳
renderDefaultContent呼叫後回傳預設的 Tool Call Group UI，可傳 { title } 覆寫標題

回傳 null 即隱藏，回傳 JSX 即自訂渲染。不設此 prop 則維持預設行為。

深入閱讀​

Tool Call 對應的 SSE 事件規格，見 Asgard 開發者文件：