# A2UI: để AI agent tự dựng giao diện thật trên web và mobile — hướng dẫn cài đặt và dùng

> A2UI (Agent-to-User Interface) là framework mã nguồn mở giúp AI agent trả lời bằng giao diện thật (nút, form, danh sách…) thay vì chỉ chữ. Agent gửi mô tả giao diện dưới dạng dữ liệu JSON, app của bạn vẽ lại bằng thành phần native. Với người mới, cách dễ nhất là thử A2UI Composer trên trình duyệt trước; tích hợp vào app thì cần biết lập trình.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-06 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/a2ui-agent-dung-giao-dien-native-react-flutter-swiftui

A2UI là một framework mã nguồn mở để AI agent không chỉ trả lời bằng chữ mà còn trả về giao diện thật: form, nút bấm, danh sách, biểu đồ. Agent không viết code giao diện. Nó gửi một bản mô tả giao diện dưới dạng dữ liệu, và app của bạn vẽ bản mô tả đó bằng thành phần native của chính app (React, Angular, Lit, Flutter, SwiftUI, Jetpack Compose).

Tên đầy đủ là Agent-to-User Interface. Repo gồm một giao thức truyền dữ liệu giao diện theo kiểu streaming (giao diện hiện dần ra khi agent đang nghĩ), các bộ vẽ giao diện (renderer) cho web và mobile, và các bộ SDK để dựng agent bằng Python, TypeScript, Dart. Hiện repo có khoảng 17.220 sao và 1.395 fork, dùng giấy phép Apache-2.0.

Ai nên đọc bài này? Chủ yếu là lập trình viên đang làm app có chatbot hoặc agent và muốn câu trả lời của AI là giao diện bấm được. Nếu bạn làm kinh doanh hoặc văn phòng và chưa code, bạn vẫn thử được công cụ trực quan trên trình duyệt mà không phải cài gì. Điểm đáng giá nhất là tính an toàn: agent chỉ được dùng những thành phần bạn cho phép, vì giao diện là dữ liệu có kiểm tra chặt chứ không phải code chạy tuỳ ý.

```repo
- repo | a2ui-project/a2ui
- kind | Framework
- desc | A2UI là framework mã nguồn mở để AI agent gửi giao diện dưới dạng dữ liệu, còn app hiển thị bằng thành phần native của React, Flutter, SwiftUI, Compose.
- stars | 17k
- lang | TypeScript
- license | Apache-2.0
```

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

### Giao diện là dữ liệu, không phải code

A2UI mô tả giao diện bằng dữ liệu theo một lược đồ (schema) cố định. Agent chỉ nói được những gì lược đồ cho phép. Lợi ích thực tế: nếu AI trả lời sai hoặc bị lừa, nó vẫn không thể nhét mã độc vào app của bạn. README gọi đây là nguyên tắc «security first».

### Hiển thị bằng thành phần native

Giao diện được vẽ bằng framework mà app của bạn đang dùng. Không cần WebView hay HTML nhúng. Nhờ vậy giao diện nhanh và nhìn giống phần còn lại của app. README nêu các renderer cho Lit (web components), Angular, React, Flutter, SwiftUI, và Jetpack Compose nằm trong chủ đề của repo.

### Một agent, nhiều nền tảng

Cùng một agent có thể gửi giao diện cho web, iOS, Android mà trải nghiệm vẫn đồng nhất. Nếu công ty bạn có app trên nhiều nền tảng, bạn không phải viết lại phần giao diện cho từng nơi.

### Streaming, giao diện hiện dần

Giao thức được thiết kế để mô hình ngôn ngữ sinh ra dễ dàng và gửi qua mạng nhanh, hỗ trợ vẽ dần. Người dùng thấy giao diện hình thành ngay thay vì chờ cả khối.

### Danh mục thành phần (catalog) do bạn kiểm soát

Mỗi renderer có một catalog: danh sách widget mà agent được phép ghép. Bạn quyết định agent được dùng gì. README cũng liệt kê các catalog bổ sung như `@a2ui/catalog-mcp` (gọi công cụ MCP và vẽ giao diện trả về) và `@a2ui/catalog-vegachart` (vẽ biểu đồ Vega/Vega-Lite, mục này README ghi là chưa phát hành, dùng được từ mã nguồn).

### Agent SDK

SDK giúp agent thương lượng catalog, tạo prompt, kiểm tra đầu ra của mô hình rồi chuyển thành thông điệp A2UI. Có sẵn gói nối với giao thức A2A (`a2ui-a2a`) và Agent Development Kit (`a2ui-adk`) cho Python.

### Công cụ thử nhanh không cần cài

