tambo-ai / tambo

8,996430+300 todayTypeScript

面向React的生成式UI开发工具包

Tambo是一个面向React的开源生成式UI工具包，专为构建能够动态渲染界面的AI智能体而设计。开发者可以使用Zod模式注册自己的React组件，智能体便能根据用户指令（如“显示区域销售数据”或“添加任务”）自动选择匹配的组件，并实时流式传输属性参数，从而在应用中生成可交互的UI。该工具包内置了状态管理、流式处理以及对模型上下文协议（MCP）的支持，简化了将AI对话能力与现有UI组件系统连接的过程。适用于需要集成智能助手、实现自然语言驱动界面更新或构建动态响应式应用的React开发场景。

💡 应用场景

最适合为已有React应用快速添加自然语言驱动的动态UI生成能力，让用户通过对话直接操作界面。

构建AI助手界面

问题：开发者想为应用添加智能助手功能，但需要手动编写大量逻辑来解析用户指令并调用对应的UI组件。

方案：使用Tambo注册业务组件（如销售图表、任务列表），智能体根据用户自然语言指令自动选择并渲染对应组件，实现“显示销售数据”直接生成图表界面。

示例：用户说“帮我展示上季度各区域销售额对比”，Tambo自动匹配并渲染已注册的<SalesChart>组件，并流式传输区域、时间范围等参数。

自然语言驱动应用

问题：用户希望通过聊天或语音指令直接操作应用界面（如添加任务、修改设置），而不需要手动点击按钮或填写表单。

方案：通过Tambo将表单、列表等交互组件注册为可生成单元，AI智能体解析用户指令后动态更新UI状态，实现“添加一个明天下午的会议”自动创建任务项。

示例：在任务管理应用中，用户输入“把项目评审会改到周五”，Tambo自动更新对应的<TaskItem>组件属性并重新渲染界面。

动态仪表盘生成

问题：需要根据用户实时需求动态组装数据仪表盘，传统方式需要预置多种布局模板或编写复杂的状态管理逻辑。

方案：将各种数据可视化组件（图表、指标卡、表格）注册到Tambo，用户通过自然语言描述需求，系统自动组合并渲染相应的组件集合。

示例：用户说“我想看实时用户活跃度、留存率和地域分布”，Tambo自动选择并排列<ActiveUsersChart>、<RetentionRateCard>、<GeoDistributionMap>三个组件。

快速集成AI能力

问题：已有成熟的React组件库，但想快速为其添加AI对话交互能力，而不想重写组件通信和状态管理逻辑。

方案：利用Tambo的Zod模式注册现有组件，内置的流式处理和状态管理自动处理AI指令到组件属性的转换，只需少量代码即可让现有组件支持AI驱动。

示例：电商后台已有<ProductTable>、<InventoryChart>等组件，通过Tambo包装后即可支持“显示库存低于100的商品”等自然语言查询。

📊 项目信息

语言: TypeScript
Stars: ⭐ 8,996
Forks: 430
今日新增: +300
排名: #1
收录: 总榜
趋势日期: 2026年2月12日
最后推送: 2026/2/12

🏷️ 标签

ReactTypeScript生成式UIAI助手开箱即用可扩展前端开发者AI应用开发者

📸 截图

5分钟上手 Tambo：构建生成式UI的React智能体

本指南将帮助你在5分钟内创建一个React应用，集成Tambo智能体并看到组件动态渲染的效果

🖥️ 操作系统

macOSWindowsLinux

⚙️ 运行环境

Node.js>= 18.0

🔧 工具

npm 或 yarn— 包管理工具

📝 操作步骤

创建React应用并安装Tambo

使用Create React App快速搭建项目并安装Tambo核心包

创建TypeScript React应用

$ npx create-react-app my-tambo-app --template typescript

进入项目目录

$ cd my-tambo-app

安装Tambo核心包

$ npm install @tambo-ai/tambo

✓预期输出：项目创建成功，Tambo包安装完成

💡如果已有React项目，可直接执行npm install @tambo-ai/tambo

配置TamboProvider

在应用入口文件中设置TamboProvider，这是Tambo的核心上下文

✓预期输出：在App.tsx中看到TamboProvider配置

💡记得替换YOUR_API_KEY为实际的API密钥

创建示例组件并注册

创建一个简单的React组件，并使用Zod模式注册到Tambo中

✓预期输出：组件成功注册，可以在智能体中使用

💡Zod模式定义了组件接收的参数类型，智能体会根据模式自动匹配

