agent-elements

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Elements skill

Agent Elements技能

Project-aware context for building chat and agent UIs with Agent Elements — an open-source shadcn registry at

https://agent-elements.21st.dev

这是为使用Agent Elements构建聊天和Agent UI提供的项目感知上下文——Agent Elements是一个开源的shadcn注册表，地址为

https://agent-elements.21st.dev

。

What this skill gives you

该技能能为你带来什么

When this skill loads, you know:

The registry is shadcn-compatible. Every component is installed with
```
npx shadcn@latest add https://agent-elements.21st.dev/r/<component>.json
```
. Files land under
```
components/agent-elements/
```
(the library's internal
```
components/
```
prefix is stripped — see Paths below).
The API is typed around the Vercel AI SDK. Messages are
```
UIMessage[]
```
from
```
ai
```
, status is
```
ChatStatus
```
.
```
useChat()
```
plugs in directly.
The full component catalog with API shapes and composition rules (see sections below).
Theming guardrails — the Tailwind tokens Agent Elements depends on.

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

注册表兼容shadcn：每个组件都可通过
```
npx shadcn@latest add https://agent-elements.21st.dev/r/<component>.json
```
安装。文件会被放置在
```
components/agent-elements/
```
目录下（库内部的
```
components/
```
前缀会被移除——见下方路径说明）。
API围绕Vercel AI SDK进行类型定义：消息为
```
ai
```
包中的
```
UIMessage[]
```
，状态为
```
ChatStatus
```
。
```
useChat()
```
可直接接入。
完整的组件目录及API结构与组合规则（见下方章节）。
主题约束——Agent Elements依赖的Tailwind令牌。

Detection

检测条件

Consider this project "Agent Elements-ready" if any of these are true:

```
components/agent-elements/
```
exists on disk
```
components.json
```
includes an alias or registry reference to Agent Elements
```
package.json
```
dependencies include
```
ai
```
+
```
@tabler/icons-react
```
and the user mentions Agent Elements

If the folder does not exist yet, install on demand with:

bash

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

agent-chat

transitively pulls every other component it needs via

registryDependencies

(MessageList, InputBar, tool renderers, shared utils).

如果满足以下任一条件，则认为该项目“已准备好使用Agent Elements”：

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

如果该目录尚未存在，可通过以下命令按需安装：

bash

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

agent-chat

会通过

registryDependencies

自动拉取它所需的所有其他组件（MessageList、InputBar、工具渲染器、共享工具）。

Paths (post-install layout)

安装后的路径结构

After

shadcn add

, files sit under

@/components/agent-elements/

with this shape:

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 rule: always import from the exact file, never from a barrel.

tsx

// ✅
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";

执行

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

导入规则：始终从具体文件导入，切勿从桶文件导入。

tsx

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

// ❌ 错误写法——不存在桶文件
import { AgentChat } from "@/components/agent-elements";

Component catalog

组件目录

Chat surface

聊天界面

AgentChat — the full chat shell. Renders
```
MessageList
```
+
```
InputBar
```
, handles tool invocations via
```
toolRenderers
```
, shows an empty state with optional
```
suggestions
```
. Props:
```
messages
```
,
```
status
```
,
```
onSend
```
,
```
onStop
```
,
```
toolRenderers?
```
,
```
suggestions?
```
,
```
attachments?
```
,
```
classNames?
```
,
```
slots?
```
.
MessageList — transcript only. Use when you need the input bar somewhere else. Accepts
```
toolRenderers
```
and
```
showCopyToolbar
```
.
UserMessage / ErrorMessage / Markdown — low-level message pieces.
```
Markdown
```
streams safely (external links get
```
rel="noreferrer"
```
by default).

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

Input

输入组件

InputBar — composer. Props:

status

onSend({ content })

onStop

value?

onChange?

(controlled),

attachedImages

attachedFiles

with their remove handlers,

leftActions

rightActions

slots,

suggestions?

questionBar?

infoBar?

Suggestions — quick-prompt chips for the empty state or inline.
ModelPicker / ModeSelector — designed to drop into
```
leftActions
```
. Both accept a simple
```
{ id, name, version? }
```
/
```
{ id, label, icon?, description? }
```
shape. Do not import
```
CLAUDE_MODELS
```
— it was removed; supply your own array.
SendButton / AttachmentButton / FileAttachment — usable standalone if you're building a custom composer.

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 — 如果你正在构建自定义编辑器，这些组件可单独使用。

Tool cards

工具卡片

All tool cards accept a

part

prop of type

