HeroUI Agents 产品研究：托管助手、Generative UI 与产品交付形式

HeroUI Agents 官方文档：Overview

AI 参与说明（Agent：Codex）：本文依据 HeroUI Agents、HeroUI Pro 与竞品的公开官方文档、产品页面和发布记录整理，重点研究产品形式、交付边界与应用内工作流。资料核查日期为 2026-10-13；Pro 价格经过未登录公开页面核对，Agents 仍是邀请制 beta，本次未申请权限、购买或接入其真实服务。正文内实验是依据文档制作的本地教学模型，不是上游运行时实现或真实模型演示。产品定位、采用建议与商业价值判断均为分析。本文使用 research、Anatomy 与 humanizer-zh 辅助研究、讲解和编辑。运行记录：模型 gpt-6.1-sol，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai；任务运行记录中的 CLI 版本为 0.162.0-alpha.17.2，不代表桌面 App 版本。

HeroUI Agents 的产品形式，是交付给网站的一套托管助手：最终用户在应用内提问，助手取得业务数据、生成适合当前任务的界面，并通过应用提供的工具执行动作。 它把模型、对话、生成界面和运行观察一起交给 HeroUI；客户继续负责业务接口、用户权限和浏览器中的工具实现。这个分工决定了它的价值、接入成本和限制。Agents Overview

这个链接容易与 HeroUI Pro 的“帮助 Coding Agent 编写组件”混淆。HeroUI Pro 主要交付开发阶段的组件与设计资产；HeroUI Agents 主要服务产品运行时的最终用户。本文以 Agents 为主线，Pro 用来解释其设计基础和产品家族关系。

产品家族：三个交付对象

新版 Pro 是 HeroUI OSS 的付费扩展，通过软件包持续发行；Chat 的发布记录单独区分其 requests、tokens、credits 用量与 Pro 下载用量；Agents 的 FAQ 则明确无需客户采用 HeroUI React 或 Pro，也不要求客户自备 LLM provider key。Pro Introduction、HeroUI Chat 发布记录、Agents FAQ

所以，“购买 Pro”“给 Coding Agent 安装 Skill”和“让产品用户使用 Agents”是三种不同操作。不能用 Pro 组件数量描述 Agent UI 的覆盖范围，也不能把 Chat credits 当作 Agents 的赠送额度。

从用户体验看：助手是应用的另一条操作路径

传统界面要求用户先知道数据在哪、过滤器怎么设、哪个按钮能完成动作。HeroUI Agents 希望让用户先表达目标，再由工具和生成界面组织操作。例如，用户问“比较最近几个月的支出”，结果可以同时包含指标、趋势和明细；用户再提出调整要求，助手可以显示表单和确认操作。Generative UI 说明

按这个产品主张，可以将体验理解为下面的闭环。例子用于说明产品形式，不是本次真实服务验收结果：

这里的关键变化是：返回界面本身成为回答的一部分，动作也能留在同一次交互里。 用户不必把回答抄回另一个表单，开发者也不必提前为每一种问法做一张完整页面。这是根据产品设计作出的价值判断；减少多少步骤、多少时间，需要实测。

它也不会自动替代应用全部界面。登录、核心导航、稳定的高频设置仍适合固定页面。Generative UI 更适合“呈现方式取决于这次问题和数据”的场景；官方同样建议保留关键流程的传统 UI。Generative UI 边界

入口形式与品牌控制

官方 Appearance 文档列出 Floating、Sidebar、Chat Bar 三种入口：分别是角落启动按钮、右侧全高面板、底部输入条。全屏是部分入口的展开状态。客户可以配置颜色、字体、圆角、欢迎文案、建议问题等，并选择 Dashboard 配置或代码覆盖。Appearance

这使同一套 Hosted Agent 可以进入不同产品。产品团队选择助手出现的位置，供应商维护对话、确认、错误和生成内容等状态。代价是客户无法像维护自己的一棵 React 组件树那样控制全部内部结构。

运行边界：谁负责什么

The application exposes explicit tools; HeroUI operates the hosted conversation and UI.

React 接入包 @heroui/agent 是客户页面上的桥接层；对话 UI 及其 renderer 依赖从托管 iframe 加载。普通 JavaScript 网站可以使用 loader。React 接入要求 React 19+；可选 Next.js 入口要求 Next.js 15+，但 vanilla 路线没有框架依赖。Quickstart 另外提供 Vite、TanStack Start 和 React Router 接入示例。Installation

