1. מבוא
בשיעור Codelab הזה תלמדו איך ליצור את סוכן ה-AI הראשון שלכם שלב אחר שלב באמצעות הערכה לפיתוח סוכנים (ADK) של Google ו-Gemini. תיצרו סוכן בסיסי לכתיבת בלוג שתפקידו לתכנן ולכתוב תוכן, ותראו את המושגים המרכזיים של חשיבה ופעולה.
הפעולות שתבצעו:
- מגדירים את סביבת הפיתוח ל-ADK.
- יצירת מערכת מרובת סוכנים עם מתכנן וכותב.
- מריצים את הסוכן באופן מקומי ומקיימים איתו אינטראקציה באמצעות ממשק המשתמש האינטרנטי של ADK.
הדרישות
- דפדפן אינטרנט כמו Chrome.
- Python 3.10 ואילך מותקן במחשב.
- מפתח Google AI Studio API.
ה-Codelab הזה מיועד למפתחים בכל הרמות, כולל מתחילים.
משך הזמן המשוער: 30 דקות.
2. מדריך ויזואלי: מהם סוכני AI?
לפני שמתחילים לבנות, כדאי להבין מהם סוכני AI ומהם הדפוסים הנפוצים שהם פועלים לפיהם.
מה זה סוכן AI?

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

אחד ההסברים הברורים ביותר מופיע במאמר המחקר ReAct: Synergizing Reasoning and Acting in Language Models. הרעיון במאמר הזה היה פשוט אבל עוצמתי: מודלים של שפה לא צריכים רק ליצור טקסט בבת אחת. הם יכולים למעשה להסיק מסקנות שלב אחר שלב, לבצע פעולה כמו הפעלת כלי או API, לבחון את התוצאה ואז להחליט מה לעשות בהמשך.
המחזור הזה של חשיבה רציונלית, פעולה, מידע שנקלט והתאמה הוא הבסיס לאופן שבו סוכני AI מודרניים פועלים. ההגדרה הזו תואמת להגדרה של Google Cloud: מערכות עם יכולות חשיבה רציונלית, תכנון וזיכרון, עם אוטונומיה מספקת כדי להתאים את עצמן ולקבל החלטות בשם המשתמש.
שלושה דפוסי התנהגות של סוכנים
לא כל הסוכנים מתנהגים באותו אופן. אפשר לחלק אותם לשלושה דפוסים רחבים:

