ADK और A2A की मदद से, फ़ॉर्मूला ई ट्रैक प्लानर के लिए मल्टी-एजेंट सिस्टम बनाना

1. 1. खास जानकारी

इस कोडलैब में, आपको एक मल्टी-एजेंट सिस्टम बनाने का तरीका बताया गया है. यह सिस्टम, फ़ॉर्मूला ई स्ट्रीट सर्किट डिज़ाइन करता है और एफ़आईए के आसान नियमों के तहत उसे मंज़ूरी दिलाता है.

आपको agents-cli का इस्तेमाल करके, दो स्टैंडर्ड Agent Development Kit (ADK) प्रोजेक्ट जनरेट करने होंगे. इसके बाद, आपको ज़रूरी हिस्से लिखने होंगे: एजेंट की स्किल, तीन एजेंट, और एक आकलन. अन्य सभी चीज़ें (प्रोजेक्ट लेआउट, सर्वर, डिपेंडेंसी, डिप्लॉयमेंट कॉन्फ़िगरेशन) सीएलआई से आती हैं.

क्या आपको फ़ॉर्मूला ई के बारे में ज़्यादा जानकारी नहीं है?

आपको मोटरस्पोर्ट के बारे में जानकारी होना ज़रूरी नहीं है. ये पांच शब्द काफ़ी हैं:

• Formula E: एफ़आईए की ऑल-इलेक्ट्रिक रेसिंग चैंपियनशिप. ज़्यादातर रेस, शहर के बीचों-बीच बने अस्थायी स्ट्रीट सर्किट पर होती हैं.
• होमोलोगेशन: एफ़आईए की ओर से दी गई आधिकारिक मंज़ूरी, जिससे यह पता चलता है कि सर्किट पर रेस करना सुरक्षित है. होमोलोगेशन नहीं, तो रेस नहीं.
• रीजनरेटिव ब्रेकिंग: जब कार में ब्रेक लगाया जाता है, तो उसकी मोटर बैटरी को रीचार्ज करती हैं. ज़ोर से ब्रेक लगाने पर ज़्यादा ऊर्जा वापस मिलती है. इसलिए, इस कोडलैब के नियमों के मुताबिक, कम से कम एक बार ज़ोर से ब्रेक लगाना ज़रूरी है.
• सीएडी लेयर: सर्किट के डिज़ाइन ड्रॉइंग में मौजूद लेयर के नाम. जैसे, रेसिंग लाइन, पिट लेन, और बैरियर. एफ़आईए यह जांच करता है कि ज़रूरी सुरक्षा उपकरण मौजूद हैं या नहीं.
• अटैक मोड: रेसिंग लाइन से बाहर मौजूद ऐक्टिवेशन ज़ोन से गुज़रने पर, ड्राइवरों को कुछ समय के लिए ज़्यादा पावर मिलती है.

आपके एजेंट दोनों तरफ़ से काम करते हैं: एक एजेंट सर्किट डिज़ाइन करता है और दो एजेंट एफ़आईए के लिए उसकी जांच करते हैं.

आपको क्या बनाना होगा

हरे रंग के बॉक्स एजेंट हैं और डैश वाले बॉक्स उनके टूल हैं. ADK प्लेग्राउंड में भी इन्हें इसी तरह दिखाया जाता है. इनमें से दो टूल, अन्य एजेंट को रैप करते हैं: fia_assessor, एफ़आईए असेसर एजेंट है, जिसके पास एफ़आईए के नियमों का पालन करने की स्किल है. वहीं, remote_gatekeeper, A2A के ज़रिए दूसरे प्रोजेक्ट में गेटकीपर एजेंट को कॉल करता है.

एजेंट	प्रोजेक्ट	नौकरी	thinking_level
लीड आर्किटेक्ट	track-planner	वेन्यू की जानकारी पढ़ता है, Assessor से सवाल पूछता है, समस्याओं को ठीक करता है, और Gatekeeper से अनुमति मांगता है	HIGH
एफ़आईए असेसर	track-planner	यह एफ़आईए स्किल और स्कोरिंग टूल का इस्तेमाल करके, लेआउट की जांच करता है	MEDIUM
डिजिटल ट्विन गेटकीपर	gatekeeper	यह होमोलोकेशन की आखिरी चेकलिस्ट को चलाता है	LOW

आपको क्या सीखने को मिलेगा

• agents-cli scaffold create, ADK प्रोजेक्ट को कैसे लेआउट करता है और किन फ़ाइलों में बदलाव किया जाता है.
• डोमेन नॉलेज को एजेंट स्किल (SKILL.md, references/, scripts/) के तौर पर पैकेज करने और उसे ADK के SkillToolset के साथ लोड करने का तरीका.
• हर एजेंट के काम के हिसाब से thinking_level को कैसे मैच किया जाए.
• agents-cli eval run की मदद से एजेंट का आकलन करने का तरीका.
• एजेंट को Agent Runtime पर डिप्लॉय करने का तरीका, एजेंट की पहचान और सेवा खाते के बीच का अंतर, और डिप्लॉय किए गए एजेंट को A2A प्रोटोकॉल के ज़रिए कॉल करने का तरीका.

इस कोडलैब में मौजूद वेन्यू, एफ़आईए के नियम, और एनर्जी मॉडल, सीखने-सिखाने के लिए आसान बनाए गए हैं. ये एफ़आईए या फ़ॉर्मूला ई का आधिकारिक डेटा नहीं है.

2. 2. अपना एनवायरमेंट सेट अप करने का तरीका

शुरू करने से पहले

आपके पास बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट होना चाहिए. अगर किसी इवेंट में इस कोडलैब को फ़ॉलो किया जा रहा है, तो आपको दिए गए खाते और प्रोजेक्ट का इस्तेमाल करें.

क्या इस खाते का इस्तेमाल Google Cloud के साथ पहली बार किया जा रहा है? कोई भी निर्देश चलाने से पहले, Google Cloud console खोलें, साइन इन करें, और सेवा की शर्तें स्वीकार करें. ऐसा न करने पर, gcloud कमांड UREQ_TOS_NOT_ACCEPTED के साथ काम नहीं करते.

Cloud Shell खोलें और अपना प्रोजेक्ट सेट करें

Cloud Shell खोलें. इसके बाद, यह कमांड चलाएं:

# 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"

ये वैरिएबल सिर्फ़ मौजूदा Cloud Shell सेशन के लिए होते हैं. अगर Cloud Shell फिर से कनेक्ट होता है या आपको नए टैब में उनकी ज़रूरत है, तो उन्हें फिर से सेट करें. सातवें चरण में, इन सभी को एक ही ब्लॉक में दिखाया गया है.

अपने एजेंट के लिए क्रेडेंशियल बनाना

gcloud में पहले से साइन इन किया हुआ है. हालांकि, आपके एजेंट जो Python कोड चलाते हैं वे ऐप्लिकेशन डिफ़ॉल्ट क्रेडेंशियल (एडीसी) का इस्तेमाल करते हैं. इसके लिए, अलग से साइन इन करना ज़रूरी है:

gcloud auth application-default login

प्रिंट किए गए लिंक को खोलें और उसी खाते से साइन इन करें. इसके बाद, कोड को कॉपी करें और उसे Cloud Shell में वापस चिपकाएं. इसके बाद, वह प्रोजेक्ट सेट करें जिसके लिए कोटा का बिल भेजा जाता है:

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

अगर आपने ऐसा नहीं किया, तो एजेंट service account info is missing 'email' field के साथ रन नहीं हो पाएगा.

एपीआई चालू करना

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

हर एपीआई का मकसद:

API	इनके लिए इस्तेमाल होता है
aiplatform	Gemini मॉडल और एजेंट रनटाइम
cloudresourcemanager, serviceusage, iam	प्रोजेक्ट और अनुमति की जांच, जो gcloud और agents-cli deploy चलाते हैं
compute	यह Compute Engine का डिफ़ॉल्ट सेवा खाता बनाता है. इसका इस्तेमाल, सातवें चरण में डिप्लॉय करने के लिए किया जाता है
storage, logging, cloudtrace	स्टोरेज, लॉग, और ट्रेस, जैसा कि एजेंट रनटाइम सेटअप गाइड में सुझाया गया है
cloudbuild, artifactregistry	कंटेनर बिल्ड और इमेज, जिन्हें सातवें चरण में डिप्लॉय करने के लिए सावधानी के तौर पर शामिल किया गया है

कई प्रोजेक्ट में इनमें से कुछ सुविधाएं पहले से ही चालू हैं. पहले से चालू एपीआई को चालू करने से कुछ नहीं बदलता.

uv और 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

इस कोडलैब को agents-cli 1.10.0 के साथ टेस्ट किया गया था. इसलिए, जनरेट की गई फ़ाइलें पाने के लिए, यह वर्शन इंस्टॉल करें.

कोई एपीआई पासकोड नहीं है. इस कोडलैब में मौजूद हर चीज़ की पुष्टि, आपके Google Cloud क्रेडेंशियल (ऐप्लिकेशन के डिफ़ॉल्ट क्रेडेंशियल) से की जाती है. GEMINI_API_KEY न बनाएं.

3. 3. प्रोजेक्ट का ढांचा तैयार करना और ऐसेट जोड़ना

दोनों प्रोजेक्ट जनरेट करें

agents-cli scaffold create, डिप्लॉय किया जा सकने वाला पूरा ADK प्रोजेक्ट जनरेट करता है. इसे दो बार चलाएं, हर एजेंट सिस्टम के लिए एक बार.

सबसे पहले, ट्रैक प्लानर:

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

इसके बाद, गेटकीपर:

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

झंडा	मतलब
--agent adk	Python ADK टेंप्लेट से शुरू करना
--deployment-target agent_runtime	एजेंट रनटाइम के लिए सर्वर और कॉन्फ़िगरेशन जनरेट करना
--prototype	सीआई/सीडी को स्किप करें; प्रोजेक्ट को कम से कम रखें
--yes	बिना पूछे डिफ़ॉल्ट सेटिंग स्वीकार करें

लेआउट को एक्सप्लोर करना