sequenceDiagram
    participant U as User
    participant H as Customer Page / Bridge
    participant S as Customer Server
    participant A as Hosted Agent
    participant API as Product API
    H->>S: 请求 browser credential
    S-->>H: 经服务端确认身份的凭据
    H->>A: 建立连接，提交 Tool Manifest 与显式 page context
    U->>A: 提出任务
    A->>H: 请求调用 Client Tool
    opt 当前权限模式要求确认
        A->>U: 展示批准或拒绝
        U-->>A: 批准
    end
    H->>API: 按当前用户会话请求业务数据
    API-->>H: 经业务授权的数据
    H-->>A: JSON 可序列化结果
    A-->>U: 经 Agent UI contract 验证的 Generative UI

图简化了凭据刷新、iframe handshake、重连和流式片段。它展示的是职责边界，不能据此推导一次业务写入具有跨服务事务或 exactly-once 保证。Quickstart、Client Tools

值得关注的是，它减少了客户搭建 Agent 后端的工作，仍然需要一个 token endpoint。纯静态网站也要补一个小型 serverless 接口；“添加脚本即可”并不意味着完全没有服务端接入工作。

数据如何变成界面

Agent UI 的输入、约束与结果

官方组件文档给出四个环节：Client Tool 返回结构化数据；Hosted Agent 选择兼容组件并准备 typed payload；检查 Agent UI contract；agent-ui 按主题和交互规则渲染。模型可以组合数据可视化、信息展示、表单和动作四组内置组件。Agent UI Components

Tools 文档进一步给出当前路径：模型通过 getUIComponents 取得定义与示例，再调用 composeUI，其中 specStream 是构建 root、elements 等字段的 JSONL patches；json-render 编译该流，HeroUI 检查并渲染结果。新界面通过增量描述出现，而不是把模型生成的任意 JavaScript 当成页面代码执行。Dataset interfaces

下面的实验把这条转换缩成一个可预测的模型。销量输入变化时，Tool Result、图表长度、总数和表格一起变化；切换组件时，数据仍相同，但组织方式改变。删除教学 Schema 要求的字段会阻止本例输出，说明验证位于数据到界面的边界上。

{"op":"add","path":"/root","value":"sales-layout"}
{"op":"add","path":"/elements","value":{}}
{"op":"add","path":"/elements/sales-layout","value":{"type":"teaching-stack","props":{"title":"四日销量（教学数据）"},"children":["sales-view"]}}
{"op":"add","path":"/elements/sales-view","value":{"type":"bar-chart","props":{"title":"四日销量（教学数据）","unit":"件","data":[{"label":"周一","value":24},{"label":"周二","value":42},{"label":"周三","value":30},{"label":"周四","value":54}]},"children":[]}}

实验的限制： 它使用自写的最小 Schema 和确定性的组件选择，未调用 HeroUI 服务或模型。实际 Agent 可能补调用工具、选择其他组件或返回文字；不能把本例的拒绝界面说成 HeroUI 对相同数据必然产生的行为。销量求和也只是本例的显式计算，不是上游对所有数据的默认规则。

预制目录的价值与约束

Component Catalog 让供应商集中维护布局、主题、交互和 Agent UI contract。它提供比任意网页生成更可控的表达范围，也降低客户配置一套生成式组件系统的成本。

但 Custom Components 仍标为 Soon。当前跨源 iframe 不接受客户任意 React 组件或 Markdown renderer。客户今天可以把生成的 Action 接到自己的 Client Tools；未来计划中的 custom UI API 尚未定型，不应作为已交付能力采购。Custom Components

因此应先拿实际业务数据试 Component Catalog：需要的字段关系、复杂编辑、表格行为或专业视图能否表达。外观接近自有产品，不等于能渲染自有全部组件。

工具设计决定助手能做多深

工具分为三类。Client Tools 在用户浏览器中执行；Built-in Toolkits 在 HeroUI 运行时提供；连接到 Agent 的 MCP servers 提供外部系统能力。Tools

