Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Xây dựng Trình lập kế hoạch đường đua Formula E có nhiều tác nhân bằng ADK và A2A

1. 1. Tổng quan

Trong lớp học lập trình này, bạn sẽ xây dựng một hệ thống nhiều tác nhân để thiết kế một đường đua đường phố Formula E và được phê duyệt theo một bộ quy tắc đơn giản của FIA.

Bạn sẽ sử dụng agents-cli để tạo hai dự án Bộ công cụ phát triển tác nhân (ADK) tiêu chuẩn, sau đó viết các phần quan trọng: một Kỹ năng của tác nhân, ba tác nhân và một bản đánh giá. Mọi thứ khác (bố cục dự án, máy chủ, phần phụ thuộc, cấu hình triển khai) đều đến từ CLI.

Bạn mới biết đến Formula E?

Bạn không cần phải biết về đua xe thể thao. Năm thuật ngữ sau đây là đủ:

Formula E: giải vô địch đua xe hoàn toàn bằng điện của FIA. Hầu hết các cuộc đua đều diễn ra trên các đường đua tạm thời ở trung tâm thành phố.
Homologation: sự phê duyệt chính thức của FIA rằng một đường đua là an toàn để đua. Không có chứng nhận, không có cuộc đua.
Phanh tái tạo: khi xe phanh, động cơ sẽ sạc lại pin. Phanh càng mạnh thì càng thu hồi được nhiều năng lượng, vì vậy, quy tắc của lớp học lập trình này yêu cầu ít nhất một vùng phanh mạnh.
Lớp CAD: các lớp được đặt tên trong bản vẽ thiết kế của đường đua, chẳng hạn như đường đua, làn đường pit và rào chắn. FIA sẽ kiểm tra xem các trường bắt buộc có trong đó hay không.
Chế độ tấn công: tay đua được tăng sức mạnh tạm thời bằng cách lái xe qua vùng kích hoạt nằm ngoài đường đua.

Các tác nhân của bạn đóng cả hai vai trò: một bên thiết kế đường đua, bên còn lại kiểm tra đường đua cho FIA.

Sản phẩm bạn sẽ tạo ra

Kiến trúc: trong dự án track-planner, chạy trong Cloud Shell, tác nhân track_planner sử dụng get_track_topology, fia_assessor và remote_gatekeeper. remote_gatekeeper gọi tác nhân gatekeeper qua A2A. Trong dự án gatekeeper, chạy trên Agent Runtime, tác nhân gatekeeper sử dụng verify_infrastructure_checklist.

Hộp màu xanh lục là tác nhân và hộp nét đứt là công cụ của tác nhân, giống như cách sân chơi ADK vẽ chúng. Hai trong số các công cụ này bao bọc các tác nhân khác: fia_assessor là tác nhân Đánh giá FIA có kỹ năng tuân thủ FIA và remote_gatekeeper gọi tác nhân Gatekeeper trong dự án khác qua A2A.

Tác nhân	Dự án	Công việc	`thinking_level`
Kiến trúc sư trưởng	`track-planner`	Đọc địa điểm, hỏi Người đánh giá, khắc phục vấn đề, yêu cầu Người kiểm duyệt phê duyệt	`HIGH`
Chuyên viên đánh giá FIA	`track-planner`	Kiểm tra bố cục bằng kỹ năng FIA và công cụ chấm điểm	`MEDIUM`
Người gác cổng bản sao kỹ thuật số	`gatekeeper`	Chạy danh sách kiểm tra phê duyệt cuối cùng	`LOW`

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

Cách agents-cli scaffold create bố trí một dự án ADK và những tệp bạn chỉnh sửa.
Cách đóng gói kiến thức chuyên môn thành một Kỹ năng của tác nhân (SKILL.md, references/, scripts/) và tải kỹ năng đó bằng SkillToolset của ADK.
Cách so khớp thinking_level với công việc của từng nhân viên hỗ trợ.
Cách đánh giá tác nhân bằng agents-cli eval run.
Cách triển khai tác nhân cho Môi trường thời gian chạy của tác nhân, sự khác biệt giữa Danh tính tác nhân và tài khoản dịch vụ, cũng như cách gọi tác nhân đã triển khai qua giao thức A2A.

2. 2. Thiết lập môi trường

Trước khi bắt đầu

Bạn cần có một dự án trên Google Cloud đã bật tính năng thanh toán. Nếu bạn đang tham gia lớp học lập trình này tại một sự kiện, hãy sử dụng tài khoản và dự án được cung cấp cho bạn.

Mở Cloud Shell và thiết lập dự án

Mở Cloud Shell, sau đó chạy:

# Cloud Shell sometimes opens without a project set. If so, this sets it to
# the first project on your account.
if [ -z "$(gcloud config get-value project 2>/dev/null)" ]; then
  gcloud config set project "$(gcloud projects list --format='value(projectId)' --limit=1)"
fi

export GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)"
export REGION="us-central1"
export ASSETS="$HOME/devrel-demos/codelabs/formula-e-track-planner"
echo "Project: $GOOGLE_CLOUD_PROJECT  Region: $REGION"

Tạo thông tin xác thực cho nhân viên hỗ trợ

gcloud đã đăng nhập, nhưng mã Python mà tác nhân của bạn chạy sử dụng Thông tin xác thực mặc định của ứng dụng (ADC), cần có thông tin đăng nhập riêng:

gcloud auth application-default login

Mở đường liên kết được in, đăng nhập bằng cùng một tài khoản, sao chép mã rồi dán lại vào Cloud Shell. Sau đó, hãy đặt dự án mà hạn mức được tính phí:

gcloud auth application-default set-quota-project "$GOOGLE_CLOUD_PROJECT"

Bật API

gcloud services enable \
    aiplatform.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    storage.googleapis.com \
    cloudresourcemanager.googleapis.com \
    serviceusage.googleapis.com \
    compute.googleapis.com \
    iam.googleapis.com \
    logging.googleapis.com \
    cloudtrace.googleapis.com

Mục đích của từng API:

API	Dùng cho
`aiplatform`	Các mô hình Gemini và Agent Runtime
`cloudresourcemanager`, `serviceusage`, `iam`	Các bước kiểm tra dự án và quyền mà `gcloud` và `agents-cli deploy` chạy
`compute`	Tạo tài khoản dịch vụ mặc định của Compute Engine mà quá trình triển khai ở Bước 7 sử dụng
`storage`, `logging`, `cloudtrace`	Bộ nhớ, nhật ký và dấu vết, theo đề xuất trong Hướng dẫn thiết lập thời gian chạy của tác nhân
`cloudbuild`, `artifactregistry`	Bản dựng và hình ảnh vùng chứa, được đưa vào để đề phòng cho việc triển khai ở Bước 7

