Vibe Coding AI Agents: Quản lý vòng đời của tác nhân bằng Agents CLI và ADK 2.0

1. Tổng quan

Trong lớp học lập trình này, bạn sẽ tìm hiểu cách sử dụng Agents CLI để quản lý toàn bộ vòng đời phát triển cục bộ của một tác nhân AI. Cho dù bạn đang bao bọc các mô hình Gemini hiện có hay xây dựng tác nhân tuỳ chỉnh từ đầu bằng Bộ công cụ phát triển tác nhân (ADK 2.0), Agents CLI đều cung cấp các công cụ để tạo khung, xây dựng, kiểm tra và thử nghiệm tác nhân của bạn ở cấp cục bộ.

Kiến thức bạn sẽ học được

  • Cách cài đặt và thiết lập agents-cli và các kỹ năng liên quan.
  • Cách tạo khung cho một dự án tác nhân mới.
  • Cấu trúc và các tệp chính của một dự án tác nhân quy trình công việc đồ thị ADK 2.0.
  • Cách chạy quy trình kiểm tra tự động và dọn dẹp mã.
  • Cách khởi chạy và sử dụng sân chơi web cục bộ để kiểm thử tương tác với tính năng tự động tải lại.

Bạn cần có

  • Python 3.11 trở lên
  • uv uv
  • Node.js 18+ (nếu sử dụng các kỹ năng của tác nhân lập trình)
  • Antigravity IDE (cài đặt và định cấu hình từ Google Antigravity)

Điều kiện tiên quyết

Lớp học lập trình này giả định rằng bạn đã quen với:

  • Sử dụng cửa sổ dòng lệnh và dòng lệnh.

Bạn không cần có kinh nghiệm sử dụng tác nhân AI hoặc ADK 2.0!

2. Thiết lập quy trình xác thực và môi trường

Cung cấp thông tin xác thực để tác nhân gọi các mô hình Gemini.

Lựa chọn 1: Khoá Gemini API (Google AI Studio)

Nếu bạn đang sử dụng khoá Gemini API tiêu chuẩn (bạn có thể lấy khoá này từ Google AI Studio), hãy xuất khoá đó trong phiên dòng lệnh IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Lựa chọn 2: Thông tin xác thực mặc định của ứng dụng trên Google Cloud

Nếu bạn đang sử dụng Vertex AI trên Google Cloud, hãy xác thực bằng Thông tin xác thực mặc định của ứng dụng trên Google Cloud (ADC) và thiết lập dự án trên đám mây của Google Cloud đang hoạt động:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Thiết lập Agents CLI và các kỹ năng

Bước đầu tiên là cài đặt công cụ agents-cli. Công cụ này xử lý công việc quản lý dự án tác nhân.

Sau khi cài đặt Antigravity, hãy chạy lệnh thiết lập ngay trong cửa sổ dòng lệnh.

👉 Mở cửa sổ dòng lệnh và chạy:

uvx google-agents-cli setup

Lệnh này sẽ tự động cài đặt:

  1. Công cụ Agents CLI trên toàn hệ thống.
  2. 7 kỹ năng trợ lý lập trình dành riêng cho từng miền mà Antigravity có thể sử dụng để giúp bạn xây dựng, tạo khung, đánh giá và triển khai tác nhân. Các kỹ năng này được cài đặt một lần trên toàn hệ thống vào ~/.agents/skills/ và được Antigravity tự động phát hiện.

Lưu ý: Các kỹ năng được cài đặt vào ~/.agents/skills/ và được Antigravity tự động chọn. Bạn có thể xác minh điều này bằng lệnh /skills hoặc chế độ cài đặt Antigravity.

Kết quả dự kiến (đã cắt bớt):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Tạo dự án tác nhân

Trong phần này, bạn sẽ tạo một thư mục dự án có cấu trúc đầy đủ bằng mẫu nguyên mẫu.

👉 Nhắc Antigravity:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity sẽ tự động chạy lệnh tạo khung (agents-cli scaffold create customer-support-agent --prototype --yes) và thiết lập các tệp dự án cho bạn.

5. Khám phá mã tác nhân

👉 Yêu cầu Antigravity giải thích mã đã tạo:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

