Skip to content

docs(a2ui): add system prompts guides #2782

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
PupilTong merged 1 commit into from
Jun 3, 2026
Merged

docs(a2ui): add system prompts guides #2782

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 7 additions & 6 deletions packages/genui/a2ui/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,12 +86,12 @@ generated UI actions through `onAction`.

## What You Own

| Part | Owner | Role |
| ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `@lynx-js/genui/a2ui` | This package | ReactLynx renderer, `MessageStore`, catalog APIs, built-in components, protocol helpers, and client function entries. |
| `genui a2ui` | GenUI CLI | Build-time commands for generating custom catalog artifacts and A2UI system prompts. |
| Your Agent service | Your application | Receives user prompts/actions, calls a model with the A2UI prompt and catalog, validates output, and returns messages. |
| Your transport adapter | Your application | Calls the Agent service, handles REST or streaming responses, writes messages into `MessageStore`, and forwards actions. |
| Part | Owner | Role |
| ------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `@lynx-js/genui/a2ui` | This package | ReactLynx renderer, `MessageStore`, catalog APIs, built-in components, protocol helpers, and client function entries. |
| `npx @lynx-js/genui a2ui` | GenUI CLI | Build-time commands for generating custom catalog artifacts and A2UI system prompts. |
| Your Agent service | Your application | Receives user prompts/actions, calls a model with the A2UI prompt and catalog, validates output, and returns messages. |
| Your transport adapter | Your application | Calls the Agent service, handles REST or streaming responses, writes messages into `MessageStore`, and forwards actions. |

## First Things To Know

Expand All @@ -109,4 +109,5 @@ generated UI actions through `onAction`.