添加智能体交互界面

在应用中添加输入框和显示区域，让用户可以与智能体交互

✓预期输出：应用中出现输入框和组件渲染区域

💡useTamboThreadInput() hook会自动处理输入状态

启动应用并测试

运行开发服务器，测试智能体是否能动态渲染组件

启动开发服务器

$ npm start

✓预期输出：浏览器自动打开 http://localhost:3000，看到应用界面

💡在输入框中尝试输入'显示欢迎消息'，应该能看到WelcomeMessage组件渲染

✅ 验证成功

确认Tambo智能体已正确集成并能动态渲染UI

✓应用在浏览器中正常打开
✓输入框可以输入文本
✓输入'显示欢迎消息'后，页面动态渲染出欢迎组件
✓组件正确显示传入的参数内容

⚡ 快速提示

配置使用userKey进行服务器端身份验证，userToken用于客户端

开发Zod模式要尽可能精确，这有助于智能体准确匹配组件

性能Tambo支持流式传输属性，可以实现更流畅的UI更新体验

🔍 常见问题排查

❓ TamboProvider报错：缺少userKey或userToken

→ 确保在TamboProvider中提供了userKey或userToken参数，用于标识线程所有者

❓ 组件注册后智能体无法识别

→ 检查Zod模式是否正确，确保模式与组件props类型匹配

❓ TypeScript类型错误

→ 确保安装了正确的TypeScript版本（>=4.9），并检查类型导入是否正确

❓ 智能体没有响应

→ 检查API密钥是否正确，网络连接是否正常，以及TamboProvider配置是否完整

🎯 下一步

查看官方文档

深入了解Tambo的高级功能和配置选项

探索内置组件

尝试Tambo提供的其他内置组件和示例

集成自己的业务组件

将项目中的现有组件注册到Tambo中

配置MCP支持

设置模型上下文协议，增强智能体的上下文理解能力

难度

初级

预计时间

3-5小时

目标人群

具备基础React和TypeScript知识的开发者，希望在自己的React应用中集成AI对话能力，实现自然语言驱动UI更新的前端开发者或AI应用开发者。

🎯 学完你将掌握

你将学会如何将现有的React组件注册到Tambo AI智能体中，并通过自然语言指令（如“显示图表”）让智能体自动选择并渲染对应的交互式UI组件。

📋 前置知识

React基础熟悉

Tambo是一个React工具包，你需要理解JSX、组件、Props、Hooks（如useState, useEffect）等核心概念才能使用它。

TypeScript基础了解

项目使用TypeScript编写，了解基础类型（如interface, type）和泛型有助于理解示例代码和类型提示。

Node.js与npm/yarn/pnpm了解

用于安装项目依赖和运行开发服务器。

Zod基础了解

Tambo使用Zod模式来定义组件的属性（Props）结构，这是智能体理解如何调用组件的关键。了解Zod的基本模式定义（如z.object, z.string）即可。

📚 学习资源

必看

Tambo Documentation

最权威的指南，包含API详解、概念解释和进阶指南。

必看

GitHub README 及 “Get Started” 部分

项目首页，包含最精炼的概述和快速启动代码片段。

🗺️ 学习阶段

环境准备与项目理解

⏱ 30分钟

创建React项目并安装Tambo

1. 使用Create React App或Vite创建一个新的TypeScript React项目。 2. 在项目根目录下，通过npm/pnpm/yarn安装Tambo核心包：`npm install @tambo-ai/tambo`。

💡确保你的Node.js版本较新（建议v18+）。如果你已有现成的React项目，可以直接在项目中安装。

通读README，理解核心概念

仔细阅读项目README的“What is Tambo?”和“How It Works”部分。理解三个核心概念：1. 用Zod模式注册组件。2. 智能体根据指令选择并流式传输Props。3. 用户与渲染出的组件交互。

💡重点关注“Show me sales by region”和“Add a task”这两个例子，它们直观展示了Tambo的工作流程。

快速上手：第一个Tambo智能体

⏱ 1-1.5小时

设置TamboProvider

1. 在你的应用根组件（如App.tsx）中，导入并包裹`TamboProvider`。 2. 根据README的“Get Started”部分，配置`apiKey`（从Tambo平台获取）和用户标识（`userKey`或`userToken`）。对于本地测试，可以先关注组件注册流程。

💡`userKey`用于服务端或可信环境，`userToken`用于客户端。初次体验时，可以暂时使用一个模拟的`apiKey`或关注离线演示部分（如果文档有提供）。

