← Trang chủ

ĐÃ REVIEW & SẴN SÀNG CÀI ĐẶT

ag-ui

ag-ui-protocol/ag-ui

AG-UI là giao thức mở, dựa trên sự kiện, đưa AI agent vào giao diện ứng dụng: chat chạy chữ theo thời gian thực, đồng bộ trạng thái hai chiều, tool chạy trên frontend, giao diện do agent dựng và bước chờ người duyệt. LangGraph, CrewAI, Google ADK, Pydantic AI, Mastra… đã hỗ trợ. Miễn phí, giấy phép MIT.

TỪNG BƯỚC

Hướng dẫn cài đặt ag-ui

Hướng dẫn từng bước nằm ngay trên trang này, viết cho người chưa từng cài phần mềm từ GitHub.

Cập nhật 16/11/2026
Ảnh xem trước của ag-ui trên GitHub
Sao GitHub
21.037
Ngôn ngữ
TypeScript
Hạng trending
#10
Đã thêm
16/11/2026

Cách cài đặt ag-ui từng bước

Làm lần lượt từ trên xuống. Mỗi khung chữ xám là một lệnh: chép nguyên dòng, dán vào cửa sổ dòng lệnh rồi nhấn Enter.

Chưa từng dùng dòng lệnh? Đọc phần này trước (1 phút)

Dòng lệnh (Terminal) là một cửa sổ để gõ lệnh cho máy tính. Bạn không cần hiểu lệnh, chỉ cần chép đúng và dán vào.

  1. Windows: nhấn phím Windows, gõ "PowerShell", rồi nhấn Enter.
  2. macOS: nhấn Command + Space, gõ "Terminal", rồi nhấn Enter.
  3. Linux: nhấn Ctrl + Alt + T.
  4. Chép một lệnh trong hướng dẫn, bấm chuột phải vào cửa sổ vừa mở để dán (macOS: Command + V), rồi nhấn Enter.
  5. Chờ lệnh chạy xong (con trỏ nhấp nháy trở lại ở dòng mới) rồi mới làm lệnh tiếp theo.

Dòng bắt đầu bằng dấu # chỉ là ghi chú, không cần chép. Nếu hiện chữ đỏ báo lỗi, xem mục lỗi thường gặp ở cuối hướng dẫn.

1. AG-UI là gì?

AG-UI (Agent-User Interaction Protocol, repo ag-ui-protocol/ag-ui) là một giao thức mở: một bộ quy ước chung để AI agent (chương trình AI tự làm nhiều bước, gọi công cụ, ra quyết định) nói chuyện với giao diện mà người dùng nhìn thấy, ví dụ khung chat trong web app của bạn. Agent không gửi dữ liệu theo kiểu riêng của từng framework nữa, mà phát ra một dòng sự kiện chuẩn: bắt đầu chạy, từng đoạn chữ của câu trả lời, gọi công cụ, cập nhật trạng thái, kết thúc. Giao diện chỉ cần hiểu một ngôn ngữ đó là hiển thị được agent nào cũng như nhau.

Theo README, AG-UI đứng cạnh hai giao thức quen thuộc khác: MCP cho agent dùng công cụ, A2A cho các agent nói chuyện với nhau, còn AG-UI đưa agent vào ứng dụng có người dùng. Dự án miễn phí, giấy phép MIT. Bản 1.0 phát hành ngày 17/9/2026 và là bản đầu tiên có đặc tả (specification) chính thức.

Nói thẳng: đây là công cụ cho lập trình viên. AG-UI không phải một app để tải về và dùng ngay. Nếu bạn không viết phần mềm, cách hợp nhất để "thấy" AG-UI là mở bản demo trên web (Bước 1 bên dưới).

Hợp với bạn nếu:

  • Bạn đã có (hoặc định làm) một AI agent bằng LangGraph, CrewAI, Mastra, Pydantic AI, Google ADK, Microsoft Agent Framework, LlamaIndex, Agno, AG2, Claude Agent SDK… và muốn gắn nó vào giao diện web.
  • Bạn muốn có sẵn các tính năng: chat chạy chữ theo thời gian thực, trạng thái đồng bộ hai chiều giữa agent và giao diện, agent gọi được công cụ chạy trên trình duyệt, agent tự dựng giao diện, và bước dừng lại chờ người dùng duyệt.
  • Bạn đã quen chạy lệnh npx, npm trên máy.

Chưa hợp nếu:

  • Bạn tìm một chatbot làm sẵn để dùng hằng ngày. AG-UI là phần "đường ống" bên dưới, không phải sản phẩm cuối.
  • Bạn không muốn dùng khóa API trả phí của nhà cung cấp mô hình. Các ứng dụng mẫu cần một khóa như vậy để agent trả lời được.