Client Tools 不需要 HeroUI 猜测页面 DOM。开发者为工具写名称、说明、参数 Schema 和 execute，明确暴露“查订单”“打开详情”“调整筛选”等能力。这能让 Agent 操作已有软件，也让产品团队决定哪些行为进入助手入口。

下面是依据 SDK 文档整理的集成片段，展示 read/write 分工，不是完整可启动应用。它还需要有效的 beta Agent、getAuthToken、业务 apiClient 和服务端 token endpoint；本次未用真实服务运行。

import {createToolHelper} from '@heroui/agent';
import {z} from '@heroui/agent/zod';

type AppContext = {
  apiClient: {
    listOrders: (status: string) => Promise<unknown>;
    requestCancellation: (id: string) => Promise<unknown>;
  };
};

const tool = createToolHelper<AppContext>();

export const tools = [
  tool({
    name: 'list_orders',
    description: 'List orders visible to the signed-in customer by status',
    parameters: z.object({status: z.string()}),
    execute: ({status}, context) => context.apiClient.listOrders(status),
  }),
  tool({
    name: 'request_cancellation',
    description: 'Request cancellation of an eligible order owned by the customer',
    parameters: z.object({id: z.string().min(1)}),
    needsApproval: true,
    execute: ({id}, context) => context.apiClient.requestCancellation(id),
  }),
];

needsApproval 在默认 auto 模式下要求确认。ask 确认每次工具调用，full 则不要求确认，包括设了该标记的工具。业务接口仍须校验订单归属、状态和允许执行的动作；确认卡表达用户意愿，不能替代权限检查。Client Tools API、Approval modes

数据并没有全部留在浏览器

Client Tools 的实现函数和共享 context 留在页面；显式 page context 和工具返回值跨入托管边界，成为后续处理的输入。浏览器凭据由客户服务端按匿名 ID 或当前登录身份签发；匿名 ID 由 SDK 在浏览器生成并保存。登录后可以刷新凭据，退出时应 shutdown() 清理本地状态。Client Tools、Identifying users

普通工具结果当前有 64 KiB 上限，大数据可用 execution.uploadDataSource 提交 JSON、CSV、TSV，文档列出的上限为 10 MB。这是不同的数据路径：数据源可直接进入 artifact provider，而不是把所有行加入 conversation model context。Large datasets

尤其不能把官网的敏感数据宣传概括成“任何数据都不会到外部供应商”。文件生成文档明确涉及 OpenAI Code Interpreter，可能使用 Anthropic Code Execution 作为回退，供应商留存条款适用，并明确该处理不属于 Zero Data Retention 或 HIPAA eligible 路径。本次没有进行数据流审计，公开页面不足以证明全部场景的合规保证。File generation 条件

Dashboard 让它成为可运营的产品

HeroUI Agents 把配置与运行记录放进 Dashboard，让团队在接入 SDK 之后还能持续调整助手。这些管理能力是其 SaaS 交付的一部分。

Knowledge Base 与实时数据各司其职

Knowledge Base 用于文档、稳定政策和操作说明，支持文件、公开网页及 Markdown；检索采用语义与关键词组合，并保留引用。需要认证的网页不能直接通过公开爬取取得。个人订单和实时余额应通过 Client Tools 提供。Knowledge base

这意味着接入团队需要分清：什么是所有用户可用的背景知识，什么是按当前用户权限取得的实时结果。把个人数据当成一般文档导入，不能从这个产品的工具桥接设计获得权限保护。

配置与可观察状态

Monitor 区分用量趋势与具体活动：前者看 conversations、messages、monthly active users 和 run success rate；后者进入 Users、Conversations、Logs，查到用户实际看到的内容，以及某次 Run 的工具、延迟和错误。其 run success rate 按进入终态的运行计算，不能直接当作业务任务成功率。Monitor、Logs

从产品使用角度，应同时观察两件事：运行是否正常结束，用户是否完成目标。例如助手正常输出了图表，但过滤条件错了，仍然属于业务失败。本文建议用真实任务结果补足平台运行指标。

从回答到可下载成果

除了嵌在对话中的 UI，产品还提供文件成果。内置 PDF、DOCX、PPTX、XLSX Skills 为文档、演示与工作簿提供专门指导；关闭某个 Skill 后基本导出仍可用。用户可以检查数据后继续要求导出，把一次对话延伸成可交付文件。Skills