Extract<UIMessage["parts"][number], { type: \

tool-<Name>` }>

from the AI SDK. Register them via

toolRenderers

on

AgentChat

MessageList`:

tsx

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

Cards available:

BashTool — command + stdout, collapsible.

EditTool — diff card. Supports

input.old_string

input.new_string

output.structuredPatch

, plus an approval footer via

input.approval

SearchTool — grouped search results. Pass
```
results
```
or use
```
output.results
```
.
TodoTool — diffed todo list from
```
input.todos
```
vs
```
output.oldTodos
```
.
PlanTool — plan title + summary with approve/reject footer.
ToolGroup — collapses consecutive tool calls into one row.
SubagentTool — sub-agent task with nested tools.

McpTool — generic MCP tool output; use

parseMcpToolType

from

@/components/agent-elements/tools/tool-registry

to get

mcpInfo

ThinkingTool — collapsible reasoning row.
GenericTool — fallback for unknown tools.
QuestionTool — clarifying question with single/multi/text answer kinds.

所有工具卡片都接受一个

part

属性，类型为AI SDK中的

Extract<UIMessage["parts"][number], { type: \

tool-<Name>` }>

。 通过在

AgentChat

MessageList

上注册

toolRenderers`来使用它们：

tsx

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

可用的卡片：

BashTool — 命令+标准输出，可折叠。
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 — 带单选/多选/文本回答类型的澄清问题组件。

Streaming states

流式状态组件

TextShimmer — shimmering status label.
SpiralLoader — Lottie spiral; use for multi-second loading states.

TextShimmer — 闪烁的状态标签。
SpiralLoader — Lottie螺旋加载器；适用于多秒级的加载状态。

Composition patterns

组合模式

Full chat with tool rendering (most common)

带工具渲染的完整聊天界面（最常用）

tsx

"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,
      }}
    />
  );
}

tsx

"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,
      }}
    />
  );
}

Composer with mode + model pickers

带模式选择器和模型选择器的编辑器

tsx

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" />
    </>
  }
/>

tsx

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" />
    </>
  }
/>

Custom tool renderer

自定义工具渲染器

toolRenderers

values are React components that receive

{ part, chatStatus }

. Return whatever UI you want; reuse

GenericTool

as a fallback shell.

toolRenderers

的值是接收

{ part, chatStatus }

的React组件。你可以返回任意UI；可复用

GenericTool

作为回退外壳。

Theming

主题设置

Agent Elements reads these Tailwind CSS vars (shadcn-style). Do not remove or rename them in the consumer theme:

--an-foreground

--an-background

--an-primary-color

Standard shadcn tokens:

--background

--foreground

--border

--muted

--muted-foreground

--accent

--primary

, etc.

Customising a component is just editing the installed file. Prefer that over wrapping — the code is yours now.

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

--an-foreground

--an-background

--an-primary-color

标准shadcn令牌：

--background

--foreground

--border

--muted

--muted-foreground

--accent

--primary

等。

自定义组件只需编辑已安装的文件。优先选择直接编辑而非包装——代码现在归你所有。

When NOT to use Agent Elements

请勿使用Agent Elements的场景

Projects using
```
assistant-ui
```
,
```
ai-elements
```
,
```
copilotkit
```
, or another kit — don't mix.
Pure chat UIs that never render tool calls or plans —
```
InputBar
```
+ your own message rendering may be enough; skip
```
AgentChat
```
.
React < 19 or Tailwind < v4 — the components depend on both.

使用
```
assistant-ui
```
、
```
ai-elements
```
、
```
copilotkit
```
或其他套件的项目——不要混合使用。
从不渲染工具调用或计划的纯聊天UI——
```
InputBar
```
+ 你自己的消息渲染可能已足够；无需使用
```
AgentChat
```
。
React版本低于19或Tailwind版本低于v4——组件依赖这两者。

Quick answers for common asks

常见问题快速解答

"Add Agent Elements to this project" → run

npx shadcn@latest init

components.json

is missing, then

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

"Switch the default SendButton look" → edit
```
components/agent-elements/input/send-button.tsx
```
directly. Tokens live on
```
--an-*
```
CSS vars.
"Render a custom tool" → map its type in
```
toolRenderers
```
; fall back to
```
GenericTool
```
for unknown tools.
"Use with useChat" → pass
```
messages
```
and
```
status
```
straight through, translate
```
sendMessage
```
/
```
stop
```
to
```
onSend({ content })
```
/
```
onStop
```
.

“将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 reference

注册表参考

Index:

https://agent-elements.21st.dev/r/index.json

Per-component:

https://agent-elements.21st.dev/r/<id>.json

Full docs in one file:

https://agent-elements.21st.dev/llms-full.txt

索引：

https://agent-elements.21st.dev/r/index.json

单个组件：

https://agent-elements.21st.dev/r/<id>.json

完整文档单文件版：

https://agent-elements.21st.dev/llms-full.txt