2. Cần chuẩn bị gì?

  • Máy tính Windows, macOS hoặc Linux, có kết nối mạng.
  • Node.js 20.9.0 trở lên. Node.js là phần mềm nền để chạy chương trình viết bằng JavaScript; cài nó sẽ có luôn lệnh npm và npx. Công cụ tạo dự án của CopilotKit (được AG-UI gọi tới) yêu cầu tối thiểu bản này. Tải miễn phí ở https://nodejs.org (chọn bản LTS).
  • Khóa API của nhà cung cấp mô hình, thường là OpenAI. Ví dụ mẫu LangGraph Python yêu cầu điền OPENAI_API_KEY vào file .env. Khóa này tính tiền theo bảng giá của nhà cung cấp, không phải của AG-UI. Lấy khóa OpenAI ở https://platform.openai.com/api-keys.
  • (Chỉ khi chọn agent viết bằng Python) Python 3.12 trở lên (https://www.python.org/downloads/) và uv, trình quản lý gói Python (https://docs.astral.sh/uv/). Mẫu dùng Mastra hay LangGraph JavaScript thì không cần Python.

Không cần tài khoản AG-UI. Bản demo trên web ở Bước 1 không cần cài gì.

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

Bước 1: Xem bản demo trên web trước (không cần cài)

Mở https://dojo.ag-ui.com trên trình duyệt. Đây là "Dojo", trang demo chính thức của dự án, gom từng tính năng nhỏ của AG-UI thành ví dụ riêng.

Thấy gì là đúng: cột bên trái có ô chọn framework (mục "Integrations") và danh sách ví dụ như "Beautiful Chat", "Frontend Tools", "Generative UI"; bên phải là khung chat "How can I help you today?". Bấm "Code" để xem mã của ví dụ đang mở.

Bước 2: Kiểm tra Node.js

Mở Terminal (macOS/Linux) hoặc PowerShell (Windows) và gõ:

node --version

Thấy gì là đúng: một dòng như v22.x.x hoặc v24.x.x (từ v20.9.0 trở lên). Nếu báo không tìm thấy lệnh hoặc số thấp hơn, cài Node.js bản LTS từ https://nodejs.org rồi mở lại cửa sổ dòng lệnh.

Bước 3: Tạo dự án AG-UI

Đi tới thư mục bạn muốn đặt dự án (ví dụ thư mục Documents), rồi chạy:

npx create-ag-ui-app@latest

Lần đầu, npm có thể hỏi có muốn tải gói create-ag-ui-app không, gõ y rồi Enter. Sau đó công cụ hỏi hai câu:

  1. "What client do you want to use?" (bạn dùng giao diện nào). Chọn CopilotKit/Next.js để có web app có khung chat. Lựa chọn CLI client tạo một ứng dụng chạy trong cửa sổ dòng lệnh.
  2. "What would you like to name your project?" (tên dự án). Mặc định là my-ag-ui-app. Tên chỉ được chứa chữ, số, dấu gạch ngang và gạch dưới.

Sau đó công cụ gọi trình tạo dự án của CopilotKit và có thể hỏi thêm chọn mẫu agent. Nếu đã biết framework mình dùng, bạn có thể chọn luôn bằng cờ, ví dụ:

npx create-ag-ui-app@latest --langgraph-py

Các cờ có sẵn: --langgraph-py, --langgraph-js, --crewai-flows, --mastra, --pydantic-ai, --llamaindex, --agno, --ag2, --adk.

Thấy gì là đúng: xuất hiện một thư mục mới mang tên dự án, bên trong có package.json và file README.md của mẫu.

Bước 4: Điền khóa API

Đi vào thư mục dự án và tạo file .env từ file mẫu.

macOS / Linux:

cd my-ag-ui-app
cp .env.example .env

Windows (PowerShell):

cd my-ag-ui-app
Copy-Item .env.example .env

Mở file .env bằng trình soạn thảo (Notepad, VS Code…), điền khóa vào dòng tương ứng, ví dụ OPENAI_API_KEY=..., rồi lưu lại. Tên biến cụ thể có thể khác giữa các mẫu; README trong thư mục dự án ghi rõ cần điền gì.

Thấy gì là đúng: file .env có dòng khóa API với giá trị thật, không còn chữ mẫu như your-openai-api-key-here.

Lưu ý: không chia sẻ file .env và không đưa nó lên GitHub. Ai có khóa này đều tiêu được tiền trong tài khoản của bạn.

Bước 5: Cài thư viện và chạy

npm install
npm run dev

Với mẫu agent Python, npm install sẽ tự cài thêm phần Python bằng uv theo README của mẫu.

Thấy gì là đúng: dòng lệnh không còn trả về dấu nhắc mà liên tục in nhật ký, trong đó có địa chỉ http://localhost:3000.

4. Dùng lần đầu

  1. Mở trình duyệt, vào http://localhost:3000.
  2. Bạn sẽ thấy trang mẫu có khung chat của CopilotKit. Gõ một câu hỏi ngắn, ví dụ "Xin chào, bạn làm được gì?".
  3. Câu trả lời hiện ra từng chữ một: đó là sự kiện văn bản AG-UI được agent phát ra và giao diện hiển thị theo thời gian thực.
  4. Thử các tính năng mẫu có sẵn (tùy mẫu, ví dụ đổi màu nền hay thêm mục vào danh sách bằng lời). Khi agent gọi công cụ hoặc đổi trạng thái, giao diện cập nhật ngay.

Muốn dừng ứng dụng, quay lại cửa sổ dòng lệnh và bấm Ctrl + C.

Để hiểu sâu hơn, đọc phần Concepts trong tài liệu chính thức: https://docs.ag-ui.com (mục Events liệt kê toàn bộ loại sự kiện).

5. Lỗi thường gặp và cách sửa

Dấu hiệuNguyên nhânCách sửa
Báo không tìm thấy lệnh npx hoặc nodeChưa cài Node.js, hoặc cài xong chưa mở lại cửa sổ dòng lệnhCài Node.js LTS từ https://nodejs.org, đóng rồi mở lại Terminal/PowerShell
Công cụ dừng và báo cần Node.js 20.9.0 trở lênNode.js quá cũCài bản LTS mới, kiểm tra lại bằng node --version
"Project name can only contain letters, numbers, hyphens, and underscores"Tên dự án có dấu cách, dấu tiếng Việt hoặc ký tự đặc biệtĐặt tên như my-ag-ui-app, agent_demo
Trang mở được nhưng chat báo lỗi, không có câu trả lờiThiếu hoặc sai khóa API trong .env, hoặc tài khoản nhà cung cấp hết tiềnKiểm tra lại .env, lưu file, tắt (Ctrl + C) rồi chạy lại npm run dev
Không tìm thấy uv hoặc python (mẫu Python)Chưa cài Python 3.12+ hoặc uvCài theo link ở mục 2, mở lại cửa sổ dòng lệnh
Báo cổng 3000 đang bậnMột ứng dụng khác đang dùng cổng 3000Tắt ứng dụng kia, hoặc mở địa chỉ khác mà nhật ký in ra
npm báo EALLOWSCRIPTSnpm 12 từ chối cài khi biến môi trường npm_config_allow_scripts đang được đặtChạy đúng lệnh thay thế mà công cụ CopilotKit in ra trên màn hình

6. Gỡ cài đặt / cập nhật

  • Gỡ: AG-UI không cài gì vào hệ thống. Tắt ứng dụng (Ctrl + C) rồi xóa thư mục dự án là xong. Nếu không dùng nữa, bạn có thể thu hồi khóa API trên trang của nhà cung cấp.
  • Cập nhật công cụ tạo dự án: lệnh npx create-ag-ui-app@latest luôn lấy bản mới nhất, không cần làm gì thêm.
  • Cập nhật thư viện trong dự án đã tạo: trong thư mục dự án, chạy:
npm update

Lưu ý khi lên bản 1.0: dự án tạo từ trước tháng 9/2026 có thể dùng thư viện AG-UI 0.x. Đọc trang "Migrating to 1.0" trong tài liệu chính thức (https://docs.ag-ui.com) trước khi nâng cấp lớn.

7. Câu hỏi hay gặp

AG-UI có mất tiền không? Không. AG-UI là mã nguồn mở, giấy phép MIT. Bạn chỉ trả tiền cho nhà cung cấp mô hình AI mà agent của bạn dùng.

Có cần mạng không? Có. Cần mạng để tải thư viện và để agent gọi tới mô hình AI qua khóa API.

Dữ liệu chat có bị gửi đi đâu không? Nội dung bạn gõ được gửi tới agent của bạn, rồi tới nhà cung cấp mô hình mà bạn cấu hình (ví dụ OpenAI). Bản thân giao thức AG-UI chỉ là cách định dạng dữ liệu giữa agent và giao diện.

AG-UI khác MCP thế nào? MCP giúp agent dùng công cụ và dữ liệu bên ngoài. AG-UI giúp agent hiển thị và tương tác với người dùng trong ứng dụng. Hai cái dùng chung được với nhau.

Tôi dùng framework khác, không có trong danh sách thì sao? README liệt kê SDK cho TypeScript và Python, cùng các SDK cộng đồng cho Go, Rust, Java, Kotlin, .NET, Dart, Ruby, C++. Bạn cũng có thể tự phát sự kiện theo đặc tả ở https://docs.ag-ui.com.

GitHot tự viết và kiểm tra lại với tài liệu chính thức của dự án. Thấy bước nào sai hoặc khó hiểu, hãy nhắn cho GitHot qua các kênh ở cuối trang.

XEM TẠI SAO NÓ HOT

Xem review gốc

Quay lại video đã dẫn bạn đến đây.

Xem trên TikTok ↗

Không bỏ lỡ repo tiếp theo

Mỗi repo mới đều có video review kèm hướng dẫn cài đặt tại đây.

Theo dõi trên TikTok ↗

LỊCH SỬ

Đã lên GitHub Trending

  1. Ngày 17/11#1019.854
  2. Ngày 16/11#118.585
  3. Ngày 15/11#217.646
  4. Ngày 14/11#817.239