Nhiều dự án đã bật một số chế độ cài đặt này. Việc bật một API đã bật sẽ không thay đổi điều gì.

Cài đặt `uv` và `agents-cli`

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv tool install google-agents-cli==1.10.0
agents-cli --version

Lớp học lập trình này đã được kiểm thử với agents-cli 1.10.0, vì vậy, hãy cài đặt phiên bản đó để nhận được các tệp được tạo giống nhau.

3. 3. Tạo khung cho dự án và thêm thành phần

Tạo cả hai dự án

agents-cli scaffold create tạo một dự án ADK hoàn chỉnh, có thể triển khai. Chạy hai lần, mỗi lần cho một hệ thống tác nhân.

Đầu tiên là công cụ lập kế hoạch theo dõi:

cd ~
agents-cli scaffold create track-planner \
  --agent adk \
  --deployment-target agent_runtime \
  --region "$REGION" \
  --prototype \
  --yes

Sau đó, người trực điện thoại:

cd ~
agents-cli scaffold create gatekeeper \
  --agent adk \
  --deployment-target agent_runtime \
  --region "$REGION" \
  --prototype \
  --yes

Cờ	Ý nghĩa
`--agent adk`	Bắt đầu từ mẫu ADK Python
`--deployment-target agent_runtime`	Tạo máy chủ và cấu hình cho Thời gian chạy tác nhân
`--prototype`	Bỏ qua CI/CD; giữ cho dự án ở mức tối giản
`--yes`	Chấp nhận các giá trị mặc định mà không cần nhắc

Khám phá bố cục

Dự án được tạo sẽ có dạng như sau. Bạn chỉ chỉnh sửa các tệp được đánh dấu ✍️:

track-planner/
├── agents-cli-manifest.yaml   # Records the template, deployment target and root agent name
├── pyproject.toml             # Dependencies (google-adk, a2a-sdk, ...)
├── .env                       # Your project and model location, filled in for you
├── Dockerfile                 # Used by `agents-cli deploy`; copies app/ into the image
├── app/
│   ├── agent.py               # ✍️ Your agents
│   ├── fast_api_app.py        # Generated server: ADK API, A2A routes, Agent Runtime routes
│   └── app_utils/             # Generated helpers (A2A, sessions)
└── tests/
    ├── unit/                  # Fast tests with no model calls
    ├── integration/           # Generated server tests
    └── eval/                  # ✍️ eval_config.yaml and datasets for `agents-cli eval`

Để xem nội dung mô tả về mọi tệp được tạo, hãy xem phần Cấu trúc dự án trong hướng dẫn về CLI của tác nhân.

Dùng thử tác nhân đã tạo

Trước khi thay đổi bất cứ điều gì, hãy chạy tác nhân mẫu để xem khung sườn cung cấp cho bạn những gì. Cài đặt các phần phụ thuộc và khởi động sân chơi cục bộ trên cổng 8080:

cd ~/track-planner
agents-cli install
agents-cli playground --port 8080

Để mở, hãy nhấp vào nút Web Preview (Bản xem trước trên web) trong thanh công cụ Cloud Shell (biểu tượng con mắt ở trên cùng bên phải), sau đó chọn Preview on port 8080 (Xem trước trên cổng 8080).

Trong sân chơi, hãy đặt cho tác nhân mẫu một câu hỏi mà các công cụ của tác nhân đó có thể trả lời, ví dụ:

What's the weather in San Francisco?

Bảng điều khiển bên cho thấy từng sự kiện, bao gồm cả lệnh gọi công cụ get_weather và kết quả của lệnh gọi đó. Bạn sẽ sử dụng cùng một chế độ xem sau này để theo dõi các nhân viên hỗ trợ của riêng bạn.

Khi bạn hoàn tất, hãy quay lại dòng lệnh và nhấn tổ hợp phím Ctrl+C để dừng Playground.

Thêm thành phần Formula E

Dữ liệu về địa điểm, quy tắc của FIA, tập lệnh vật lý, công cụ và tập dữ liệu đánh giá không phải là nội dung bài học, vì vậy, bạn nên sao chép các dữ liệu này từ GitHub thay vì nhập:

cd ~
git clone --depth 1 --filter=blob:none --sparse \
  --branch formula-e-lab-v1 \
  https://github.com/tdsymonds/devrel-demos.git
git -C devrel-demos sparse-checkout set codelabs/formula-e-track-planner

cp -r "$ASSETS/track-planner/." ~/track-planner/
cp -r "$ASSETS/gatekeeper/." ~/gatekeeper/

formula-e-lab-v1 là thẻ phát hành cố định, vì vậy mọi người đều nhận được các tệp giống nhau. $ASSETS được đặt ở Bước 2 và trỏ đến thư mục bạn vừa sao chép.

Thao tác này sẽ thêm các tệp sau:

track-planner/
├── app/
│   ├── tools.py                                  # get_track_topology, evaluate_track_layout
│   ├── auth.py                                   # A2A client with per-request token refresh
│   ├── data/circuits.json                        # Five candidate venues
│   └── skills/fia-compliance-skill/
│       ├── references/track_regulations.md       # The FIA rules
│       └── scripts/calculate_regen_zones.py      # Braking-energy calculator
└── tests/
    ├── unit/test_tools.py
    └── eval/datasets/track_eval.json, track_eval_quick.json
gatekeeper/
├── app/tools.py                                  # verify_infrastructure_checklist
└── tests/unit/test_tools.py

Cài đặt và kiểm thử

(cd ~/track-planner && agents-cli install && uv run pytest tests/unit)
(cd ~/gatekeeper && agents-cli install && uv run pytest tests/unit)

agents-cli install chạy uv sync để tạo môi trường ảo cho mỗi dự án. Tất cả các kiểm thử đơn vị đều phải đạt.

4. 4. Viết kỹ năng tuân thủ FIA

Kỹ năng của tác nhân đóng gói các chỉ dẫn, tài liệu tham khảo và tập lệnh vào một thư mục. SkillToolset của ADK tải dữ liệu theo ba cấp, nhờ đó tác nhân chỉ đọc những thông tin cần thiết:

Cấp độ	Tệp	Thời điểm nhân viên hỗ trợ nhìn thấy thông tin này
1	`SKILL.md` trang đầu (`name`, `description`)	Luôn luôn (vài chục mã thông báo)
2	`SKILL.md` nội dung	Khi gọi `load_skill`
3	`references/`, `scripts/`	Khi gọi `load_skill_resource` hoặc `run_skill_script`

