# a2ui: Tạo giao diện động bằng AI — hướng dẫn cài đặt và dùng

> A2UI là framework generative UI, cho phép agent stream dữ liệu mô tả giao diện để ứng dụng hiển thị bằng component native trên React, Angular, Lit, Flutter, SwiftUI và Jetpack Compose. Repo phù hợp với ứng dụng có UI do agent hoặc server điều khiển; phần cài đặt từ README chưa được mô tả đầy đủ nên người mới nên bắt đầu bằng Composer hoặc Quickstart.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-10-20 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/a2ui-tao-giao-dien-dong-bang-ai

A2UI là framework mã nguồn mở giúp agent tạo và truyền giao diện người dùng động dưới dạng dữ liệu, sau đó ứng dụng render giao diện đó bằng component native. Thay vì để mô hình sinh mã giao diện tùy ý, A2UI dùng một schema và giao thức riêng để mô tả UI, dữ liệu, trạng thái và tương tác.

Repo này phù hợp với đội ngũ xây chatbot có giao diện tương tác, ứng dụng server-driven, sản phẩm chạy trên nhiều nền tảng hoặc hệ thống cần giới hạn quyền của agent. Điểm đáng giá nhất là cùng một agent có thể stream UI đến React, Angular, Lit, Flutter, SwiftUI và Jetpack Compose mà không cần nhúng WebView hay HTML vào mọi nơi.

Repo hiện có khoảng 17.270 sao và 1.400 fork. Mã nguồn chính dùng TypeScript, giấy phép Apache-2.0. Dự án vẫn còn được cập nhật, nhưng một số package trong repo chưa được phát hành riêng và phải dùng từ source.

```repo
- repo | a2ui-project/a2ui
- kind | Framework
- desc | Framework mã nguồn mở để agent tạo giao diện động bằng dữ liệu và render bằng component native trên web, mobile.
- stars | 17k
- lang | TypeScript
- license | Apache-2.0
```

## A2UI làm được gì

A2UI nối ba phần: agent, giao thức truyền dữ liệu và renderer trong ứng dụng. Agent sinh mô tả UI, SDK kiểm tra rồi chuyển thành thông điệp A2UI Transport, còn renderer biến thông điệp đó thành component của framework bạn đang dùng.

### Tạo UI động thay vì chỉ trả lời bằng văn bản

Agent có thể tạo một luồng giao diện phù hợp với yêu cầu hiện tại của người dùng. Ví dụ, thay vì trả lời nhiều bước bằng chữ, ứng dụng có thể hiển thị một form, lựa chọn, nội dung xác nhận hoặc các thành phần tương tác phù hợp với ngữ cảnh.

Điều này hữu ích khi người dùng cần hoàn thành một việc cụ thể như lọc dữ liệu, điền thông tin hoặc chọn phương án. Agent có thể điều chỉnh luồng UI theo hành động tiếp theo của người dùng.

### Stream giao diện với độ trễ thấp

Giao thức A2UI được thiết kế cho việc truyền UI động qua mạng và progressive rendering. Ứng dụng có thể bắt đầu hiển thị phần giao diện đã nhận được thay vì chờ toàn bộ trải nghiệm hoàn tất.

Cách này phù hợp với chatbot, trợ lý nội bộ và các ứng dụng có agent từ xa. Người dùng thấy tiến trình sớm hơn, còn agent có thể tiếp tục bổ sung dữ liệu hoặc thành phần giao diện.

### Render bằng component native của từng nền tảng

A2UI có các renderer cho nhiều công nghệ: React, Angular, Lit, Flutter, SwiftUI và Jetpack Compose. Renderer dùng component native của framework thay vì bắt ứng dụng chuyển sang WebView hoặc HTML.

Lợi ích thực tế là giao diện có thể hòa nhập với ứng dụng hiện có, giữ hiệu năng và hình thức quen thuộc của nền tảng. Đội ngũ không nhất thiết phải đổi framework chỉ để thêm tính năng agentic.

### Dùng một agent cho nhiều nền tảng