जनरेट किया गया प्रोजेक्ट कुछ ऐसा दिखता है. सिर्फ़ उन फ़ाइलों में बदलाव किया जा सकता है जिन पर ✍️ का निशान लगा हो:

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`

जनरेट की गई हर फ़ाइल के ब्यौरे के लिए, Agents CLI की गाइड में प्रोजेक्ट का स्ट्रक्चर देखें.

app/agent.py खोलें: इस टेंप्लेट में, मौसम की जानकारी देने वाला एक छोटा एजेंट शामिल है. इसका name, agents-cli-manifest.yaml में root_agent_name से मेल खाता है. अपने एजेंट बनाते समय, इन दोनों को सिंक करके रखें.

जनरेट किए गए एजेंट को आज़माएं

कोई भी बदलाव करने से पहले, टेंप्लेट एजेंट को चलाकर देखें कि स्कैफ़ोल्ड आपको क्या देता है. डिपेंडेंसी इंस्टॉल करें और पोर्ट 8080 पर लोकल प्लेग्राउंड शुरू करें:

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

इसे खोलने के लिए, Cloud Shell टूलबार में वेब की झलक बटन पर क्लिक करें. यह सबसे ऊपर दाईं ओर मौजूद आंख का आइकॉन होता है. इसके बाद, पोर्ट 8080 पर झलक देखें को चुनें.

प्लेग्राउंड में, टेंप्लेट एजेंट से ऐसा सवाल पूछें जिसका जवाब उसके टूल दे सकें. उदाहरण के लिए:

What's the weather in San Francisco?

साइड पैनल में हर इवेंट दिखता है. इसमें get_weather टूल कॉल और उसका नतीजा भी शामिल है. बाद में, अपने एजेंट को फ़ॉलो करने के लिए, इसी व्यू का इस्तेमाल किया जाएगा.

काम पूरा होने के बाद, टर्मिनल पर वापस जाएं और प्लेग्राउंड को बंद करने के लिए, Ctrl+C दबाएं.

Formula E की ऐसेट जोड़ें

वेन्यू डेटा, एफ़आईए के नियम, फ़िज़िक्स स्क्रिप्ट, टूल, और इवैल्यूएशन डेटासेट, इस लेसन का हिस्सा नहीं हैं. इसलिए, इन्हें टाइप करने के बजाय GitHub से कॉपी करें:

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 एक तय रिलीज़ टैग है. इसलिए, सभी को एक जैसी फ़ाइलें मिलती हैं. $ASSETS को दूसरे चरण में सेट किया गया था. यह उस फ़ोल्डर पर ले जाता है जिसे आपने अभी-अभी क्लोन किया है.

इससे ये फ़ाइलें जुड़ जाती हैं:

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

इंस्टॉल करना और टेस्ट करना

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

agents-cli install, हर प्रोजेक्ट के लिए वर्चुअल एनवायरमेंट बनाने के लिए uv sync को चलाता है. सभी यूनिट टेस्ट पास होने चाहिए.

क्या आपको लगता है कि आप पीछे छूट रहे हैं? किसी भी समय, cp -r "$ASSETS/solution/track-planner/." ~/track-planner/ और cp -r "$ASSETS/solution/gatekeeper/." ~/gatekeeper/ का इस्तेमाल करके, तैयार फ़ाइलों को कॉपी करें.

4. 4. एफ़आईए के नियमों का पालन करने वाली स्किल तैयार करना

एजेंट स्किल, निर्देशों, रेफ़रंस दस्तावेज़ों, और स्क्रिप्ट को एक फ़ोल्डर में पैकेज करती है. एडीके का SkillToolset इसे तीन लेवल में लोड करता है. इससे एजेंट सिर्फ़ वही जानकारी पढ़ता है जिसकी उसे ज़रूरत होती है:

लेवल	फ़ाइल	एजेंट को यह कब दिखता है
1	SKILL.md फ़्रंट मैटर (name, description)	हमेशा (कुछ दर्जन टोकन)
2	SKILL.md बॉडी	load_skill को कॉल करने पर
3	references/, scripts/	जब load_skill_resource या run_skill_script को कॉल किया जाता है

स्किल app/skills/ में मौजूद है, क्योंकि जनरेट किया गया Dockerfile, डिप्लॉय की गई इमेज में सिर्फ़ app/ को कॉपी करता है.

लेवल 3 की फ़ाइलें देखना

आपने तीसरे चरण में, स्किल के तीसरे लेवल की फ़ाइलें कॉपी की हैं:

• references/track_regulations.md में वे नियम होते हैं जिनकी जांच Assessor करता है: लंबाई और चौड़ाई की सीमाएं, हर ब्रेकिंग ज़ोन के लिए ज़रूरी बैरियर, ज़रूरी CAD लेयर (अस्पताल के रास्तों के लिए मेडिकल लेयर भी), रीजेनरेशन टारगेट, और Attack Mode के नियम.
• scripts/calculate_regen_zones.py एक कैलकुलेटर है. ब्रेकिंग ज़ोन में गाड़ी की एंट्री स्पीड, एग्ज़िट स्पीड, और ब्रेकिंग डिस्टेंस के आधार पर, यह सिस्टम रिकवर की गई ऊर्जा और कॉर्नर के लिए ज़रूरी बैरियर का हिसाब लगाता है. इससे एजेंट को फ़िज़िक्स का अनुमान लगाने की ज़रूरत नहीं पड़ती.

लंदन के टर्न 10 के लिए स्क्रिप्ट चलाएं, जहां कारें 82 मीटर की दूरी पर 215 से 55 किलोमीटर प्रति घंटे की रफ़्तार से ब्रेक लगाती हैं:

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

यहां कार 508 किलोवॉट ऊर्जा रिकवर करती है, जो 250 किलोवॉट के टारगेट से ज़्यादा है. यह 2G से ज़्यादा की स्पीड को धीमा कर देता है. इसलिए, कोने में 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"}

SKILL.md में बदलाव करें

ऐसी फ़ाइल बनाएं जो स्किल को एक साथ जोड़ती हो:

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

यह कॉन्टेंट जोड़ें:

---
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 को पढ़कर ही मॉडल यह तय करता है कि स्किल का इस्तेमाल कब करना है. इसलिए, इसमें यह बताया जाता है कि स्किल क्या काम करती है और इसका इस्तेमाल कब करना है.

देखें कि स्किल कैसे काम करती है

Cloud Shell Editor में app/tools.py खोलें:

cloudshell edit app/tools.py

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, स्किल फ़ोल्डर को पढ़ता है: SKILL.md, references/, और scripts/.
• SkillToolset, इसे ऐसे टूल में बदल देता है जिन्हें एजेंट कॉल कर सकता है: list_skills, load_skill, load_skill_resource, और run_skill_script.
• UnsafeLocalCodeExecutor, run_skill_script को इस मशीन पर Python स्क्रिप्ट चलाने की अनुमति देता है. यह लैब के लिए ठीक है. प्रोडक्शन में सैंडबॉक्स किए गए एक्ज़ीक्यूटर का इस्तेमाल करें.

अगले चरण में, इस टूलसेट को Assessor से अटैच किया जाएगा.

5. 5. एजेंट के बारे में जानकारी दें

Gemini 3 मॉडल, टोकन बजट के बजाय thinking_level (LOW, MEDIUM या HIGH) का इस्तेमाल करके, रीज़निंग को कंट्रोल करते हैं. ADK में, इसे types.ThinkingConfig(thinking_level=types.ThinkingLevel.HIGH) से सेट किया जाता है. इसे हर एजेंट के काम के हिसाब से सेट करें: ज़्यादा सोचने का मतलब है बेहतर प्लानिंग, लेकिन इससे इंतज़ार का समय और लागत बढ़ जाती है.

गेटकीपर (LOW)

गेटकीपर सिर्फ़ डिटरमिनिस्टिक चेकलिस्ट चलाता है. इसलिए, इसे ज़्यादा तर्क की ज़रूरत नहीं होती. टेंप्लेट एजेंट को बदलें:

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",
)

Gatekeeper को डिवाइस पर चलाना

दूसरा Cloud Shell टैब खोलें और पोर्ट 8001 पर Gatekeeper का जनरेट किया गया सर्वर चालू करें:

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

इस टैब को खुला रखें और Gatekeeper सर्वर को चालू रहने दें. इसे (Ctrl+C) बंद न करें या टैब को बंद न करें. ट्रैक प्लानर और छठे चरण में किया जाने वाला आकलन, http://localhost:8001 पर मौजूद इस लोकल गेटकीपर सर्वर को तब तक कॉल करता है, जब तक कि आप आठवें चरण में डिप्लॉय किए गए सर्वर पर स्विच नहीं कर लेते.

पहले टैब पर वापस जाएं और Gatekeeper का एटूए एजेंट कार्ड देखें. इससे अन्य एजेंट को यह पता चलता है कि Gatekeeper क्या है और यह क्या कर सकता है:

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

आपको इस तरह का JSON दिखेगा (छोटे फ़ॉर्मैट में):

{
  "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 और description, सीधे तौर पर आपकी Agent(...) परिभाषा से आते हैं.
• skills में बताया गया है कि एजेंट क्या कर सकता है. ADK ने टूल की docstring का इस्तेमाल करके, verify_infrastructure_checklist को अपने-आप जोड़ दिया है.
• supportedInterfaces, कॉलर को बताता है कि A2A अनुरोध कहां भेजने हैं. इसलिए, आपने सर्वर को APP_URL=http://localhost:8001 से शुरू किया: कॉलर पहले कार्ड को पढ़ता है. इसके बाद, कार्ड जिस url का विज्ञापन दिखाता है उसे अपने अनुरोध भेजता है.

यहां कुछ भी मैन्युअल तरीके से नहीं लिखा गया है: स्कैफ़ोल्ड किया गया सर्वर, आपके एजेंट से कार्ड बनाता है. ट्रैक प्लानर इस कार्ड को पढ़कर, गेटकीपर को ढूंढेगा और उसे कॉल करेगा.

असेसर (MEDIUM) और लीड आर्किटेक्ट (HIGH)

ट्रैक प्लानर में दो एजेंट होते हैं:

• Assessor कई नियमों को ध्यान में रखता है, इसलिए इसे MEDIUM मिलता है. इसे AgentTool में रैप किया गया है. इसलिए, लीड आर्किटेक्ट इसे एक फ़ंक्शन की तरह कॉल करता है और फ़ैसला वापस पाता है.
• लीड आर्किटेक्ट, प्लान बनाता है, समस्याओं को ठीक करता है, और कोऑर्डिनेट करता है, ताकि HIGH. यह RemoteA2aAgent के ज़रिए Gatekeeper तक पहुंचता है. इसे create_remote_gatekeeper_agent() ने app/auth.py में बनाया है. साथ ही, इसे AgentTool में रैप किया है.

दोनों हेल्पर को टूल के तौर पर क्यों रैप करें? AgentTool, कॉलर को जवाब देता है, ताकि लीड आर्किटेक्ट के पास कंट्रोल रहे और वह फ़ाइनल ब्लूप्रिंट लिख सके. अगर गेटकीपर sub_agent होता, तो लीड आर्किटेक्ट बातचीत को उसे सौंप देता. इसके बाद, गेटकीपर का शॉर्ट स्टेटस ही फ़ाइनल जवाब होता.

किसी ऐसे एजेंट पर output_schema सेट न करें जिसमें tools या sub_agents भी हो. इससे टूल कॉलिंग और डेलिगेशन की सुविधा बंद हो जाती है.

ट्रैक प्लानर की app/agent.py फ़ाइल खोलें:

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

यहां दिया गया कोड कॉपी करें और ~/track-planner/app/agent.py के पूरे कॉन्टेंट को इससे बदलें:

"""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",
)

पूरे सिस्टम को Playground में चलाएं

पक्का करें कि Gatekeeper अब भी आपके दूसरे टैब में चल रहा हो. पहले टैब में, ट्रैक प्लानर का प्लेग्राउंड शुरू करें:

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

वेब की झलक > पोर्ट 8080 पर झलक देखें पर क्लिक करें, जैसा कि आपने तीसरे चरण में किया था.

नियमों का पालन करने वाले किसी वेन्यू पर सर्किट बनाने का अनुरोध करें:

Design and homologate a Formula E circuit at Tokyo Bay.

एजेंट के काम करने के दौरान, इवेंट पैनल देखें. आपको ये विकल्प इस क्रम में दिखेंगे:

1. get_track_topology: लीड आर्किटेक्ट, टोक्यो बे का डेटा लोड करता है.
2. fia_assessor: लीड आर्किटेक्ट, लेआउट को असेसर को सौंपता है. इसके बाद, असेसर load_skill, load_skill_resource, और run_skill_script (हर ब्रेकिंग ज़ोन के लिए एक बार) को कॉल करता है. इसके बाद, evaluate_track_layout को कॉल करता है.
3. remote_gatekeeper: लीड आर्किटेक्ट, A2A के ज़रिए गेटकीपर को कॉल करता है. आपको दूसरे टैब में अनुरोध लॉग किया हुआ दिखेगा.
4. लीड आर्किटेक्ट का फ़ाइनल ब्लूप्रिंट, जिसमें हर सीएडी लेयर और गेटकीपर का मंज़ूरी स्टेटस शामिल हो.

किसी भी इवेंट पर क्लिक करके, उसके सटीक इनपुट और आउटपुट देखें.

अब एक नया सेशन शुरू करें और किसी ऐसी जगह की जानकारी खोजें जो नियमों का उल्लंघन करती हो:

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

इस बार, असेसर 6.8 मीटर के चिकेन को अस्वीकार कर देता है. इसके बाद, लीड आर्किटेक्ट ज़्यादा चौड़ा चिकेन बनाने का सुझाव देता है. फिर, तय किया गया लेआउट गेटकीपर के पास पहुंचने से पहले, असेसर के पास वापस जाता है.

काम पूरा होने के बाद, प्लेग्राउंड को बंद करने के लिए पहले टैब में Ctrl+C दबाएं. Gatekeeper को दूसरे टैब में चलने दें: आपको अगले चरण में इसकी ज़रूरत पड़ेगी.

6. 6. एजेंट का आकलन करना

agents-cli eval run, आपके एजेंट को किसी डेटासेट पर चलाता है. साथ ही, हर टर्न और टूल कॉल को रिकॉर्ड करता है और नतीजों को ग्रेड देता है. आपको तय करना होगा कि tests/eval/eval_config.yaml में क्या मेज़र करना है.

डेटासेट देखें

Cloud Shell Editor में डेटासेट खोलें:

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

इस फ़ाइल में eval_cases की सूची होती है. हर केस में एक eval_case_id, एक prompt (उपयोगकर्ता क्या पूछता है), और एक reference (एक अच्छा जवाब कैसा दिखता है) होता है. एलएलएम जज, एजेंट के जवाब की तुलना रेफ़रंस से करता है.

eval_case_id	इससे क्या टेस्ट किया जाता है
fe_001_tokyo_compliant	ऐसा वेन्यू जो हर नियम का पालन करता है और जिसे मंज़ूरी मिल जाती है
fe_002_monaco_narrow	6.8 मीटर लंबा चिकेन, चौड़ाई के नियम का पालन नहीं करता
fe_003_berlin_too_long	4,350 मीटर लंबा यह सर्किट, लंबाई के नियम को पूरा नहीं करता
fe_004_missing_layers	लेआउट में ज़रूरी सीएडी लेयर मौजूद नहीं हैं
fe_005_low_regen	ब्रेकिंग ज़ोन, 250 किलोवॉट के टारगेट से कम है
fe_006_sao_paulo_medical	अस्पताल का ऐक्सेस, जिसके लिए मेडिकल सीएडी लेयर की ज़रूरत होती है
fe_007_attack_mode	रेस ट्रैक पर अटैक मोड ज़ोन
fe_008_multiturn_remediation	मल्टी-टर्न बातचीत: मोनाको को अस्वीकार कर दिया गया है. उपयोगकर्ता, समस्या को ठीक करने के लिए कहता है. साथ ही, ठीक किए गए लेआउट को मंज़ूरी मिलनी चाहिए

आखिरी केस में, prompt के बजाय agent_data का इस्तेमाल किया गया है. यह बातचीत के पिछले टर्न को फिर से चलाता है, ताकि यह टेस्ट किया जा सके कि एजेंट सिर्फ़ एक सवाल का जवाब देने के बजाय, फ़ॉलो-अप अनुरोध को कैसे हैंडल करता है.

एक ही फ़ोल्डर में मौजूद track_eval_quick.json में सिर्फ़ दो केस हैं: केस 1 (एक सवाल) और केस 8 (एक बातचीत). आपको वह मॉडल चलाना होगा, क्योंकि वह तेज़ है और कम कोटा इस्तेमाल करता है.

मेट्रिक लिखें

डेटासेट से पता चलता है कि एजेंट से क्या पूछना है. eval_config.yaml में जवाबों को स्कोर देने का तरीका बताया गया है. agents-cli eval run, एजेंट के हर केस का जवाब देने के बाद उसे पढ़ता है. साथ ही, हर जवाब पर हर मेट्रिक को लागू करता है.

स्कैफ़ोल्ड से जनरेट की गई फ़ाइल खोलें:

cloudshell edit tests/eval/eval_config.yaml

इसमें पहले से ही एक सामान्य एलएलएम जज (custom_response_quality) और एक agent_turn_count मेट्रिक मौजूद होती है. यह मेट्रिक सिर्फ़ टर्न की गिनती करती है. किसी भी एजेंट के लिए यह एक अच्छी शुरुआत है. हालांकि, इसमें Formula E के बारे में कुछ नहीं बताया गया है. आप जज को बनाए रखेंगे और एक ऐसी मेट्रिक जोड़ेंगे जो इस डोमेन के लिए खास नियम की जांच करती है.

अच्छे आकलन में आम तौर पर दो तरह की मेट्रिक शामिल होती हैं:

टाइप	स्कोर कैसे तय किया जाता है	अच्छा है	ट्रेड-ऑफ़
LLM-as-a-judge	मॉडल, जवाब और केस के reference को पढ़ता है. इसके बाद, वह 1 से 5 के बीच स्कोर देता है और इसकी वजह बताता है	फ़ज़ी क्वालिटी: क्या जवाब सही, पूरा, और साफ़ है?	हर केस के लिए, मॉडल को कॉल करने पर शुल्क लगता है. हर बार रन करने पर, स्कोर में थोड़ा अंतर हो सकता है
कोड मेट्रिक	Python का एक छोटा फ़ंक्शन, जवाब की जांच करता है	सटीक और जांचे जा सकने वाले तथ्य: क्या जवाब में कोई ऐसी जानकारी शामिल है जो ज़रूरी है?	यह सिर्फ़ यह जांच करता है कि कोड में क्या लिखा जा सकता है

फ़ाइल के कॉन्टेंट को इससे बदलें:

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"),
          }

हर हिस्से का क्या काम होता है:

• metrics_to_run में, रन की जाने वाली मेट्रिक के नाम की सूची होती है. यहां से किसी मेट्रिक का नाम हटाने पर, वह मेट्रिक बंद हो जाती है. हालांकि, वह मिटती नहीं है.
• custom_response_quality, एलएलएम जज है. custom_function_file ने tests/eval/response_quality.py पर पॉइंट हासिल किए. ये पॉइंट, स्कैफ़ोल्ड ने जनरेट किए थे. अगर आपको आकलन करने वाला प्रॉम्प्ट देखना है, तो इसे खोलें.
• fia_cad_layer_compliance आपकी कोड मेट्रिक है. इसे custom_function में इनलाइन लिखा जाता है. हर केस के लिए, इसे एक instance (प्रॉम्प्ट, एजेंट का आखिरी response, और reference) मिलता है. जिन मामलों में जवाब के तौर पर अनुमति मिलने की उम्मीद होती है उनमें यह जांच की जाती है कि जवाब में सभी चार ज़रूरी सीएडी लेयर के नाम शामिल हों. साथ ही, उन लेयर की सूची बनाई जाती है जो मौजूद नहीं हैं. उदाहरण के लिए, ऐसा ब्लूप्रिंट जिसमें F1_TEC3 को शामिल नहीं किया गया है, उसका स्कोर 0.75 होगा. अन्य मामलों को 1.0 स्कोर दिया जाता है. ऐसा इसलिए, क्योंकि अस्वीकार किए गए या अटैक मोड वाले जवाब में हर लेयर को शामिल करने की ज़रूरत नहीं होती.

सीएडी लेयर की जांच क्यों करें? मंज़ूरी पा चुका ऐसा ब्लूप्रिंट जिसमें कोई ज़रूरी लेयर शामिल न हो, वह गलत होता है. भले ही, वह पढ़ने में सही लगे. एलएलएम जज इसे अनदेखा कर सकता है. कोड की जांच करने पर, हर बार एक ही नियम को एक ही तरीके से लागू किया जाता है.

यह मेट्रिक सिर्फ़ आखिरी जवाब को पढ़ती है. instance में agent_data भी शामिल है. इसमें हर टर्न के टूल कॉल का पूरा रिकॉर्ड होता है. ज़्यादा बेहतर मेट्रिक, ट्रैजेक्ट्री की जांच करने के लिए इसका इस्तेमाल कर सकती है. उदाहरण के लिए, remote_gatekeeper को सिर्फ़ fia_assessor के बाद कॉल किया गया था.

जांच करें

लोकल Gatekeeper को अपने दूसरे टैब में चालू रखें. इसके बाद, यह कमांड चलाएं:

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

आकलन में कुछ मिनट लगते हैं. हर केस में, मल्टी-एजेंट फ़्लो को पूरी तरह से चलाया जाता है. इसमें लीड आर्किटेक्ट, HIGH पर करीब दस मॉडल कॉल करता है. इसलिए, Step 1/2: eval generate की प्रोसेस धीमी होती है. यह अटक नहीं रहा है.

इंतज़ार न करें. सातवें चरण में डिप्लॉय करने में भी कुछ मिनट लगते हैं. इसलिए, इसे अभी Cloud Shell के नए टैब में शुरू करें. समीक्षा पूरी होने के बाद, इस चरण पर वापस आएं.

इसके पूरा होने के बाद, Cloud Shell Editor की मदद से artifacts/grade_results/ में एचटीएमएल रिपोर्ट खोलें. fia_cad_layer_compliance के कम स्कोर से पता चलता है कि लीड आर्किटेक्ट के फ़ाइनल जवाब में लेयर शामिल नहीं हैं. इसके निर्देश को और सटीक बनाएं और आकलन फिर से करें.

क्या आपने तय समय से पहले टास्क पूरा कर लिया है? --dataset tests/eval/datasets/track_eval.json के साथ सभी आठ केस चलाएं. इसमें करीब 10 मिनट लगते हैं.

7. 7. गेटकीपर को एजेंट रनटाइम में डिप्लॉय करना

सिर्फ़ Gatekeeper को डिप्लॉय किया जाता है. ट्रैक प्लानर, Cloud Shell में चलता रहता है और उसे कॉल करता है.

नया Cloud Shell टैब खोलें

डिप्लॉय करने में पांच से आठ मिनट लगते हैं. इसलिए, इसे नए टैब में करें. इस दौरान, छठे चरण में किया गया आकलन पूरा हो जाएगा:

1. Cloud Shell टूलबार में, नया टैब खोलें (+) पर क्लिक करें.
2. नए टैब में, दूसरे चरण के वैरिएबल सेव नहीं रहते. इसलिए, उन्हें फिर से सेट करें:

   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 को चालू रहने दें: आकलन के लिए अब भी इसका इस्तेमाल किया जाता है. साथ ही, डिप्लॉय करने के लिए इसे बंद करने की ज़रूरत नहीं होती.

डिप्लॉय करें

नए टैब में, Gatekeeper को डिप्लॉय करें. यह प्रोजेक्ट के Compute Engine के डिफ़ॉल्ट सेवा खाते के तौर पर चलता है:

cd ~/gatekeeper
PROJECT_NUMBER=$(gcloud projects describe "$GOOGLE_CLOUD_PROJECT" --format="value(projectNumber)")
agents-cli deploy \
  --no-agent-identity \
  --service-account "${PROJECT_NUMBER}[e-mail]" \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --region "$REGION" \
  --no-confirm-project

डिप्लॉयमेंट में करीब पांच से आठ मिनट लगते हैं. Cloud Shell टैब के चलने के दौरान उसे बंद न करें. अगर लॉग स्ट्रीम डिसकनेक्ट हो जाती है, तो agents-cli deploy --status की मदद से प्रोग्रेस देखें. इंतज़ार के दौरान, छठे चरण पर वापस जाएं और अपनी इवैल्यूएशन रिपोर्ट पढ़ें.

यह सेवा खाता क्यों? --service-account के बिना, एजेंट रनटाइम एजेंट को उसके डिफ़ॉल्ट सर्विस एजेंट के तौर पर चलाता है. गेटकीपर के लिए यह काफ़ी है. हालांकि, सर्विस एजेंट को अन्य एजेंट रनटाइम एजेंट को कॉल करने की अनुमति नहीं है. इसलिए, आठवें चरण के आखिर में, डिप्लॉय किए गए ट्रैक प्लानर को 403 Forbidden मिलेगा. यह ऐक्सेस देने के लिए, आईएएम में बदलाव करने की अनुमति होनी चाहिए. कई प्रोजेक्ट में, Compute Engine के डिफ़ॉल्ट सेवा खाते के पास एडिटर की भूमिका होती है. इसलिए, यह आईएएम में बदलाव किए बिना काम करता है. इस तरह के ऐक्सेस की वजह से, आपके मालिकाना हक वाले प्रोजेक्ट में एजेंट की पहचान का इस्तेमाल करना बेहतर विकल्प है. इसके बारे में नीचे बताया गया है.

क्या आपके पास प्रोजेक्ट का मालिकाना हक है? इसके बजाय, एजेंट की पहचान का इस्तेमाल करें. एजेंट आइडेंटिटी, डिप्लॉय किए गए हर एजेंट को सिस्टम से मैनेज किया जाने वाला अपना प्रिंसिपल देती है. इसके लिए, वर्कलोड के बीच शेयर किए गए सेवा खाते का इस्तेमाल नहीं किया जाता. agents-cli, नई पहचान को आईएएम भूमिकाएं देता है. इसलिए, आपके पास मालिक या प्रोजेक्ट आईएएम एडमिन की भूमिका होनी चाहिए. ऊपर दिए गए कमांड के बजाय, यह कमांड चलाएं:

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

क्या एजेंट की पहचान की पुष्टि नहीं हो पाई और आपको Permission 'resourcemanager.projects.setIamPolicy' denied गड़बड़ी का कोड मिला? आपके खाते से IAM नीति में बदलाव नहीं किया जा सकता. हालांकि, असफल कोशिश की वजह से, पहले से ही एक खाली Agent Runtime संसाधन बन गया है. इसे मिटाएं और डिप्लॉयमेंट रिकॉर्ड को रीसेट करें. इसके बाद, ऊपर दिए गए सेवा खाते को डिप्लॉय करें:

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

एजेंट की पहचान की जांच करना

agents-cli, डिप्लॉय किए गए संसाधन को 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

आउटपुट की दूसरी लाइन, उस आइडेंटिटी को दिखाती है जिसके तौर पर Gatekeeper चलता है:

इनके साथ डिप्लॉय किया गया	आउटपुट का उदाहरण
सेवा खाता (डिफ़ॉल्ट)	[e-mail]
एजेंट की पहचान	agents.global.org-.system.id.goog/resources/aiplatform/projects//locations/us-central1/reasoningEngines/

सेवा खाते को प्रोजेक्ट में मौजूद उन सभी चीज़ों के साथ शेयर किया जाता है जो इसका इस्तेमाल करती हैं. एजेंट आइडेंटिटी, इस एजेंट से जुड़ी होती है. इसलिए, इसे सिर्फ़ वे भूमिकाएं दी जा सकती हैं जिनकी इसे ज़रूरत है. साथ ही, ऑडिट लॉग में इसकी कार्रवाइयां अलग से देखी जा सकती हैं.

क्या आपको जांचने की पूरी क्षमता चाहिए? जिस प्रोजेक्ट के मालिक आप हैं उसमें agents-cli infra single-project, प्रॉम्प्ट और जवाब की लॉगिंग के साथ-साथ एजेंट के आंकड़ों के लिए BigQuery डेटासेट सेट अप करता है. यह सेवा खाते और आईएएम बाइंडिंग बनाता है. इसलिए, इसे एजेंट आइडेंटिटी जैसी ही अनुमतियों की ज़रूरत होती है. एजेंट सीएलआई की जांच करने की क्षमता से जुड़ी गाइड देखें.

8. 8. A2A पर डिप्लॉय किए गए Gatekeeper से कनेक्ट करना

एजेंट रनटाइम, गेटकीपर के जनरेट किए गए A2A रूट को पुष्टि किए गए /api पाथ के पीछे दिखाता है.

पक्का करें कि छठे चरण में की गई जांच पूरी हो गई हो. इसके बाद, अपने दूसरे टैब (Ctrl+C) में लोकल गेटकीपर को बंद करें. अब से, ट्रैक प्लानर डिप्लॉय किए गए मॉडल को कॉल करेगा. अपने पहले टैब में, ट्रैक प्लानर को इस पर ले जाएं:

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

क्लाइंट अपने टोकन को रीफ़्रेश क्यों करता है

app/auth.py खोलें. Google Cloud के ऐक्सेस टोकन एक घंटे के बाद खत्म हो जाते हैं. इसलिए, स्टार्टअप के समय तय Authorization हेडर सेट करने वाला क्लाइंट, एक घंटे के बाद 401 Unauthorized के साथ काम करना बंद कर देता है. GoogleAuthRefresh, httpx.Auth को सबक्लास करता है और हर अनुरोध पर क्रेडेंशियल की जांच करता है. साथ ही, ज़रूरत पड़ने पर उन्हें रीफ़्रेश करता है. create_remote_gatekeeper_agent() इसे सिर्फ़ https:// यूआरएल के लिए अटैच करता है.

शुरू से लेकर आखिर तक चलाएं

प्लेग्राउंड को फिर से शुरू करें, ताकि यह नए GATEKEEPER_A2A_URL को चुन सके:

agents-cli playground --port 8080

Web Preview > Preview on port 8080 पर क्लिक करें. इसके बाद, नया सेशन शुरू करें और यह सवाल पूछें:

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

इवेंट, पांचवें चरण की तरह ही दिखते हैं. हालांकि, remote_gatekeeper कॉल अब आपके दूसरे टैब के बजाय, Agent Runtime पर Gatekeeper को जाता है.

एजेंट रनटाइम पर कॉल देखें

यह साबित करना कि अनुरोध, डिप्लॉय किए गए गेटकीपर तक वाकई A2A के ज़रिए पहुंचा है:

1. Cloud Console में, Agent Platform खोजें. इसके बाद, बाएं मेन्यू में जाकर डिप्लॉयमेंट खोलें.
2. gatekeeper को चुनें.
3. सेशन टैब खोलें.

आपको एक नया सेशन दिखेगा, जिसका यूज़र आईडी A2A_USER_ से शुरू होता है. Gatekeeper के A2A सर्वर ने इसे तब बनाया, जब आपके ट्रैक प्लानर ने इसे कॉल किया. गेटकीपर के मॉडल कॉल और उस अनुरोध के लिए उसके verify_infrastructure_checklist टूल कॉल को देखने के लिए, उसी पेज पर ट्रेस टैब खोलें.

ज़रूरी नहीं: ट्रैक प्लानर को भी डिप्लॉय करें

फ़िलहाल, ट्रैक प्लानर Cloud Shell में चलता है. इसलिए, Gatekeeper को किए जाने वाले इसके A2A कॉल, आपके क्रेडेंशियल का इस्तेमाल करते हैं. प्लानर को भी डिप्लॉय करें. दोनों एजेंट, एजेंट रनटाइम पर चलते हैं और डिप्लॉय की गई अपनी पहचानों के साथ एक-दूसरे को कॉल करते हैं.

प्लेग्राउंड को बंद करने के लिए, Ctrl+C दबाएं. इसके बाद, प्लानर को उसी तरह डिप्लॉय करें जिस तरह गेटकीपर को किया था:

cd ~/track-planner
PROJECT_NUMBER=$(gcloud projects describe "$GOOGLE_CLOUD_PROJECT" --format="value(projectNumber)")
agents-cli deploy \
  --no-agent-identity \
  --service-account "${PROJECT_NUMBER}[e-mail]" \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --region "$REGION" \
  --no-confirm-project

दोनों एजेंट, एक ही Compute Engine सेवा खाते के तौर पर काम करते हैं. --service-account को बनाए रखें: इसके बिना, प्लानर, Agent Runtime के डिफ़ॉल्ट सर्विस एजेंट के तौर पर चलता है और Gatekeeper को कॉल नहीं कर सकता. सातवें चरण में, इस सेवा खाते की ज़रूरत क्यों है? देखें.

क्या आपने Gatekeeper के लिए एजेंट आइडेंटिटी का इस्तेमाल किया है? प्लानर के लिए भी इसका इस्तेमाल करें. इसके लिए, PROJECT_NUMBER लाइन और --no-agent-identity और --service-account फ़्लैग को --agent-identity से बदलें. प्लानर को गेटकीपर से अलग, अपनी एजेंट आइडेंटिटी मिलती है. इससे A2A कॉल, सही मायने में एजेंट से एजेंट के बीच होता है. agents-cli, उस आइडेंटिटी roles/aiplatform.user को अनुमति देता है जिससे Gatekeeper को कॉल किया जा सकता है.

डिप्लॉय किया गया प्लानर, गेटकीपर तक कैसे पहुंचता है:

• agents-cli deploy, .env में मौजूद वैल्यू को डिप्लॉयमेंट में कॉपी करता है. इससे प्लानर को वह GATEKEEPER_A2A_URL मिलता है जिसे आपने ऊपर जोड़ा है.
• एजेंट रनटाइम में, app/auth.py में मौजूद GoogleAuthRefresh आपकी पहचान के बजाय, प्लानर की डिप्लॉय की गई पहचान का इस्तेमाल करता है.

डिप्लॉयमेंट में करीब पांच से आठ मिनट लगते हैं. इसके पूरा होने के बाद, देखें कि प्लानर किस आइडेंटिटी के तौर पर चलता है:

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

डिप्लॉय किए गए सिस्टम को आज़माने के लिए:

1. Cloud Console में, Agent Platform > डिप्लॉयमेंट पर वापस जाएं.
2. track-planner को चुनें और Playground टैब खोलें.
3. नीचे दी गई चीज़ें डालें:

   Design and homologate a Formula E circuit at Tokyo Bay.
   

4. ब्लूप्रिंट के लिए, गेटकीपर से मंज़ूरी मिलने का इंतज़ार करें.
5. डिप्लॉयमेंट पर वापस जाएं. इसके बाद, gatekeeper को चुनें और सेशन टैब खोलें. सबसे नया A2A_USER_ सेशन, डिप्लॉय किए गए प्लानर से आया है, न कि Cloud Shell से.

अगले चरण में, स्टोरेज खाली करते समय प्लानर को भी मिटाएं:

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

9. 9. समस्या हल करना और स्टोरेज खाली करना

समस्या का हल

समस्या का ब्यौरा	ठीक करें
UREQ_TOS_NOT_ACCEPTED	Cloud Console में जाकर, सेवा की शर्तें स्वीकार करें. इसके बाद, फिर से कोशिश करें.
प्रोजेक्ट (unset) है	दूसरे चरण में दिए गए प्रोजेक्ट कमांड को फिर से चलाएं.
service account info is missing 'email' field	gcloud auth application-default login (दूसरा चरण) चलाएं. इसके बाद, चल रहे सभी सर्वर रीस्टार्ट करें.
SKILL.md के नुकसान पर FileNotFoundError	चौथा चरण पूरा करें या $ASSETS/solution/track-planner/. को ~/track-planner/ में कॉपी करें.
Connection refused से localhost:8001	लोकल Gatekeeper शुरू करें (पांचवां चरण) या GATEKEEPER_A2A_URL को डिप्लॉय किए गए Gatekeeper पर सेट करें (आठवां चरण).
डिप्लॉय करने पर Permission 'resourcemanager.projects.setIamPolicy' denied	आपके खाते से एजेंट की पहचान की सुविधा का इस्तेमाल नहीं किया जा सकता. सातवें चरण में दिए गए क्लीन-अप बॉक्स में दिए गए निर्देशों का पालन करें. इसके बाद, सेवा खाते को डिप्लॉय करें.
तैनात किया गया ट्रैक प्लानर, गेटकीपर से 403 Forbidden रिपोर्ट करता है	प्लानर की पहचान को गेटकीपर को कॉल करने की अनुमति नहीं है. इसे सातवें चरण में बताए गए तरीके के मुताबिक, --service-account के साथ फिर से डिप्लॉय करें. अगर आपके पास प्रोजेक्ट का मालिकाना हक है, तो इसे --agent-identity के साथ फिर से डिप्लॉय करें.
429 RESOURCE_EXHAUSTED	आपने Gemini का कोटा पूरा कर लिया है. एक मिनट इंतज़ार करें या --concurrency 1 --qps 2 को agents-cli eval run में जोड़ें.
Address already in use	दूसरे सर्वर को बंद करें या कोई दूसरा --port चुनें.

व्यवस्थित करें

डिप्लॉय किए गए Gatekeeper को मिटाएं, ताकि वह चलता न रहे:

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"

अगर आपने सिर्फ़ इस कोडलैब के लिए कोई प्रोजेक्ट बनाया है, तो पूरे प्रोजेक्ट को मिटाया जा सकता है. अगर आप किसी इवेंट में हैं, तो आपको दिया गया प्रोजेक्ट तब तक अपने पास रखें, जब तक आयोजक कुछ और न कहें.

आपको क्या सीखने को मिला

• agents-cli scaffold create आपको एक स्टैंडर्ड और डिप्लॉय किया जा सकने वाला ADK प्रोजेक्ट देता है. आपको सिर्फ़ एजेंट, स्किल, और आकलन लिखने होते हैं.
• एजेंट की स्किल, डोमेन की जानकारी को प्रॉम्प्ट से तब तक बाहर रखती हैं, जब तक एजेंट को इसकी ज़रूरत न हो.
• thinking_level की मदद से, हर एजेंट के लिए गहराई से विश्लेषण करने की क्षमता के बजाय, स्पीड को प्राथमिकता दी जा सकती है.
• agents-cli eval run, "क्या यह काम करता है?" को ऐसे स्कोर में बदल देता है जिन्हें ट्रैक किया जा सकता है.
• एजेंट आइडेंटिटी और ए2ए की मदद से, अलग-अलग जगहों पर डिप्लॉय किए गए एजेंट सुरक्षित तरीके से साथ मिलकर काम कर सकते हैं.

ज़्यादा जानें

• एजेंट सीएलआई
• एडीके दस्तावेज़
• एडीके स्किल
• ADK A2A
• एजेंट रनटाइम पर एजेंट की पहचान