Antigravity CLI và SDK: chạy agent từ dòng lệnh, đặt rules và quyền để tự động hoá dự án web

Google Antigravity nâng cao, phần tiếp theo của bài nhập môn

Cập nhật tháng 10/2026. Antigravity CLI và SDK thay đổi nhanh; tên cờ lệnh, đường dẫn cấu hình và hạn mức có thể khác đôi chút khi bạn đọc. Mọi chi tiết kỹ thuật trong bài lấy từ tài liệu chính thức tại antigravity.google, được dẫn ở cuối bài.

Ở bài nhập môn Google Antigravity, bạn đã giao agent dựng một trang đặt lịch qua ứng dụng có giao diện đồ hoạ: đọc kế hoạch, bình luận, duyệt. Cách đó hợp với việc mới, cần người nhìn từng bước. Nhưng dự án web đang chạy có nhiều việc lặp lại y hệt, như soát thay đổi trước khi commit hay viết ghi chú bàn giao. Những việc này nên chạy bằng một câu lệnh, cùng một bộ quy tắc.

1. Antigravity CLI và SDK là gì

Từ Google I/O tháng 5/2026, Antigravity có bốn bề mặt dùng chung một bộ máy agent (harness). Theo bài viết chính thức trên Google Cloud Blog, vì chung bộ máy nên rules, skills và plugin dùng được ở cả bốn; chọn bề mặt nào là chọn cách làm việc, không phải chọn năng lực.

Nếu đội bạn từng dùng Gemini CLI: tài liệu chuyển đổi chính thức cho biết Antigravity CLI vẫn đọc tệp GEMINI.md và AGENTS.md, còn extension cũ được chuyển thành plugin bằng lệnh agy plugin import gemini.

2. Khi nào dùng CLI, khi nào dùng ứng dụng 2.0

Nguyên tắc dễ nhớ: việc cần người nhìn thì dùng 2.0, việc cần lặp lại đúng khuôn thì dùng CLI.

• Dùng Antigravity 2.0 khi làm tính năng mới, cần duyệt kế hoạch và ảnh chụp giao diện, hoặc đặt lịch cho agent chạy định kỳ.
• Dùng CLI khi cần chạy trên máy chủ không có màn hình, gắn vào Git hook, đưa vào script bàn giao, hoặc khi bạn quen bàn phím và muốn chạy agent nền mà không khoá cửa sổ đang làm.
• Dùng SDK khi CLI đã không đủ: cần công cụ Python riêng (ví dụ gọi API nội bộ), cần lưu phiên làm việc, gắn hook vòng đời hoặc đưa agent lên Google Cloud.

Nếu bạn đã đọc bài Codex exec và GitHub Actions, hãy hình dung agy -p là vai tương đương phía Google. Bức tranh rộng hơn giữa các công cụ có ở bài so sánh trợ lý lập trình AI cho đội nhỏ.

3. Thực hành: tự động hoá việc lặp lại trong một dự án web

Tình huống minh hoạ: một agency 5 người ở Đà Nẵng làm website WordPress cho khách. Mỗi lần bàn giao, trưởng nhóm tự soát: có lộ khoá API không, có sửa nhầm tệp cấu hình không. Mục tiêu là biến việc soát đó thành câu lệnh ai cũng chạy giống nhau.

4. Ba lệnh mẫu

Đổi tên tệp, thư mục cho đúng dự án của bạn. Các lệnh dưới đây chạy trong thư mục gốc của dự án.

Mẫu 1: Tệp quyền tối thiểu cho việc soát thay đổi

Chỉ ba lệnh Git chỉ-đọc được tự chạy; đẩy code, xoá tệp và sửa wp-config.php bị chặn hẳn; mọi lệnh khác phải hỏi, tức bị từ chối khi chạy không tương tác.

Mẫu 2: Rule chỉ nạp khi agent đụng tới tệp PHP

Mẫu 3: Soát thay đổi trước khi commit, kết quả dạng JSON

Đưa lệnh này vào Git hook pre-commit hoặc một script kiem-tra.sh dùng chung, và cho script dừng lại nếu trường status khác SUCCESS. Lệnh cần công cụ jq để đọc JSON.

5. Khi nào cần đến SDK

