ToolFallback

ToolFallback 是工具调用的通用回退（Fallback）UI。当没有为特定工具名称注册自定义 ToolUI 时，assistant-ui 会使用此组件渲染工具调用的参数、结果、状态和审批界面。

引入

import {
  ToolFallback,
  ToolFallbackRoot,
  ToolFallbackTrigger,
  ToolFallbackContent,
  ToolFallbackArgs,
  ToolFallbackResult,
  ToolFallbackError,
  ToolFallbackApproval,
} from "aui-components";

基本用法

Thread 默认使用 ToolFallback 作为未匹配工具的回退 UI。你也可以通过 components.ToolFallback prop 覆盖：

<Thread
  components={{
    ToolFallback: CustomToolFallback,
  }}
/>

直接使用子组件组合：

<ToolFallbackRoot>
  <ToolFallbackTrigger toolName="search" status={{ type: "complete" }} />
  <ToolFallbackContent>
    <ToolFallbackArgs argsText='{"query": "hello world"}' />
    <ToolFallbackResult result={{ items: ["result1", "result2"] }} />
  </ToolFallbackContent>
</ToolFallbackRoot>

Props

该组件没有公开的 Props。

ToolFallbackRoot Props

export type ToolFallbackRootProps = {
  /** 控制展开状态（受控模式） */
  open?: boolean;
  /** 展开状态变化回调 */
  onOpenChange?: (open: boolean) => void;
  /** 默认展开状态 */
  defaultOpen?: boolean;
};

ToolFallbackTrigger

<ToolFallbackTrigger
  toolName="search" // 工具名称，显示为 "Used tool: search"
  status={{ type: "running" }} // 工具调用状态
/>

状态图标映射

状态	图标	说明
`running`	`LoaderIcon` (旋转)	工具执行中
`complete`	`CheckIcon`	执行成功
`incomplete`	`XCircleIcon`	执行失败/取消
`requires-action`	`AlertCircleIcon`	需要用户审批

取消状态：status.type === "incomplete" && status.reason === "cancelled" 时显示 "Cancelled tool" 并带有删除线样式。

ToolFallbackContent

折叠内容容器，与 Reasoning 和 ToolGroup 使用相同的动画系统：

animate-collapsible-down/up 开合动画
fade-in + blur-in + slide-in-from-top-1 内容入场

ToolFallbackArgs

展示工具调用的参数：

<ToolFallbackArgs argsText='{"query": "hello world"}' />

参数以 JSON.stringify 格式展示在 <pre> 块中
如果 argsText 为空，不渲染

ToolFallbackResult

展示工具调用的结果：

<ToolFallbackResult result={{ data: "some result" }} />

结果以 JSON 格式展示（字符串直接显示，其他类型 JSON.stringify(result, null, 2)）
如果 result === undefined，不渲染

ToolFallbackError

展示工具调用的错误信息：

<ToolFallbackError
  status={{ type: "incomplete", reason: "error", error: "Network timeout" }}
/>

仅在 status.type === "incomplete" 时渲染
取消原因显示 "Cancelled reason:"
其他错误显示 "Error:"

ToolFallbackDuration

展示工具调用的耗时：

<ToolFallbackDuration /> // 自动使用 useToolCallElapsed()

<1s — 小于 1 秒
X.Xs — 小于 10 秒
Xs — 小于 60 秒
Xm Ys — 大于 60 秒
如果 elapsedMs === undefined，不渲染

ToolFallbackApproval

当工具调用需要用户审批时显示的审批界面：

<ToolFallbackApproval
  addResult={addResult}
  resume={resume}
  interrupt={interrupt}
  approval={approval}
  respondToApproval={respondToApproval}
/>

审批选项

审批支持以下选项类型：

kind	标签	说明
`allow-once`	"Allow"	本次允许
`allow-always`	"Always allow"	始终允许
`reject-once`	"Deny"	本次拒绝
`reject-always`	"Always deny"	始终拒绝

确认对话框

当选项设置了 confirm 属性时，需要二次确认：

// 选项配置示例
{
  id: "allow-always",
  kind: "allow-always",
  confirm: {
    title: "Always allow search?",
    description: "This will grant permanent search permissions."
  },
  grants: ["search:read", "search:write"]
}

审批流程

工具调用状态变为 requires-action
ToolFallback 自动展开
显示审批选项按钮
用户点击 Allow / Deny（或调用 respondToApproval）
工具继续执行

自定义 ToolUI 优先级

当为特定工具注册了自定义 UI 时，该 UI 会优先于 ToolFallback 渲染：

// 在 AssistantRuntimeProvider 中注册
const runtime = useChatRuntime({
  api: "/api/chat",
  // 自定义工具 UI 优先于 ToolFallback
  tools: {
    search: {
      render: () => <CustomSearchTool />,
    },
  },
});