跳至主要内容

REFERENCE

SDK 範例

@asgard-js/core 與 @asgard-js/react 的用法與可以直接操作的範例。

工具呼叫

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

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

  1. 訊息結構​

    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， 你完全不需要手動處理。

  2. 狀態判斷​

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

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

  3. 內建工具呈現（標籤、圖示、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" />

  4. 自訂 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 則維持預設行為。

  5. 深入閱讀​

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

準備好開始了嗎？

想知道 Asgard 怎麼用在你的團隊？跟我們聊聊。

聯絡我們