agent-elements

Agent Elements 技能

用于构建聊天和 Agent UI 的项目感知上下文，基于 Agent Elements — 一个开源的 shadcn 注册表，地址为 https://agent-elements.21st.dev。

此技能为你提供的内容

加载此技能后，你将了解：

1. 该注册表兼容 shadcn。 每个组件都通过 npx shadcn@latest add https://agent-elements.21st.dev/r/<component>.json 安装。文件会放在 components/agent-elements/ 下（库内部的 components/ 前缀会被移除——详见下文的路径部分）。
2. API 围绕 Vercel AI SDK 进行类型化。 消息为来自 ai 的 UIMessage[]，状态为 ChatStatus。可直接接入 useChat()。
3. 完整的组件目录，包含 API 结构和组合规则（见下文各节）。
4. 主题设置注意事项——Agent Elements 所依赖的 Tailwind 令牌。

检测

满足以下任一条件时，可认为此项目已为 Agent Elements 做好准备：

• 磁盘上存在 components/agent-elements/ 目录
• components.json 包含指向 Agent Elements 的别名或注册表引用
• package.json 依赖项包含 ai 和 @tabler/icons-react，且用户提到了 Agent Elements

如果该目录尚不存在，请按需安装：

npx shadcn@latest add https://agent-elements.21st.dev/r/agent-chat.json

agent-chat 会通过 registryDependencies 间接拉取其所需的所有其他组件（MessageList、InputBar、工具渲染器、共享工具函数）。

路径（安装后的布局）

运行 shadcn add 后，文件会放在 @/components/agent-elements/ 下，结构如下：

components/agent-elements/
  agent-chat.tsx
  message-list.tsx
  input-bar.tsx
  markdown.tsx
  user-message.tsx
  error-message.tsx
  text-shimmer.tsx
  spiral-loader.tsx
  input/
    attachment-button.tsx
    send-button.tsx
    file-attachment.tsx
    suggestions.tsx
    model-picker.tsx
    mode-selector.tsx
  tools/
    bash-tool.tsx
    edit-tool.tsx
    search-tool.tsx
    todo-tool.tsx
    plan-tool.tsx
    tool-group.tsx
    subagent-tool.tsx
    mcp-tool.tsx
    thinking-tool.tsx
    generic-tool.tsx
  question/
    question-tool.tsx
  hooks/use-tool-complete.ts
  utils/cn.ts
  types.ts

导入规则： 始终从确切文件导入，切勿从汇总导出文件导入。

// ✅
import { AgentChat } from "@/components/agent-elements/agent-chat";
import { BashTool } from "@/components/agent-elements/tools/bash-tool";

// ❌ — no barrel exists
import { AgentChat } from "@/components/agent-elements";

组件目录

聊天界面

• AgentChat — 完整的聊天外壳。渲染 MessageList + InputBar， 通过 toolRenderers 处理工具调用，并显示包含可选 suggestions 的空状态。属性：messages、status、onSend、onStop、 toolRenderers?、suggestions?、attachments?、classNames?、slots?。
• MessageList — 仅显示对话记录。需要将输入栏放在其他位置时使用。支持 toolRenderers 和 showCopyToolbar。
• UserMessage / ErrorMessage / Markdown — 底层消息组件。 Markdown 可安全地流式输出（外部链接默认会添加 rel="noreferrer"）。

输入

• InputBar — 输入框。属性：status、onSend({ content })、onStop、 value? + onChange?（受控）、attachedImages/attachedFiles 及其移除处理器、leftActions/rightActions 插槽、suggestions?、 questionBar?、infoBar?。
• Suggestions — 用于空状态或行内显示的快捷提示词选项。
• ModelPicker / ModeSelector — 专为放入 leftActions 而设计。两者 均接受简单的 { id, name, version? } / { id, label, icon?, description? } 结构。不要导入 CLAUDE_MODELS——它已被移除；请提供你自己的数组。
• SendButton / AttachmentButton / FileAttachment — 构建自定义输入框时，可单独使用。

工具卡片

