Google ADK Samples

מה זה

Agent Development Kit (ADK) הוא ה-framework הקוד-פתוח של Google לבנייה, debug ופריסה של AI agents. התיעוד הרשמי מגדיר אותו כ-"open-source, code-first toolkit" — הדגש על code-first מכוון: agent מוגדר כקוד Python רגיל, לא כקובץ YAML או graph שמציירים בכלי ויזואלי. הרישיון הוא Apache-2.0. שני מאגרים נפרדים מרכיבים את הסיפור:

• google/adk-python — ה-SDK עצמו. הגרסה הנוכחית היא v2.2.0 (4 ביוני 2026), והמאגר עומד על כ-20k כוכבים ב-GitHub. tags חדשים יוצאים בקצב גבוה, אז נעלו את ה-dependency אם אכפת לכם משחזוריות.
• google/adk-samples — מאגר הדוגמאות שעליו המאמר הזה מתמקד: עשרות sample agents בשש שפות. נכון ליוני 2026: 9.6k כוכבים, 2.7k forks, 771 commits ב-main, מעל מאה תורמים, Apache-2.0.

נקודה אחת שכדאי לדעת מראש: שני המאגרים נושאים את ההסתייגות "This is not an officially supported Google product." זהו קוד שמתחזקת קבוצה בתוך Google, אבל בלי SLA — אל תבנו עליו תלות production בלי לקרוא את הקוד בעצמכם.

הדוגמאות אינן hello-worlds של צעצוע. כל אחת נשלחת כפרויקט עצמאי עם dependencies מנעולים, README מקומי ובדרך כלל dataset הערכה (eval) משלה. הקטגוריות שמכוסות תחת python/agents/ כוללות בין היתר academic-research, customer-service, data-science, financial-advisor, blog-writer, brand-aligner ו-antom-payment — שירות לקוחות, מחקר, מדעי נתונים, ייעוץ פיננסי, יצירת תוכן ותשלומים. הן מיועדות לשכפול ועיצוב מחדש, לא רק לקריאה.

איך זה עובד — ארכיטקטורה

המודל המנטלי של ADK מורכב מסוג אחד של agent חושב ושלושה controllers דטרמיניסטיים שמתזמרים אותו:

• LlmAgent (לרוב פשוט Agent) — ה-"מוח". מודל + instruction + קבוצת כלים + (אופציונלית) sub-agents. הוא זה שמנמק, מחליט איזה כלי לקרוא, ומתי לסיים.
• Workflow agents — controllers שמכתיבים את סדר ההרצה במקום שהמודל יחליט עליו. שלושה טיפוסים: SequentialAgent (פס ייצור — sub-agent אחד אחרי השני, פלט של אחד הוא קלט של הבא), ParallelAgent (הרצה במקביל של משימות בלתי-תלויות) ו-LoopAgent (לולאת while עד עמידה בתנאי).
• Shared session state — "לוח לבן" משותף. agent כותב תוצאה ל-state object ו-agents אחרים בהיררכיה קוראים ממנו — כך עוברת מידע בין שלבים בלי string concatenation ידני.

ההבחנה הזו היא הליבה: דברים שאתם רוצים שיהיו דטרמיניסטיים (סדר, מקבול, לולאה) הם קוד מפורש דרך workflow agents, ודברים שדורשים שיקול דעת הם ה-LlmAgent. ADK 2.0 הוסיף מעל זה Graph Workflows — הרצה מבוססת-גרף שמערבבת את שני העולמות — ו-Task API להאצלה מוקלדת בין agents.

המודלים הם model-agnostic. ברירת המחדל היא Gemini (התיעוד מוביל עם gemini-2.5-flash), אבל התיעוד מציין במפורש תמיכה ב-Claude של Anthropic, ב-Gemma, ובמודלים מקומיים/קהילתיים דרך Ollama, vLLM ו-LiteLLM, וכן ניתוב ארגוני דרך Apigee AI Gateway. כלים יכולים להיות פונקציות Python רגילות (function tools), agents אחרים (agent tools), יכולות מובנות כמו Google Search והרצת קוד, או חיבורים דרך OpenAPI ו-MCP. עבור function tool, המודל מקבל את ה-signature וה-docstring של הפונקציה כמפרט הכלי — אז התיעוד שאתם כותבים הוא ה-API שהמודל רואה.

מאגר הדוגמאות משקף את החלוקה הזו במבנה התיקיות: תיקייה עליונה אחת לכל שפה (python/, typescript/, go/, java/, kotlin/, android/), כל אחת עם פרויקט עצמאי לכל agent. ההתפלגות לא אחידה בכלל: Python מחזיק את הרוב המוחלט של ה-agents (עשרות), ואילו השאר עדיין דלילים — TypeScript ו-Go עם agent אחד כל אחד, Java ו-Kotlin עם שניים, Android עם אחד (fun-facts). בפועל, אם אתם לא ב-Python, ADK עצמו זמין לכם אבל ה-דוגמאות שתלמדו מהן יהיו ברובן Python שתצטרכו לתרגם לשפתכם.

