Persona.js

Persona：打造 WebMCP 原生 AI 智能体 UI 体验的轻量级 VanillaJS 库

在当前 AI 驱动的应用浪潮中，为用户提供流畅、智能且高度集成的交互界面至关重要。Persona 正是为此而生的 Agent UI 库。它由 Runtype 开发，旨在帮助开发者在 Web 端创建纯 JavaScript 构建的智能体前端体验。作为一款 WebMCP 原生 的工具，Persona 不仅轻量且具有极强的扩展性，能够无缝融入任何技术栈。

什么是 Persona (What's Persona)

Persona 是一个专为 Web 打造的 VanillaJS Agent UI 库。它不仅是一个聊天窗口，更是一个能够深度集成到网页逻辑中的智能体交互框架。Persona 的核心理念是“轻量级”与“原生支持”，它不依赖于特定的重型框架，开发者可以使用纯 JS 实现复杂的智能体交互逻辑。

Persona 基于 WebMCP（Model Context Protocol for Web）协议，这意味着它能够发现并直接驱动页面上的工具（如搜索、购物车、预订表单等）。通过 Persona，您可以将 AI 智能体转变为一个真正能够操作您应用的“智能副驾驶”，而不仅仅是一个只会对话的窗口。

Persona 的核心特性 (Features)

Persona 具备多项专为现代 Web 智能体设计的先进特性，确保了其在不同场景下的高性能表现：

1. WebMCP 原生集成 (Agentic)

Persona 能够直接操作您的应用。通过 WebMCP 标准，Persona 可以识别并暴露页面动作（如搜索、表单提交等）作为智能体工具。智能体可以直接驱动这些功能，并内置了用户确认环节，确保安全可控。最重要的是，这一切都无需后端集成，直接在前端即可完成。

2. 完美的样式隔离 (Isolation)

担心 UI 库会破坏您现有的网页样式？Persona 采用了 Shadow DOM 渲染技术，并对 CSS 进行了前缀处理。这保证了 Persona 组件与宿主页面的样式完全隔离。您可以将其放入任何页面，既不会影响页面原有样式，也不会被页面样式干扰。

3. 多样化的布局模式 (Layouts)

Persona 提供了三种开箱即用的布局，只需简单的配置即可切换：

• FLOATING (浮动模式)：在角落显示的启动器，适合客服、文档、销售或新手引导场景。
• DOCKED (停靠模式)：侧边栏形式，作为一个“Copilot”常驻在应用旁边。
• FULLSCREEN (全屏模式)：提供沉浸式的全屏助手体验。

4. 强大的流式传输支持 (Transport)

Persona 支持基于 SSE (Server-Sent Events) 的流式传输，并配有可插拔的解析器。无论您使用何种后端（如 Vercel AI SDK、OpenAI Agents、LangGraph.js 等），都可以通过 customFetch 和 parseSSEEvent 轻松对接。

5. 灵活的主题定制 (Theming)

Persona 提供了一个三层令牌树（Token Tree）系统：调色板、语义化、组件化。它支持暗黑模式，并提供实时主题编辑器（Theme Editor），无需 Fork 代码即可让 UI 完全契合您的品牌视觉。

如何使用 Persona (How to Use)

Persona 的集成非常简单，您可以选择通过 NPM 安装或直接引用脚本标签。

安装方式

使用 NPM 安装：

npm install @runtypelabs/persona

快速初始化代码示例

以浮动挂件（Widget）为例，您只需几行代码即可启动：

import "@runtypelabs/persona/widget.css";
import { initAgentWidget } from "@runtypelabs/persona";

initAgentWidget({
  target: "#chat",
  config: {
    apiUrl: "https://your-api.com/chat",
    // 默认为浮动启动器布局
  },
});

注册 WebMCP 工具

为了让智能体能够使用您页面的功能，您可以在页面代码中注册工具：

document.modelContext.registerTool({
  name: "search_products",
  description: "搜索产品目录",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" },
    },
    required: ["query"],
  },
  async execute({ query }) {
    return searchCatalog(query);
  },
});

Persona 会自动发现这些工具，并在需要时通过对话界面提示用户调用。

Persona 的应用场景 (Use Case)

Persona 广泛的适应性使其能够胜任多种业务场景，官方提供了丰富的 Demo 参考：

• 电商助手 (WebMCP Storefront)：智能体可以搜索商品、管理购物车并引导结账。
• 日程管理 (WebMCP Calendar)：通过自然语言直接进行预订和日程查询。
• 演示文稿 (WebMCP Slides)：使用智能体控制幻灯片的播放和内容调整。
• 内容交互：如 Bakery Assistant（烘焙助手）或 Docs Agent，为用户提供即时的文档查阅和业务咨询。
• 高级交互体验：包括语音集成、Artifact 侧边栏、流式动画以及动态组件展示。

常见问题解答 (FAQ)

Q: Persona 是否支持所有后端？

A: 是的。Persona 支持任何 SSE 后端。它为 Vercel AI SDK、OpenAI Agents、LangGraph.js、Hono、Express、SvelteKit 等提供了预构建的示例和适配方案。

Q: 引入 Persona 会影响我的网站加载速度吗？

A: 不会。Persona 是基于 VanillaJS 构建的轻量级库，体积非常小，且不依赖大型框架，能够确保高性能的加载体验。

Q: 如何自定义 UI 样式？

A: 您可以使用内置的主题编辑器或通过三层 Token 系统自定义颜色和组件样式。由于使用了 Shadow DOM，您的样式定义将非常精准，不会发生冲突。

Q: Persona 的授权协议是什么？

A: Persona 采用 MIT 开源协议，由 Runtype 团队维护并支持开发者社区进行扩展。

Persona 不仅仅是一个 UI，它是 Web 智能体的未来入口。通过将 WebMCP 与轻量级的 VanillaJS 相结合，它为开发者提供了一个快速、稳健且极其灵活的工具集，用于构建下一代智能网页应用。