Một agent có thể stream UI đến web, iOS, Android và ứng dụng Flutter thông qua cùng tư duy giao thức. Mỗi nền tảng vẫn có adapter và catalog riêng để ánh xạ dữ liệu sang component phù hợp.

Đây là lựa chọn đáng cân nhắc khi sản phẩm có nhiều client nhưng muốn giữ hành vi và trải nghiệm nhất quán giữa các màn hình.

### Giới hạn quyền của agent bằng schema

A2UI mô tả giao diện bằng dữ liệu đã xác thực thay vì mã thực thi tùy ý. Ứng dụng kiểm soát catalog và những khả năng nào được cấp cho agent.

Cơ chế này giúp tạo trust boundary giữa agent từ xa và phần quan trọng của ứng dụng. Bạn có thể giới hạn agent không được tự ý xử lý dữ liệu nhạy cảm hoặc gọi những khả năng ngoài phạm vi đã cho phép.

### Kết nối agent SDK với hệ sinh thái khác

Các package trong repo gồm SDK agent, phần kết nối A2A, phần kết nối ADK và catalog MCP. Ở phía TypeScript, `@a2ui/catalog-mcp` có thể gọi MCP tools và render các thông điệp A2UI trả về trong kết quả tool hoặc UI resources.

Repo cũng có catalog VegaChart để render đặc tả Vega và Vega-Lite trên A2UI surface. Package này được ghi rõ là chưa phát hành, nên cần kiểm tra source trước khi đưa vào sản phẩm.

## Cần chuẩn bị gì

Tư liệu được cung cấp không nêu một danh sách hệ điều hành cụ thể. Vì vậy, chưa thể khẳng định A2UI hỗ trợ riêng Windows, macOS hay Linux theo một quy trình cài đặt chính thức trong README.

Nếu làm việc với phần Python, `pyproject.toml` yêu cầu Python từ phiên bản 3.10 trở lên. Repo có các package Python như `a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a` và `a2ui-adk`.

Nếu làm việc với phần TypeScript, repo có `package.json`, `yarn.lock` và workspace package tên `a2ui-workspace`. Các package TypeScript gồm core web, renderer cho Lit, Angular, React, markdown và agent SDK. README không ghi rõ phiên bản Node.js hay trình quản lý package bắt buộc.

Bạn cũng cần chọn nền tảng muốn render: web, Flutter, SwiftUI hoặc Jetpack Compose. README không yêu cầu API key, tài khoản dịch vụ, GPU hay phần cứng đặc biệt. README cũng không nói chi tiết cần mô hình LLM nào; chỉ mô tả agent thường được hỗ trợ bởi language model hoặc decision model.

```note
A2UI giúp giới hạn khả năng của agent bằng schema và catalog, nhưng không tự động làm mọi dữ liệu an toàn. Hãy chỉ cấp cho agent những component, tool và dữ liệu mà ứng dụng thực sự cho phép.
```

## Cài đặt từng bước

```steps
- Lấy mã nguồn | Clone repository A2UI về máy
- Vào thư mục | Mở terminal trong thư mục dự án
- Chọn lối bắt đầu | Dùng Quickstart, Composer hoặc Theater theo mục tiêu
- Đọc package tương ứng | Xem package.json hoặc pyproject.toml trước khi cài sâu hơn
```

### Lấy mã nguồn về máy

README cung cấp nhiều package và đường dẫn bắt đầu, nhưng không ghi một chuỗi lệnh cài đặt hoàn chỉnh. Bạn có thể lấy source bằng lệnh Git phổ thông dưới đây, sau đó đọc hướng dẫn trong repo.

```bash
git clone https://github.com/a2ui-project/a2ui.git
```

Lệnh này tạo một bản sao repository trên máy. Bạn cần cài Git trước và chạy lệnh ở thư mục mà bạn muốn lưu mã nguồn. Nếu terminal báo không tìm thấy `git`, hãy cài Git rồi mở lại terminal.

### Vào đúng thư mục dự án

Sau khi clone xong, chuyển vào thư mục `a2ui`:

```bash
cd a2ui
```