README giới thiệu A2UI Composer (soạn giao diện bằng trình soạn trực quan rồi lấy JSON dán vào prompt của agent) và A2UI Theater (xem các kịch bản streaming có sẵn trên renderer Lit, React, Angular). Cả hai chạy trên trình duyệt.

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

Tư liệu chỉ nói rõ vài điều:

- Python từ 3.10 trở lên nếu bạn dùng phần Python (theo `pyproject.toml`).
- Repo có `package.json` ở gốc (tên gói `a2ui-workspace`) và `yarn.lock`, tức phần TypeScript dùng npm/yarn. README không ghi phiên bản Node yêu cầu.
- Để dùng renderer Flutter cần Dart/Flutter; để dùng Swift thì cài qua Swift Package Manager từ `Package.swift` ở gốc repo.
- Một agent cần có mô hình ngôn ngữ phía sau. README không nói bắt buộc nhà cung cấp nào, và cũng không nói cần API key hay GPU hay không. Nếu bạn làm theo hướng dẫn Quickstart, hãy xem trang đó để biết chính xác.
- Hệ điều hành: README không nêu yêu cầu cụ thể.

```note
A2UI là bộ khung cho lập trình viên, không phải phần mềm cài một lần là dùng. Nếu bạn chưa code, hãy bắt đầu bằng A2UI Composer trên trình duyệt để hiểu ý tưởng. Khi nối agent với mô hình ngôn ngữ có tính phí, bạn có thể phát sinh chi phí API và phải giữ kín key.
```

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

Lưu ý thẳng: README của repo không có một lệnh cài đặt duy nhất. Nó chỉ liệt kê các gói và trỏ tới trang Quickstart trên website. Vì vậy mình không chép lệnh tự nghĩ ra. Các bước dưới đây chỉ gồm phần chắc chắn đúng và chỉ bạn nơi xem lệnh chính thức.

```steps
- Thử không cần cài | Mở A2UI Composer hoặc A2UI Theater trên trình duyệt để xem A2UI làm gì
- Chọn hướng đi | Quyết định bạn làm phía agent (Python/TypeScript/Dart) hay phía app (renderer)
- Tải mã nguồn | Dùng git clone để lấy repo về máy
- Xem quickstart | Làm theo trang Quickstart (khoảng 5 phút) để chạy app mẫu đủ backend và frontend
- Thêm gói vào dự án | Dùng đúng tên gói trong README, lệnh cài xem trang tài liệu của từng gói
```

### Thử trước trên trình duyệt

Trước khi đụng tới terminal, hãy mở A2UI Composer (đường dẫn có trong README, phần Quick links). Bạn dựng giao diện bằng trình soạn trực quan rồi lấy JSON ra. Mất khoảng một phút và không cần cài gì. A2UI Theater cho bạn xem các kịch bản streaming có sẵn.

### Chọn hướng đi

README chia gói theo ngôn ngữ:

- Python: `a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`.
- TypeScript: `@a2ui/web_core`, `@a2ui/lit`, `@a2ui/angular`, `@a2ui/react`, `@a2ui/markdown-it`, `@a2ui/agent`, `@a2ui/catalog-mcp`, `@a2ui/catalog-vegachart`.
- Dart/Flutter: `a2ui_core`, `a2ui_agent`, `a2ui_flutter`, `a2ui_cli`. Riêng `a2ui_cli` tải ở trang GitHub Releases của repo.
- Swift: các thư viện như `A2UISwiftCore`, `A2UISwiftUI`, cài qua Swift Package Manager từ `Package.swift`.

Người làm web thường chọn bộ `@a2ui/web_core` cùng một renderer (ví dụ `@a2ui/react`). Phía agent chọn SDK cùng ngôn ngữ với backend của bạn.

### Tải mã nguồn về máy

Mở terminal (PowerShell trên Windows, Terminal trên macOS/Linux) ở thư mục bạn muốn lưu dự án, rồi chạy:

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

Lệnh đầu tải toàn bộ repo về. Lệnh thứ hai đi vào thư mục vừa tải. Bạn cần cài Git trước. Người mới hay quên bước `cd`, khiến các lệnh sau báo không tìm thấy file.

### Làm theo Quickstart

README mô tả Quickstart là một app đủ backend và frontend, mất khoảng 5 phút, để bạn hiểu A2UI từ đầu đến cuối rồi tuỳ biến. Các lệnh cụ thể nằm trên trang Quickstart của website a2ui.org, không nằm trong README. Mình không chép lại vì tư liệu mình có không chứa chúng. Repo cũng có thư mục `samples/`, `docs/` và file `CONTRIBUTING.md` để bạn xem thêm cách chạy từ mã nguồn.