Kỹ năng này nằm trong app/skills/ vì Dockerfile được tạo chỉ sao chép app/ vào hình ảnh đã triển khai.

Xem các tệp cấp 3

Bạn đã sao chép các tệp cấp 3 của kỹ năng trong Bước 3:

references/track_regulations.md chứa các quy tắc mà Người đánh giá kiểm tra: giới hạn chiều dài và chiều rộng, rào chắn cần thiết cho từng vùng phanh, các lớp CAD bắt buộc (cộng với các lớp y tế cho các tuyến đường đến bệnh viện), mục tiêu tái tạo và các quy tắc về Chế độ tấn công.
scripts/calculate_regen_zones.py là một máy tính. Dựa trên tốc độ vào cua, tốc độ ra cua và khoảng cách phanh của một vùng phanh, AI sẽ tính toán năng lượng thu hồi và rào chắn cần thiết cho khúc cua, nhờ đó, nhân viên không bao giờ phải đoán các thông số vật lý.

Chạy tập lệnh cho Khúc cua 10 của London, nơi xe giảm tốc từ 215 xuống 55 km/h trên quãng đường 82 mét:

cd ~/track-planner
uv run python app/skills/fia-compliance-skill/scripts/calculate_regen_zones.py \
  --entry-kph 215 --exit-kph 55 --brake-dist-m 82

Xe thu hồi khoảng 508 kW tại đây, cao hơn mục tiêu 250 kW. Xe giảm tốc ở mức hơn 2G, vì vậy, góc cua cần có rào chắn Tecpro (F1_TEC3):

{"entry_kph": 215.0, "exit_kph": 55.0, "brake_dist_m": 82.0, "deceleration_g": 2.07, "estimated_regen_kw": 507.7, "meets_250kw_target": true, "required_barrier_layer": "F1_TEC3"}

Viết `SKILL.md`

Tạo tệp liên kết kỹ năng:

cloudshell edit app/skills/fia-compliance-skill/SKILL.md

Thêm nội dung này:

---
name: fia-compliance-skill
description: >
  FIA Formula E street circuit rules: length and width limits, mandatory CAD
  layers, barrier selection, and Gen3 regenerative braking estimates. Use when
  designing, checking or fixing a Formula E circuit layout.
---

# FIA Formula E Compliance

Follow these steps for every circuit you check.

1. **Read the rules.** Call `load_skill_resource` with
   `file_path="references/track_regulations.md"`.
2. **Estimate regeneration for every heavy braking zone.** Call
   `run_skill_script` with `file_path="scripts/calculate_regen_zones.py"` and
   `args={"entry-kph": <entry>, "exit-kph": <exit>, "brake-dist-m": <distance>}`.
   Never guess kW values. Use the highest `estimated_regen_kw` as the
   circuit's peak regeneration.
3. **Check barriers.** Any zone whose `required_barrier_layer` is `F1_TEC3`
   needs the `F1_TEC3` CAD layer.
4. **Report.** List every rule the layout fails and a concrete fix for each
   one.

description là nội dung mà mô hình đọc để quyết định thời điểm sử dụng kỹ năng, vì vậy, nội dung này cho biết cả phạm vi của kỹ năng và thời điểm sử dụng kỹ năng.

Xem cách kỹ năng được kết nối

Mở app/tools.py trong Trình chỉnh sửa Cloud Shell:

cloudshell edit app/tools.py

Tìm hàm build_fia_skill_toolset:

def build_fia_skill_toolset() -> SkillToolset:
    return SkillToolset(
        skills=[load_skill_from_dir(SKILL_DIR)],
        code_executor=UnsafeLocalCodeExecutor(),
    )

load_skill_from_dir đọc thư mục kỹ năng: SKILL.md, references/ và scripts/.
SkillToolset biến các hàm này thành công cụ mà tác nhân có thể gọi: list_skills, load_skill, load_skill_resource và run_skill_script.
UnsafeLocalCodeExecutor cho phép run_skill_script chạy tập lệnh Python trên máy này. Điều này phù hợp với lớp học lập trình; hãy sử dụng trình thực thi hộp cát trong môi trường thực tế.

Bạn sẽ đính kèm bộ công cụ này vào Assessor trong bước tiếp theo.

5. 5. Viết tác nhân

Các mô hình Gemini 3 kiểm soát khả năng suy luận bằng thinking_level (LOW, MEDIUM hoặc HIGH) thay vì ngân sách mã thông báo. Trong ADK, bạn đặt giá trị này bằng types.ThinkingConfig(thinking_level=types.ThinkingLevel.HIGH). Hãy điều chỉnh cho phù hợp với công việc của từng tác nhân: suy nghĩ nhiều hơn đồng nghĩa với việc lập kế hoạch tốt hơn, nhưng độ trễ và chi phí cũng cao hơn.

Người gác cổng (`LOW`)

Gatekeeper chỉ chạy một danh sách kiểm tra tất định, nên không cần suy luận nhiều. Thay thế tác nhân mẫu:

cloudshell edit ~/gatekeeper/app/agent.py

"""FIA Digital Twin Gatekeeper agent.

This agent runs in its own project and is deployed to Agent Runtime. The track
planner calls it over the A2A protocol.
"""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.genai import types

from app.tools import verify_infrastructure_checklist

# Tested with Gemini 3.8 Flash. To try Gemini 4 Argon, change this to
# "gemini-4-argon", delete the `temperature` settings below (Argon ignores
# them) and run `uv add "google-genai>=2.30.1"` in this project first.
MODEL = "gemini-3.8-flash"

