Hydra AITambo组件体系详解Generative 生成式组件与 Interactable 可交互组件实战指南【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai本文是一份围绕 TamboHydra AI 的 Generative UI SDK for React组件体系的实战技术指南。它系统讲解两种核心组件类型——由 AI 按需动态创建的Generative Components生成式组件与预先放置在 UI 中、由 AI 观察和更新的Interactable Components可交互组件覆盖注册方式、propsSchema配置、ComponentRenderer渲染、withTamboInteractable双向更新等完整链路。读完本文你将能够在自己的 React 应用中接入tambo-ai/react正确注册组件、渲染 AI 生成结果并让 AI 通过自然语言直接操作你预先摆放的界面组件。本文以技能参考文档 components.md 为主体并结合仓库内 react-sdk 的源码实现与测试用例对每一处 API 的底层机制进行溯源验证。组件体系概览两种互补的组件类型Tambo 的组件体系只包含两种组件类型两者分工明确、互为补充维度Generative生成式组件Interactable可交互组件创建方式AI 按需动态创建开发者预先放置在 UI 中渲染时机单次渲染随 AI 回复出现会话期间持续存在Props 来源AI 生成一次AI 可持续更新 props典型场景聊天回复、仪表盘图表设置面板、表单、任务看板一句话概括Generative 组件是 AI 说出来的界面Interactable 组件是 AI 能动手操作的界面。前者回答AI 如何根据用户请求现造一个 UI后者回答AI 如何接管你页面里已经存在的 UI 并实时更新它。快速开始无论使用哪种类型第一步都是把组件注册到TamboProvider上。以下是最小可用示例摘自参考文档的 Quick Start// Generative: AI creates when needed const components: TamboComponent[] [ { name: WeatherCard, component: WeatherCard, description: Shows weather. Use when user asks about weather., propsSchema: z.object({ city: z.string(), temp: z.number() }), }, ]; TamboProvider components{components} App / /TamboProvider;这里的核心约定是components数组中的每一项都是一个TamboComponent包含nameAI 引用的标识、component实际的 React 组件、description告诉 AI 何时使用它、propsSchemaAI 生成 props 的契约。从源码看TamboComponent类型定义在 component-metadata.ts它继承自tambo-ai/client的基类并用ComponentTypeany覆盖了 React 相关的字段。源码注释特别强调component字段必须传组件本身而不是组件实例const MyComponent () { return divMy Component/div; }; // 正确传 Component 本身 const components [MyComponent];TamboProvider内部会把components交给TamboRegistryProvider处理。查看 tambo-registry-provider.tsx 的registerComponent实现可知每个组件注册时会被校验validateAndPrepareComponent、规范化 props schema并存入以name为键的ComponentRegistry中若传入同名组件且开启覆盖警告会输出overwriting component name的 console 警告。也就是说name必须全局唯一否则后面的注册会覆盖前面的。Generative Components让 AI 按需生成界面注册生成式组件生成式组件的完整注册示例参考文档核心示例import { TamboProvider, TamboComponent } from tambo-ai/react; import { z } from zod; const WeatherCardSchema z.object({ city: z.string().describe(City name), temperature: z.number().describe(Temperature in Celsius), condition: z.string().describe(Weather condition), }); const components: TamboComponent[] [ { name: WeatherCard, component: WeatherCard, description: Displays weather for a city. Use when user asks about weather., propsSchema: WeatherCardSchema, }, ]; TamboProvider apiKey{apiKey} components{components} App / /TamboProvider;TamboProvider在这里同时接收了apiKey与components。apiKey对应NEXT_PUBLIC_TAMBO_API_KEYNext.js或VITE_TAMBO_API_KEYVite等环境变量详见技能主文档 SKILL.md 的 Environment Variables 小节。propsSchemaAI 生成 props 的合同propsSchema是生成式组件的核心配置有两个关键约束参考文档 Key Points必须是 Zod object并且每个字段都要调用.describe()。.describe()写入的字符串就是 AI 理解该字段含义的唯一依据例如z.string().describe(City name)让 AI 知道city应该填城市名而不是国家名。description 字段告诉 AI 何时使用该组件。它相当于组件的触发条件说明写得越清晰AI 在用户消息中匹配到正确组件的概率越高。使用 ComponentRenderer 渲染 AI 生成的组件组件注册到 Provider 后AI 回复中的组件块需要通过ComponentRenderer渲染到消息列表里。参考文档给出了完整示例import { ComponentRenderer } from tambo-ai/react; function Message({ message, threadId, }: { message: TamboThreadMessage; threadId: string; }) { return ( div {message.content.map((block) { switch (block.type) { case text: return p key{${message.id}:text}{block.text}/p; case component: return ( ComponentRenderer key{block.id} content{block} threadId{threadId} messageId{message.id} / ); default: return null; } })} /div ); }消息的content数组中的每个 block 有两种类型text纯文本与component组件块。对component块交给ComponentRenderer处理即可。注意key{block.id}至关重要——ComponentRenderer依靠稳定的 key 在 React 调和reconciliation过程中保持组件实例不被销毁。源码视角ComponentRenderer 内部做了什么从 v1-component-renderer.tsx 的实现可以看到完整的渲染链路从注册表查找组件通过getComponentFromRegistry(content.name, registry.componentList)按名称查找已注册组件。若找不到registry.ts 会抛出Tambo tried to use Component ${name}, but it was not found错误。解析 props支持流式使用partial-json库的parse解析 props。这一步正是流式渲染的关键——AI 回复尚未结束时 props 可能是残缺的 JSON 片段partial-json能宽容地解析这些半成品数据让组件在流式输出过程中就能逐步渲染出来。校验 props如果组件带 schema标准 Schema 兼容会用~standard.validate校验解析后的 props。校验失败时不会阻断渲染只是打印 warning 并按原始 props 渲染保证 UI 始终有内容呈现。包一层组件上下文用ComponentContentProvider包裹渲染结果注入componentId、threadId、messageId、componentName使得组件内部可以通过useTamboComponentState等 Hook 访问组件上下文。失败兜底任何异常都会被捕获并记录详细错误上下文threadId、messageId、componentName、streamingState、props渲染返回null或传入的fallback。生成式组件关键要点Key PointspropsSchemaZod 对象每个字段用.describe()描述含义description用自然语言告诉 AI 何时使用该组件Streaming流式流式渲染时 props 一开始是undefined的因此 props 要么声明为 optional要么在组件内做优雅降级处理如默认值类型安全用z.infertypeof Schema生成 TypeScript props 类型让 AI 生成的 props 与组件签名对齐。type WeatherCardProps z.infertypeof WeatherCardSchema; // { city: string; temperature: number; condition: string }Interactable Components让 AI 操作你预先放置的 UI与生成式组件不同可交互组件由你直接放进页面AI 可以看见它的当前 props并通过自然语言指令更新它们。使用 withTamboInteractable 包装组件参考文档的 Note 示例import { withTamboInteractable } from tambo-ai/react; import { z } from zod; const NoteSchema z.object({ title: z.string().describe(Note title), content: z.string().describe(Note content), color: z.enum([white, yellow, blue]).optional(), }); function Note({ title, content, color white }: Props) { return ( div style{{ backgroundColor: color }} h3{title}/h3 p{content}/p /div ); } export const InteractableNote withTamboInteractable(Note, { componentName: Note, description: A note with editable title, content, and color, propsSchema: NoteSchema, });withTamboInteractable接收两个参数原始组件 配置对象InteractableConfig。从 with-tambo-interactable.tsx 的源码可见配置对象支持四个字段字段类型说明componentNamestring组件在 Tambo 中的标识名称descriptionstring组件用途描述LLM 依据它理解如何与该组件交互propsSchema?SupportedSchemaProps可选的 props schema提供后 AI 更新 props 时会按它校验stateSchema?SupportedSchemaState可选的 state schema提供后 state 更新会按它校验此外还有一组可选的回调/注入 propsWithTamboInteractableProps见 with-tambo-interactable.tsxinteractableId?可手动指定的实例 ID不传则自动生成唯一 IDonInteractableReady?: (id: string) void组件注册完成回调onPropsUpdate?: (newProps) voidTambo 通过工具调用更新 props 后的回调。可交互组件的工作原理How It Works参考文档给出了四条核心机制逐一结合源码展开1. Auto-registration挂载即注册withTamboInteractable生成的包装组件在useEffect挂载阶段调用addInteractableComponent()完成注册with-tambo-interactable.tsx。注册时会在componentName后追加一个随机后缀生成唯一 ID如Note-a1b2c3实现同一组件多个实例互不干扰。卸载时自动调用removeInteractableComponent清理同时注销其关联工具。2. Context sending当前 props 自动暴露给 AI注册时组件的当前 props 会被存储进TamboInteractableProvider的组件列表。AI 可通过全局工具get_all_interactable_components与get_interactable_component_by_id实时读取所有可交互组件及其 props工具实现见 tambo-interactable-provider.tsx。同时props 变化时会通过updateInteractableComponentProps同步包装组件里会用JSON.stringify对比上一次序列化结果避免无意义的重复同步with-tambo-interactable.tsx。3. Tool registration更新工具自动注册这是AI 能操作 UI的底层支撑。TamboInteractableProvider为每个可交互组件自动注册两个工具tambo-interactable-provider.tsxupdate_component_props_id按propsSchema生成 JSON Schema 并转为**部分可选partial**结构AI 只需传入想修改的字段即可局部更新update_component_state_id同理更新组件 state支持stateSchema校验。两个工具默认都带tamboStreamableHint: true注解因此 props/state 更新可以实时流式呈现。若想关闭某个组件工具流的实时流式可在annotations中设置{ tamboStreamableHint: false }见 InteractableConfig.annotations。TamboInteractableProvider还维护了一个工具归属映射卸载组件时会连带注销它名下的所有工具。4. Bidirectional用户编辑与 AI 更新双向打通用户 → AI用户在界面上修改组件props 变化自动同步给 AI供后续指令参考AI → 用户AI 调用update_component_props_id工具updateInteractableComponentProps对 props 做浅比较后执行部分合并更新tambo-interactable-provider.tsx组件随即以新 props 重渲染。在可交互组件内部管理状态useTamboComponentState如果组件内部有本地状态希望同时被 AI 感知和修改例如便签的isPinned可以配合useTamboComponentStateHook。从 use-tambo-v1-component-state.ts 的类型签名可见其用法与useState几乎一致但返回三元组const [count, setCount, { isPending, error, flush }] useTamboComponentState( count, 0, // 初始值 500, // 可选防抖毫秒数默认 500 );该 Hook 支持三种模式源码注释明确说明Rendered components生成式组件内与后端做双向状态同步Interactable components可交互组件内通过 interactable provider 同步 state即走update_component_state_id工具链路No context yet在上下文尚未就绪如首帧渲染时退化为纯useState无副作用。何时使用哪种组件参考文档末尾的对照表是选型决策的核心依据GenerativeInteractableAI 按需创建你预先放置在 UI 中一次性渲染会话期间持续存在Props 只生成一次AI 可以持续更新 props适用聊天回复、仪表盘适用设置、表单、任务看板选型建议如果这个 UI 是AI 回答的一部分回答完就翻篇——选 Generative如果这个 UI 是你应用里本来就有的功能界面希望用户能用自然语言指挥 AI 去操作它——选 Interactable。两者的结合点在于可交互组件被 AI 渲染在消息里时同样能享受ComponentRendererComponentContentProvider的上下文注入这正是生成后仍可被操作的进阶玩法。配套参考技能主流程building-with-tambo/SKILL.md安装、Provider 接线、Chat UI 布局选型的完整 Step-by-Step组件渲染细节component-rendering.md流式 props、loading 状态、持久化状态组件渲染器源码v1-component-renderer.tsx 及测试 v1-component-renderer.test.tsx可交互 HOC 源码with-tambo-interactable.tsx 及测试 with-tambo-interactable.test.tsx可交互 Provider 源码tambo-interactable-provider.tsx组件状态 Hook 源码use-tambo-v1-component-state.ts【免费下载链接】hydra-aiGenerative UI SDK for React项目地址: https://gitcode.com/GitHub_Trending/hy/hydra-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考