- [Overview and architecture](./docs/overview.md)
- [Catalogs, built-ins, and custom components](./docs/catalog-guide.md)
- [System prompts](./docs/system-prompts.md)
- [Open the A2UI playground](https://lynxjs.org/a2ui)
13 changes: 7 additions & 6 deletions packages/genui/a2ui/README_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,12 +78,12 @@ async function sendPrompt(input: string) {

## 你需要负责什么

| 部分 | 负责人 | 作用 |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `@lynx-js/genui/a2ui` | 这个包 | ReactLynx renderer、`MessageStore`、Catalog API、内置组件、协议辅助能力，以及 client function entries。 |
| `genui a2ui` | GenUI CLI | 构建期命令，用来生成自定义 catalog artifacts 和 A2UI system prompts。 |
| 你的 Agent 服务 | 你的应用 | 接收用户 prompt/action，带着 A2UI prompt 和 catalog 调用模型，校验输出，然后返回 messages。 |
| 你的 transport adapter | 你的应用 | 调用 Agent 服务，处理 REST 或流式响应，把 messages 写入 `MessageStore`，并转发 generated UI actions。 |
| 部分 | 负责人 | 作用 |
| ------------------------- | --------- | ------------------------------------------------------------------------------------------------------- |
| `@lynx-js/genui/a2ui` | 这个包 | ReactLynx renderer、`MessageStore`、Catalog API、内置组件、协议辅助能力，以及 client function entries。 |
| `npx @lynx-js/genui a2ui` | GenUI CLI | 构建期命令，用来生成自定义 catalog artifacts 和 A2UI system prompts。 |
| 你的 Agent 服务 | 你的应用 | 接收用户 prompt/action，带着 A2UI prompt 和 catalog 调用模型，校验输出，然后返回 messages。 |
| 你的 transport adapter | 你的应用 | 调用 Agent 服务，处理 REST 或流式响应，把 messages 写入 `MessageStore`，并转发 generated UI actions。 |

## 首次接入要知道

Expand All @@ -99,4 +99,5 @@ async function sendPrompt(input: string) {

- [概览与架构](./docs/overview_zh.md)
- [Catalogs、内置组件与自定义组件](./docs/catalog-guide_zh.md)
- [System Prompts](./docs/system-prompts_zh.md)
- [打开 A2UI Playground](https://lynxjs.org/a2ui)
6 changes: 4 additions & 2 deletions packages/genui/a2ui/docs/catalog-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,7 +346,7 @@ and pair it the same way you would a built-in.
2. Run the public CLI to emit the JSON:

```bash
genui a2ui generate catalog --catalog-dir src/catalog --out-dir dist/catalog
npx @lynx-js/genui a2ui generate catalog --catalog-dir src/catalog --out-dir dist/catalog
```

3. Pair the generated JSON with the component:
Expand All @@ -358,7 +358,7 @@ and pair it the same way you would a built-in.
const catalog = defineCatalog([[MyChart, myChartManifest]]);
```

`genui a2ui generate catalog` is the user-facing command;
`npx @lynx-js/genui a2ui generate catalog` is the user-facing command;
`@lynx-js/genui/a2ui-catalog-extractor` is the TypeDoc-powered engine behind
it. Two constraints to keep extraction happy: the component folder name must
match the exported function name (`src/catalog/MyChart/index.tsx` exports
Expand Down Expand Up @@ -396,4 +396,6 @@ All of these are exported from `@lynx-js/genui/a2ui` (and from the

- [Overview and architecture](./overview.md) — how a message becomes UI, the
responsibility split, and the export map.
- [System prompts](./system-prompts.md) — generate the model instructions
that pair an Agent with your catalog.
- [Open the A2UI playground](https://lynxjs.org/a2ui) — try it live.
5 changes: 3 additions & 2 deletions packages/genui/a2ui/docs/catalog-guide_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -326,7 +326,7 @@ MyChart.displayName = 'MyChart';
2. 运行公开 CLI 输出 JSON：

```bash
genui a2ui generate catalog --catalog-dir src/catalog --out-dir dist/catalog
npx @lynx-js/genui a2ui generate catalog --catalog-dir src/catalog --out-dir dist/catalog
```

3. 把生成的 JSON 与组件配对：
Expand All @@ -338,7 +338,7 @@ MyChart.displayName = 'MyChart';
const catalog = defineCatalog([[MyChart, myChartManifest]]);
```

`genui a2ui generate catalog` 是面向用户的命令；
`npx @lynx-js/genui a2ui generate catalog` 是面向用户的命令；
`@lynx-js/genui/a2ui-catalog-extractor` 是它背后由 TypeDoc 驱动的引擎。两条约束
能让抽取顺利进行：组件文件夹名必须与导出的 function 名一致
（`src/catalog/MyChart/index.tsx` 导出 `function MyChart`），并且框架级 props
Expand Down Expand Up @@ -369,4 +369,5 @@ MyChart.displayName = 'MyChart';

- [概览与架构](./overview_zh.md)——一条 message 如何变成 UI、职责划分，以及
export 映射。
- [System Prompts](./system-prompts_zh.md)——生成让 Agent 与你的 catalog 配套的模型指令。
- [打开 A2UI playground](https://lynxjs.org/a2ui)——在线体验。
20 changes: 11 additions & 9 deletions packages/genui/a2ui/docs/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,15 +147,15 @@ The package draws a hard line between what it provides and what your
application provides. Keeping that line crisp is the reason the runtime
stays transport-agnostic and the catalog stays explicit.

| Piece | Runs in | Owner | Responsibility |
| ----------------- | ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent service | Server | Your application | Turns prompts and client actions into validated A2UI message arrays. Prompts the model with the same catalog contract the client renders. |
| Transport adapter | Client shell | Your application | Sends prompts/actions to the Agent over REST/SSE/WebSocket, then writes the returned messages into a `MessageStore`. |
| `MessageStore` | Client | This package | Stores raw A2UI messages in arrival order and notifies subscribers. It does not parse or interpret the protocol. |
| `<A2UI>` | Client | This package | Owns a `MessageProcessor` per mount, consumes new messages, renders the active surface, and forwards generated UI actions through `onAction`. |
| Catalog API | Client + Agent handshake | This package | Maps protocol component/function names to local implementations and optional JSON schemas. Compose it with `defineCatalog` and friends. |
| Built-ins | Client | This package | A2UI v0.9 basic-catalog component renderers, per-component JSON-Schema manifests, and client-side basic-catalog function implementations. |
| `genui a2ui` | Build / setup time | GenUI CLI | Generates custom catalog artifacts and A2UI system prompts. Not required when both Agent and renderer use the built-in basic catalog. |
| Piece | Runs in | Owner | Responsibility |
| ------------------------- | ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent service | Server | Your application | Turns prompts and client actions into validated A2UI message arrays. Prompts the model with the same catalog contract the client renders. |
| Transport adapter | Client shell | Your application | Sends prompts/actions to the Agent over REST/SSE/WebSocket, then writes the returned messages into a `MessageStore`. |
| `MessageStore` | Client | This package | Stores raw A2UI messages in arrival order and notifies subscribers. It does not parse or interpret the protocol. |
| `<A2UI>` | Client | This package | Owns a `MessageProcessor` per mount, consumes new messages, renders the active surface, and forwards generated UI actions through `onAction`. |
| Catalog API | Client + Agent handshake | This package | Maps protocol component/function names to local implementations and optional JSON schemas. Compose it with `defineCatalog` and friends. |
| Built-ins | Client | This package | A2UI v0.9 basic-catalog component renderers, per-component JSON-Schema manifests, and client-side basic-catalog function implementations. |
| `npx @lynx-js/genui a2ui` | Build / setup time | GenUI CLI | Generates custom catalog artifacts and A2UI system prompts. Not required when both Agent and renderer use the built-in basic catalog. |

A useful way to remember it: **the server decides, the client renders, and
the catalog is the contract they agree on.** The catalog is the one piece
Expand Down Expand Up @@ -307,4 +307,6 @@ Lifecycle notes that save debugging time:

- [Catalogs, built-ins, and custom components](./catalog-guide.md) — compose
the contract, add manifests, and register your own components.
- [System prompts](./system-prompts.md) — generate the model instructions
that pair an Agent with your catalog.
- [Open the A2UI playground](https://lynxjs.org/a2ui) — try it live.
19 changes: 10 additions & 9 deletions packages/genui/a2ui/docs/overview_zh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,15 +140,15 @@ SSE、WebSocket，或一个 in-process mock。renderer 不关心 messages 是怎
这个包在「它提供什么」和「你的应用提供什么」之间划了一条硬边界。保持这条边界
清晰，正是运行时保持传输无关、catalog 保持显式的原因。

| 部分 | 运行位置 | 负责人 | 职责 |
| ----------------- | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| Agent 服务 | Server | 你的应用 | 把 prompt 和 client action 转成经过校验的 A2UI message 数组。使用与 client 可渲染能力一致的 catalog contract 提示模型。 |
| Transport adapter | Client shell | 你的应用 | 通过 REST/SSE/WebSocket 把 prompt/action 发给 Agent，再把返回的 messages 写入 `MessageStore`。 |
| `MessageStore` | Client | 这个包 | 按到达顺序保存原始 A2UI messages 并通知订阅者。它不解析也不解释协议语义。 |
| `<A2UI>` | Client | 这个包 | 每次 mount 拥有一个 `MessageProcessor`，消费新 messages，渲染 active surface，并通过 `onAction` 转发 generated UI action。 |
| Catalog API | Client + Agent handshake | 这个包 | 把协议中的 component/function 名称映射到本地实现和可选 JSON schema。用 `defineCatalog` 等组合它。 |
| 内置能力 | Client | 这个包 | A2UI v0.9 basic-catalog 的组件 renderer、逐组件 JSON-Schema manifest，以及客户端 basic-catalog function 实现。 |
| `genui a2ui` | 构建 / 接入阶段 | GenUI CLI | 生成自定义 catalog artifacts 和 A2UI system prompt。当 Agent 和 renderer 都用内置 basic catalog 时不需要它。 |
| 部分 | 运行位置 | 负责人 | 职责 |
| ------------------------- | ------------------------ | --------- | -------------------------------------------------------------------------------------------------------------------------- |
| Agent 服务 | Server | 你的应用 | 把 prompt 和 client action 转成经过校验的 A2UI message 数组。使用与 client 可渲染能力一致的 catalog contract 提示模型。 |
| Transport adapter | Client shell | 你的应用 | 通过 REST/SSE/WebSocket 把 prompt/action 发给 Agent，再把返回的 messages 写入 `MessageStore`。 |
| `MessageStore` | Client | 这个包 | 按到达顺序保存原始 A2UI messages 并通知订阅者。它不解析也不解释协议语义。 |
| `<A2UI>` | Client | 这个包 | 每次 mount 拥有一个 `MessageProcessor`，消费新 messages，渲染 active surface，并通过 `onAction` 转发 generated UI action。 |
| Catalog API | Client + Agent handshake | 这个包 | 把协议中的 component/function 名称映射到本地实现和可选 JSON schema。用 `defineCatalog` 等组合它。 |
| 内置能力 | Client | 这个包 | A2UI v0.9 basic-catalog 的组件 renderer、逐组件 JSON-Schema manifest，以及客户端 basic-catalog function 实现。 |
| `npx @lynx-js/genui a2ui` | 构建 / 接入阶段 | GenUI CLI | 生成自定义 catalog artifacts 和 A2UI system prompt。当 Agent 和 renderer 都用内置 basic catalog 时不需要它。 |

一个好记的方式：**server 决策，client 渲染，catalog 是两边达成一致的
contract。** catalog 是唯一同时活在 wire 两侧的部分——你的 client 注册实现，
Expand Down Expand Up @@ -285,4 +285,5 @@ MessageStore ──subscribe──► <A2UI> ──► MessageProcessor ──

- [Catalogs、内置组件与自定义组件](./catalog-guide_zh.md)——组合 contract、加入
manifest、注册你自己的组件。
- [System Prompts](./system-prompts_zh.md)——生成让 Agent 与你的 catalog 配套的模型指令。
- [打开 A2UI playground](https://lynxjs.org/a2ui)——在线体验。
Loading
Loading