这些 Skills 由 HeroUI 管理，内容只读、随其版本更新；管理 API 不支持上传、创建副本、移除或固定到旧版本。它们与开发者安装到 Codex 等工具里的 heroui-agents Skill 是两个执行位置，不应混为同一套用户自定义扩展机制。

开发者接入也被做成了产品流程

文档页面提供 Copy Prompt，开发者可以把集成任务交给 Coding Agent。公共 heroui-agents Skill 教它检查应用、配置 Agent、接入 SDK、工具和验证；Agents MCP 则让它读取工作区、创建或调整 Agent、管理知识和排查运行。Building with AI、Agent skill

公开文档给出的 Skill 安装命令是：

npx skills add https://heroui.pro/docs/skills/heroui-agents

该命令这里只作为官方接入入口展示，本次研究未执行安装。Skill 是公开资料，安装它不等于登录或取得工作区权限。实际配置还要连接 MCP，完成账户授权和 workspace 选择。

三种 MCP 方向

这三者分别发生在组件开发、助手管理、产品运行过程中。Agents MCP 的 API/管理读操作没有独立使用费，不代表用户对话、模型与产品使用免费；文档明确现有用量和限制继续适用。Agents MCP、Runtime MCP servers、Pro MCP

这是一个值得学习的接入设计：产品同时提供给人操作的 Dashboard，以及给 Coding Agent 操作的管理接口。接入者仍然要判断目标工作区、已有 Agent 和权限范围，工具写入成功也还要核验运行状态。

商业形式：Pro 许可与 Agents 服务不能混算

截至核查日，Agents 仍为邀请制 beta、人工审核开通，公开页面未提供价目。它是 hosted-only 服务，不支持客户 self-host 或带入自己的 Agent 运行时。这些是当前采用条件，不应据此推定未来正式套餐。Agents FAQ

API 有工作区 usage 与 credits 字段，但本次没有找到公开的 credit 单价、换算规则、套餐额度和超额结算细则。采购时应另行取得 Agents 的价格与服务约定，不能拿 Pro 的一次性买断价格估计运行成本。Workspace usage API

Pro 的现行价格作为家族背景

下表是 2026-10-13 未登录公开价格页显示的美元价格，未进入付款流程。它是 Pro 组件与资产许可，不是 Agents 报价。Pro Pricing

Team 至少两席。Pro 首购包含一年 Updates Window；不续更仍可使用已获得版本，后续版本获取需要相应权益。团队席位和持续软件包更新，让新版 Pro 的交付更接近付费软件供应链。Licensing

Pro 许可允许用在商业成品中，但不允许公开再分发底层 Pro 组件、模板或其源码。开源成品与开源付费素材是不同边界。本文只研究公开接口和资料，不复制商业组件实现。Terms

产品复用有一个明确证据

2026-09-15 的 Design System Agent 发布记录明确：Pro Design Systems 编辑器里的聊天就是一个限定在当前 draft 的 Hosted Agent。它可以读取 draft、应用 patch、从网站提取品牌信息；符合条件的 Pro owners 使用 sponsored usage。这个赞助场景不要求个人 Agents subscription 或 credits，不能外推为所有网站嵌入免费。Design System Agent release

这个实例说明 HeroUI 已把 Agents 用到自己的产品里：编辑器提供工具，Hosted Agent 组织操作，用户检查结果。从产品策略看，它既是功能，也是展示接入模式的渠道；这属于基于公开功能的分析，不是客户转化或营收证据。

与相关方案比较：比较交付责任

官方也有一页 Agent comparison，但其资料核查日期为 2026-09-20。下面按本次能查到的竞品自身最新资料更新，不把厂商自评当成独立评测。官方比较页

CopilotKit 的比较依据是其 Frontend SDKs 和 Backend Connections。其公开价格当前为 Developer 免费、Pro 39 美元/月、Team 100 美元/seat/月，企业方案另议；不同层级包括不同能力，不能只用起价比较总成本。CopilotKit Pricing

Tambo 的状态已经变化： 2026-10-01 官方公告关闭新注册，并计划于 2026-10-31 停止 Cloud API、2026-11-30 删除云端用户数据。开源和 self-host 路线保留，但用户须自行维护。不能把旧的 Cloud pricing 当成当前可持续采购方案。Tambo 关闭公告、Self-Hosting Guide