### Thêm gói vào dự án của bạn

README ghi tên các gói nhưng không ghi lệnh cài từng gói. Hãy mở trang tài liệu của gói đó trên website và dùng đúng lệnh ở đó. Ngoài ra, README lưu ý những gói đánh dấu «Not published yet» thì dùng được từ mã nguồn trong repo, không cài từ kho gói.

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

Tư liệu không mô tả một lệnh kiểm tra cài đặt cụ thể. Cách kiểm tra hợp lý nhất theo đúng nội dung README là:

- Với Composer và Theater: giao diện hiện ra và các kịch bản streaming chạy được trên trình duyệt.
- Với Quickstart: app mẫu có backend và frontend khởi động được, và khi bạn nhắn yêu cầu, agent trả về giao diện (không chỉ chữ) được vẽ trên màn hình.
- Khi tự tích hợp: agent gửi ra thông điệp A2UI, renderer của bạn vẽ ra widget từ catalog. Nếu chỉ thấy chữ thô hoặc JSON hiện nguyên trên màn hình, nghĩa là phần renderer chưa nối đúng.

Cách đối chiếu chắc chắn nhất là so với kết quả mà trang Quickstart mô tả.

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

Các tình huống dưới đây bám vào khả năng README nêu: agent dựng giao diện theo nhu cầu, vẽ native, chạy trên nhiều nền tảng. Phần câu lệnh là prompt mẫu mình gợi ý cho agent của bạn, không phải lệnh của repo.

### Chủ shop làm trợ lý đặt hàng trong app bán hàng

Bạn có một app bán hàng trên React và một chatbot tư vấn. Thay vì khách phải qua ba màn hình để chọn sản phẩm, chọn size, nhập địa chỉ, agent dựng luôn một form gọn ngay trong khung chat. Prompt mẫu cho agent:

```text
Khách muốn đặt áo thun. Hãy hiển thị form gồm: chọn size, chọn màu, số lượng và nút Đặt hàng. Chỉ dùng các thành phần có trong catalog.
```

Kết quả: khách thấy form thật bấm được, vẽ bằng thành phần React của app. Nếu bạn không cho phép agent hiện ô nhập số thẻ, nó cũng không làm được, vì catalog chặn.

> Giao diện là dữ liệu có kiểm tra, nên agent có sáng tạo đến đâu cũng chỉ ghép được những mảnh bạn đã cho phép.
>
> — Ông T

### Nhân viên văn phòng muốn thử ý tưởng trước khi nhờ dev

Bạn không code nhưng muốn đưa cho đội kỹ thuật một mẫu «màn hình báo cáo» như bạn hình dung. Mở A2UI Composer, dựng bố cục bằng trình soạn trực quan, lấy JSON ra và dán vào prompt của agent. Kết quả: bạn có một bản mô tả giao diện cụ thể để dev dùng, thay vì mô tả bằng lời rồi hiểu sai.

### Dev app mobile làm một agent cho cả iOS, Android và web

Công ty có app Flutter, app SwiftUI và web React. Dev dựng một agent bằng SDK (Python hoặc TypeScript), rồi mỗi nền tảng gắn renderer tương ứng. Agent gửi cùng một luồng giao diện, mỗi app vẽ bằng widget native của mình. Kết quả: logic và giao diện do agent quyết định nằm một chỗ, bạn không phải viết lại cho từng nền tảng.

### Dev dùng agent bên thứ ba qua ranh giới tin cậy

Bạn muốn dùng một agent từ bên ngoài nhưng không muốn nó đụng vào dữ liệu nhạy cảm như số tài khoản. README nêu đúng trường hợp này: lược đồ nghiêm ngặt và giao diện biểu diễn bằng dữ liệu đã kiểm tra giúp giữ ranh giới tin cậy. Kết quả: agent chỉ hiển thị và thu thập thông qua các thành phần bạn cấp phép.

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

### Không thấy lệnh cài trong README

Đây không phải lỗi mà là cách repo tổ chức: README chỉ trỏ tới website. Cách xử lý an toàn: mở trang Quickstart trên website của dự án, hoặc xem `CONTRIBUTING.md`, thư mục `docs/` và `samples/` trong repo. Đừng đoán lệnh rồi chạy bừa.

### Chạy lệnh báo không tìm thấy file hoặc thư mục

Thường do bạn đang mở terminal sai chỗ. Sau khi `git clone`, hãy `cd a2ui` rồi mới chạy tiếp. Trên Windows, kiểm tra bằng cách xem đường dẫn hiện ở đầu dòng lệnh.

### Phiên bản Python hoặc Node không khớp

