Next ‘26 Developer Keynote: Building ADK Agents with Skills and Tools

1. מבוא

בשיעור Codelab הזה נסביר איך ליצור סוכן מתוחכם לתכנון מרתון באמצעות ערכה לפיתוח סוכנים (ADK). תבחנו בהדרגה את היכולות של הסוכן, החל מהנחיית מערכת מובנית היטב ועד לטעינה דינמית של כישורים ומיפוי של כלי MCP. לבסוף, תבדקו את הסוכן באופן מקומי ותפרסו אותו בסביבת זמן הריצה של הסוכן (Agent Engine).

הפעולות שתבצעו:

  • אתחול של פרויקט חדש של סוכן ADK
  • כתיבת הנחיית מערכת חזקה באמצעות כלי ליצירת הנחיות מובנות
  • הוספת כלי MCP של מפות Google להקשר של מיקומים בעולם האמיתי
  • טעינה דינמית של מיומנויות בארגז הכלים של הסוכן
  • בדיקה מקומית של הפעלת הסוכן
  • פריסה של הסוכן ב-Agent Engine ‏ (Cloud Run)

הדרישות

  • דפדפן אינטרנט כמו Chrome
  • פרויקט ב-Google Cloud שהחיוב בו מופעל
  • היכרות בסיסית עם Python

ה-Codelab הזה מיועד למפתחים ברמת ביניים שרוצים ליצור סוכני AI גנרטיבי ייעודיים.

משך הזמן המשוער: 45 דקות

העלות של המשאבים שנוצרו ב-codelab הזה צריכה להיות פחות מ-2$.

‫2. לפני שמתחילים

יצירת פרויקט ב-Google Cloud

  1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
  2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud, וכוללת מראש את הכלים הדרושים.

  1. לוחצים על Activate Cloud Shell בחלק העליון של מסוף Google Cloud.
  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

הפעלת ממשקי ה-API

מריצים את הפקודה הבאה כדי להפעיל את כל ממשקי ה-API הנדרשים:

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, משתמשים בסרגל החיפוש כדי לנווט אל Google Maps Platform > אמצעי אימות.
  2. אם מוצגת הנחיה, מאשרים את פרויקט בענן של Google.
  3. לוחצים על Create Credentials (יצירת אמצעי אימות) ובוחרים באפשרות API key (מפתח API).
  4. מעתיקים את מפתח ה-API שנוצר. תצטרכו אותו בשלב הבא.

3. הגדרת הסביבה

הקוד של ה-Codelab הזה מאוחסן ב-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, הסוכן מאותחל באמצעות המחלקה Agent של ADK. הוא מציין את המודל הבסיסי, שם זהות, ומושך את ההוראות והכלים שהוגדרו במודולים אחרים.

פותחים את 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 מסתירה את היסטוריית ההודעות, את תזמור הכלי ואת התקשורת עם ה-LLM, כדי שתוכלו להתמקד בהתנהגות של הסוכן.

כרגע, הסוכן כללי מאוד. אפשר ליצור איתו אינטראקציה כמו עם כל מודל שפה גדול אחר.

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()

זה השינוי היחיד בקוד שצריך לבצע בשלב הזה. בהמשך הקטע הזה מוסברים המושגים שמאחורי הכישורים והכלים.

כישורים

מיומנות של סוכן היא יחידה עצמאית של פונקציונליות שסוכן ADK יכול להשתמש בה כדי לבצע משימה ספציפית. מיומנות של סוכן כוללת את ההוראות, המשאבים והכלים שנדרשים למשימה, על סמך המפרט של מיומנות הסוכן. המבנה של מיומנות מאפשר לטעון אותה באופן מצטבר כדי למזער את ההשפעה על חלון ההקשר התפעולי של הסוכן.

לסוכן לתכנון מרתון מוגדרות 3 מיומנויות:

  1. ‫gis-spatial-engineering – אחראי לעיבוד נתוני GeoJSON כדי ליצור את מסלול המרתון.
  2. מיפוי – שימוש בכלים של מפות Google לחיפוש מקומות ומידע על מזג האוויר.
  3. ‫race-director – אימות מסלול המרתון בהתאם להנחיות התכנון.

למיומנויות יכולים להיות סקריפטים, נכסים נוספים והפניות.

האפליקציה טוענת את כל הכישורים ומספקת אותם ככלים ב-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

החלק הכי מעניין הוא השיטה load_skill_from_dir מ-ADK. יש עוד דרך ליצור מיומנויות ב-ADK, והיא נקראת inline. הוא לא בשימוש ב-Codelab הזה, אבל הוא נראה בערך כך:

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

הוספת כלי מיפוי

כדי ליצור מסלולים, הכלי לתכנון מרתון צריך הקשר מרחבי. כדי לעשות את זה, צריך לשלב את שרת ה-MCP (Model Context Protocol) של מפות Google.

ב-planner_agent/tools.py, אפשר לראות איך שרת ה-MCP רשום בכלי 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 כדי לקבל פרטים על מסלולים, גבהים ומיקומים.

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. פותחים את הדפדפן ועוברים לכתובת ה-URL שמוצגת במסוף (בדרך כלל 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

בסיום הפריסה, ה-CLI מפיק נקודת קצה שמתארחת בצורה מאובטחת עבור הסוכן. עכשיו אפשר לשלב את נקודת הקצה הזו באפליקציות קצה קדמי, בצ'אט בוט או במערכות אחרות של בק-אנד. אפשר גם להשתמש ב-Agent Runtime Playground כדי לבדוק את הסוכן.

הפלט אמור להיראות כך:

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, מוחקים את המשאבים שנוצרו במהלך ה-codelab הזה.

מוחקים את שירות 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 בשביל ה-Codelab הזה, אתם יכולים למחוק את הפרויקט כולו כדי להסיר את כל המשאבים וממשקי ה-API שמשויכים אליו:

gcloud projects delete $PROJECT_ID

10. מזל טוב

מעולה! יצרתם סוכן מתוחכם לתכנון מרתון באמצעות ADK.

מה למדתם

  • הפעלה של פרויקט בערכה לפיתוח סוכנים (ADK)
  • שימוש ב-PromptBuilder להנחיות מערכת מודולריות
  • שילוב יכולות מיפוי באמצעות כלי MCP ו-ApiRegistry
  • טעינה מותנית של מיומנויות באמצעות SkillToolset
  • בדיקה מקומית ופריסה ל-Agent Engine

מסמכי עזר