1. Giới thiệu
Việc thêm các tính năng vào một tác nhân hiện có (một chức năng mới dựa trên cơ sở dữ liệu) thường có nghĩa là bạn phải viết mã khởi tạo, thiết lập các tích hợp và đảm bảo mọi thứ nhất quán với các mẫu đã có trong cơ sở mã. Antigravity đẩy nhanh mọi giai đoạn của quy trình này: phân tích cơ sở mã của bạn để xây dựng ngữ cảnh cần thiết, tạo ra các quy cách có cấu trúc và kế hoạch triển khai để bạn xem xét, đồng thời thực hiện các thay đổi về mã – tất cả đều được hướng dẫn bằng kiến thức chuyên môn mà công cụ này giúp bạn nắm bắt dưới dạng các kỹ năng có thể tái sử dụng và một quy tắc dự án nhằm thực thi các nguyên tắc không thể thương lượng. Lớp học lập trình này giới thiệu một cách để tăng cường mô hình Phát triển dựa trên quy cách của Antigravity bằng cách giới thiệu một chu kỳ mới để tăng cường tài liệu quy cách tham chiếu nhiều đến spec-kit
Sản phẩm bạn sẽ tạo ra
Một ứng dụng trợ lý nhà hàng chạy cục bộ có tính năng đặt chỗ được thêm thông qua một chu kỳ SDD hoàn chỉnh:
- Đặt chỗ – khách đặt bàn và kiểm tra thông tin đặt chỗ, được hỗ trợ bởi các công cụ cơ sở dữ liệu MCP Toolbox mới và bảng Cloud SQL
reservations - (Thử thách) – phát triển giao diện người dùng của riêng bạn cho tác nhân
- (Thử thách) – triển khai lên Google Cloud với sự trợ giúp của tác nhân Antigravity
Mã khởi đầu cung cấp một tác nhân ADK đang hoạt động với tính năng tìm kiếm trong trình đơn (từ khoá + ngữ nghĩa thông qua MCP Toolbox) và theo dõi lựa chọn ưu tiên về chế độ ăn (thông qua ToolContext). Bạn có thể mở rộng ứng dụng này mà không cần viết mã ứng dụng theo cách thủ công. Antigravity sẽ xử lý việc triển khai dựa trên các thông số kỹ thuật của bạn.
Kiến thức bạn sẽ học được
- Cách khởi động ngữ cảnh dự án để Antigravity hiểu một cơ sở mã hiện có
- Cách tạo các kỹ năng Antigravity đóng gói kiến thức về miền (ví dụ: mẫu lớp học lập trình ADK) để sử dụng lại
- Cách thiết lập một quy tắc dự án mà quy trình công việc SDD xác thực trong quá trình lập kế hoạch và phân tích
- Cách sử dụng quy trình phát triển dựa trên quy cách (SDD) trong Antigravity để thêm các tính năng một cách có hệ thống
- Cách mở rộng tác nhân ADK bằng các công cụ mới dựa trên cơ sở dữ liệu thông qua Hộp công cụ MCP
Điều kiện tiên quyết
- Google Antigravity và
gitđược cài đặt trên máy cục bộ - Tài khoản Google Cloud có tài khoản thanh toán dùng thử được bật
- Việc hoàn thành 4 lớp học lập trình ADK tiên quyết trước đó (hoặc kiến thức tương đương) sẽ giúp bạn hiểu được bối cảnh trường hợp sử dụng:
- Xây dựng tác nhân AI bằng ADK: Nền tảng
- Xây dựng tác nhân AI bằng ADK: Hỗ trợ bằng các công cụ
- Xây dựng các tác nhân AI liên tục bằng ADK và CloudSQL
- Triển khai, quản lý và theo dõi ADK Agent trên Cloud Run
- Cơ sở dữ liệu dưới dạng một công cụ: RAG dựa trên tác nhân với ADK, MCP Toolbox và Cloud SQL
2. Thiết lập môi trường
Bước này sao chép kho lưu trữ khởi động, xác thực bằng Google Cloud, cung cấp cơ sở dữ liệu Cloud SQL và chuẩn bị môi trường Antigravity cục bộ.
Sao chép kho lưu trữ khởi đầu
Mở một cửa sổ dòng lệnh trong Antigravity (hoặc cửa sổ dòng lệnh của hệ thống). Nhân bản kho lưu trữ đồng hành và nhập thư mục:
git clone https://github.com/alphinside/sdd-adk-antigravity-starter.git sdd-adk-agents-agy
cd sdd-adk-agents-agy
Mở kho lưu trữ đã sao chép trong Antigravity. File (Tệp) -> Open Folder (Mở thư mục) -> chọn thư mục được sao chép sdd-adk-agents-agy
Xoá kho lưu trữ từ xa ở nguồn. Quy trình làm việc SDD tạo các nhánh git cho thông số kỹ thuật của tính năng – việc xoá kho lưu trữ từ xa sẽ ngăn chặn việc vô tình đẩy vào kho lưu trữ khởi động:
git remote remove origin
Cài đặt các điều kiện tiên quyết
Chạy tập lệnh điều kiện tiên quyết. Nó kiểm tra (và cài đặt nếu thiếu) git, curl, gcloud, uv, Python 3.12 và MCP Toolbox:
bash scripts/setup_prerequisites.sh
Xác thực bằng Google Cloud
Chạy hai lệnh xác thực. Cả hai đều mở một trình duyệt để xác thực bằng OAuth:
gcloud auth login
gcloud auth application-default login
Vì bạn đang làm việc cục bộ với Antigravity, nên bạn sẽ xác thực theo cách thủ công. auth login xác thực CLI gcloud. application-default login xác thực các SDK Google Cloud mà ứng dụng của bạn sử dụng – cả lệnh gọi Vertex AI của ADK và trình kết nối Cloud SQL Python đều dựa vào Thông tin xác thực mặc định của ứng dụng.
Thiết lập dự án trên Google Cloud
Ghi các biến vị trí vào .env trước khi chạy tập lệnh thiết lập dự án:
echo "GOOGLE_CLOUD_LOCATION=global" > .env
echo "REGION=us-central1" >> .env
GOOGLE_CLOUD_LOCATION=globalđược dùng cho các lệnh gọi Vertex AI / Gemini API.REGION=us-central1được dùng cho Cloud SQL và cơ sở hạ tầng GCP khác
Tải xuống và chạy tập lệnh thiết lập dự án. Thao tác này sẽ tạo hoặc xác thực một dự án trên Google Cloud có tính năng thanh toán dùng thử và lưu mã dự án vào .env rồi lấy mã dự án đó:
curl -sL https://raw.githubusercontent.com/alphinside/cloud-trial-project-setup/main/setup_verify_trial_project.sh -o setup_verify_trial_project.sh
bash setup_verify_trial_project.sh && source .env
Bật các API bắt buộc:
gcloud services enable \
aiplatform.googleapis.com \
sqladmin.googleapis.com \
compute.googleapis.com \
cloudresourcemanager.googleapis.com
Cung cấp Cloud SQL
Đặt mật khẩu cơ sở dữ liệu rồi thêm mật khẩu đó vào .env:
export DB_PASSWORD=codelabpassword
echo "DB_PASSWORD=${DB_PASSWORD}" >> .env
Tạo phiên bản Cloud SQL:
gcloud sql instances create restaurant-db \
--database-version=POSTGRES_17 \
--edition=ENTERPRISE \
--region=${REGION} \
--availability-type=ZONAL \
--tier=db-custom-1-3840 \
--root-password=${DB_PASSWORD} \
--enable-google-ml-integration \
--database-flags cloudsql.enable_google_ml_integration=on &
Cấp db-custom-1-3840 là cấp tối thiểu bắt buộc để tích hợp ML của Vertex AI. Cờ --enable-google-ml-integration cho phép Cloud SQL gọi trực tiếp các mô hình nhúng Gemini từ SQL – điều này hỗ trợ tính năng tìm kiếm ngữ nghĩa.
Cài đặt các phần phụ thuộc
Mở một thẻ thiết bị đầu cuối mới. Đảm bảo rằng bạn vẫn đang ở trong thư mục dự án kho lưu trữ được sao chép và tải lại các biến môi trường:
source .env
Chúng ta sẽ sử dụng uv làm trình quản lý dự án Python. uv là một trình quản lý dự án và gói Python nhanh chóng được viết bằng Rust ( docs ). Lớp học lập trình này sử dụng uv để tăng tốc độ và đơn giản hoá. Cài đặt các phần phụ thuộc Python:
uv sync
Sau đó, hãy cập nhật tệp .env của tác nhân ADK bằng cấu hình dự án của bạn:
cat > restaurant_concierge/.env <<EOF
GOOGLE_CLOUD_PROJECT=${GOOGLE_CLOUD_PROJECT}
GOOGLE_CLOUD_LOCATION=global
GOOGLE_GENAI_USE_VERTEXAI=True
EOF
Giờ đây, chúng ta sẽ có tất cả kho lưu trữ tác nhân ADK khởi động cần thiết để làm việc. Giờ hãy thảo luận thêm về Antigravity và Spec-driven development trong phần tiếp theo trong khi chờ mọi thứ sẵn sàng
3. Khám phá mã khởi đầu và tìm hiểu về phương pháp phát triển dựa trên thông số kỹ thuật
Bước này sẽ hướng dẫn bạn tìm hiểu cấu trúc mã khởi đầu, giới thiệu phương pháp luận Phát triển dựa trên quy cách, gieo hạt cơ sở dữ liệu và xác minh rằng tác nhân cơ sở hoạt động trước khi bạn bắt đầu mở rộng tác nhân đó.
Cấu trúc dự án
Mở dự án kho lưu trữ được sao chép trong trình chỉnh sửa Antigravity và xem bố cục thư mục:
sdd-adk-agents-agy/ ├── .agents/ │ ├── workflows/ # SDD slash commands (/speckit.*) – manual trigger │ │ ├── speckit.specify.md │ │ ├── speckit.clarify.md │ │ ├── speckit.plan.md │ │ ├── speckit.tasks.md │ │ ├── speckit.analyze.md │ │ ├── speckit.implement.md │ │ ├── speckit.checklist.md │ │ └── speckit.constitution.md │ ├── skills/ # Antigravity skills (loaded on demand, agent determined) │ │ ├── adk-agent-development/ │ │ │ ├── SKILL.md # ADK patterns │ │ │ └── examples/ │ │ │ ├── basic_agent.py │ │ │ ├── Dockerfile │ │ │ ├── server.py │ │ │ ├── stateful_agent.py │ │ │ ├── toolbox_agent.py │ │ │ ├── tools_agent.py │ │ │ └── tools.yaml │ │ └── repo-research/ │ │ └── SKILL.md # Repo analysis │ └── rules/ # Always-active context ├── .specify/ # spec-kit SDD templates and memory │ ├── memory/constitution.md │ ├── templates/ │ └── scripts/ ├── restaurant_concierge/ # ADK agent package │ ├── __init__.py │ ├── agent.py # LlmAgent + ToolContext tools + Toolbox integration │ └── .env # Vertex AI configuration ├── server.py # FastAPI server wrapping the agent ├── tools.yaml # MCP Toolbox tool definitions ├── scripts/ # Setup scripts └── pyproject.toml
Tệp chính
Tệp ứng dụng của nhân viên hỗ trợ
restaurant_concierge/agent.py– Tác nhân cốt lõi. MộtLlmAgentkết hợp các công cụ cơ sở dữ liệu của MCP Toolbox với tính năng theo dõi lựa chọn ưu tiên về chế độ ăn dựa trênToolContext. Tác nhân tải tất cả các công cụ từ máy chủ Hộp công cụ và thêm hai hàm Python (save_dietary_preference,get_dietary_preferences) sử dụngToolContextđể quản lý trạng thái.tools.yaml– Định nghĩa về công cụ MCP Toolbox. Có 3 công cụ tìm kiếm trong trình đơn được xác định: tìm kiếm bằng từ khoá (search_menu), tìm kiếm ngữ nghĩa thông quapgvector(semantic_search_menu) và bộ lọc danh mục (get_menu_by_category). Hiện chưa có công cụ đặt phòng – bạn sẽ thêm những công cụ đó sauserver.py– Một máy chủ FastAPI tối thiểu, minh hoạ cách bạn có thể truy cập vào ADK dưới dạng đối tượng FastAPI.get_fast_api_app()từ ADK cung cấp các điểm cuối tích hợp, bao gồm cả/run_ssecho API quản lý phiên và truyền phát trực tiếp SSE.
Antigravity Files
.agents/skills/adk-agent-development/SKILL.md– Một kỹ năng được định cấu hình sẵn ( do Antigravity tạo) chứa các mẫu tham chiếu cô đọng từ cả 4 lớp học lập trình ADK. Trang này hiện không hoạt động (thiếu phần đầu YAML) – bạn sẽ cần cập nhật trang này sau. Antigravity tự động tải kỹ năng này khi phát hiện thấy công việc liên quan đến các tính năng của tác nhân ADK và ví dụ về các tính năng đó – đây là kiến thức hướng dẫn Antigravity khi lập kế hoạch cho tính năng đặt phòng sau này.agents/skills/repo-research/SKILL.md– Một kỹ năng giúp Antigravity phân tích kho lưu trữ theo từng bước và tạo ra một tài liệu ngữ cảnh dự án có cấu trúc. Công cụ này sử dụng phương pháp gồm 4 giai đoạn: quét bề mặt (chỉ cây thư mục), tệp cấu hình và siêu dữ liệu, điểm truy cập và mô hình dữ liệu, sau đó là các bước đi sâu có mục tiêu – mỗi giai đoạn dừng lại và ghi lại kết quả trước khi chuyển sang giai đoạn tiếp theo. Giống như kỹ năng ADK, kỹ năng này sẽ không hoạt động cho đến khi bạn thêm phần đầu YAML sau này. Sau khi kích hoạt, hãy gọi tính năng này để tạo.agents/rules/project-context.md– một tài liệu toàn diện về quy trình tham gia, bao gồm cấu trúc, các phần phụ thuộc trong thời gian chạy, giao diện API và bảng thuật ngữ theo miền.
Phát triển dựa trên thông số kỹ thuật: từ lập kế hoạch tích hợp của Antigravity đến SDD có cấu trúc
Trợ lý lập trình AI giúp bạn dễ dàng tạo mã từ một câu lệnh. Rủi ro: bạn mô tả một tính năng trong một câu, trợ lý viết hàng trăm dòng và bạn chấp nhận vì thấy có vẻ đúng. Đôi khi, việc này được gọi là "lập trình theo cảm tính" – bạn điều hướng theo cảm giác, chấp nhận hoặc từ chối đầu ra dựa trên việc đầu ra có vẻ hoạt động hay không. Ngôn ngữ này phù hợp với các nguyên mẫu và tập lệnh dùng một lần. Điều này sẽ không hiệu quả khi cơ sở mã tăng lên, khi các tính năng tương tác hoặc khi bạn xem lại mã sau vài tuần và không thể tái tạo lý do đưa ra quyết định.
Phát triển dựa trên quy cách (SDD) sẽ thêm cấu trúc vào vòng lặp này. Trước khi tạo bất kỳ mã nào, bạn sẽ viết một bản đặc tả: chức năng của tính năng, đối tượng mà tính năng phục vụ, tiêu chí thành công. Trợ lý AI sẽ dựa vào bản quy cách đó để hoạt động, và bạn cũng vậy khi xem xét kết quả đầu ra của trợ lý. Đặc tả này trở thành nguồn đáng tin cậy duy nhất cho ý định. Nếu mã khác với quy cách, bạn sẽ phát hiện ra trong quá trình xem xét. Nếu các yêu cầu thay đổi, trước tiên, bạn hãy cập nhật thông số kỹ thuật, sau đó tạo lại. Các quyết định được ghi lại chứ không phải ứng biến.
Sự đánh đổi là có thật: SDD chậm hơn mỗi tính năng so với mã rung. Bạn viết tài liệu trước khi viết mã. Nhưng lợi ích sẽ tăng lên theo thời gian – mọi thay đổi trong tương lai đối với cơ sở mã đều có bối cảnh, mọi hoạt động triển khai do AI tạo đều có hợp đồng có thể xem xét và bạn có thể giới thiệu cho cộng tác viên (con người hoặc AI) bằng cách chỉ cho họ xem các quy cách thay vì giải thích các quyết định dựa trên trí nhớ.
Antigravity đã tuân theo các nguyên tắc phát triển dựa trên quy cách. Khi bạn đặt tác nhân ở Chế độ lập kế hoạch, tác nhân sẽ tạo ra hai cấu phần phần mềm trước khi viết bất kỳ mã nào:
- Kế hoạch triển khai – thông tin tổng quan về phương pháp kỹ thuật được đề xuất, các thay đổi về tệp và quyết định về cấu trúc
- Danh sách việc cần làm – danh sách các mục công việc được phân chia theo cấu trúc
Antigravity yêu cầu bạn xem xét và phê duyệt các cấu phần phần mềm này trước khi thực thi. Vòng lặp lập kế hoạch rồi triển khai là cốt lõi của quá trình phát triển dựa trên quy cách: quy cách hướng dẫn mã chứ không phải ngược lại.
Lớp học lập trình này sẽ tiếp tục xây dựng nền tảng đó bằng một quy trình có ý kiến, được kiểm soát phiên bản dựa trên spec-kit – một khung phát triển dựa trên quy cách của GitHub. Mỗi tính năng đều trải qua một quy trình có chủ đích, trong đó mỗi cấu phần phần mềm là một tài liệu độc lập mà bạn có thể xem xét, chỉnh sửa và theo dõi trong git. Quy trình này bao gồm 2 giai đoạn kiểm tra chất lượng không bắt buộc (làm rõ và phân tích) để phát hiện các vấn đề trước khi chúng trở thành vấn đề triển khai:
Giai đoạn | Cấu phần phần mềm | Mục đích |
|
| Xác định NỘI DUNG cần xây dựng (hướng đến người dùng, không phụ thuộc vào công nghệ) |
| Cập nhật vào | Xác định các khu vực chưa được chỉ định, đặt câu hỏi làm rõ có mục tiêu, mã hoá câu trả lời trở lại vào bản đặc tả |
|
| Thiết kế CÁCH xây dựng (phương pháp kỹ thuật, mô hình dữ liệu, nghiên cứu) |
|
| Chia kế hoạch thành các bước có thứ tự và có thể thực hiện |
| Báo cáo phân tích | Xem xét các nhiệm vụ để tìm rủi ro, điểm thiếu sót hoặc trường hợp đặc biệt còn thiếu trước khi triển khai |
| Thay đổi mã | Thực hiện các nhiệm vụ và đánh dấu vào từng nhiệm vụ |
Mọi cấu phần phần mềm đều được duy trì dưới dạng một tệp trong specs/<feature-branch>/, được kiểm soát phiên bản trong git và có thể sử dụng lại. Nếu cuộc trò chuyện bị gián đoạn hoặc bạn muốn xem lại các quyết định sau này, thì tài liệu đặc tả luôn có sẵn chứ không bị chôn vùi trong nhật ký trò chuyện.
Kho lưu trữ khởi đầu bao gồm các quy trình SDD này trong .agents/workflows/ và các mẫu trong .specify/templates/. Sau này, bạn sẽ dùng các tính năng này để thêm vào tác nhân.
4. Hoàn tất quá trình thiết lập Cloud SQL và đảm bảo Base Agent hoạt động
Chuyển lại sang thẻ dòng lệnh nơi đang chạy lệnh tạo Cloud SQL. Sau khi quá trình này hoàn tất, hãy xác minh rằng phiên bản đã sẵn sàng:
gcloud sql instances describe restaurant-db --format="value(state)"
Nếu kết quả cho thấy RUNNABLE, hãy tiếp tục. Nếu kết quả là PENDING_CREATE, hãy đợi một chút rồi chạy lại lệnh.
Cấp quyền truy cập cho tài khoản dịch vụ Cloud SQL vào Vertex AI (bắt buộc đối với chức năng nhúng trong cơ sở dữ liệu):
SERVICE_ACCOUNT=$(gcloud sql instances describe restaurant-db --format="value(serviceAccountEmailAddress)")
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \
--member="serviceAccount:$SERVICE_ACCOUNT" \
--role="roles/aiplatform.user" \
--quiet
Tạo cơ sở dữ liệu:
gcloud sql databases create restaurant_db --instance=restaurant-db
Bạn sẽ thấy kết quả như sau
Creating Cloud SQL database...done. Created database [restaurant_db]. instance: restaurant-db name: restaurant_db project: <your-project-id>
Gieo dữ liệu vào cơ sở dữ liệu
Tải các biến môi trường và chạy tập lệnh gieo dữ liệu cơ sở dữ liệu để tạo giản đồ và chèn 16 mục trong trình đơn:
source .env
uv run python scripts/seed_db.py
Kết quả đầu ra dự kiến:
Creating extensions... Creating menu_items table... Inserting 16 menu items... Seeded 16 menu items. Done.
Tạo các vectơ nhúng cho tìm kiếm ngữ nghĩa:
uv run python scripts/generate_embeddings.py
Kết quả đầu ra dự kiến:
Generating embeddings for 16 menu items... Generated embeddings for 16 menu items.
Thao tác này sử dụng hàm embedding() tích hợp của Cloud SQL (thông qua tiện ích google_ml_integration) để gọi gemini-embedding-001 trực tiếp từ SQL. Các vectơ 3072 chiều được lưu trữ trong cột embedding của menu_items – không cần mã nhúng phía ứng dụng.
Kiểm thử nhân viên hỗ trợ cơ bản
Khởi động MCP Toolbox dưới dạng một quy trình nền:
set -a; source .env; set +a # Export env variables to child process
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &
Hộp công cụ phân phát các công cụ cơ sở dữ liệu qua HTTP. Nhân viên hỗ trợ sẽ kết nối với thiết bị này vào lúc http://127.0.0.1:5000.
Khởi động giao diện người dùng dành cho nhà phát triển ADK:
uv run adk web .
Mở Giao diện người dùng dành cho nhà phát triển trong trình duyệt. Sau đó, hãy kiểm thử tác nhân bằng những câu lệnh sau:
What appetizers do you have?
I'm vegetarian
Can I make a reservation for tomorrow?
Dừng giao diện người dùng dành cho nhà phát triển ADK bằng cách nhấn Ctrl+C hai lần. Để Toolbox chạy ở chế độ nền – bạn sẽ dùng lại công cụ này sau
5. Khởi động bối cảnh dự án bằng Antigravity
Bây giờ, hãy mô phỏng mọi thứ với một điều kiện "khá gần" với công việc hằng ngày của chúng ta:
- Kho lưu trữ không được quản lý tốt
- README lỗi thời
- Tài liệu không được cập nhật thường xuyên
Điều đầu tiên chúng ta muốn làm trong trường hợp này thường là tạo một bản đồ hoặc bối cảnh về dự án mà chúng ta muốn Antigravity thực hiện. Bước này cho thấy một ví dụ về cách giúp Antigravity hiểu rõ cơ sở mã hiện có bằng cách tạo một kỹ năng phân tích kho lưu trữ và tạo một tài liệu bối cảnh dự án.
Nó cũng thiết lập hiến pháp dự án – những nguyên tắc không thể thương lượng mà quy trình SDD xác thực. Nhờ đó, Antigravity có được bối cảnh và các ràng buộc cần thiết cho các chu kỳ SDD sau này
Hệ phân cấp ngữ cảnh Antigravity
Antigravity sử dụng 3 cấp độ bối cảnh, mỗi cấp độ có một phạm vi khác nhau:
- Quy tắc (
.agents/rules/): Hướng dẫn luôn hoạt động. Mọi cuộc trò chuyện trong không gian làm việc này đều có thể thấy các quy tắc ( nếu bạn đã kích hoạt). Sử dụng các quy tắc cho bối cảnh trên toàn dự án, chẳng hạn như quyết định về cấu trúc, tiêu chuẩn mã hoá hoặc thông tin về ngăn xếp công nghệ. - Kỹ năng (
.agents/skills/): Kiến thức theo yêu cầu. Antigravity chỉ tải một kỹ năng khi tác vụ hiện tại khớp với trườngdescriptioncủa kỹ năng đó. Sử dụng các kỹ năng để tham khảo tài liệu dành riêng cho từng lĩnh vực. - Quy trình công việc (
.agents/workflows/): Lệnh/sẽ kích hoạt các câu lệnh đã lưu. Sử dụng quy trình công việc cho các quy trình nhiều bước có thể lặp lại, chẳng hạn như quy trình SDD.
Kích hoạt các kỹ năng
Kho lưu trữ khởi đầu có 2 kỹ năng được viết sẵn trong .agents/skills/. Các tệp này chứa hướng dẫn chi tiết nhưng bắt đầu bằng chú thích TODO(codelab) thay vì phần đầu YAML bắt buộc. Nếu không có phần đầu, Antigravity sẽ không thể phát hiện ra các tệp này.
Các kỹ năng chống lại trọng lực yêu cầu một khối frontmatter YAML ở đầu tệp có 2 trường:
name– giá trị nhận dạng duy nhất của kỹ năngdescription– bản tóm tắt bằng ngôn ngữ tự nhiên mà Antigravity so khớp khi quyết định tải kỹ năng nào cho một yêu cầu nhất định
Mở
.agents/skills/adk-agent-development/SKILL.md
trong trình chỉnh sửa. Thay thế 2 dòng nhận xét TODO(codelab) ở trên cùng bằng phần đầu này:
---
name: adk-agent-development
description: Comprehensive guide for building, developing, and deploying AI agents using Google's Agent Development Kit (ADK) with Gemini models, covering agent creation, tools, state management, persistence, deployment, and database integration via MCP Toolbox.
---
Mở
.agents/skills/repo-research/SKILL.md
trong trình chỉnh sửa. Thay thế 2 dòng nhận xét TODO(codelab) ở trên cùng bằng phần đầu này:
---
name: repo-research
description: Analyze a repository's structure, technologies, and patterns to create or update a project context document. Use when asked to research, analyze, or understand a codebase.
---
Xác minh rằng cả hai kỹ năng đều có phần đầu hợp lệ:
head -4 .agents/skills/adk-agent-development/SKILL.md
head -4 .agents/skills/repo-research/SKILL.md
Mỗi trường phải cho thấy dấu phân cách --- bao bọc các trường name: và description:. Nếu thiếu dấu phân cách hoặc trường, Antigravity sẽ không nhận ra kỹ năng.
Cả hai kỹ năng này đều được tải theo yêu cầu – Antigravity so khớp yêu cầu của bạn với trường description và chỉ lấy hướng dẫn đầy đủ khi có liên quan.
Tạo bối cảnh dự án
Đảm bảo thư mục quy tắc tồn tại:
mkdir -p .agents/rules
Trong hộp Agent Manager/Chat (Trình quản lý/Trò chuyện của Antigravity) (nhấn ctrl + L ở chế độ chỉnh sửa), hãy bắt đầu một cuộc trò chuyện mới. Loại:
Research this repository and create a project context document
Antigravity sẽ so khớp yêu cầu của bạn với kỹ năng repo-research và bắt đầu phân tích cơ sở mã một cách có hệ thống. Công cụ này đọc các tệp cấu hình, mã nguồn và tài liệu, sau đó điền thông tin vào mẫu ngữ cảnh dự án bằng những thông tin tìm được.
Sau khi hoàn tất, hãy mở .agents/rules/project-context.md trong trình chỉnh sửa. Nội dung này chứa thông tin cụ thể về dự án: ngăn xếp công nghệ (Python 3.12, ADK, MCP Toolbox, Cloud SQL), cấu trúc dự án, mô hình dữ liệu (bảng menu_items có pgvector) và các công cụ tích hợp bên ngoài.
Đặt quy chế dự án
Quy trình công việc SDD tham chiếu đến một bản quy chế dự án tại .specify/memory/constitution.md trong quá trình lập kế hoạch và phân tích. Quy trình /speckit.plan sẽ chạy "Kiểm tra nội dung vi phạm" đối với nội dung đó và /speckit.analyze sẽ gắn cờ các lỗi vi phạm là NGHIÊM TRỌNG. Nếu hiến pháp được để trống dưới dạng mẫu có mã thông báo giữ chỗ, thì các bước kiểm tra này sẽ không có gì để xác thực – các kế hoạch và phân tích sẽ chạy mà không có biện pháp bảo vệ.
Hiến pháp xác định các nguyên tắc không thể thương lượng của dự án. Đây là một kho lưu trữ nhỏ do một nhà phát triển duy trì, vì vậy, quy tắc này phải phản ánh phạm vi đó – giữ cho mọi thứ đơn giản, nhất quán và tránh thiết kế quá mức.
Trong Agent Manager của Antigravity, hãy bắt đầu một cuộc trò chuyện mới. Chạy quy trình xử lý hiến pháp:
/speckit.constitution This is a small restaurant concierge ADK agent maintained by one developer. Set 3 principles: (1) All database operations go through MCP Toolbox tool definitions in tools.yaml — no raw SQL in Python code, no ORM. (2) Session state uses ADK ToolContext — no custom state management, no external state stores. (3) Keep it simple — follow existing file and naming conventions exactly.
Antigravity điền các nguyên tắc cụ thể vào mẫu hiến pháp, chỉ định một phiên bản (1.0.0) và chạy quy trình kiểm tra tính nhất quán trên các mẫu SDD.
Xem lại bản hiến pháp đã tạo tại .specify/memory/constitution.md. Xác minh rằng 3 nguyên tắc này có xuất hiện và được nêu rõ ràng.
6. SDD Cycle — Add Reservation Feature
Bước này hướng dẫn bạn thực hiện một chu kỳ SDD hoàn chỉnh để thêm tính năng đặt chỗ cho trợ lý ảo của nhà hàng. Bạn sẽ điều khiển Antigravity qua từng giai đoạn – chỉ định, làm rõ, lập kế hoạch, thực hiện các nhiệm vụ, phân tích, triển khai – quan sát cách từng cấu phần phần mềm được xây dựng dựa trên cấu phần phần mềm trước đó. Đây là trải nghiệm học tập cốt lõi của lớp học lập trình.
Chỉ định đối tượng
Trong Agent Manager của Antigravity, hãy bắt đầu một cuộc trò chuyện mới. Nhập lệnh /speckit.specify về quy trình làm việc kèm theo nội dung mô tả tính năng:
/speckit.specify Add reservation booking capability to the restaurant concierge agent. Guests should be able to make a table reservation by providing their name, party size, date, and time. They should also be able to check existing reservations. The agent should confirm reservation details before booking and handle special requests (e.g., "window seat", "birthday celebration").
Antigravity tạo một nhánh tính năng, tạo một tài liệu đặc tả và chạy quy trình xác thực chất lượng. Nếu Antigravity đặt câu hỏi làm rõ, hãy trả lời dựa trên nội dung mô tả tính năng ở trên.
Quy cách này tập trung vào ĐIỀU GÌ và TẠI SAO chứ không phải CÁCH THỨC. Nội dung này mô tả trải nghiệm người dùng ("Khách có thể đặt chỗ bằng cách cung cấp tên, số người, ngày và giờ") mà không đề cập đến bảng SQL, tools.yaml hoặc API ADK. Thông tin chi tiết về việc triển khai sẽ có trong giai đoạn lập kế hoạch.
Xem lại quy cách đã tạo tại specs/<branch-name>/spec.md. Xác minh để đảm bảo tài liệu này ghi lại các yêu cầu về chức năng và tiêu chí thành công.
Làm rõ quy cách (không bắt buộc)
Chạy quy trình làm rõ để xác định và giải quyết các khu vực không được chỉ định rõ trong quy cách:
/speckit.clarify
Antigravity quét quy cách để tìm những điểm mơ hồ, tiêu chí chấp nhận còn thiếu và các yêu cầu chưa được chỉ định rõ. Đưa ra các câu hỏi làm rõ có mục tiêu – mỗi câu hỏi đều có thể trả lời bằng một lựa chọn hoặc cụm từ ngắn gọn. Câu trả lời của bạn được mã hoá trực tiếp trở lại bản đặc tả, giúp bản đặc tả chính xác hơn trước khi bắt đầu lập kế hoạch.
Lập kế hoạch triển khai
Chạy quy trình lập kế hoạch:
/speckit.plan
Antigravity tạo ra một kế hoạch kỹ thuật thông qua 2 giai đoạn:
- Giai đoạn nghiên cứu – giải quyết những điều chưa biết về cơ sở mã hiện có, tạo
research.md - Giai đoạn thiết kế – tạo
data-model.md(định nghĩa thực thể đặt phòng) và cập nhậtproject-context.md
Antigravity nên sử dụng kỹ năng adk-agent-development trong quá trình lập kế hoạch. Xem xét các cấu phần phần mềm chính:
specs/<branch-name>/plan.md– phương pháp kỹ thuật: những tệp cần sửa đổi, những mẫu cần tuân theospecs/<branch-name>/data-model.md– định nghĩa về thực thể đặt phòng (cột, loại, mối quan hệ)specs/<branch-name>/research.md– quyết định đã đưa ra và lý do
Tạo việc cần làm
Chạy quy trình công việc về các việc cần làm
/speckit.tasks
Antigravity chia kế hoạch thành một danh sách việc cần làm có thứ tự trong specs/<branch-name>/tasks.md. Các tác vụ tuân theo định dạng danh sách kiểm tra nghiêm ngặt có mã nhận dạng, dấu hiệu ưu tiên và đường dẫn tệp, ví dụ:
- [ ] [T001] [P] Create reservations table schema in scripts/seed_db.py - [ ] [T002] [P] Add create_reservation tool to tools.yaml - [ ] [T003] [P] Add list_reservations tool to tools.yaml - [ ] [T004] [P] Update agent instruction in restaurant_concierge/agent.py
Các nhiệm vụ được sắp xếp theo giai đoạn: Thiết lập → Nền tảng → Câu chuyện người dùng → Hoàn thiện. Quét danh sách việc cần làm để hiểu rõ những nội dung sẽ được tạo và sửa đổi.
Phân tích các việc cần làm (không bắt buộc)
Chạy quy trình phân tích để xem xét các nhiệm vụ về rủi ro và lỗ hổng:
/speckit.analyze
Antigravity kiểm tra danh sách việc cần làm dựa trên quy cách và kế hoạch, tìm các trường hợp đặc biệt còn thiếu, các việc có thể xung đột hoặc khoảng trống giữa các yêu cầu của quy cách và công việc đã lên kế hoạch. Giải quyết các vấn đề nghiêm trọng trước khi triển khai.
7. Triển khai
Chạy quy trình triển khai:
/speckit.implement
Antigravity trình bày kế hoạch triển khai và cấu phần phần mềm của nhiệm vụ cuối cùng. Xem xét và phê duyệt để tiếp tục
Antigravity sẽ thực hiện các nhiệm vụ và đánh dấu từng nhiệm vụ khi hoàn thành. Khi hoàn tất, hệ thống sẽ trình bày phần Hướng dẫn hoàn chỉnh
Kiểm thử các thay đổi về mã
Sau khi hoàn tất quá trình triển khai, hãy xác minh rằng các thay đổi chính đã được thực hiện. Tên và nội dung chính xác của tệp có thể khác nhau, nhưng các mẫu này phải xuất hiện như trong tools.yaml và agent.py:
# Verify reservation tools were added to tools.yaml
grep -i "reservation" tools.yaml
Bạn sẽ thấy một số kết quả như sau
...
get_reservations_by_name:
Retrieve all reservations for a guest by their name. Uses case-insensitive
SELECT id, guest_name, party_size, reservation_datetime, special_requests, created_at
FROM reservations
ORDER BY reservation_datetime DESC
...
Và đối với agent.py
# Verify agent instruction was updated
grep -i "reservation" restaurant_concierge/agent.py
# Check what files changed
git diff --name-only
Có thể bạn sẽ thấy những thay đổi như sau
...
- **Table Reservations**: Help guests book a table or check their existing reservations.
## Reservation Booking Rules
When a guest wants to make a reservation, collect ALL of the following before confirming:
**IMPORTANT**: Before calling `book_reservation`, you MUST:
- Only call `book_reservation` after the guest says "yes" or "confirm"
## Checking Reservations
When a guest asks to check their reservations:
- Use `get_reservations_by_name` to find their bookings
book_reservation,
...
Các thay đổi sẽ ảnh hưởng đến tập lệnh cơ sở dữ liệu ban đầu, hãy thử thực thi tập lệnh đó
source .env
uv run python scripts/seed_db.py
Tập lệnh đã cập nhật sẽ tạo bảng reservations nếu bảng này chưa tồn tại. Bạn sẽ thấy đầu ra xác nhận rằng bảng mới đã được tạo (dữ liệu menu_items hiện có vẫn được giữ nguyên).
Nếu mọi thứ diễn ra suôn sẻ đến thời điểm này, chúng ta có thể kiểm thử tính năng này trên giao diện người dùng dành cho nhà phát triển của tác nhân ADK. Khởi động lại Toolbox để chọn các định nghĩa công cụ mới trong tools.yaml. Dừng mọi quy trình Toolbox hiện có, sau đó bắt đầu một quy trình mới:
pkill -f toolbox 2>/dev/null
toolbox --tools-file tools.yaml --address 127.0.0.1 --port 5000 &
Khởi động giao diện người dùng dành cho nhà phát triển ADK:
uv run adk web .
Mở http://localhost:8000 trong trình duyệt rồi thử nghiệm với các câu lệnh sau:
I'd like to book a table for 4 people on Friday at 7pm under the name Timmy
Do I have any upcoming reservations?
Bây giờ, hãy dừng giao diện người dùng dành cho nhà phát triển ADK bằng cách nhấn Ctrl+C hai lần.
8. Thử thách (Không bắt buộc)
Giờ đây, bạn đã biết toàn bộ quy trình SDD. Hãy thử nghiệm:
- Chạy chu kỳ SDD thứ hai để tạo giao diện trò chuyện trên web cho nhân viên hỗ trợ khách hàng của nhà hàng – lần này không có hướng dẫn từng bước.
- Triển khai tác nhân của bạn lên Cloud Run cho trường hợp sản xuất
Gợi ý
- Dự án này không có khung giao diện người dùng. Antigravity nên đề xuất HTML/CSS/JS thuần tuý – nếu đề xuất React hoặc các ngôn ngữ tương tự, hãy hướng dẫn Antigravity theo hướng đơn giản (nguyên tắc "giữ cho đơn giản" trong hiến pháp của bạn sẽ nắm bắt được điều này).
- Máy chủ ADK hiển thị
/run_sseđể truyền phát trực tuyến và/apps/{app_name}/users/{user_id}/sessionsđể quản lý phiên. Antigravity phát hiện những thông tin này từ bối cảnh dự án. - Sau khi triển khai, hãy khởi động máy chủ bằng
uv run uvicorn server:app --host 0.0.0.0 --port 8080(không phảiadk web) để hoạt động gắn tệp tĩnh. - Kiểm thử tại
http://localhost:8080/static/index.html. - Các lớp học lập trình tham chiếu đã cho thấy cách triển khai và duy trì tác nhân ADK, hãy tham khảo Antigravity về vấn đề này!
9. Xin chúc mừng!
Bạn đã mở rộng một tác nhân ADK của nhân viên hỗ trợ nhà hàng bằng tính năng đặt chỗ – hoàn toàn thông qua quy trình làm việc SDD của Antigravity mà không cần viết mã ứng dụng theo cách thủ công.
Sản phẩm bạn đã tạo
- Một trợ lý ADK của nhân viên hỗ trợ nhà hàng có chức năng tìm kiếm thực đơn, tìm kiếm ngữ nghĩa, theo dõi lựa chọn ưu tiên về chế độ ăn uống và đặt chỗ
- Một kỹ năng Antigravity để nghiên cứu kho lưu trữ, tạo và duy trì tài liệu bối cảnh dự án
- Một bản quy tắc dự án nhằm thực thi các nguyên tắc không thể thương lượng trong quá trình lập kế hoạch và phân tích
- Một chu trình SDD hoàn chỉnh minh hoạ quy trình chỉ định → làm rõ → lập kế hoạch → công việc → phân tích → triển khai
Kiến thức bạn học được
- Cách sử dụng quy trình phát triển dựa trên quy cách trong Antigravity để thêm các tính năng vào cơ sở mã hiện có một cách có hệ thống
- Cách tạo các kỹ năng Antigravity để đóng gói kiến thức về miền nhằm sử dụng lại trong các cuộc trò chuyện
- Cách khởi động bối cảnh dự án để Antigravity đưa ra quyết định sáng suốt về lựa chọn kiến trúc, mẫu và công nghệ
- Cách thiết lập một quy tắc dự án mà quy trình công việc SDD xác thực
- Cách mở rộng tác nhân ADK bằng các công cụ mới dựa trên cơ sở dữ liệu thông qua Hộp công cụ MCP
Dọn dẹp
Dừng mọi quy trình cục bộ đang chạy (Hộp công cụ):
pkill -f toolbox 2>/dev/null
Xoá phiên bản Cloud SQL để không bị tính phí liên tục:
gcloud sql instances delete restaurant-db --quiet
Bạn có thể xoá toàn bộ dự án:
gcloud projects delete $GOOGLE_CLOUD_PROJECT