Next ‘26 डेवलपर कीनोट: स्किल और टूल की मदद से ADK एजेंट बनाना

1. परिचय

इस कोडलैब में, Agent Development Kit (ADK) का इस्तेमाल करके, बेहतर मैराथन प्लानर एजेंट बनाया जाएगा. इसमें, एजेंट की क्षमताओं की जांच की जाएगी. जैसे, सिस्टम प्रॉम्प्ट को अच्छी तरह से स्ट्रक्चर करना, डाइनैमिक स्किल लोडिंग, और एमसीपी टूल को मैप करना. आखिर में, एजेंट की जांच स्थानीय तौर पर की जाएगी. इसके बाद, इसे एजेंट रनटाइम (Agent Engine) में डिप्लॉय किया जाएगा.

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

  • नया ADK एजेंट प्रोजेक्ट शुरू करना
  • स्ट्रक्चर्ड बिल्डर का इस्तेमाल करके, एक मज़बूत सिस्टम प्रॉम्प्ट लिखें
  • असल दुनिया की लोकेशन के कॉन्टेक्स्ट के लिए, Google Maps के एमसीपी टूल जोड़ना
  • एजेंट के टूलसेट में, डाइनैमिक तरीके से स्किल लोड करना
  • एजेंट को लोकल लेवल पर एक्ज़ीक्यूट करके देखना
  • एजेंट को Agent Engine (Cloud Run) पर डिप्लॉय करें

आपको किन चीज़ों की ज़रूरत होगी

  • कोई वेब ब्राउज़र, जैसे कि Chrome
  • बिलिंग की सुविधा वाला Google Cloud प्रोजेक्ट
  • Python के बारे में बुनियादी जानकारी

यह कोडलैब, उन डेवलपर्स के लिए है जिन्हें जनरेटिव एआई एजेंट बनाने का कुछ अनुभव है.

अनुमानित अवधि: 45 मिनट

इस कोडलैब में बनाए गए संसाधनों की लागत 2 डॉलर से कम होनी चाहिए.

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

Google Cloud प्रोजेक्ट बनाना

  1. Google Cloud Console में, प्रोजेक्ट चुनने वाले पेज पर, Google Cloud प्रोजेक्ट चुनें या बनाएं.
  2. पक्का करें कि आपके Cloud प्रोजेक्ट के लिए बिलिंग चालू हो. किसी प्रोजेक्ट के लिए बिलिंग चालू है या नहीं, यह देखने का तरीका जानें.

Cloud Shell शुरू करना

Cloud Shell, Google Cloud में चलने वाला एक कमांड-लाइन एनवायरमेंट है. इसमें ज़रूरी टूल पहले से लोड होते हैं.

  1. Google Cloud कंसोल में सबसे ऊपर मौजूद, Cloud Shell चालू करें पर क्लिक करें.
  2. Cloud Shell से कनेक्ट होने के बाद, अपने क्रेडेंशियल की पुष्टि करें:
    gcloud auth list
  3. पुष्टि करें कि आपका प्रोजेक्ट कॉन्फ़िगर किया गया है:
    gcloud config get project
  4. अगर आपका प्रोजेक्ट उम्मीद के मुताबिक सेट नहीं है, तो इसे सेट करें:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

पुष्टि करें:

gcloud auth list

अपने प्रोजेक्ट की पुष्टि करें:

gcloud config get project

अगर ज़रूरी हो, तो इसे सेट करें:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

एपीआई चालू करें

सभी ज़रूरी एपीआई चालू करने के लिए, यह निर्देश चलाएं:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Google Maps API पासकोड बनाना

Google Maps MCP टूल का इस्तेमाल करने के लिए, आपको Maps API पासकोड जनरेट करना होगा.

  1. Google Cloud Console में, खोज बार का इस्तेमाल करके Google Maps Platform > क्रेडेंशियल पर जाएं.
  2. अगर कहा जाए, तो अपने Google Cloud प्रोजेक्ट की पुष्टि करें.
  3. क्रेडेंशियल बनाएं पर क्लिक करें और एपीआई पासकोड चुनें.
  4. जनरेट किए गए एपीआई पासकोड को कॉपी करें. आपको इसकी ज़रूरत अगले चरण में पड़ेगी.

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

इस कोडलैब के लिए, कोड को GitHub पर होस्ट किया गया है. आपको रिपॉज़िटरी को क्लोन करना होगा. इसमें डायरेक्ट्री स्ट्रक्चर और ज़रूरी सब-कॉम्पोनेंट (जैसे, skills/ डायरेक्ट्री) शामिल हैं.

  1. रिपॉज़िटरी का क्लोन बनाएं और प्रोजेक्ट फ़ोल्डर पर जाएं:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Python वर्चुअल एनवायरमेंट सेट अप करें और ADK इंस्टॉल करें:
uv venv
source .venv/bin/activate
uv sync
  1. Maps API पासकोड सेट करें. ऐप्लिकेशन इसे एनवायरमेंट वैरिएबल से पढ़ता है:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