התקנה והגדרה

ה-Python SDK הוא התקנת pip אחת. נדרש Python 3.10 ומעלה.

# 1. Create a clean virtualenv (uv is fastest; venv works too)
python3 -m venv .venv
source .venv/bin/activate

# 2. Install the SDK
pip install google-adk

# Or, with optional integrations (Vertex AI, extra connectors):
pip install "google-adk[extensions]"

# 3. Authenticate to a model provider
#    Gemini API key (fastest path):
export GOOGLE_API_KEY="your-key-here"

#    Or Vertex AI on GCP:
gcloud auth application-default login
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

# 4. Clone the samples repo for working examples
git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents

# 5. Pick a sample and follow its local README
#    (most use Poetry; install if you don’t have it: pipx install poetry)
cd customer-service
poetry install

שלוש נקודות כניסת CLI שה-SDK מגיע איתן:

# Interactive REPL chat with an agent
adk run path/to/my_agent

# Local web UI — opens a chat surface with traces & tool calls
adk web path/to/agents_dir

# Local API server — useful for wiring an agent into other apps
adk api_server path/to/agents_dir

יכולות מרכזיות — שלוש דוגמאות

הדרך הטובה ביותר להבין את ה-framework היא לטפס בסולם: agent של מודל בלבד, אותו agent עם כלי, ואז דוגמה אמיתית מהמאגר עם sub-agents. שלוש הדוגמאות הבאות עוברות בדיוק את הציר הזה, וכולן רצות מקומית באותן שלוש פקודות CLI שראינו למעלה.

דוגמה 1 — ה-agent המינימלי. שלושה קבצים: __init__.py, agent.py עם אובייקט ה-agent, ו-.env עם ה-API key. adk run מזהה אותם אוטומטית. שימו לב שאין boilerplate של רישום או config — משתנה בשם root_agent בקובץ הוא כל מה ש-ADK מחפש.

# my_agent/agent.py
from google.adk import Agent

root_agent = Agent(
    name="greeting_agent",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant. Greet the user warmly.",
)

# Run it
adk run my_agent

# Or open the web UI on http://localhost:8000
adk web .

דוגמה 2 — agent עם כלי. כלים הם פונקציות Python רגילות. ADK סורק את ה-signature וה-docstring כדי לבנות את מפרט הכלי שהמודל רואה.

# weather_agent/agent.py
from google.adk import Agent
import requests

def get_weather(city: str) -> dict:
    """Return the current temperature in Celsius for a city."""
    r = requests.get(
        "https://api.open-meteo.com/v1/forecast",
        params={"latitude": 52.52, "longitude": 13.41, "current": "temperature_2m"},
    )
    return r.json()

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.5-flash",
    instruction=(
        "You are a concise weather assistant. "
        "When the user asks about weather, call get_weather and report "
        "the temperature in plain English."
    ),
    tools=[get_weather],
)

דוגמה 3 — הרצת דוגמה אמיתית מהמאגר. ה-agent customer-service תחת python/agents/ הוא multi-turn agent עם sub-agent לחיפוש הזמנות. המסלול המלא מהורדה ועד שיחה:

git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents/customer-service

# Install deps (this sample uses Poetry)
poetry install

# Copy and fill in the env
cp .env.example .env
# … edit .env to add GOOGLE_API_KEY or Vertex settings

# Run it
poetry run adk run customer_service

# Or load all samples into the local web UI at once
cd ../..
adk web agents

ברגע ש-adk web פעיל מקבלים ממשק שיחה, trace חי של כל קריאת מודל והפעלת כלי, ויכולת לעבור בין agents מ-dropdown — שימושי להשוואת גישות בין הדוגמאות ללא הפעלה מחדש. ה-trace הוא הנקודה החשובה כאן: כשהמודל בוחר כלי שגוי או נתקע בלולאה, רואים את זה בעיניים במקום לנחש מתוך לוגים. זו הסיבה ש-adk web הוא נקודת הכניסה שאני ממליץ עליה ללימוד — קוראים את הקוד של הדוגמה במקביל לצפייה בה רצה צעד-צעד.

שלוש הדוגמאות יחד מכסות את כל מה שצריך כדי לקרוא כל אחד מעשרות ה-agents שב-python/agents/: כולם נבנים מאותם אבני יסוד — Agent, רשימת tools, ובדוגמאות המורכבות יותר היררכיה של sub-agents שמתואמת דרך ה-shared state. ברגע שמזהים את התבנית, מאגר הדוגמאות נקרא כקטלוג ולא כעשרות פרויקטים נפרדים שצריך ללמוד מאפס.

הערכה ופריסה

שני הצעדים שמפרידים demo מ-agent שאפשר לסמוך עליו — מדידה ופריסה — מובנים ב-ADK ולא מושארים לכם.

