Renderer 将其转换为真正的 React UI。
此集成非常适合数据丰富的输出,如报告、仪表板和数据浏览器,其中模型既是数据分析师又是 UI 设计师。
工作原理
- 生成系统提示: 在启动时调用一次
openuiLibrary.prompt();它生成完整的 openui-lang 参考,模型使用它来编写有效的组件树 - 在第一条消息时注入: 当新对话开始时将系统提示作为开场系统消息发送
- 模型编写 openui-lang: 模型用像
root = Stack([header, kpis, chart])这样的程序来响应,而不是散文 - 使用
Renderer渲染: 将文本传递给 OpenUI 的Renderer和组件库;它解析并渲染树
安装
npm install @langchain/react @openuidev/react-ui @openuidev/react-headless @openuidev/react-lang
OpenUI 需要 React 19+ 和
zustand。前端代码仅适用于 React;LangGraph 代理后端可以用 TypeScript 或 Python 编写。导入组件样式
在您的 CSS 入口点或直接在根组件中导入 OpenUI 的捆绑样式:@import "@openuidev/react-ui/components.css";
@import "@openuidev/react-ui/styles/index.css";
生成系统提示
OpenUI 提供了一个openuiLibrary.prompt() 函数,生成完整的 openui-lang 参考,包括所有组件签名、语法规则、流式传输提示和示例。在模块加载时调用一次:
import { openuiLibrary, openuiPromptOptions } from "@openuidev/react-ui/genui-lib";
// Generate the full openui-lang system prompt. Call this once at startup,
// not inside a component, to avoid recomputing it on every render.
const SYSTEM_PROMPT = openuiLibrary.prompt({
...openuiPromptOptions,
preamble:
"You are a report generator. When asked for a report, produce a detailed, " +
"data-rich report using openui-lang: executive summary, KPI cards, charts, " +
"tables, and multiple sections. Your ENTIRE response must be raw openui-lang " +
"— no code fences, no markdown, no prose.",
});
preamble 覆盖默认角色。添加 additionalRules 以注入特定于任务的约束:
const SYSTEM_PROMPT = openuiLibrary.prompt({
...openuiPromptOptions,
preamble: "You are a report generator...",
additionalRules: [
...(openuiPromptOptions.additionalRules ?? []),
"Always end the report with 3–4 follow-up query buttons using " +
"Button({ type: 'continue_conversation' }, 'secondary') inside a " +
"Card([CardHeader('Explore Further'), Buttons([...])], 'sunk').",
],
});
通过 useStream 注入系统提示
将系统提示作为每个新线程的第一条消息发送。检查stream.messages.length === 0 以检测新线程并添加 system 消息:
import { useCallback } from "react";
import { useStream } from "@langchain/react";
const SYSTEM_PROMPT = openuiLibrary.prompt({ ... });
export function App() {
const stream = useStream({
apiUrl: import.meta.env.VITE_LANGGRAPH_API_URL ?? "/api/langgraph",
assistantId: "my_agent",
reconnectOnMount: true,
fetchStateHistory: true,
});
const handleSubmit = useCallback(
(text: string) => {
// Inject the system prompt only on the first message of a new thread.
// Subsequent messages already have it in their persisted history.
const isNewThread = stream.messages.length === 0;
stream.submit({
messages: [
...(isNewThread
? [{ type: "system", content: SYSTEM_PROMPT }]
: []),
{ type: "human", content: text },
],
});
},
[stream],
);
// ...
}
使用 Renderer 渲染
将 AI 消息的文本内容连同openuiLibrary 直接传递给 Renderer:
import { Renderer } from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
import { AIMessage } from "langchain";
function MessageList({ messages, isLoading }) {
const lastAiIdx = messages.reduce(
(acc, msg, i) => (AIMessage.isInstance(msg) ? i : acc),
-1,
);
return messages.map((msg, i) => {
if (AIMessage.isInstance(msg)) {
const text = typeof msg.content === "string" ? msg.content : "";
return (
<Renderer
key={msg.id ?? i}
response={text}
library={openuiLibrary}
isStreaming={isLoading && i === lastAiIdx}
/>
);
}
// ... human message bubble
});
}
isStreaming={true},以便 Renderer 在定义到达时优雅地处理未解析的引用。
openui-lang 格式
模型编写的是程序而不是 JSON 规范。每个语句都是赋值;root 是入口点。官方提示教模型这种格式,包括提升——首先编写 root,以便 UI shell 立即出现:
root = Stack([header, execSummary, kpis, marketSection])
header = CardHeader("State of AI in 2025", "Comprehensive Analysis")
execSummary = MarkDownRenderer("## Executive Summary\n\nThe AI market reached...")
kpi1 = Card([CardHeader("$826B", "Global Market"), TextContent("42% YoY", "small")], "sunk")
kpi2 = Card([CardHeader("78%", "Adoption"), TextContent("Fortune 500", "small")], "sunk")
kpis = Stack([kpi1, kpi2], "row", "m", "stretch", "start", true)
col1 = Col("Segment", "string")
col2 = Col("Revenue ($B)", "number")
tbl = Table([col1, col2], [["Generative AI", 286], ["ML Infra", 198]])
s1 = Series("Revenue", [286, 198, 147])
ch1 = BarChart(["Gen AI", "ML Infra", "Vision"], [s1])
marketSection = Card([CardHeader("Market Breakdown"), tbl, ch1])
root 行,以便页面结构立即出现,每个部分在模型定义时逐步填充。
渐进式渲染工具
将useStream 直接连接到 Renderer 会导致在每个流式令牌时重新渲染,并产生数百次每个响应的无操作重新解析。这会导致图表组件在其数据尚未到达时崩溃。以下工具解决了这些问题:
| 问题 | 解决方案 |
|---|---|
| 部分字符串字面量 | truncateAtOpenString / closeOrTruncateOpenString — 在解析前删除或关闭不完整的字符串 |
| 中间令牌抖动 | useStableText — 在完整的语句边界(name = Expr(...))而非每个令牌时控制 Renderer 更新 |
| 图表空数据崩溃 | chartDataRefsResolved — 在将图表包含在快照之前验证其 Series 和标签数组是否已定义 |
还没有 root / 回退 | buildProgressiveRoot — 当模型尚未编写时,从顶级变量合成 root = Stack([...]) |
| Snake_case 标识符 | sanitizeIdentifiers — 解析器只接受 camelCase;转换模型发出的任何 snake_case 名称 |
stable 传递给 <Renderer>:
import {
useCallback,
useEffect,
useMemo,
useRef,
useState,
} from "react";
import {
type ActionEvent,
BuiltinActionType,
Renderer,
} from "@openuidev/react-lang";
import { openuiLibrary } from "@openuidev/react-ui/genui-lib";
/** Strip any markdown code fence the model may have emitted. */
function stripCodeFence(text: string): string {
return text
.replace(/^```[a-z]*\r?\n?/i, "")
.replace(/\n?```\s*$/i, "")
.trim();
}
/**
* The openui-lang parser only accepts camelCase identifiers.
* Convert any snake_case variable names the model emits; string content is untouched.
*/
function sanitizeIdentifiers(text: string): string {
const toCamel = (s: string) =>
s.replace(/_([a-zA-Z0-9])/g, (_, c: string) => c.toUpperCase());
const snakeVars: string[] = [];
for (const m of text.matchAll(/^([a-zA-Z][a-zA-Z0-9]*(?:_[a-zA-Z0-9]+)+)\s*=/gm)) {
if (!snakeVars.includes(m[1])) snakeVars.push(m[1]);
}
if (snakeVars.length === 0) return text;
let result = "";
let inStr = false;
let i = 0;
while (i < text.length) {
if (text[i] === "\\" && inStr) { result += text[i] + (text[i + 1] ?? ""); i += 2; continue; }
if (text[i] === '"') { inStr = !inStr; result += text[i++]; continue; }
if (!inStr) {
let replaced = false;
for (const v of snakeVars) {
if (text.startsWith(v, i) && !/[a-zA-Z0-9_]/.test(text[i + v.length] ?? "")) {
result += toCamel(v); i += v.length; replaced = true; break;
}
}
if (!replaced) result += text[i++];
} else {
result += text[i++];
}
}
return result;
}
/**
* Walk the text tracking open strings. If the text ends mid-string, truncate to
* the last safe newline — this prevents a partial string literal from consuming
* any `root = Stack(…)` line we synthesise later.
*/
function truncateAtOpenString(text: string): string {
let inStr = false;
let lastSafeNewline = 0;
for (let i = 0; i < text.length; i++) {
const ch = text[i];
if (ch === "\\" && inStr) { i++; continue; }
if (ch === '"') { inStr = !inStr; continue; }
if (ch === "\n" && !inStr) lastSafeNewline = i;
}
return inStr ? text.slice(0, lastSafeNewline) : text;
}
/**
* Like truncateAtOpenString, but synthesises a closing `")` when the partial
* line is a TextContent statement. This lets text render token-by-token while
* all other partial-string lines are still truncated.
*/
function closeOrTruncateOpenString(text: string): string {
let inStr = false;
let lastSafeNewline = 0;
for (let i = 0; i < text.length; i++) {
const ch = text[i];
if (ch === "\\" && inStr) { i++; continue; }
if (ch === '"') { inStr = !inStr; continue; }
if (ch === "\n" && !inStr) lastSafeNewline = i;
}
if (!inStr) return text;
const safeText = lastSafeNewline > 0 ? text.slice(0, lastSafeNewline) : "";
const partialLine = text.slice(lastSafeNewline > 0 ? lastSafeNewline + 1 : 0);
if (/^[a-zA-Z][a-zA-Z0-9]*\s*=\s*TextContent\(/.test(partialLine)) {
return (lastSafeNewline > 0 ? safeText + "\n" : "") + partialLine + '")';
}
return safeText;
}
/** Count lines that form a complete assignment ending with `)` or `]`. */
function countCompleteStatements(text: string): number {
let count = 0;
for (const line of text.split("\n")) {
const t = line.trimEnd();
if ((t.endsWith(")") || t.endsWith("]")) && /^[a-zA-Z]/.test(t)) count++;
}
return count;
}
const CHART_TYPES = new Set([
"BarChart", "LineChart", "AreaChart", "RadarChart",
"HorizontalBarChart", "PieChart", "RadialChart",
"SingleStackedBarChart", "ScatterChart",
]);
const OPENUI_KEYWORDS = new Set([
"true", "false", "null", "grouped", "stacked", "linear", "natural", "step",
"pie", "donut", "string", "number", "action", "row", "column", "card", "sunk",
"clear", "info", "warning", "error", "success", "neutral", "danger", "start",
"end", "center", "between", "around", "evenly", "stretch", "baseline",
"small", "default", "large", "none", "xs", "s", "m", "l", "xl",
"horizontal", "vertical",
]);
/**
* Chart components (recharts) crash with `.map() on null` when their labels or
* series props are unresolved. Before committing a stable snapshot, verify that
* every chart in the text has all its data variables already defined.
*/
function chartDataRefsResolved(text: string): boolean {
const lines = text.split("\n");
const complete = new Set<string>();
for (const line of lines) {
const t = line.trimEnd();
const m = t.match(/^([a-zA-Z][a-zA-Z0-9]*)\s*=/);
if (m && (t.endsWith(")") || t.endsWith("]"))) complete.add(m[1]);
}
for (const line of lines) {
const t = line.trimEnd();
const m = t.match(/^([a-zA-Z][a-zA-Z0-9]*)\s*=\s*([A-Z][a-zA-Z0-9]*)\(/);
if (!m || !CHART_TYPES.has(m[2]) || !t.endsWith(")")) continue;
const rhs = t.slice(t.indexOf("=") + 1).replace(/"(?:[^"\\]|\\.)*"/g, '""');
for (const [, name] of rhs.matchAll(/\b([a-zA-Z][a-zA-Z0-9]*)\b/g)) {
if (/^[a-z]/.test(name) && !OPENUI_KEYWORDS.has(name) && !complete.has(name))
return false;
}
}
return true;
}
/**
* If the model hasn't written a `root = Stack(…)` yet, synthesise one from the
* top-level variables (those defined but not referenced inside any other expression).
* This enables progressive rendering even when the model writes root last.
*/
function buildProgressiveRoot(text: string): string {
if (!text) return text;
const safe = truncateAtOpenString(text);
if (/^root\s*=/m.test(safe)) return safe;
const defs: string[] = [];
const seen = new Set<string>();
for (const m of safe.matchAll(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=/gm)) {
if (!seen.has(m[1])) { defs.push(m[1]); seen.add(m[1]); }
}
if (defs.length === 0) return safe;
const referenced = new Set<string>();
for (const line of safe.split("\n")) {
const thisVar = line.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\s*=/)?.[1];
const stripped = line.replace(/"(?:[^"\\]|\\.)*"/g, '""');
for (const v of defs) {
if (v !== thisVar && new RegExp(`\\b${v}\\b`).test(stripped)) referenced.add(v);
}
}
const topLevel = defs.filter((v) => !referenced.has(v));
const rootVars = topLevel.length > 0 ? topLevel : defs;
return `${safe.trimEnd()}\nroot = Stack([${rootVars.join(", ")}], "column", "l")`;
}
/**
* Gate Renderer updates to moments when at least one new *complete* statement
* has arrived. This eliminates hundreds of no-op re-parses during streaming.
*
* Special case: TextContent lines update token-by-token (via closeOrTruncate)
* so text renders progressively without waiting for the full line to complete.
*/
function useStableText(raw: string, isStreaming: boolean): string {
const [stable, setStable] = useState<string>("");
const lastCount = useRef(0);
useEffect(() => {
const safe = truncateAtOpenString(raw); // strict — for counting only
const enhanced = closeOrTruncateOpenString(raw); // display — closes partial TextContent
if (!isStreaming) { setStable(enhanced); return; }
const count = countCompleteStatements(safe);
const newComplete = count > lastCount.current && chartDataRefsResolved(safe);
const partialTextContent = enhanced !== safe;
if (newComplete || partialTextContent) {
if (newComplete) lastCount.current = count;
setStable(enhanced);
}
}, [raw, isStreaming]);
return stable;
}
function AIMessageView({
raw,
isStreaming,
onSubmit,
}: {
raw: string;
isStreaming: boolean;
onSubmit: (text: string) => void;
}) {
const stable = useStableText(raw, isStreaming);
const processed = useMemo(() => buildProgressiveRoot(stable), [stable]);
const handleAction = useCallback(
(event: ActionEvent) => {
if (event.type === BuiltinActionType.ContinueConversation) {
onSubmit(event.humanFriendlyMessage);
}
},
[onSubmit],
);
if (!processed) return null;
return (
<Renderer
response={processed}
library={openuiLibrary}
isStreaming={isStreaming}
onAction={handleAction}
/>
);
}
export function MessageList({ messages, isLoading, onSubmit }) {
const lastAiIdx = messages.reduce(
(acc, msg, i) => (msg.getType() === "ai" ? i : acc),
-1,
);
return messages.map((msg, i) => {
if (msg.getType() === "human") {
return (
<div key={msg.id ?? i} className="flex justify-end">
<div className="user-bubble">
{typeof msg.content === "string" ? msg.content : ""}
</div>
</div>
);
}
if (msg.getType() === "ai") {
const raw = sanitizeIdentifiers(
stripCodeFence(typeof msg.content === "string" ? msg.content : ""),
);
if (!raw) return null;
return (
<div key={msg.id ?? i}>
<AIMessageView
raw={raw}
isStreaming={isLoading && i === lastAiIdx}
onSubmit={onSubmit}
/>
</div>
);
}
return null;
});
}
后续查询
OpenUI 的Button 组件支持 continue_conversation 操作类型。当用户点击后续按钮时,Renderer 触发 onAction,上面的 AIMessageView 将按钮的标签作为下一条用户消息提交,与在输入框中输入的代码路径完全相同。
通过系统提示中的 additionalRules 为每个报告添加”进一步探索”部分:
followUp1 = Button("Compare AI leaders 2024 vs 2025", { type: "continue_conversation" }, "secondary")
followUp2 = Button("Global AI investment breakdown", { type: "continue_conversation" }, "secondary")
followUpBtns = Buttons([followUp1, followUp2], "row")
followUpCard = Card([CardHeader("Explore Further"), followUpBtns], "sunk")
root = Stack([..., followUpCard])
最佳实践
- 在模块加载时生成系统提示: 不要放在 React 组件内部;提示有几 KB,应该只计算一次
- 仅在新线程时注入系统提示: 检查
stream.messages.length === 0,并在后续轮次跳过注入以避免在线程历史中重复提示 - 使用提升顺序: 首先编写
root = Stack([...]);UI shell 立即出现,部分在模型定义每个部分时逐步填充 - 在完整语句时控制更新: 避免在每个令牌时重新渲染 Renderer;仅在完整的语句(
name = ComponentCall(...))到达时更新 - 在渲染前验证图表数据: 图表组件需要其
Series和标签数组在包含在稳定快照之前定义 - 保持 camelCase 变量名: openui-lang 解析器只接受 camelCase 标识符;在系统提示的
additionalRules中强化这一点