Fin 当前按 $0.99/outcome 计费，而 outcome 可以包含某些 Procedure 完成与 handoff，并不严格等于“全自动解决一次问题”。它的产品组织方式围绕客服任务、测试和交接，比 HeroUI 的通用应用内操作主张更垂直。Fin Capabilities、Procedures、Intercom Pricing

shadcn/ui 的 registry / MCP、Untitled UI 的组件分发，以及 v0 的应用生成属于开发阶段的参照。它们帮助制作产品，不能直接等同于给最终用户的一套 Hosted Agent。shadcn MCP、Untitled UI MCP、v0 FAQ 对于已有 Agent、只想增加 Generative UI 层的团队，还可以单独评估 renderer 或 UI protocol；没有必要为局部界面能力更换整个运行时。

产品形式值得学习的五点

以下是本文的产品分析，并非 HeroUI 的收入、留存或性能结论。

第一，设计资产被延伸成运行时服务。 组件包主要帮助团队在开发时做选择，Agents 则根据用户请求选择呈现方式。相同的设计经验可以用于两种交付，运行时产品还要承担延迟、错误、用量和持续可用性。其运行成本与组件的永久许可需要分别评估。

第二，接到客户已有的业务系统。 Client Tools 连接既有页面状态和 API，团队可以先挑一个场景增加助手入口，不必先重建应用。但价值取决于工具是否贴近任务：只有几个泛化查询工具，很难完成跨记录和多步修改。

第三，成品目录与控制台一起降低接入工作量。 Catalog 负责默认表达，Dashboard 负责配置与观察。把两者组合，交付才从“你可以开发一个助手”变成“这里有一个可以持续运营的助手”。取舍是客户接受供应商的界面结构和升级节奏。

第四，Coding Agent 成为接入渠道。 Copy Prompt、公共 Skill 和管理 MCP 把产品接入变成可被 Coding Agent 执行的任务。这能减少查文档和手写胶水代码的工作；权限选择、业务设计和验收仍需要负责的人。

第五，持续价值要落到任务结果上。 精致图表能帮助试用，但生产采用还要回答：这个入口是否更容易找到数据、减少重复操作、可靠地完成业务动作？Tambo 退出托管服务说明关注与试用不自动转成足够采用，不能据此断言 Generative UI 整个方向没有市场。Tambo 官方经营说明

最合理的价值测量单位，应围绕完成了什么任务，而不是只看生成了多少条消息或组件。定价最终采用何种单位，HeroUI 的公开 beta 材料尚未确认。

当前限制、文档差异与待确认事项

以上分别来自 Agents FAQ、Appearance、Custom Components、Identifying users、Terms 与 Privacy。主题加载有同页冲突，语言支持有不同口径；高级外观权益与身份关联则需要分清适用范围。资料存在差异，不等于已经确认产品故障。

另外，当前 API rate limits 是每 key 120 requests/min、每 Agent 600 requests/min。这是 API 速率限制，不能当作聊天并发数、模型吞吐承诺或免费额度。Usage limits

如何判断是否值得采用

建议从一个频繁、数据结构明确的任务开始，例如“查询并比较订单，然后打开对应详情”。先做读取与导航，再增加经过确认的写入。用下列小范围试验取得决定性证据，而不是只观看演示。

这些是建议的采用标准，本次没有通过真实 beta 实测。申请试用前，还应确认对话导出和删除、服务停用后的迁移、地区与子处理者、可用性承诺、正式计费及模型成本。

当前判断：适合把它作为“完整应用内助手”的候选，特别是业务 API 已清楚、希望减少 Agent 后端与 UI 组装工作、能接受托管 Catalog 的团队。 如果硬性要求自建运行时、复用任意自有组件或采用开放 UI 协议，应优先比较保留这些控制权的路线。HeroUI Agents 的优势主张足够具体；是否形成生产优势，还取决于真实任务验证和正式服务条件。

关联阅读

• Agent 栏目：Agent、工具和产品研究的主题导航。
• kapa.ai：文档导入、Retrieval 与 Blog 接入流程：知识检索层与嵌入助手的边界。
• React Native UI 方案横评：HeroUI Native、Paper、Tamagui 与 gluestack-ui：HeroUI 的移动组件层，与 Hosted Agent 属于不同交付范围。