• Evaluation — הרבה מהדוגמאות נשלחות עם dataset הערכה לצד קוד ה-agent: קלטים ידועים והתנהגות/פלט צפוי. במקום "נראה בסדר", מקבלים ציון שאפשר להריץ שוב אחרי כל שינוי instruction או החלפת מודל ולראות אם נשברתם.
• Deployment — אותו agent אורז לכמה יעדים: Google Cloud Run, GKE (Kubernetes), ה-Agent Runtime/Agent Engine המנוהל של Google Cloud, או קונטיינר משלכם. ה-framework הוא deployment-agnostic — הקוד לא משתנה לפי היעד.

שתי דרכי הזדהות נפוצות לעבודה מקומית: מפתח Gemini API דרך GOOGLE_API_KEY (המסלול המהיר), או Vertex AI על GCP עם gcloud auth application-default login ו-GOOGLE_GENAI_USE_VERTEXAI=true. רוב הדוגמאות מצפות לאחד מהשניים ב-.env מקומי.

מה חדש בגרסה 2

גרסת 2.0 הייתה כתיבה מחדש שהזיזה את ADK מ-"framework ל-agent אחד" ל-"framework למערכת agents". מי שמכיר את 1.x צריך לשים לב לשתי תוספות מרכזיות:

• Graph Workflows — הרצה מבוססת-גרף שמשלבת קוד דטרמיניסטי עם נימוק של מודל בתוך מבנה גרף יחיד, במקום לבחור בין השניים.
• Task API — האצלה מוקלדת בין agents, שמחליפה את קריאות ה-sub-agent הרופפות יותר של 1.x במעטפות משימה מסודרות.

הגרסה הנוכחית היא v2.2.0 (4 ביוני 2026), ו-tags יוצאים בקצב גבוה. עיקרון אצבע: נעלו ל-minor (למשל google-adk~=2.2) אם אכפת לכם משחזוריות בין סביבות.

מתי להשתמש — ומגבלות

frameworks של agents מתרבים כבר שנתיים, ו-ADK מעניין משלוש סיבות פרגמטיות. ראשית, הוא code-first: agent הוא Python, אז גם git diff, code review ובדיקות עובדים עליו כמו על כל קוד אחר — בניגוד ל-frameworks שמסתירים את הלוגיקה ב-YAML או ב-graph ויזואלי. שנית, ההפרדה בין LlmAgent ל-workflow agents נותנת שליטה אמיתית: סדר, מקבול ולולאות שאתם רוצים שיהיו דטרמיניסטיים הם קוד מפורש, לא תקווה שהמודל יבחר נכון. שלישית, model-agnostic אמיתי — Gemini, Claude, Gemma או מודל מקומי דרך Ollama/vLLM, בלי לשכתב את ה-agent.

המגבלות מציאותיות. כאמור, אף אחד משני המאגרים אינו "officially supported Google product" — אין SLA, וה-API השתנה משמעותית בין 1.x ל-2.x, אז ציפו ל-breaking changes ולתחזוקה שוטפת אם אתם מאמצים מוקדם. וכיסוי השפות מטעה: ה-SDK זמין בשש שפות, אבל מאגר הדוגמאות הוא כמעט-כולו Python (עשרות agents מול בודדים בכל שפה אחרת). אם ה-stack שלכם הוא Go, Java או Kotlin, ה-framework פתוח בפניכם אבל את הדוגמאות תצטרכו ברובן לתרגם בעצמכם.

בשימוש יומיומי המנוף הגדול של מאגר הדוגמאות הוא שהוא מתפקד כקטלוג זרעים ולא כקריאת רקע בלבד: כל agent מגיע באותה צורה חוזרת (agent.py + רשימת tools + לעיתים eval dataset), אז ברגע שמזהים את התבנית אפשר לשכפל דוגמה מתאימה, לקצץ את מה שלא רלוונטי, ולהמשיך מנקודה רצה במקום מקובץ ריק. מניסיון, כדאי להחזיק את כל ה-agents החדשים על אותה צורה אחידה — כשכולם נראים אותו דבר, ניתוב שלהם לתוך dispatcher משותף או הרצה שלהם זה לצד זה ב-adk web הופך לכמעט-חינמי, בלי קוד הדבקה לכל אחד. הטרייד-אוף בשימוש יומיומי הוא שצריך משמעת: קל להיגרר לשכפל דוגמה שלמה כשבעצם צריך רק שני אבני יסוד ממנה, אז שווה לקרוא את הדוגמה עד הסוף לפני ההעתקה.

מקורות

מאגר הדוגמאות: github.com/google/adk-samples — Apache-2.0, 9.6k כוכבים, 771 commits, מעל מאה תורמים (נכון ליוני 2026).
Python SDK: github.com/google/adk-python — v2.2.0 (2026-06-04), כ-20k כוכבים.
תיעוד רשמי: adk.dev (לשעבר google.github.io/adk-docs).