创建并注册你的第一个组件

1. 创建一个简单的React组件，例如一个显示欢迎信息的`Greeting`组件，它接受一个`name`属性。 2. 使用`defineComponent`函数和Zod模式（`z.object({ name: z.string() })`）来定义这个组件的“调用接口”。 3. 使用`useTambo()`钩子返回的`register`函数注册这个组件。

💡从最简单的组件开始，不要涉及复杂状态。先确保“注册”这个动作成功，理解Zod模式如何描述你的Props。

模拟指令，观察组件渲染

1. 在组件内或通过一个测试按钮，模拟调用`useTambo().appendMessage`，发送一条包含你组件名称和参数的指令（例如，一个符合你定义的Zod结构的对象）。 2. 观察UI中是否成功渲染出了你的`Greeting`组件，并显示了传入的`name`。

💡这一步的关键是验证“指令 -> Zod模式匹配 -> 组件渲染”的链路是否打通。如果文档有在线Playground或示例代码仓库，直接克隆并运行是最高效的方式。

核心功能探索

⏱ 1.5-2小时

实现流式属性传输

修改你的组件Zod模式，使其包含一些可能需要逐步加载的属性（例如，一个`content`字段，其内容由AI流式生成）。观察当智能体流式传输这些属性时，你的组件如何实时更新。

💡这是Tambo的核心特性之一。查看文档中关于流式Props的部分，理解`streaming`参数或相关钩子的使用。

使用useTamboThreadInput处理用户输入

在应用中集成一个输入框，使用`useTamboThreadInput`钩子来获取用户输入并将其发送给智能体。体验完整的“用户输入指令 -> AI响应并选择组件 -> 渲染UI”的交互循环。

💡这个钩子帮你管理了输入状态和提交逻辑，是构建聊天式AI助手界面的关键。

探索状态管理与组件交互

创建一个更复杂的组件（如一个简单的待办事项列表），它内部有自己的状态（新增、完成）。注册后，通过AI指令（如“添加一个买菜的任务”）来触发组件状态的更新，理解Tambo如何作为UI层与AI逻辑的桥梁。

💡思考组件的“状态”是应该由组件自身管理，还是通过Props由外部（AI智能体）驱动。参考`TamboProvider`的示例。

回顾与连接

⏱ 30分钟

阅读关键文档与示例

前往官方文档（docs.tambo.co），重点阅读“组件注册”、“属性流式传输”、“与AI模型集成”等核心章节。查找并运行官方的示例项目（Example或Demo）。

💡示例代码是最佳的学习资源，能帮你理解最佳实践和项目结构。

规划你的实践项目

基于所学，构思一个能将Tambo用起来的迷你项目点子。例如：一个智能仪表盘，可以用自然语言添加图表组件；或一个笔记应用，可以用语音指令格式化文本。

💡从“我有一个XX组件，我想用一句话让它出现/变化”这个场景开始思考。

⚠️ 常见错误

❌ Zod模式定义与组件Props类型不匹配

✅ 确保`defineComponent`中Zod模式推导出的类型，与你组件实际接收的Props类型（通常是`interface`或`type`）完全一致。使用TypeScript的泛型来确保类型安全，例如 `defineComponent<YourPropsType>({...})`。

❌ 忘记在应用顶层包裹TamboProvider，或Provider配置错误

✅ 检查`TamboProvider`是否包裹了所有需要使用Tambo的组件。仔细核对`apiKey`、`userKey`/`userToken`的配置，根据环境（客户端/服务端）选择正确的参数。

❌ 未能正确处理异步或流式Props

✅ 当组件属性需要支持流式更新时，确保你的组件能够响应Props的变化。使用React的`useEffect`监听相关Prop的变化，并更新组件内部状态或视图。

❌ 认为Tambo会“自动”理解所有现有组件

✅ Tambo不会自动扫描你的项目。你必须显式地使用`register`函数为每个想要被AI调用的组件进行注册和模式定义。从核心组件开始注册，逐步扩展。

🚀 后续方向

1. 深入研究与不同AI模型/后端的集成（如OpenAI, Anthropic），配置模型上下文协议（MCP）。2. 探索高级特性，如自定义工具（Tools）、组件间通信、复杂状态管理策略。3. 学习如何优化智能体提示（Prompt），使其更准确地理解你的组件库和业务领域。4. 将Tambo集成到现有的、规模较大的React应用或设计系统中。5. 关注社区，了解其他开发者是如何使用Tambo构建创新应用的。