Từ đây, các file như `package.json`, `pyproject.toml`, `typescript/`, `python/`, `dart/`, `swift/` và `kotlin/` nằm trong phạm vi dự án. README chưa ghi lệnh cài dependency cụ thể cho workspace, vì vậy không nên tự đoán tên package manager, cờ lệnh hoặc script chạy.

### Chọn lối bắt đầu phù hợp

Nếu muốn hiểu toàn bộ luồng agent đến frontend, README hướng tới Quickstart. Quickstart được mô tả là một ứng dụng A2UI full-stack có backend và frontend, giúp học quy trình end-to-end rồi tùy biến cho nhu cầu riêng.

Nếu chỉ muốn thử tạo JSON giao diện bằng trình biên tập trực quan, hãy bắt đầu bằng A2UI Composer. README mô tả Composer là công cụ chạy trên trình duyệt, không cần cài đặt, cho phép tạo A2UI JSON rồi dán vào prompt của agent.

Nếu muốn xem các tình huống stream dựng sẵn, dùng A2UI Theater. Công cụ này cũng không cần cài đặt và cho phép xem các scenario qua renderer Lit, React và Angular.

### Đọc đúng package trước khi phát triển

README chưa ghi lệnh cài đặt riêng cho npm hoặc Python. Repo chỉ cho biết package workspace là `a2ui-workspace`, đồng thời có `package.json` và `pyproject.toml` để khai báo cách chạy.

Vì vậy, sau khi vào repo, hãy mở hai file này và đọc script, workspace và dependency được khai báo. Nếu cần dùng package chưa phát hành, README nói rõ package đó có thể được dùng từ source. Đừng thay thế bằng tên package khác hoặc tự thêm biến môi trường khi tài liệu chưa yêu cầu.

## Kiểm tra đã chạy được chưa

Cách kiểm tra ít phụ thuộc môi trường nhất là mở A2UI Composer trong trình duyệt. Nếu trình biên tập hiển thị và cho phép bạn tạo A2UI JSON, bạn đã có thể thử phần mô tả UI mà chưa cần cài source.

Bạn cũng có thể mở A2UI Theater để xem các kịch bản stream dựng sẵn. Kết quả mong đợi là bạn xem được các scenario trên renderer Lit, React và Angular.

Nếu muốn kiểm tra source local, hãy đối chiếu package và script trong `package.json` hoặc `pyproject.toml`. README được cung cấp không nêu lệnh chạy dev server, lệnh test hay màn hình đầu ra cụ thể, nên không thể đưa ra một lệnh xác nhận chính xác hơn mà không bịa thêm tư liệu.

Khi kiểm tra một tích hợp hoàn chỉnh, kết quả cần quan sát là agent tạo được thông điệp A2UI, SDK xử lý và xác thực được thông điệp, rồi renderer hiển thị component native tương ứng. Nếu agent chỉ trả về chữ hoặc renderer không nhận component, cần kiểm tra lại catalog, adapter và luồng transport.

## Dùng vào việc thật

### Trợ lý bán hàng cho chủ shop

Một chủ shop có thể dùng agent để hướng dẫn khách chọn sản phẩm theo nhu cầu. Thay vì chỉ trả lời danh sách dài, agent tạo một luồng UI động gồm các lựa chọn phù hợp, sau đó điều chỉnh bước tiếp theo theo câu trả lời của khách.

Cách yêu cầu có thể là: “Hãy tạo luồng chọn sản phẩm theo ngân sách, mục đích sử dụng và màu sắc. Chỉ dùng các thành phần có trong catalog của ứng dụng.” Agent không sinh mã giao diện tùy ý; nó tạo mô tả dữ liệu để renderer của ứng dụng hiển thị.

Kết quả mong đợi là khách đi qua một trải nghiệm ngắn, trực tiếp và phù hợp hơn với nhu cầu ngay lúc đó.

### Biểu mẫu nội bộ cho nhân viên văn phòng