- סוכנים עוקבים: הסוכנים האלה פועלים שלב אחרי שלב כמו בקו ייצור: שלב 1, אחר כך שלב 2, אחר כך שלב 3. הם צפויים, אבל קשיחים.
- סוכנים ריאקטיביים: הסוכנים האלה מקבלים החלטות ברגע נתון. הם בודקים את המצב הנוכחי ושואלים: 'מה עלי לעשות עכשיו?'. יכול להיות שהם ישתמשו בכלי א' בפעם אחת ובכלי ב' בפעם הבאה. הם גמישים, אבל לא מתכננים מראש.
- סוכנים מתכננים או סוכנים שמתבססים על שיקול דעת: הסוכנים האלה עוצרים כדי לתכנן, ואז מבצעים את התוכנית. למשל, כשמזמינים נסיעה – לא קונים סתם כרטיס טיסה באופן אקראי, אלא בוחרים תאריכים, מלונות, מסדרים את השלבים ואז מבצעים אותם.
איזו מהאפשרויות היא הנכונה? זה תלוי בבעיה. לזרימות פשוטות וצפויות, אפשר להשתמש בשיטה סדרתית. למשימות דינמיות, עדיף להשתמש בגישה תגובתית. אם יש לכם יעדים מרובי-שלבים עם יחסי תלות, כדאי להשתמש בסוכני תכנון.
במעבדה הזו אנחנו בונים סוכן Deliberative/Planning שקודם יוצר ראשי פרקים ואז כותב את הפוסט בבלוג.
3. לפני שמתחילים
יצירת חשבון ופרויקט ב-Google Cloud
כדי לפרוס את הסוכן ב-Google Cloud Run בהמשך המעבדה הזו, אתם צריכים חשבון Google Cloud ופרויקט שמופעל בו חיוב.
- נכנסים למסוף Google Cloud. יוצרים פרויקט חדש או משתמשים בפרויקט קיים. אם עדיין אין לכם חשבון Google, אתם צריכים ליצור חשבון.
- כדי להשתמש במשאבי Cloud, צריך להפעיל את החיוב במסוף Cloud. העלות של ביצוע השלבים ב-Codelab הזה צריכה להיות נמוכה מכמה סנטים. משתמשים חדשים ב-Google Cloud עשויים להיות זכאים גם לתוכנית הניסיון החינמי בשווי 300$.
- רושמים את מזהה הפרויקט (שם ייחודי לכל הפרויקטים ב-Google Cloud). תצטרכו את זה כדי להגדיר ולפרוס את הסוכן.
קבלת מפתח API של Google AI Studio
כדי להשתמש במודלים של Gemini, אתם צריכים מפתח API מ-Google AI Studio.
- עוברים אל Google AI Studio.
- לוחצים על Get API Key (קבלת מפתח API).
- יוצרים מפתח חדש או משתמשים במפתח קיים. מעתיקים את המפתח לשימוש מאוחר יותר.
4. יצירת מבנה פרויקט של סוכן לכתיבת בלוג
בשלב הזה מגדירים את הספרייה והקבצים שבהם יישמר הקוד של הסוכן לכתיבת בלוג במחשב המקומי.
1. יצירת סביבת העבודה של סוכן כתיבת הבלוג
פותחים את הטרמינל ומריצים את הפקודות הבאות כדי ליצור ספרייה ייעודית לסוכן כתיבת הבלוג ולנווט אליה:
mkdir bloggeragent
cd bloggeragent
2. אתחול קבצי הסוכן
מסגרת Google ADK טוענת תהליכי עבודה של סוכנים ישירות מספריית הפרויקט. יוצרים את הקבצים הנדרשים ישירות בתיקיית הבסיס של bloggeragent:
touch requirements.txt .env __init__.py agent.py
5. התקנת יחסי תלות והגדרת הסביבה
בשלב הזה תגדירו סביבה וירטואלית של Python, תתקינו את מסגרת Google ADK ותגדירו משתני סביבה כדי לאמת את סוכן הבלוג שלכם באמצעות מודל Gemini.
1. הגדרת הדרישות לסוכן
פותחים את הקובץ requirements.txt בספרייה bloggeragent ומציינים את החבילות שסוכן הכתיבה של הבלוג צריך על ידי הוספת השורות הבאות:
google-adk==2.2.0
python-dotenv
2. יצירת סביבה וירטואלית לסוכן
מהספרייה bloggeragent, יוצרים ומפעילים סביבה וירטואלית של Python כדי לבודד את החבילות של הסוכן:
python3 -m venv .venv
source .venv/bin/activate
3. התקנה של מסגרת ADK
כדי להתקין את התלות שמוגדרת ב-requirements.txt ולהכין את סביבת העבודה המקומית לשימוש ב-Google ADK:
pip install -r requirements.txt
4. הגדרת פרטי כניסה ל-API של הסוכן
פותחים את הקובץ .env שיצרתם בתיקיית הבסיס של הפרויקט ומוסיפים את מפתח ה-API של Gemini:
GOOGLE_API_KEY=your_api_key
מחליפים את your_api_key במפתח שהעתקתם מ-Google AI Studio.
6. יצירת כותב בלוג מרובה סוכנים
בשלב הזה תטמיעו את תהליך העבודה המרכזי של מערכת סוכני הכתיבה של הבלוג.
במקום צ'אטבוט פשוט עם הנחיה אחת, תבנו מערכת מרובת סוכנים (MAS) מורכבת שמשתמשת בלולאות לתיקון עצמי ובאימות של תוכנית המתאר כדי לכתוב פוסטים טכניים באיכות גבוהה. האימייל הזה נשלח בהמשך לתבנית התכנון/ההתלבטות שדיברנו עליה קודם.
סקירה כללית של הארכיטקטורה