Theo trang tổng quan SDK, đây là thư viện Python cài bằng pip install google-antigravity, xác thực bằng biến môi trường GEMINI_API_KEY hoặc qua Vertex AI với tài khoản Google Cloud. Hai lớp chính là Agent và LocalAgentConfig. SDK cho viết công cụ bằng hàm Python, chính sách duyệt công cụ bằng code, hook vòng đời, agent con và lưu phiên.

Với agency nhỏ, hãy dùng CLI và skill trước, chỉ chuyển sang SDK khi cần nối agent vào hệ thống riêng. Tài liệu không ghi rõ SDK đang thử nghiệm hay ổn định, nên thử trên dự án nội bộ trước.

6. Lỗi thường gặp và cách khắc phục

• Rule viết xong mà agent không làm theo. Tệp trong .agents/rules/ thiếu phần đầu YAML hoặc ghi sai giá trị trigger (ví dụ alwaysOn thay vì always_on) sẽ bị bỏ qua mà không báo lỗi. Tệp đặt trong thư mục con như .agents/rules/php/ cũng không được quét, trừ khi khai báo trong .agents/rules.json.
• Lệnh -p chạy xong, mã thoát 0 nhưng agent không làm gì. Thao tác cần duyệt đã bị từ chối mềm. Đọc phần cảnh báo ở stderr, rồi thêm đúng lệnh đó vào allow.
• Muốn nhanh nên dùng –dangerously-skip-permissions. Tài liệu cảnh báo cờ này duyệt mọi thao tác, kể cả ghi tệp và chạy lệnh. Không dùng cho dự án của khách; hãy viết danh sách allow hẹp.
• Cả đội cài mà mỗi máy một kiểu quyền. Tệp settings.json của CLI nằm trong thư mục người dùng, không nằm trong dự án. Hãy lưu một tệp mẫu trong kho mã và hướng dẫn mọi người chép vào, còn rules và skills thì để trong .agents/ để đi cùng dự án.

7. Bài tập thực hành

1. Cài Antigravity CLI, chạy agy trong một dự án thử, viết AGENTS.md 10–15 dòng mô tả quy ước của đội.
2. Tạo một rule kiểu glob cho loại tệp đội bạn hay sửa nhất (PHP, CSS hoặc JavaScript). Nhờ agent sửa một tệp khớp mẫu và kiểm tra nó có làm theo rule không.
3. Viết settings.json theo mẫu 1, chạy lệnh mẫu 3 trên một thay đổi có cố ý chèn một khoá API giả. Ghi lại agent có phát hiện không và mất bao lâu.

8. Thuật ngữ cần biết

• Chế độ không tương tác (headless): chạy agent bằng một câu lệnh, không có khung chat, in kết quả rồi thoát, dùng cho script và CI. Nguồn: Antigravity CLI Headless mode.
• Rule: chỉ dẫn và ràng buộc lâu dài mà agent tự nạp từ tệp trong dự án hoặc máy, theo bốn kiểu kích hoạt. Nguồn: Antigravity Rules.
• Skill: thư mục chứa tệp SKILL.md mô tả một quy trình nhiều bước, agent chỉ đọc toàn bộ khi cần. Nguồn: Antigravity Skills.
• Git hook: script Git tự chạy tại một thời điểm như trước khi commit, hợp để gắn bước soát tự động. Nguồn: git-scm.com.

9. Tìm hiểu thêm

• Getting started, thẻ CLI: lệnh cài cho từng hệ điều hành và lần chạy đầu.
• CLI best practices: chế độ quyền, agent con chạy nền, các lệnh gạch chéo.
• Permissions: cú pháp allow, ask, deny và thứ tự ưu tiên.
• Workflows to skills: chuyển workflow cũ sang skill.
• Antigravity SDK overview: cài đặt, xác thực và ví dụ mẫu.
• Choosing your surface (Google Cloud Blog): khi nào dùng 2.0, CLI, IDE hay SDK.

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

PDL Digital đào tạo và triển khai AI cho đội làm web và doanh nghiệp, từ viết quy tắc dự án, đặt quyền an toàn cho agent đến tự động hoá quy trình bàn giao. Xem trang đào tạo để chọn khoá phù hợp.