एनवायरमेंट वैरिएबल कॉन्फ़िगर करना

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

  1. सैंपल एनवायरमेंट फ़ाइल कॉपी करें:
cp planner_agent/sample.env planner_agent/.env
  1. planner_agent/.env खोलें. इसके बाद, GOOGLE_CLOUD_PROJECT फ़ील्ड में अपना Google Cloud प्रोजेक्ट आईडी डालें. साथ ही, GOOGLE_MAPS_API_KEY फ़ील्ड में, बनाया गया Google Maps API पासकोड डालें.

फ़ाइल कुछ ऐसी दिखनी चाहिए:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. नया ADK एजेंट बनाना

एजेंट के बारे में जानकारी देने वाली मुख्य फ़ाइल एक्सप्लोर करें: planner_agent/agent.py.

build-agents-with-skills रिपॉज़िटरी में, एजेंट को ADK की Agent क्लास का इस्तेमाल करके शुरू किया जाता है. यह मॉड्यूल, मुख्य मॉडल, पहचान का नाम तय करता है. साथ ही, अन्य मॉड्यूल में तय किए गए निर्देशों और टूल को शामिल करता है.

शुरू करने के लिए कोड की जांच करने के लिए, planner_agent/agent.py खोलें:

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

Agent क्लास, मैसेज के इतिहास, टूल ऑर्केस्ट्रेशन, और एलएलएम कम्यूनिकेशन को अलग कर देती है, ताकि आप एजेंट के व्यवहार पर फ़ोकस कर सकें.

फ़िलहाल, एजेंट के जवाब बहुत सामान्य हैं. इसके साथ, किसी अन्य एलएलएम की तरह इंटरैक्ट किया जा सकता है.

uv run adk run planner_agent

इस कमांड से, एजेंट के साथ चैट शुरू हो जाएगी. यह gemini-3-flash-preview को अपने मॉडल के तौर पर इस्तेमाल करता है और सामान्य सवालों के जवाब दे सकता है.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

एजेंट को मैराथन के बारे में पहले से ही कुछ जानकारी है. हालांकि, नियमों और रूट की प्लानिंग के साथ मैराथन की योजना बनाने के लिए यह काफ़ी नहीं है.

5. सिस्टम प्रॉम्प्ट बनाना

सिस्टम प्रॉम्प्ट (निर्देश) से, एजेंट के व्यवहार का पता चलता है. यह प्रोजेक्ट, एक बड़ी स्ट्रिंग के बजाय PromptBuilder (planner_agent/utils.py) का इस्तेमाल करके, निर्देशों को डाइनैमिक तरीके से कंपोज़ करता है.

प्रॉम्प्ट को लॉजिकल सेक्शन में कैसे बांटा गया है, यह देखने के लिए planner_agent/prompts.py खोलें:

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

planner_agent/agent.py में, यह पहले से ही इंपोर्ट किया जा चुका है.

TODO: Replace Instruction and Description वाला सेक्शन ढूंढें. इसके बाद, instruction और description वैरिएबल को फिर से असाइन करने के लिए, अनकमेंट करें.

कोड का वह सेक्शन ऐसा दिखना चाहिए:

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

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

एजेंट के इस वर्शन को आज़माया जा सकता है:

uv run adk run planner_agent

चैट विंडो में, यह प्रॉम्प्ट भेजें:

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

कुछ समय बाद, आपको इस तरह का जवाब मिलेगा:

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

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

6. स्किल और टूल जोड़ना

planner_agent/agent.py में स्किल और टूल चालू करने के लिए, TODO: Replaces Tools वाला सेक्शन ढूंढें और अगली दो लाइनों से कमेंट हटाएं. आपका कोड ऐसा दिखना चाहिए:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

इस चरण में, कोड में सिर्फ़ यही बदलाव करना ज़रूरी है. इस सेक्शन के बाकी हिस्से में, कौशल और टूल से जुड़े कॉन्सेप्ट के बारे में बताया गया है.

कौशल

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

मैराथन की योजना बनाने वाले एजेंट के लिए, तीन तरह की स्किल तय की गई हैं:

  1. gis-spatial-engineering - यह GeoJSON डेटा को प्रोसेस करके मैराथन का रूट बनाता है.
  2. मैपिंग - जगहों और मौसम की जानकारी खोजने के लिए, Google Maps के टूल का इस्तेमाल करें.
  3. race-director - Validate marathon route follows planning guidelines.

स्किल में स्क्रिप्ट, अतिरिक्त ऐसेट, और रेफ़रंस हो सकते हैं.

ऐप्लिकेशन, सभी स्किल लोड करता है और उन्हें planner_agent/tools.py में टूल के तौर पर उपलब्ध कराता है. ध्यान दें कि get_tools() फ़ंक्शन में यह कैसे किया जाता है:

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