Một phòng vận hành có thể dùng agent để tạo form xử lý yêu cầu nội bộ. Ví dụ, nhân viên nhập mục đích xin mua thiết bị, agent hỏi thêm thông tin cần thiết rồi dựng luồng nhập và xác nhận.

Đội phát triển có thể dùng cùng agent cho web React và một ứng dụng Flutter nếu sản phẩm có cả hai client. Mỗi client dùng renderer native của mình, còn dữ liệu UI đi theo giao thức chung.

Kết quả là nhân viên không phải tìm qua nhiều màn hình cố định. Tuy nhiên, các trường dữ liệu nhạy cảm và quyền gửi yêu cầu vẫn phải được ứng dụng kiểm soát.

### Dashboard dữ liệu có phần trình bày linh hoạt

Một ứng dụng phân tích có thể nhận yêu cầu tự nhiên như: “Tóm tắt tình hình bán hàng và hiển thị biểu đồ phù hợp.” Với catalog VegaChart, A2UI có thể render đặc tả Vega hoặc Vega-Lite trên surface A2UI.

README ghi package catalog VegaChart là chưa phát hành, nên đây phù hợp hơn với thử nghiệm hoặc phát triển từ source. Trước khi dùng thật, cần kiểm tra khả năng tương thích và mức ổn định của package trong repo.

### Agent gọi MCP tools rồi hiển thị kết quả

Một đội kỹ thuật có thể dùng `@a2ui/catalog-mcp` khi ứng dụng đã có MCP tools. Package này được README mô tả là catalog có thể gọi MCP tools và render A2UI messages trả về trong tool results hoặc UI resources.

Ví dụ, agent nhận yêu cầu lấy dữ liệu từ một tool được cho phép, sau đó hiển thị kết quả bằng các component trong catalog. Cách này giúp kết quả từ tool đi vào trải nghiệm UI thay vì chỉ xuất hiện như văn bản.

Hãy giới hạn rõ tool và catalog được cấp. Agent không nên được quyền gọi mọi tool chỉ vì renderer có thể hiển thị kết quả.

> Giao diện do agent tạo chỉ đáng tin khi ứng dụng kiểm soát được dữ liệu, catalog và quyền mà agent được phép dùng.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Tự đoán sai lệnh cài đặt

README được cung cấp chưa ghi lệnh cài dependency hoặc lệnh chạy ứng dụng. Việc tự dùng một lệnh quen thuộc có thể làm sai workspace hoặc cài nhầm package.

Cách xử lý an toàn là mở `package.json` và `pyproject.toml`, xem script và dependency đã khai báo, rồi đối chiếu tài liệu trong `docs/`, `samples/` và package tương ứng.

### Dùng renderer nhưng thiếu catalog phù hợp

Core library chỉ là phần xử lý thông điệp và trạng thái. Adapter ánh xạ dữ liệu sang framework, còn catalog cung cấp các widget mà agent được phép compose.

Nếu renderer không hiển thị thành phần, hãy kiểm tra cả core, adapter và catalog. Đừng chỉ thay đổi prompt của agent khi phần catalog chưa có component cần thiết.

### Agent tạo ra khả năng ngoài phạm vi ứng dụng

A2UI có schema và cơ chế catalog để tạo ranh giới, nhưng ứng dụng vẫn phải quyết định khả năng nào được cấp. Nếu cấp quá rộng, agent có thể tạo trải nghiệm vượt quá yêu cầu kinh doanh hoặc chạm vào dữ liệu nhạy cảm.

Hãy giới hạn catalog, xác thực input và output, đồng thời không cấp quyền xử lý thông tin tài chính, số tài khoản hoặc PII nếu không cần thiết.

### Trộn package đã phát hành với package từ source

README ghi một số package chưa phát hành, trong đó có catalog VegaChart. Nếu coi chúng như package ổn định đã công bố, quá trình cài hoặc triển khai có thể không giống dự kiến.

Hãy kiểm tra trạng thái package trong README và source. Với package chưa phát hành, nên thử trong môi trường phát triển trước khi đưa vào hệ thống chính.

### Kỳ vọng mọi nền tảng có cùng giao diện pixel-perfect