Trong Antigravity IDE, các tệp và cấu phần phần mềm dự án mới tạo sẽ xuất hiện ngay trong ngăn phụ (bên trái). Bạn có thể xem app/agent.py tại đó hoặc mở tệp này trong trình khám phá tệp IDE để khám phá mã đã tạo khung.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Khái niệm chính

  • Quy trình công việc và các cạnh: Trong ADK 2.0, các ứng dụng tác nhân được sắp xếp dưới dạng đồ thị bằng cách sử dụng Workflow. Danh sách edges xác định luồng thực thi, liên kết các nút với nhau từ START và cho phép phân nhánh có điều kiện dựa trên các tuyến (ví dụ: định tuyến đến faq_agent trên "shipping" hoặc handle_unrelated trên "unrelated").
  • LlmAgent: Các nút khai báo xác định các tác vụ do LLM hỗ trợ với các hướng dẫn, mô hình và kết quả có cấu trúc cụ thể (output_schema).
  • Các nút và ngữ cảnh: Các hàm Python được trang trí bằng @node (hoặc các hàm tiêu chuẩn) thực hiện logic, truy cập vào trạng thái thực thi thông qua Context và tạo các đối tượng Event để truyền dữ liệu và tín hiệu định tuyến dọc theo đồ thị.
  • Mô hình: `gemini-3.1-flash-lite' được sử dụng làm mô hình suy luận nhanh mặc định.
  • Trình bao bọc ứng dụng: Đối tượng cấp cao nhất App bao bọc quy trình công việc gốc. Các công cụ bên ngoài như sân chơi cục bộ, các bộ khai thác đánh giá ADK và Thời gian chạy tác nhân sẽ khám phá và thực thi quy trình công việc của bạn thông qua giao diện app tiêu chuẩn này.

6. Kiểm tra tự động

Trước khi chạy hoặc kiểm thử tác nhân, bạn nên đảm bảo mã của mình được dọn dẹp và định dạng đúng cách.

👉 Nhắc Antigravity:

Run linting on my agent project to verify its health.

Antigravity sẽ thực thi agents-cli lint ở chế độ nền để chạy các quy trình kiểm tra được định cấu hình trước, xác minh các lượt nhập, cú pháp và tính nhất quán của định dạng trên các tệp của bạn.

7. Kiểm thử tương tác bằng sân chơi

Sân chơi web cục bộ là cách nhanh nhất để xác minh hành vi của tác nhân. Sân chơi này cung cấp một giao diện trò chuyện tương tác, nơi bạn có thể trò chuyện với tác nhân và kiểm tra các lượt thực thi công cụ theo thời gian thực.

👉 Nhắc Antigravity:

Launch the local development playground for my agent.

Antigravity sẽ khởi động máy chủ phát triển cục bộ (agents-cli playground). Mở URL được cung cấp (thường là http://127.0.0.1:8080/dev-ui/?app=app) trong trình duyệt web, chọn thư mục app trong trình đơn thả xuống để bắt đầu trò chuyện với tác nhân.

Bắt đầu trò chuyện với tác nhân trong giao diện web. Hãy thử đặt câu hỏi liên quan đến việc vận chuyển:

How much is standard shipping?

Lưu ý cách quy trình công việc phân loại và định tuyến thành công đến faq_agent để trả lời. Ngoài ra, hãy thử đặt một câu hỏi không liên quan để xác minh rằng quy trình công việc định tuyến đến handle_unrelated và từ chối trả lời một cách chính xác:

What is the weather like?

Kiểm thử tính năng tự động tải lại theo thời gian thực

Bạn có thể xem cách các chỉnh sửa theo thời gian thực đối với tác nhân được phản ánh trong Sân chơi.

  1. Sửa đổi hướng dẫn faq_agent trong app/agent.py bằng cách yêu cầu Antigravity: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Gửi một tin nhắn mới cho tác nhân trong sân chơi để kiểm thử tính năng tự động tải lại: 
    How much is standard shipping?
    Sân chơi sẽ tự động tải lại và thực thi mã đã cập nhật theo thời gian thực mà không cần khởi động lại máy chủ! Bây giờ bạn sẽ thấy một số biểu tượng cảm xúc trong câu trả lời.

8. Thực thi dòng lệnh

Để kiểm thử nhanh, tự động hoá hoặc viết tập lệnh, bạn có thể yêu cầu Antigravity chạy tác nhân ngay từ cửa sổ dòng lệnh.

👉 Nhắc Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

Antigravity sẽ thực thi lệnh truy vấn (agents-cli run "How long does standard delivery take?"). Lệnh này chạy một quy trình suy luận nhanh trong một lượt và in câu trả lời cuối cùng của tác nhân cùng với thông tin chi tiết về việc thực thi công cụ.

9. Dọn dẹp

Để tránh để lại các tài nguyên không mong muốn trong môi trường cục bộ, hãy làm theo các bước dọn dẹp sau:

  1. Dừng máy chủ cục bộ: Nếu máy chủ agents-cli playground vẫn đang chạy, hãy dừng máy chủ này trong cửa sổ dòng lệnh bằng cách nhấn Ctrl + C.
  2. Xoá các tệp dự án cục bộ: Xoá thư mục dự án tác nhân đã tạo khung khỏi máy cục bộ.
rm -rf customer-support-agent

10. Tổng kết và các bước tiếp theo

Xin chúc mừng! Bạn đã quản lý thành công vòng đời phát triển cục bộ từ đầu đến cuối của một tác nhân AI bằng Agents CLI và ADK 2.0.

Kiến thức bạn học được

  • Thiết lập các công cụ: Đã cài đặt Agents CLI và định cấu hình các kỹ năng quy trình công việc dành riêng cho từng miền cho Antigravity.
  • Tạo khung cho một dự án: Đã tạo một dự án có cấu trúc đầy đủ customer-support-agent bằng các mẫu tiêu chuẩn.
  • Phân tích cấu trúc ADK 2.0: Đã khám phá các quy trình công việc đồ thị, tác nhân LLM, nút, cạnh và định tuyến có điều kiện.
  • Quản lý tình trạng cục bộ: Đã chạy các quy trình kiểm tra chất lượng mã tự động bằng agents-cli lint.
  • Xác minh hành vi: Đã kiểm thử tác nhân một cách tương tác với tính năng tải lại nhanh theo thời gian thực thông qua sân chơi và chạy các quy trình kiểm thử nhanh trên dòng lệnh.

Tiếp theo là gì?

Bây giờ bạn đã nắm vững vòng lặp phát triển cục bộ, sau đây là cách bạn có thể mở rộng và đưa tác nhân vào hoạt động thực tế:

  • Đánh giá: Chấm điểm tác nhân của bạn dựa trên một bộ đánh giá bằng cách sử dụng agents-cli eval run để đo lường độ chính xác và tìm các hồi quy.
  • Quy mô đám mây doanh nghiệp: Triển khai & Khả năng quan sát: Đóng gói và triển khai tác nhân của bạn vào các môi trường thực tế như Thời gian chạy tác nhân hoặc Cloud Run bằng cách sử dụng agents-cli deploy. Thiết lập dữ liệu đo từ xa thực tế để truyền trực tuyến nhật ký và dấu vết thực thi đến Cloud Trace và BigQuery.

Tài nguyên khác