工具呼叫 (Tool Call)

當 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;
  toolsetName: string;
  parameter: Record<string, unknown>;
  result?: Record<string, unknown>;
  isComplete: boolean;
  time: Date;
  traceId?: string;
};

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

狀態判斷

狀態	條件
pending	isComplete === false
completed	isComplete === true && !result?.error
error	isComplete === true && result?.error

自訂 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）
time	第一筆 tool call 的時間戳
renderDefaultContent	呼叫後回傳預設的 Tool Call Group UI，可傳 { title } 覆寫標題

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