所有工具卡片都接受一个 part 属性，其类型为 AI SDK 中的 Extract<UIMessage["parts"][number], { type: \tool-` }>。通过 AgentChat/MessageList上的toolRenderers` 注册它们：

<AgentChat
  toolRenderers={{
    Bash: BashTool,
    Edit: EditTool,
    Write: EditTool,      // Write reuses EditTool
    Search: SearchTool,
    WebSearch: SearchTool,
    TodoWrite: TodoTool,
    PlanWrite: PlanTool,
    Task: SubagentTool,
    Thinking: ThinkingTool,
  }}
/>

可用卡片：

• BashTool — 命令和 stdout，可折叠。
• EditTool — 差异卡片。支持 input.old_string/input.new_string 或 output.structuredPatch，并可通过 input.approval 显示审批页脚。
• SearchTool — 分组的搜索结果。传入 results 或使用 output.results。
• TodoTool — 根据 input.todos 与 output.oldTodos 显示差异待办列表。
• PlanTool — 计划标题和摘要，带有批准/拒绝页脚。
• ToolGroup — 将连续的工具调用折叠成一行。
• SubagentTool — 带有嵌套工具的子 Agent 任务。
• McpTool — 通用 MCP 工具输出；使用 @/components/agent-elements/tools/tool-registry 中的 parseMcpToolType 获取 mcpInfo。
• ThinkingTool — 可折叠的推理行。
• GenericTool — 未知工具的回退组件。
• QuestionTool — 可通过单选、多选或文本作答的澄清问题。

流式状态

• TextShimmer — 闪烁的状态标签。
• SpiralLoader — Lottie 螺旋动画；用于持续数秒的加载状态。

组合模式

带工具渲染的完整聊天（最常见）

"use client";

import { AgentChat } from "@/components/agent-elements/agent-chat";
import { BashTool } from "@/components/agent-elements/tools/bash-tool";
import { EditTool } from "@/components/agent-elements/tools/edit-tool";
import { SearchTool } from "@/components/agent-elements/tools/search-tool";
import { useChat } from "@ai-sdk/react";

export default function Chat() {
  const { messages, status, sendMessage, stop } = useChat();
  return (
    <AgentChat
      messages={messages}
      status={status}
      onSend={({ content }) => sendMessage({ text: content })}
      onStop={stop}
      toolRenderers={{
        Bash: BashTool,
        Edit: EditTool,
        Write: EditTool,
        Search: SearchTool,
      }}
    />
  );
}

带模式和模型选择器的输入框

import { InputBar } from "@/components/agent-elements/input-bar";
import { ModeSelector } from "@/components/agent-elements/input/mode-selector";
import { ModelPicker } from "@/components/agent-elements/input/model-picker";
import { IconBulb, IconCursor } from "@tabler/icons-react";

const modes = [
  { id: "agent", label: "Agent", icon: IconCursor },
  { id: "plan", label: "Plan", icon: IconBulb },
];
const models = [
  { id: "sonnet", name: "Sonnet", version: "4.6" },
  { id: "opus", name: "Opus", version: "4.7" },
];

<InputBar
  status="ready"
  onSend={handleSend}
  onStop={handleStop}
  leftActions={
    <>
      <ModeSelector modes={modes} defaultValue="agent" />
      <ModelPicker models={models} defaultValue="sonnet" />
    </>
  }
/>

自定义工具渲染器

toolRenderers 的值是接收 { part, chatStatus } 的 React 组件。 返回任意 UI 即可；可以复用 GenericTool 作为回退外壳。

主题

Agent Elements 会读取这些 Tailwind CSS 变量（shadcn 风格）。请勿在使用方主题中删除或重命名它们：

• --an-foreground、--an-background、--an-primary-color
• 标准 shadcn 令牌：--background、--foreground、--border、 --muted、--muted-foreground、--accent、--primary 等。

自定义组件只需编辑已安装的文件。优先采用这种方式，而不是进行封装——现在代码归你所有。

不适合使用 Agent Elements 的情况

• 使用 assistant-ui、ai-elements、copilotkit 或其他套件的项目—— 不要混用。
• 从不渲染工具调用或计划的纯聊天 UI——InputBar 加上自定义消息渲染可能就够了；可以不使用 AgentChat。
• React < 19 或 Tailwind < v4——这些组件依赖两者。

常见问题速答

• “在此项目中添加 Agent Elements” → 如果缺少 components.json，运行 npx shadcn@latest init，然后运行 npx shadcn@latest add https://agent-elements.21st.dev/r/agent-chat.json。
• “更改默认 SendButton 的外观” → 直接编辑 components/agent-elements/input/send-button.tsx。令牌位于 --an-* CSS 变量中。
• “渲染自定义工具” → 在 toolRenderers 中映射其类型；对于未知工具，回退到 GenericTool。
• “与 useChat 配合使用” → 直接传入 messages 和 status， 将 sendMessage/stop 转换为 onSend({ content })/onStop。

Registry 参考

• 索引：https://agent-elements.21st.dev/r/index.json
• 单个组件：https://agent-elements.21st.dev/r/<id>.json
• 合并在一个文件中的完整文档： https://agent-elements.21st.dev/llms-full.txt