root_agent = Agent(
    # Must match `root_agent_name` in agents-cli-manifest.yaml.
    name="gatekeeper",
    model=Gemini(
        model=MODEL,
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    description=(
        "FIA Digital Twin Gatekeeper. Runs the final homologation checklist "
        "for a Formula E circuit blueprint."
    ),
    instruction=(
        "You are the FIA Digital Twin Gatekeeper. For every circuit blueprint "
        "you receive, call `verify_infrastructure_checklist` with its circuit "
        "ID, CAD layers, minimum width and peak regeneration. Reply with the "
        "status and any missing CAD layers. Never approve a blueprint the "
        "checklist rejects."
    ),
    # A deterministic checklist needs little reasoning: keep it fast and cheap.
    generate_content_config=types.GenerateContentConfig(
        temperature=0.0,
        thinking_config=types.ThinkingConfig(
            thinking_level=types.ThinkingLevel.LOW,
        ),
    ),
    tools=[verify_infrastructure_checklist],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Chạy Gatekeeper trên thiết bị

Mở thẻ Cloud Shell thứ hai và khởi động máy chủ do Gatekeeper tạo trên cổng 8001:

cd ~/gatekeeper
APP_URL=http://localhost:8001 uv run uvicorn app.fast_api_app:app --port 8001

Quay lại thẻ đầu tiên, hãy xem thẻ tác nhân A2A của Gatekeeper. Đây là cách các tác nhân khác khám phá Gatekeeper là gì và có thể làm gì:

curl -s http://localhost:8001/a2a/app/.well-known/agent-card.json | jq .

Bạn sẽ thấy JSON như sau (đã rút gọn):

{
  "name": "gatekeeper",
  "description": "FIA Digital Twin Gatekeeper. Runs the final homologation checklist for a Formula E circuit blueprint.",
  "supportedInterfaces": [
    {"url": "http://localhost:8001/a2a/app", "protocolBinding": "JSONRPC", "protocolVersion": "1.0"}
  ],
  "skills": [
    {"id": "gatekeeper", "name": "model", "description": "FIA Digital Twin Gatekeeper. ..."},
    {"id": "gatekeeper-verify_infrastructure_checklist", "name": "verify_infrastructure_checklist", "description": "Runs the final homologation checklist ..."}
  ]
}

name và description được lấy trực tiếp từ định nghĩa Agent(...) của bạn.
skills liệt kê những việc mà tác nhân có thể làm. ADK tự động thêm verify_infrastructure_checklist bằng cách sử dụng chuỗi tài liệu của công cụ.
supportedInterfaces cho người gọi biết nơi gửi yêu cầu A2A. Đó là lý do bạn khởi động máy chủ bằng APP_URL=http://localhost:8001: phương thức gọi đọc thẻ trước, sau đó gửi yêu cầu đến bất kỳ url nào mà thẻ quảng cáo.

Không có nội dung nào ở đây được viết bằng tay: máy chủ được tạo sẵn sẽ tạo thẻ từ tác nhân của bạn. Trình lập kế hoạch theo dõi sẽ đọc thẻ này để tìm và gọi Gatekeeper.

Người đánh giá (`MEDIUM`) và Kiến trúc sư trưởng (`HIGH`)

Trình lập kế hoạch theo dõi có hai tác nhân:

Assessor cân nhắc một số quy tắc, vì vậy, nó sẽ nhận được MEDIUM. Hàm này được gói trong một AgentTool, vì vậy, Kiến trúc sư trưởng gọi hàm này như một hàm và nhận được kết quả.
Kiến trúc sư trưởng lập kế hoạch, sửa lỗi và điều phối, nên sẽ nhận được HIGH. Nó đến được Gatekeeper thông qua một RemoteA2aAgent, do create_remote_gatekeeper_agent() tạo trong app/auth.py, đồng thời gói nó trong một AgentTool.

Tại sao phải gói cả hai trình trợ giúp dưới dạng công cụ? AgentTool trả về câu trả lời cho người gọi, vì vậy, Kiến trúc sư trưởng vẫn chịu trách nhiệm và viết bản thiết kế cuối cùng. Nếu Gatekeeper là sub_agent, thì Lead Architect sẽ chuyển cuộc trò chuyện cho Gatekeeper và trạng thái ngắn gọn của Gatekeeper sẽ trở thành câu trả lời cuối cùng.

Mở tệp app/agent.py của trình lập kế hoạch theo dõi:

cloudshell edit ~/track-planner/app/agent.py

Sao chép mã sau và thay thế toàn bộ nội dung của ~/track-planner/app/agent.py bằng mã đó:

"""Formula E track planner: Lead Architect, FIA Assessor and remote Gatekeeper.

- The Lead Architect (root agent) designs the circuit and stays in charge.
- The FIA Assessor checks the layout and is called as a tool (`AgentTool`).
- The Gatekeeper runs in a separate project. It is also called as a tool, over
  A2A, so its verdict comes back to the Lead Architect.
"""

from google.adk.agents import Agent
from google.adk.apps import App
from google.adk.models import Gemini
from google.adk.tools.agent_tool import AgentTool
from google.genai import types

from app.auth import create_remote_gatekeeper_agent
from app.tools import build_fia_skill_toolset
from app.tools import evaluate_track_layout
from app.tools import get_track_topology

# Tested with Gemini 3.8 Flash. To try Gemini 4 Argon, change this to
# "gemini-4-argon", delete the `temperature` settings below (Argon ignores
# them) and run `uv add "google-genai>=2.30.1"` in this project first.
MODEL = "gemini-3.8-flash"

fia_skill_toolset = build_fia_skill_toolset()

# 1. FIA Assessor: MEDIUM thinking to weigh several rules without much latency.
assessor_agent = Agent(
    name="fia_assessor",
    model=Gemini(
        model=MODEL,
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    description=(
        "FIA safety and energy assessor. Audits a proposed circuit against "
        "the geometry, regeneration and CAD layer rules."
    ),
    instruction=(
        "You are the FIA Assessor. Load the `fia-compliance-skill` and follow "
        "it. Estimate regeneration for each braking zone with "
        "`calculate_regen_zones.py`, then call `evaluate_track_layout` with "
        "the highest value. Reply with the verdict, the score and every "
        "remediation note."
    ),
    generate_content_config=types.GenerateContentConfig(
        temperature=0.1,
        thinking_config=types.ThinkingConfig(
            thinking_level=types.ThinkingLevel.MEDIUM,
        ),
    ),
    tools=[fia_skill_toolset, evaluate_track_layout],
)

# 2. Remote Gatekeeper, reached over A2A (see app/auth.py).
remote_gatekeeper = create_remote_gatekeeper_agent()

# 3. Lead Architect: HIGH thinking for multi-step planning and trade-offs.
root_agent = Agent(
    # Must match `root_agent_name` in agents-cli-manifest.yaml.
    name="track_planner",
    model=Gemini(
        model=MODEL,
        retry_options=types.HttpRetryOptions(attempts=3),
    ),
    description=(
        "Lead Formula E circuit architect. Designs FIA-compliant street "
        "circuits and gets them homologated."
    ),
    instruction=(
        "You are the Lead Formula E Circuit Architect. For every request:\n"
        "1. Call `get_track_topology` for the venue.\n"
        "2. Call the `fia_assessor` tool with the full topology.\n"
        "3. If the Assessor rejects the layout, propose concrete fixes (for "
        "example widen a sector to 10.0m or add missing CAD layers) and "
        "re-assess the fixed layout.\n"
        "4. Once the Assessor passes it, call the `remote_gatekeeper` tool "
        "with the circuit ID, CAD layers, minimum width and peak "
        "regeneration for final approval.\n"
        "5. Finish with a short blueprint: circuit ID, length, minimum width, "
        "peak regeneration, every CAD layer by name, and the Gatekeeper's "
        "status."
    ),
    generate_content_config=types.GenerateContentConfig(
        temperature=0.2,
        thinking_config=types.ThinkingConfig(
            thinking_level=types.ThinkingLevel.HIGH,
        ),
    ),
    # Both helpers are tools, so their answers come back to the Lead Architect
    # and it writes the final blueprint.
    tools=[
        get_track_topology,
        AgentTool(agent=assessor_agent),
        AgentTool(agent=remote_gatekeeper),
    ],
)

app = App(
    root_agent=root_agent,
    name="app",
)

Chạy toàn bộ hệ thống trong Playground

Đảm bảo Gatekeeper vẫn đang chạy trong thẻ thứ hai. Trong thẻ đầu tiên, hãy bắt đầu sân chơi của trình lập kế hoạch theo dõi:

cd ~/track-planner
agents-cli playground --port 8080

Nhấp vào Web Preview (Xem trước trên web) > Preview on port 8080 (Xem trước trên cổng 8080), như bạn đã làm ở Bước 3.

Yêu cầu một mạch tại địa điểm đáp ứng các quy tắc:

Design and homologate a Formula E circuit at Tokyo Bay.

Xem bảng điều khiển sự kiện khi các tác nhân hoạt động. Bạn sẽ thấy các mục sau theo thứ tự:

get_track_topology: Kiến trúc sư trưởng tải dữ liệu về Vịnh Tokyo.
fia_assessor: Kiến trúc sư trưởng giao bố cục cho Người đánh giá. Người đánh giá sẽ gọi load_skill, load_skill_resource và run_skill_script (mỗi vùng phanh một lần), sau đó gọi evaluate_track_layout.
remote_gatekeeper: Kiến trúc sư trưởng gọi cho Người nghe máy qua A2A. Bạn sẽ thấy yêu cầu được ghi lại trong thẻ thứ hai.
Bản thiết kế cuối cùng của Kiến trúc sư trưởng, liệt kê mọi lớp CAD và trạng thái ĐÃ PHÊ DUYỆT của Người gác cổng.

Nhấp vào sự kiện bất kỳ để xem chính xác dữ liệu đầu vào và đầu ra của sự kiện đó.

Bây giờ, hãy bắt đầu một phiên mới và thử một địa điểm vi phạm quy tắc:

Can the Monaco Harbour layout be homologated? If not, fix it and try again.

Lần này, Người đánh giá từ chối đoạn đường ngoằn ngoèo 6,8 m, Kiến trúc sư trưởng đề xuất một đoạn đường rộng hơn và bố cục cố định sẽ quay lại Người đánh giá trước khi đến tay Người kiểm duyệt.

Khi bạn hoàn tất, hãy nhấn tổ hợp phím Ctrl+C trong thẻ đầu tiên để dừng Playground. Để Gatekeeper chạy trong thẻ thứ hai: bạn cần Gatekeeper ở bước tiếp theo.

6. 6. Đánh giá các tác nhân

agents-cli eval run chạy tác nhân của bạn trên một tập dữ liệu, ghi lại mọi lượt và lệnh gọi công cụ, đồng thời chấm điểm kết quả. Bạn quyết định những gì cần đo lường trong tests/eval/eval_config.yaml.

Xem tập dữ liệu

Mở tập dữ liệu trong Trình chỉnh sửa Cloud Shell:

cd ~/track-planner
cloudshell edit tests/eval/datasets/track_eval.json

Tệp này chứa danh sách eval_cases. Mỗi trường hợp đều có eval_case_id, prompt (câu hỏi của người dùng) và reference (câu trả lời phù hợp). Trình đánh giá LLM so sánh câu trả lời của nhân viên hỗ trợ với câu trả lời tham khảo.

`eval_case_id`	Nội dung kiểm thử
`fe_001_tokyo_compliant`	Một địa điểm đáp ứng mọi quy tắc và được phê duyệt
`fe_002_monaco_narrow`	Đoạn đường ngoằn ngoèo dài 6,8 m không đáp ứng quy tắc về chiều rộng
`fe_003_berlin_too_long`	Đường đua dài 4.350 m không đáp ứng quy tắc về chiều dài
`fe_004_missing_layers`	Một bố cục thiếu các lớp CAD bắt buộc
`fe_005_low_regen`	Vùng phanh dưới mục tiêu 250 kW
`fe_006_sao_paulo_medical`	Cần có các lớp CAD y tế để truy cập vào bệnh viện
`fe_007_attack_mode`	Khu vực Chế độ tấn công trên đường đua
`fe_008_multiturn_remediation`	Cuộc trò chuyện nhiều lượt: Monaco bị từ chối, người dùng yêu cầu sửa và bố cục đã sửa phải được phê duyệt

Trường hợp cuối cùng sử dụng agent_data thay vì prompt. Công cụ này phát lại các lượt trước đó của một cuộc trò chuyện, nhờ đó bạn có thể kiểm tra cách tác nhân xử lý một yêu cầu tiếp theo, chứ không chỉ một câu hỏi.

track_eval_quick.json trong cùng một thư mục chỉ chứa hai trường hợp: trường hợp 1 (một câu hỏi) và trường hợp 8 (một cuộc trò chuyện). Bạn sẽ chạy truy vấn đó vì nó nhanh hơn và sử dụng ít hạn mức hơn.

Ghi chỉ số

Tập dữ liệu cho biết những điều cần hỏi nhân viên hỗ trợ. eval_config.yaml cho biết cách chấm điểm câu trả lời. agents-cli eval run sẽ đọc câu trả lời sau khi nhân viên hỗ trợ trả lời mọi trường hợp và chạy từng chỉ số cho mỗi câu trả lời.

Mở tệp mà scaffold đã tạo:

cloudshell edit tests/eval/eval_config.yaml

Thành phần này đã chứa một trình đánh giá LLM chung (custom_response_quality) và một chỉ số agent_turn_count chỉ tính số lượt. Đó là một khởi đầu tốt cho bất kỳ nhân viên hỗ trợ nào, nhưng không nói gì về Formula E. Bạn sẽ giữ lại trình đánh giá và thêm một chỉ số để kiểm tra một quy tắc dành riêng cho miền này.

Các quy trình đánh giá hiệu quả thường kết hợp hai loại chỉ số:

Loại	Cách tính điểm	Phù hợp với việc	Lựa chọn đánh đổi
LLM-as-a-judge	Một mô hình đọc câu trả lời và `reference` của trường hợp, sau đó đưa ra điểm từ 1 đến 5 kèm theo lời giải thích	Chất lượng mờ: câu trả lời có chính xác, đầy đủ và rõ ràng không?	Mỗi trường hợp sẽ tốn một lệnh gọi mô hình; điểm số có thể khác nhau một chút giữa các lần chạy
Chỉ số về mã	Một hàm Python nhỏ kiểm tra câu trả lời	Thông tin thực tế chính xác, có thể kiểm chứng: câu trả lời có chứa thông tin bắt buộc không?	Chỉ kiểm tra những gì bạn có thể thể hiện trong mã

Thay thế nội dung của tệp bằng:

metrics_to_run:
  - custom_response_quality
  - fia_cad_layer_compliance

custom_metrics:
  # LLM-as-a-judge. response_quality.py is generated by `agents-cli scaffold
  # create`; it grades the final answer against the case's `reference`.
  - name: custom_response_quality
    custom_function_file: response_quality.py

  # Deterministic code metric: an approved blueprint must name every
  # mandatory FIA CAD layer.
  - name: fia_cad_layer_compliance
    custom_function: |
      def evaluate(instance):
          response = str(instance.get("response") or "")
          reference = str(instance.get("reference") or "")
          # Only approvals must list every layer. Rejections and other
          # questions (such as Attack Mode) don't, so skip them.
          if "APPROVED" not in reference:
              return {"score": 1.0, "explanation": "Not an approval case."}
          required = [
              "F1_TRACK_CENTRELINE",
              "F1_PIT_ENTRY_SPEED_LIMIT_LANE",
              "F1_WALL_TEMP",
              "F1_TEC3",
          ]
          missing = [layer for layer in required if layer not in response]
          return {
              "score": round(1 - len(missing) / len(required), 2),
              "explanation": "Missing: " + (", ".join(missing) or "none"),
          }

Chức năng của từng phần:

metrics_to_run liệt kê các chỉ số cần chạy, theo tên. Khi bạn xoá một tên ở đây, chỉ số đó sẽ bị tắt nhưng không bị xoá.
custom_response_quality là giám khảo LLM. custom_function_file trỏ đến tests/eval/response_quality.py, do scaffold tạo ra. Hãy mở tệp này nếu bạn muốn xem câu lệnh đánh giá.
fia_cad_layer_compliance là chỉ số mã của bạn, được viết cùng dòng trong custom_function. Đối với mỗi trường hợp, hệ thống sẽ nhận được một instance (câu lệnh, response cuối cùng của tác nhân và reference). Đối với những trường hợp câu trả lời dự kiến là phê duyệt, hệ thống sẽ kiểm tra để đảm bảo câu trả lời nêu tên cả 4 lớp CAD bắt buộc và liệt kê mọi lớp còn thiếu. Ví dụ: một bản thiết kế bỏ qua F1_TEC3 sẽ đạt 0,75 điểm. Các trường hợp khác đạt 1 điểm vì câu trả lời từ chối hoặc câu trả lời ở Chế độ tấn công không cần liệt kê mọi lớp.

Tại sao cần kiểm tra các lớp CAD? Một bản thiết kế được phê duyệt nhưng bỏ qua một lớp bắt buộc là không chính xác, ngay cả khi bản thiết kế đó dễ đọc và giám khảo LLM có thể bỏ qua điều đó. Một quy trình kiểm tra mã sẽ áp dụng cùng một quy tắc theo cùng một cách trong mỗi lần chạy.

Chạy quy trình đánh giá

Tiếp tục chạy Gatekeeper cục bộ trong thẻ thứ hai, sau đó chạy:

agents-cli eval run \
  --dataset tests/eval/datasets/track_eval_quick.json \
  --config tests/eval/eval_config.yaml \
  --concurrency 1
ls artifacts/grade_results/

Quá trình đánh giá mất vài phút. Mỗi trường hợp đều chạy toàn bộ quy trình đa tác nhân, khoảng mười lệnh gọi mô hình với Kiến trúc sư trưởng về tư duy HIGH, vì vậy, Step 1/2: eval generate là phần chậm. Nó không bị kẹt.

Khi quá trình này hoàn tất, hãy mở báo cáo HTML trong artifacts/grade_results/ bằng Trình chỉnh sửa Cloud Shell. Điểm fia_cad_layer_compliance thấp cho biết câu trả lời cuối cùng của Kiến trúc sư trưởng đang bỏ sót các lớp. Hãy thử thắt chặt chỉ dẫn và chạy lại quy trình đánh giá.

7. 7. Triển khai Gatekeeper cho Agent Runtime

Bạn chỉ triển khai Gatekeeper. Trình lập kế hoạch theo dõi tiếp tục chạy trong Cloud Shell và gọi trình lập kế hoạch đó.

Mở một thẻ Cloud Shell mới

Quá trình triển khai mất từ 5 đến 8 phút, vì vậy, hãy thực hiện việc này trong một thẻ mới trong khi quá trình đánh giá ở Bước 6 hoàn tất:

Nhấp vào Mở thẻ mới (+) trên thanh công cụ Cloud Shell.

Thẻ mới không giữ lại các biến từ Bước 2, vì vậy, hãy đặt lại các biến đó:

export GOOGLE_CLOUD_PROJECT="$(gcloud config get-value project)"
export REGION="us-central1"
export ASSETS="$HOME/devrel-demos/codelabs/formula-e-track-planner"
export PATH="$HOME/.local/bin:$PATH"
echo "Project: $GOOGLE_CLOUD_PROJECT  Region: $REGION"

Để Gatekeeper cục bộ chạy trong thẻ thứ hai: quá trình đánh giá vẫn sử dụng Gatekeeper và quá trình triển khai không cần dừng Gatekeeper.

Triển khai

Trong thẻ mới, hãy triển khai Gatekeeper. Tài khoản này chạy dưới dạng tài khoản dịch vụ mặc định của Compute Engine trong dự án:

cd ~/gatekeeper
PROJECT_NUMBER=$(gcloud projects describe "$GOOGLE_CLOUD_PROJECT" --format="value(projectNumber)")
agents-cli deploy \
  --no-agent-identity \
  --service-account "${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --region "$REGION" \
  --no-confirm-project

Quá trình triển khai mất khoảng 5 đến 8 phút. Đừng đóng thẻ Cloud Shell khi thẻ này đang chạy. Nếu luồng nhật ký bị ngắt kết nối, hãy kiểm tra tiến trình bằng agents-cli deploy --status. Trong khi chờ đợi, hãy quay lại Bước 6 và đọc báo cáo đánh giá.

Tại sao lại là tài khoản dịch vụ này? Nếu không có --service-account, Agent Runtime sẽ chạy tác nhân dưới dạng tác nhân dịch vụ mặc định. Như vậy là đủ cho Gatekeeper, nhưng tác nhân dịch vụ không được phép gọi các tác nhân khác trong Môi trường thời gian chạy của tác nhân, vì vậy, trình lập kế hoạch theo dõi đã triển khai không bắt buộc ở cuối Bước 8 sẽ nhận được 403 Forbidden. Để cấp quyền truy cập đó, bạn cần có quyền thay đổi IAM. Trong nhiều dự án, tài khoản dịch vụ mặc định của Compute Engine có vai trò Người chỉnh sửa, nên tài khoản này hoạt động mà không cần thay đổi IAM. Quyền truy cập rộng đó cũng là lý do khiến Danh tính tác nhân (bên dưới) là lựa chọn phù hợp hơn trong dự án mà bạn sở hữu.

Bạn sở hữu dự án này? Thay vào đó, hãy sử dụng Danh tính của nhân viên hỗ trợ. Danh tính tác nhân cung cấp cho mỗi tác nhân được triển khai một tài khoản chính do hệ thống quản lý, thay vì một tài khoản dịch vụ được chia sẻ giữa các khối lượng công việc. agents-cli cấp vai trò IAM cho danh tính mới, vì vậy, bạn cần có vai trò Chủ sở hữu hoặc Quản trị viên IAM của dự án. Chạy lệnh này thay vì lệnh trên:

cd ~/gatekeeper
agents-cli deploy \
  --agent-identity \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --region "$REGION" \
  --no-confirm-project

Danh tính của tác nhân không khớp với Permission 'resourcemanager.projects.setIamPolicy' denied? Tài khoản của bạn không thể thay đổi chính sách IAM, nhưng lần thử không thành công đã tạo một tài nguyên Thời gian chạy của tác nhân trống. Xoá và đặt lại bản ghi triển khai, sau đó chạy lệnh triển khai tài khoản dịch vụ ở trên:

cd ~/gatekeeper
RUNTIME_ID=$(curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/projects/${GOOGLE_CLOUD_PROJECT}/locations/${REGION}/reasoningEngines" \
  | jq -r '.reasoningEngines[] | select(.displayName == "gatekeeper") | .name')
echo "Deleting: $RUNTIME_ID"
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}?force=true"
rm -f deployment_metadata.json deployment_metadata.json.lock

Kiểm tra danh tính của tác nhân

agents-cli ghi lại tài nguyên đã triển khai trong deployment_metadata.json:

export RUNTIME_ID=$(jq -r .remote_agent_runtime_id ~/gatekeeper/deployment_metadata.json)
echo "$RUNTIME_ID"

curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}" \
  | jq -r .spec.effectiveIdentity

Dòng kết quả thứ hai là danh tính mà Gatekeeper chạy dưới dạng:

Đã triển khai với	Ví dụ về đầu ra
Tài khoản dịch vụ (mặc định)	`123456789012-compute@developer.gserviceaccount.com`
Danh tính của tác nhân	`agents.global.org-.system.id.goog/resources/aiplatform/projects//locations/us-central1/reasoningEngines/`

Tài khoản dịch vụ được chia sẻ cho mọi thành phần trong dự án sử dụng tài khoản đó. Mỗi tác nhân có một Danh tính tác nhân riêng, vì vậy, bạn có thể cấp cho tác nhân đó chính xác những vai trò cần thiết và xem riêng các hành động của tác nhân đó trong nhật ký kiểm tra.

8. 8. Kết nối với Gatekeeper đã triển khai qua A2A

Thời gian chạy của tác nhân phân phát các tuyến A2A do Gatekeeper tạo phía sau đường dẫn /api đã xác thực.

Đảm bảo quá trình đánh giá ở Bước 6 đã hoàn tất, sau đó dừng Gatekeeper cục bộ trong thẻ thứ hai (Ctrl+C). Từ giờ trở đi, trình lập kế hoạch theo dõi sẽ gọi trình lập kế hoạch đã triển khai. Trong thẻ đầu tiên, hãy trỏ trình lập kế hoạch theo dõi vào thẻ đó:

export RUNTIME_ID=$(jq -r .remote_agent_runtime_id ~/gatekeeper/deployment_metadata.json)
: "${RUNTIME_ID:?No deployed Gatekeeper found. Complete Step 7 first.}"
cd ~/track-planner
echo "GATEKEEPER_A2A_URL=https://${REGION}-aiplatform.googleapis.com/reasoningEngines/v1/${RUNTIME_ID}/api/a2a/app" >> .env

Lý do ứng dụng làm mới mã thông báo

Mở app/auth.py. Mã truy cập Google Cloud sẽ hết hạn sau một giờ, vì vậy, ứng dụng đặt tiêu đề Authorization cố định khi khởi động sẽ bắt đầu không thành công với 401 Unauthorized sau một giờ. GoogleAuthRefresh phân lớp httpx.Auth và kiểm tra thông tin xác thực trên mọi yêu cầu, làm mới thông tin xác thực khi cần. create_remote_gatekeeper_agent() chỉ đính kèm thông số này cho các URL https://.

Chạy từ đầu đến cuối

Khởi động lại playground để playground nhận GATEKEEPER_A2A_URL mới:

agents-cli playground --port 8080

Nhấp vào Web Preview (Xem trước trên web) > Preview on port 8080 (Xem trước trên cổng 8080), bắt đầu một phiên mới rồi hỏi:

Assess the Monaco Harbour layout, widen the chicane to 11m, and get Gatekeeper approval.

Các sự kiện trông giống như trong Bước 5, nhưng lệnh gọi remote_gatekeeper hiện chuyển đến Gatekeeper trên Thời gian chạy của tác nhân thay vì thẻ thứ hai.

Xem cuộc gọi đến trên Agent Runtime

Chứng minh rằng yêu cầu thực sự đã đến được Gatekeeper được triển khai qua A2A:

Trong Cloud Console, hãy tìm Nền tảng tác nhân, sau đó mở phần Triển khai trong trình đơn bên trái.
Chọn gatekeeper.
Mở thẻ Phiên.

Bạn sẽ thấy một phiên mới có Mã nhận dạng người dùng bắt đầu bằng A2A_USER_. Máy chủ A2A của Gatekeeper đã tạo mã này khi trình lập kế hoạch theo dõi của bạn gọi máy chủ. Mở thẻ Dấu vết trên cùng một trang để xem lệnh gọi mô hình của Gatekeeper và lệnh gọi công cụ verify_infrastructure_checklist cho yêu cầu đó.

Không bắt buộc: triển khai cả công cụ lập kế hoạch theo dõi

Cho đến nay, trình lập kế hoạch theo dõi chạy trong Cloud Shell, vì vậy, các lệnh gọi A2A đến Gatekeeper sẽ sử dụng thông tin đăng nhập của bạn. Triển khai cả tác nhân lập kế hoạch và cả hai tác nhân đều chạy trên Môi trường thời gian chạy của tác nhân, gọi nhau bằng danh tính đã triển khai của riêng chúng.

Nhấn tổ hợp phím Ctrl+C để dừng Playground, sau đó triển khai trình lập kế hoạch theo cách tương tự như Gatekeeper:

cd ~/track-planner
PROJECT_NUMBER=$(gcloud projects describe "$GOOGLE_CLOUD_PROJECT" --format="value(projectNumber)")
agents-cli deploy \
  --no-agent-identity \
  --service-account "${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --region "$REGION" \
  --no-confirm-project

Cả hai tác nhân đều chạy dưới dạng cùng một tài khoản dịch vụ Compute Engine. Giữ lại --service-account: nếu không có tài khoản này, trình lập kế hoạch sẽ chạy dưới dạng tác nhân dịch vụ mặc định của Thời gian chạy của tác nhân và không thể gọi Gatekeeper (xem phần Tại sao lại dùng tài khoản dịch vụ này? ở Bước 7).

Cách người lập kế hoạch được triển khai tiếp cận Người gác cổng:

agents-cli deploy sao chép các giá trị trong .env vào quá trình triển khai, nhờ đó, trình lập kế hoạch sẽ nhận được GATEKEEPER_A2A_URL mà bạn đã thêm ở trên.
Trong Agent Runtime, GoogleAuthRefresh trong app/auth.py sẽ lấy danh tính đã triển khai của người lập kế hoạch thay vì danh tính của bạn.

Quá trình triển khai mất khoảng 5 đến 8 phút. Khi quá trình này hoàn tất, hãy kiểm tra xem trình lập kế hoạch chạy dưới danh tính nào:

export PLANNER_ID=$(jq -r .remote_agent_runtime_id deployment_metadata.json)
curl -s -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/${PLANNER_ID}" \
  | jq -r .spec.effectiveIdentity

Cách dùng thử hệ thống đã triển khai:

Trong Cloud Console, hãy quay lại phần Nền tảng tác nhân > Triển khai.
Chọn track-planner rồi mở thẻ Playground.

Nhập:

Design and homologate a Formula E circuit at Tokyo Bay.

Chờ bản thiết kế có trạng thái APPROVED (ĐÃ PHÊ DUYỆT) của Gatekeeper.
Quay lại phần Deployments (Triển khai), chọn gatekeeper (người gác cổng) rồi mở thẻ Sessions (Phiên). Phiên A2A_USER_ mới nhất đến từ trình lập kế hoạch đã triển khai, chứ không phải từ Cloud Shell.

Khi bạn dọn dẹp ở bước tiếp theo, hãy xoá cả trình lập kế hoạch:

curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/${PLANNER_ID}?force=true"

9. 9. Khắc phục sự cố và dọn dẹp

Khắc phục sự cố

Dấu hiệu	Cách khắc phục
`UREQ_TOS_NOT_ACCEPTED`	Chấp nhận Điều khoản dịch vụ trong Cloud Console, sau đó thử lại.
Dự án là `(unset)`	Chạy lại các lệnh của dự án ở Bước 2.
`service account info is missing 'email' field`	Chạy `gcloud auth application-default login` (Bước 2), sau đó khởi động lại mọi máy chủ đang chạy.
`FileNotFoundError` cho `SKILL.md`	Hoàn tất Bước 4 hoặc sao chép `$ASSETS/solution/track-planner/.` vào `~/track-planner/`.
`Connection refused` đến `localhost:8001`	Khởi động Gatekeeper cục bộ (Bước 5) hoặc đặt `GATEKEEPER_A2A_URL` thành Gatekeeper đã triển khai (Bước 8).
`Permission 'resourcemanager.projects.setIamPolicy' denied` khi triển khai	Tài khoản của bạn không thể sử dụng Danh tính nhân viên hỗ trợ. Làm theo hộp dọn dẹp ở Bước 7, sau đó sử dụng tài khoản dịch vụ để triển khai.
Trình lập kế hoạch theo dõi đã triển khai báo cáo `403 Forbidden` từ Gatekeeper	Danh tính của người lập kế hoạch không được phép gọi Gatekeeper. Hãy triển khai lại bằng `--service-account` như trong Bước 7 hoặc bằng `--agent-identity` nếu bạn sở hữu dự án.
`429 RESOURCE_EXHAUSTED`	Bạn đã đạt đến hạn mức sử dụng Gemini. Chờ một phút hoặc thêm `--concurrency 1 --qps 2` vào `agents-cli eval run`.
`Address already in use`	Hãy dừng máy chủ kia hoặc chọn một `--port` khác.

Dọn dẹp

Xoá Gatekeeper đã triển khai để Gatekeeper không tiếp tục chạy:

export RUNTIME_ID=$(jq -r .remote_agent_runtime_id ~/gatekeeper/deployment_metadata.json)
: "${RUNTIME_ID:?No deployed Gatekeeper found.}"
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${REGION}-aiplatform.googleapis.com/v1beta1/${RUNTIME_ID}?force=true"

Nếu đã tạo một dự án chỉ cho lớp học lập trình này, thì bạn có thể xoá toàn bộ dự án. Nếu bạn đang tham gia một sự kiện, hãy giữ nguyên dự án được giao cho đến khi ban tổ chức có thông báo khác.

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

agents-cli scaffold create cung cấp cho bạn một dự án ADK tiêu chuẩn, có thể triển khai; bạn chỉ cần viết tác nhân, kỹ năng và bản đánh giá.
Kỹ năng của tác nhân giúp tách biệt kiến thức chuyên môn khỏi câu lệnh cho đến khi tác nhân cần đến.
thinking_level cho phép bạn đánh đổi chiều sâu suy luận để lấy tốc độ cho mỗi tác nhân.
agents-cli eval run biến câu hỏi "có hiệu quả không?" thành điểm số mà bạn có thể theo dõi.
Danh tính tác nhân và A2A giúp các tác nhân được triển khai độc lập có thể làm việc cùng nhau một cách an toàn.