A2UI hướng tới khả năng dùng một agent cho nhiều nền tảng, nhưng mỗi renderer vẫn dùng component native và framework adapter riêng. Vì vậy, cùng một mô tả dữ liệu không nhất thiết tạo ra hình thức giống từng pixel trên mọi thiết bị.

Hãy tập trung vào khả năng và luồng trải nghiệm chung, đồng thời kiểm tra riêng trên React, Flutter, SwiftUI hoặc Jetpack Compose mà sản phẩm hỗ trợ.

## Có nên dùng không

A2UI đáng thử nếu bạn đang xây ứng dụng có agent hoặc server điều khiển UI, cần stream giao diện, muốn dùng component native hoặc phải phục vụ nhiều nền tảng. Kiến trúc phân tách inference, transport và rendering giúp đội phát triển có thể thay đổi agent, renderer hoặc catalog theo nhu cầu.

Điểm mạnh lớn là tính an toàn theo hướng schema và catalog. Agent tạo dữ liệu mô tả UI thay vì mã thực thi tùy ý, còn ứng dụng giữ quyền quyết định những component và khả năng được phép dùng. Repo cũng có SDK cho nhiều ngôn ngữ và adapter cho nhiều framework.

Giới hạn là phạm vi khá rộng và tài liệu README chưa cung cấp một quy trình cài đặt local hoàn chỉnh. Người mới có thể bắt đầu bằng Composer hoặc Theater, nhưng khi đi vào tích hợp thật sẽ phải đọc thêm source, package và tài liệu trong repo. Một số package chưa phát hành cũng làm tăng công việc kiểm tra tương thích.

Nếu bạn chỉ cần chatbot trả lời bằng chữ, form tĩnh hoặc một dashboard được lập trình cố định, A2UI có thể là quá nhiều. Nếu chưa cần agent điều khiển UI hoặc chỉ triển khai một màn hình đơn giản, component và logic thông thường sẽ dễ bảo trì hơn.

Với dự án muốn thử generative UI một cách có kiểm soát, A2UI là framework đáng xem xét. Hãy bắt đầu bằng Composer hoặc Theater, sau đó chọn đúng renderer và catalog trước khi kết nối dữ liệu thật.

## Câu hỏi thường gặp

### A2UI là thư viện hay framework?

A2UI là framework generative UI mã nguồn mở, kèm giao thức, core library, renderer native, catalog và agent SDK. Repo có các package cho TypeScript, Python, Dart, Flutter và Swift.

### A2UI có miễn phí không?

Repo được phát hành theo giấy phép Apache-2.0. README không nêu chi phí vận hành, chi phí mô hình hoặc chi phí của các dịch vụ bên ngoài, nên phần này chưa có thông tin cụ thể.

### Có cần GPU hoặc API key không?

README không yêu cầu GPU hay API key để dùng framework. Tài liệu cũng không chỉ định một mô hình LLM cụ thể; chi phí và yêu cầu phần cứng của agent hoặc mô hình bên ngoài chưa được nêu.

### Có chạy được trên Windows không?

Tư liệu được cung cấp không nêu hệ điều hành được hỗ trợ và cũng không có quy trình cài đặt riêng cho Windows. Bạn nên kiểm tra script trong `package.json`, `pyproject.toml` và tài liệu trong repo.

### Có thể dùng A2UI với React và Flutter cùng lúc không?

Có. README liệt kê renderer cho React và Flutter, đồng thời mô tả việc một agent stream UI đến nhiều nền tảng hoặc framework.

### A2UI có an toàn hơn việc cho agent sinh mã UI không?

A2UI thể hiện UI bằng dữ liệu đã được schema kiểm tra thay vì mã thực thi tùy ý. Tuy vậy, ứng dụng vẫn phải kiểm soát catalog, quyền, input, output và dữ liệu mà agent được phép dùng.

### Package nào trong repo chưa phát hành?

README ghi `@a2ui/catalog-vegachart` là chưa phát hành và có thể dùng từ source. Các package khác cũng cần được đối chiếu trạng thái trong repo trước khi triển khai.