כך סוכני המומחים במערכת שלכם מבצעים אינטראקציה:
הגדרת init.py
פותחים את __init__.py בעורך הטקסט ומוסיפים את שורת הייבוא הבאה כדי לחשוף את תהליך העבודה של הסוכן למפעיל:
from . import agent
כתיבת תהליך העבודה של סוכן כתיבת הבלוג
פותחים את agent.py בעורך הקוד ומוסיפים את הקוד הבא שמגדיר את הכלי לתכנון, את הכלי לכתיבה, את כלי הבדיקה של התוקף ואת הסוכן הראשי של Blogger:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
הסבר על ארכיטקטורת הסוכן
כדי להבין איך קטע הקוד שזה עתה הוספתם ב-agent.py מיישם את תהליך העבודה של תכנון וכתיבה באמצעות כמה סוכנים, נפרט את הרכיבים העיקריים שלו:
1. סוכן המשנה BlogPlanner
blog_planner הסוכן אחראי על תכנון התוכן. הוא מקבל את הנושא שהמשתמש מספק ומפיק תוכנית מובנית ב-Markdown (עם כותרת, מבוא, 4-6 קטעים ומסקנה). התוכנית נשמרת במילון המצב המשותף במפתח "blog_outline".
2. הכלי OutlineValidationChecker
הסוכן OutlineValidationChecker פועל כשער איכות. הוא בודק את "blog_outline" שנוצרו במצב. אם המתאר תקין, הוא ישיב עם "ok". אחרת, הפונקציה מחזירה את הערך "retry" לצד רשימה של מה שחסר.
3. הלולאה RobustBlogPlanner
כדי למנוע מהסוכן ליצור תוכניות גרועות, אנחנו עוטפים את המתכנן ואת בודק האימות בתוך LoopAgent שנקרא robust_blog_planner. אם האימות נכשל ומוחזר "retry", הלולאה מריצה אוטומטית את המתכנן שוב, עד 3 פעמים, כדי להבטיח תיקון עצמי לפני המעבר לשלב הבא.
4. הסוכן המשנה BlogWriter
אחרי שהתבנית מוכנה, סוכן ה-blog_writer "blog_outline" קורא מהמצב ויוצר את המאמר הטכני המלא ב-Markdown, בהתאם למבנה של התבנית ומותאם למהנדסי תוכנה.
5. הלולאה BlogPostValidationChecker & RobustBlogWriter
בדומה לתהליך יצירת התרשים, המאמר הסופי עובר אימות על ידי BlogPostValidationChecker כדי לוודא שכל החלקים העיקריים מופיעים וברורים. תהליך הכתיבה והבדיקה מתבצע בלולאה של robust_blog_writer, שמאפשרת לו לתקן את עצמו עד 3 פעמים אם הבודק מוצא בעיות.
6. חשיפת לולאות ככלים
אנחנו עוטפים את לולאת התכנון (robust_blog_planner) ואת לולאת הכתיבה (robust_blog_writer) ככלים (planner_tool ו-writer_tool) באמצעות AgentTool. כך סוכנים אחרים יכולים להפעיל את תהליכי העבודה המורכבים האלה כאילו היו כלים פשוטים.
7. הסוכן הראשי של Blogger
השירות root_agent (שנקרא Blogger) מתזמר את כל תהליך העבודה. כשנותנים לו נושא, ההוראות מכוונות אותו:
- מבקשים מ-
planner_toolליצור את המתאר המאומת. - תבצע קריאה ל-
writer_toolכדי לכתוב את הטיוטה על סמך המתאר הזה. - בסיום, תציע 3 כותרות חלופיות ו-2 טיזרים לציוצים.
ארכיטקטורת הלולאה מרובת הסוכנים הזו מבטיחה אמינות על ידי זיהוי ותיקון של שגיאות עיצוב או שגיאות מבניות ב-LLM לפני הצגת הפלט למשתמש.
7. הרצה ובדיקה של הסוכן
עכשיו הגיע הזמן לראות את הסוכן שלכם בפעולה.
1. הפעלת ממשק המשתמש באינטרנט של ADK
מוודאים שאתם נמצאים בספריית הבסיס של הפרויקט bloggeragent במסוף ושהסביבה הווירטואלית שלכם פעילה (source .venv/bin/activate), ואז מפעילים את ממשק האינטרנט:
adk web
2. אינטראקציה עם הסוכן
- פותחים את הדפדפן ועוברים לכתובת
http://127.0.0.1:8000(או ליציאה שציינתם). - ממשק המשתמש האינטרנטי של ADK יופיע עם סוכן
Bloggerשנטען והפריסה החזותית שלו (שמראה את סוכן הבסיס של Blogger שמפנה לכלים RobustBlogPlanner ו-RobustBlogWriter):
- מקלידים נושא טכני בתיבת ההודעה ומקישים על Enter. הנה כמה הנחיות מעניינות לבדיקה שאפשר להשתמש בהן כדי להעריך את הסוכן:
How to build an AI agent using planning loopsExplain the difference between REST and gRPC in microservicesA guide to using Python's asyncio for backend concurrencyWhy developers should use Docker for local database setups
- צפייה בנתוני המעקב אחר הביצוע בממשק המשתמש. תוכלו לראות את השלבים הבאים:
BlogPlannerיצירת התרשים,OutlineValidationCheckerאימות התרשים וBlogWriterכתיבת הטיוטה הסופית על סמך התרשים:
8. פריסה ב-Cloud Run
אחרי שווידאתם שהסוכן פועל באופן מקומי, אפשר לפרוס אותו ב-Google Cloud Run כדי שאחרים יוכלו להשתמש בו.
Google Cloud Run היא פלטפורמת מחשוב מנוהלת שמאפשרת להריץ קונטיינרים בלי שמירת מצב שאפשר להפעיל באמצעות בקשות לאחזור מהרשת או אירועי Pub/Sub.
1. דרישות מוקדמות לפריסה
כדי לפרוס את סוכן כתיבת הבלוג ב-Cloud Run, תצטרכו להתקין את Google Cloud CLI (gcloud) במחשב המקומי שלכם ולאמת אותו:
- מתקינים את Google Cloud CLI: אם הוא לא מותקן, פועלים לפי מדריך ההתקנה של Google Cloud CLI למערכת ההפעלה שלכם (macOS, Windows או Linux).
- מאמתים את הטרמינל המקומי: אחרי ההתקנה, מריצים את הפקודה הבאה בטרמינל כדי להיכנס לחשבון Google Cloud:
gcloud auth login - אימות האימות: מוודאים שהתחברתם לחשבון בהצלחה ושאתם יכולים לגשת למשאבים של Google Cloud:
gcloud auth list
2. הגדרת פרויקט Google Cloud
מגדירים את הפרויקט הפעיל בטרמינל:
gcloud config set project <YOUR_PROJECT_ID>
מפעילים את שירותי Google Cloud הנדרשים כדי ליצור ולפרוס את הסוכן שמוכל ב-container:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
פקודת הפריסה של ADK משתמשת ב-Google Cloud Build כדי להפוך את תהליך ה-build לאוטומטי, ולכן צריך להעניק לחשבון השירות שמוגדר כברירת מחדל ב-Compute הרשאה להשתמש ב-Cloud Build.
מריצים את הפקודה הבאה כדי למצוא את מספר הפרויקט:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
מריצים את הפקודות הבאות כדי לקשר את תפקידי ה-IAM הנדרשים (מחליפים את במזהה הפרויקט ואת במספר שמוחזר מהפקודה שלמעלה).
- נותנים ל-Cloud Build הרשאה ליצור את הקונטיינר:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- מעניקים לסוכן הפרוס הרשאת גישה ל-Gemini Enterprise כדי שהוא יוכל להפעיל מודלים של Gemini בלי להשתמש במפתח API:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
3. הגדרת משתני סביבה מקומיים
כדי לפשט את פקודת הפריסה ולמנוע שגיאות הקלדה, מגדירים את מזהה הפרויקט כמשתנה סביבה בסשן הטרמינל:
export PROJECT_ID="<YOUR_PROJECT_ID>"
4. פריסה באמצעות ADK CLI
ממשק ה-CLI של ADK מספק פקודה יעילה לפריסת הסוכן ב-Cloud Run.
מוודאים שהסביבה הווירטואלית פעילה ושנמצאים בספריית הפרויקט bloggeragent, ואז מריצים את פקודת הפריסה:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
במהלך תהליך הפריסה, תתבקשו לענות על שתי השאלות הבאות במסוף:
- מאשרים את יצירת המאגר:
מקלידיםDeploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yומקישים על Enter. - אפשר להשתמש בגישה לא מאומתת:
מקלידיםAllow unauthenticated invocations to [bloggeragent] (y/N)?
yומקישים על Enter (כך מקבלים גישה ל-ADK Web UI באופן ציבורי בדפדפן).
5. גישה לסוכן שנפרס
אחרי שהפריסה תסתיים, הפקודה תפיק כתובת URL. פותחים את כתובת ה-URL הזו בדפדפן כדי לגשת לממשק המשתמש האינטרנטי של ADK שפעיל וזמין לציבור.
9. הסרת המשאבים
כדי להימנע מחיובים שוטפים בחשבון Google Cloud, מוחקים את המשאבים שנוצרו במהלך ה-codelab הזה.
1. מחיקה של שירות Cloud Run
מוחקים את שירות bloggeragent שנפרס:
gcloud run services delete bloggeragent --region=us-east1 --quiet
2. מחיקת מאגר Artifact Registry
מוחקים את מאגר Docker שנוצר לאחסון תמונות הקונטיינר שנבנו:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
3. הפסקת השרת המקומי
כדי לעצור את שרת ה-ADK המקומי, מקישים על CTRL+C בטרמינל שבו הוא פועל ומשביתים את הסביבה הווירטואלית:
deactivate
10. מזל טוב
מעולה! יצרתם את סוכן ה-AI הראשון שלכם באמצעות ADK ו-Gemini של Google.
מה למדתם
- מושגי הליבה של סוכני AI (הסקה ופעולה).
- איך משתמשים ב-Google ADK כדי ליצור מערכת מרובת סוכנים.
- איך מריצים ובודקים את הסוכן באמצעות ממשק המשתמש באינטרנט.
השלבים הבאים
- כדאי לנסות להוסיף כלים לסוכן (כמו חיפוש באינטרנט או קריאות ל-API).
- בסרטון השני נסביר איך לשלב שרת MCP.