सबसे दिलचस्प हिस्सा, ADK का load_skill_from_dir तरीका है. ADK में स्किल बनाने का एक और तरीका है, जो कि इनलाइन है. इस कोडलैब में इसका इस्तेमाल नहीं किया गया है. हालांकि, यह कुछ ऐसा दिखता है:

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

मैपिंग टूल जोड़ना

मैराथन प्लानर को रास्ते जनरेट करने के लिए, जगह की जानकारी की ज़रूरत होती है. इसके लिए, Google Maps एमसीपी (मॉडल कॉन्टेक्स्ट प्रोटोकॉल) सर्वर को इंटिग्रेट करें.

planner_agent/tools.py में देखें कि एमसीपी सर्वर, ApiRegistry टूल के साथ कैसे रजिस्टर किया जाता है:

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

MCP टूलसेट जोड़ने पर, एजेंट को अपने-आप Google Maps से रास्तों, ऊंचाई, और जगह की जानकारी के बारे में क्वेरी करने की सुविधा मिल जाती है!

7. एजेंट को स्थानीय तौर पर चलाना

अब एजेंट, प्रॉम्प्ट, और टूल एक साथ काम कर रहे हैं. इसलिए, एजेंट को स्थानीय तौर पर चलाएं. इस बार, आपको adk web का इस्तेमाल करना होगा, ताकि Skill Load और Tool Call इवेंट देखे जा सकें.

uv run adk web

आपको कुछ ऐसा दिखेगा

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. अपना ब्राउज़र खोलें और टर्मिनल में दिखाए गए यूआरएल पर जाएं. आम तौर पर, यह http://localhost:8000 होता है.
  2. सबसे ऊपर बाईं ओर मौजूद ड्रॉप-डाउन में, planner_agent को चुनें.
  3. चैट विंडो में, यह प्रॉम्प्ट भेजें:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

आपको स्किल लोड होते हुए और टूल कॉल होते हुए दिखेंगे. कुछ ही देर में एजेंट, मैराथन का प्लान जनरेट कर देगा.

आपका यूज़र इंटरफ़ेस (यूआई) कुछ ऐसा दिखना चाहिए:

ADK का वेब यूज़र इंटरफ़ेस (यूआई)

8. एजेंट को डिप्लॉय करना

जब आपको लगे कि एजेंट लोकल तौर पर ठीक से काम कर रहा है, तब उसे Agent Engine पर डिप्लॉय किया जा सकता है. यह एजेंट को Cloud Run पर सुरक्षित तरीके से होस्ट करता है.

एजेंट को डिप्लॉय करने के लिए, ADK CLI की डिप्लॉयमेंट कमांड का इस्तेमाल करें:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

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

आउटपुट ऐसा दिखता है:

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

एजेंट से बातचीत करने के लिए, दी गई Python स्क्रिप्ट का इस्तेमाल किया जा सकता है.

  1. सैंपल एनवायरमेंट फ़ाइल कॉपी करें:
cp sample.env .env
  1. .env खोलें और GOOGLE_CLOUD_PROJECT फ़ील्ड में अपना Google Cloud प्रोजेक्ट आईडी डालें.

फ़ाइल ऐसी दिखनी चाहिए:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. अपने प्रोजेक्ट में एजेंटों को सूची में शामिल किया जा सकता है.
python main.py list

आपको कुछ ऐसा दिखेगा

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

एजेंट आईडी डिप्लॉय करने के बाद, प्रॉम्प्ट भेजा जा सकता है:

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

आपको इस तरह का आउटपुट मिलेगा:

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

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

अपने Google Cloud खाते से लगातार शुल्क लिए जाने से बचने के लिए, इस कोडलैब के दौरान बनाई गई संसाधन मिटाएं.

डिप्लॉयमेंट से बनाई गई Cloud Run सेवा मिटाएं:

python main.py delete --agent-id ${AGENT_ID}

अगर आपने Maps API पासकोड को Secret Manager में सेव किया है, तो सीक्रेट मिटाएं:

gcloud secrets delete maps-api-key --project=$PROJECT_ID

अगर आपने इस कोडलैब के लिए नया Google Cloud प्रोजेक्ट बनाया है, तो इससे जुड़े सभी संसाधनों और एपीआई को हटाने के लिए, पूरे प्रोजेक्ट को मिटाया जा सकता है:

gcloud projects delete $PROJECT_ID

10. बधाई हो

बधाई हो! आपने ADK का इस्तेमाल करके, बेहतर मैराथन प्लानर एजेंट बनाया हो.

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

  • Agent Development Kit (ADK) प्रोजेक्ट शुरू करना
  • मॉड्यूलर सिस्टम प्रॉम्प्ट के लिए PromptBuilder का इस्तेमाल करना
  • एमसीपी टूल और ApiRegistry का इस्तेमाल करके, मैपिंग की सुविधाओं को इंटिग्रेट करना
  • SkillToolset का इस्तेमाल करके, शर्तों के हिसाब से स्किल लोड करना
  • स्थानीय तौर पर जांच करना और एजेंट इंजन में डिप्लॉय करना

रेफ़रंस दस्तावेज़