Phần Python yêu cầu từ 3.10 trở lên. Nếu máy bạn dùng bản cũ hơn, cài bản mới hơn rồi thử lại. Với Node, README không nêu phiên bản, nên hãy xem hướng dẫn của gói bạn dùng.

### Giao diện không hiện, chỉ thấy chữ hoặc JSON

Thường là renderer chưa nối đúng, hoặc agent trả về thành phần không có trong catalog nên bị từ chối. Kiểm tra lại: app đã dùng đúng renderer (ví dụ `@a2ui/react`) chưa, và catalog đã bao gồm thành phần agent đang gọi chưa.

### Lộ API key khi thử với mô hình thật

Khi nối agent với mô hình ngôn ngữ, đừng dán key vào code rồi đẩy lên GitHub. Hãy để key ngoài mã nguồn và không chia sẻ ảnh chụp màn hình có key. README không nói tên biến môi trường nào, nên hãy theo hướng dẫn của nhà cung cấp mô hình bạn dùng.

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

Điểm mạnh: ý tưởng rõ, an toàn (giao diện là dữ liệu có kiểm tra), vẽ native nên nhanh, hỗ trợ nhiều framework, giấy phép Apache-2.0, và repo được cập nhật trong 3 tháng gần đây. Có công cụ thử không cần cài nên bạn đánh giá được nhanh.

Giới hạn: đây là bộ khung cho lập trình viên. Bạn phải có app và agent để gắn vào. README ghi rõ nhiều hạng mục vẫn nằm trong lộ trình (giao thức v1.1, mẫu giao diện dùng lại, logic chạy trong sandbox, công cụ đánh giá chất lượng), và một số gói chưa phát hành. Tài liệu cài đặt chính nằm ở website chứ không ở README, nên người mới sẽ phải đọc thêm.

Nên chọn A2UI khi app của bạn do agent hoặc server điều khiển, cần giao diện dựng theo nhu cầu từng người dùng, hoặc cùng một agent phải phục vụ nhiều nền tảng. Nếu bạn chỉ cần chatbot trả lời bằng chữ, hoặc giao diện cố định ít thay đổi, một form thường bằng framework quen thuộc sẽ đơn giản hơn nhiều. Còn nếu bạn chưa code, hãy dừng ở Composer và Theater để hiểu ý tưởng, rồi nhờ đội kỹ thuật làm tiếp.

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

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

Repo là mã nguồn mở theo giấy phép Apache-2.0 nên dùng và đóng góp tự do. Tuy nhiên, nếu agent của bạn gọi mô hình ngôn ngữ tính phí thì chi phí đó nằm ở nhà cung cấp mô hình, tư liệu không nói gì thêm về việc này.

### A2UI là gì, khác gì chatbot trả lời bằng chữ?

A2UI cho phép agent trả lời bằng giao diện thật như widget, form, nút, bên cạnh văn bản. Agent gửi mô tả giao diện dưới dạng dữ liệu, còn app vẽ bằng thành phần native của mình. Chatbot chữ thông thường chỉ trả về văn bản.

### Tôi không biết lập trình thì dùng được không?

Bạn thử được A2UI Composer và A2UI Theater ngay trên trình duyệt, không cần cài đặt, mỗi cái mất khoảng một phút theo README. Còn tích hợp vào app thật thì cần lập trình viên, vì phải gắn renderer và SDK vào dự án.

### A2UI hỗ trợ những nền tảng nào?

Theo README và chủ đề của repo: React, Angular, Lit (web components), Flutter, SwiftUI và Jetpack Compose. Swift được phân phối qua Swift Package Manager từ Package.swift ở gốc repo.

### Có cần GPU hoặc cấu hình máy mạnh không?

Tư liệu không nêu yêu cầu GPU hay phần cứng. A2UI là giao thức và thư viện vẽ giao diện, nên phần nặng nếu có nằm ở mô hình ngôn ngữ mà agent của bạn dùng.

### Dữ liệu và app có an toàn không?

README đặt bảo mật lên hàng đầu: giao diện được biểu diễn bằng dữ liệu, kiểm tra theo lược đồ, không cho chạy code tuỳ ý, và agent chỉ dùng các thành phần trong catalog do bạn cấp. Tư liệu không đảm bảo thêm điều gì ngoài các nguyên tắc này.

### Cài bằng lệnh nào, chạy trên Windows được không?

README không ghi lệnh cài cụ thể, mà trỏ tới trang Quickstart trên website của dự án. Tư liệu cũng không nêu hệ điều hành bắt buộc, chỉ cho biết phần Python cần từ 3.10 trở lên, nên bạn nên xem Quickstart để chắc chắn.
