סוכני AI של Vibe Coding: ניהול מחזור החיים של הסוכן באמצעות Agents CLI ו-ADK 2.0

1. סקירה כללית

ב-Codelab הזה נסביר איך להשתמש ב-Agents CLI כדי לנהל את מחזור החיים המלא של פיתוח מקומי של סוכן AI. בין אם אתם עוטפים מודלים קיימים של Gemini או בונים סוכנים בהתאמה אישית מאפס באמצעות הערכה לפיתוח סוכנים (ADK 2.0), Agents CLI מספק את הכלים ליצירת תבנית, לבנייה, לבדיקה ולניתוח של הסוכנים באופן מקומי.

מה תלמדו

  • איך להתקין ולהגדיר את agents-cli ואת המיומנויות שמשויכות אליו.
  • איך ליצור פרויקט חדש של סוכן.
  • המבנה והקבצים העיקריים של פרויקט סוכן בתהליך עבודה של גרף ADK 2.0.
  • איך מריצים בדיקת לינט אוטומטית וניקוי קוד.
  • איך מפעילים את ארגז החול המקומי לאינטרנט ומשתמשים בו לבדיקות אינטראקטיביות עם טעינה מחדש אוטומטית.

מה צריך

  • ‫Python 3.11 ואילך
  • כלי לניהול חבילות uv
  • ‫Node.js 18 ואילך (אם משתמשים במיומנויות של סוכני תכנות)
  • ‫Antigravity IDE (התקנה והגדרה מתוך Google Antigravity)

דרישות מוקדמות

ב-Codelab הזה אנחנו מניחים שאתם מכירים את הנושאים הבאים:

  • שימוש בטרמינל ובשורת פקודה.

לא נדרש ניסיון קודם עם סוכני AI או עם ADK 2.0.

2. הגדרת אימות וסביבה

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

אפשרות 1: מפתח Gemini API (Google AI Studio)

אם אתם משתמשים במפתח Gemini API רגיל (שאפשר לקבל מ-Google AI Studio), אתם יכולים לייצא אותו בסשן של מסוף IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

אפשרות 2: Application Default Credentials של Google Cloud

אם אתם משתמשים ב-Vertex AI ב-Google Cloud, אתם צריכים לבצע אימות באמצעות פרטי הכניסה שמוגדרים כברירת מחדל באפליקציה (ADC) של Google Cloud ולהגדיר את פרויקט Google Cloud הפעיל:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. הגדרת Agents CLI וכישורים

השלב הראשון הוא להתקין את הכלי agents-cli. הכלי הזה מטפל בניהול הפרויקט של הסוכן.

אחרי שמתקינים את Antigravity, מריצים את פקודת ההגדרה ישירות בטרמינל.

‫👈 פותחים טרמינל ומריצים:

uvx google-agents-cli setup

הפקודה הזו מתקינה באופן אוטומטי את:

  1. הכלי Agents CLI באופן גלובלי במערכת שלכם.
  2. ‫7 כישורים ספציפיים לתחום של עוזר התכנות Antigravity, שבעזרתם הוא יכול לעזור לכם ליצור סוכנים, להגדיר את המבנה שלהם, להעריך אותם ולפרוס אותם. הכישורים האלה מותקנים פעם אחת באופן גלובלי ב-~/.agents/skills/ ומזוהים באופן אוטומטי על ידי Antigravity.

הערה: המיומנויות מותקנות ב-~/.agents/skills/ ונאספות באופן אוטומטי על ידי Antigravity. אפשר לבדוק את זה באמצעות הפקודה /skills או ההגדרות של Antigravity.

הפלט הצפוי (עם חיתוך):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. יצירת פרויקט סוכן

בקטע הזה תיצרו ספריית פרויקט מובנית לחלוטין באמצעות תבנית האב-טיפוס.

‫👉 הנחיית Antigravity:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

‫Antigravity מריץ אוטומטית את פקודת ה-scaffolding‏ (agents-cli scaffold create customer-support-agent --prototype --yes) ומגדיר בשבילכם את קובצי הפרויקט.

5. היכרות עם קוד הסוכן

‫👉 מבקשים מ-Antigravity להסביר את הקוד שנוצר:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

ב-Antigravity IDE, קבצים וארטיפקטים של פרויקטים שנוצרו לאחרונה מוצגים ישירות בחלונית העזר (בצד שמאל). אפשר לראות את הקובץ app/agent.py שם, או לפתוח אותו מסייר הקבצים של סביבת הפיתוח המשולבת כדי לבדוק את הקוד שנוצר.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

מושגים מרכזיים

  • תהליך עבודה וקצוות: ב-ADK 2.0, אפליקציות של סוכנים מתואמות כגרף באמצעות Workflow. הרשימה edges מגדירה את זרימת הביצוע, ומקשרת בין צמתים מ-START ומאפשרת הסתעפות מותנית על סמך מסלולים (לדוגמה, ניתוב אל faq_agent ב-"shipping" או אל handle_unrelated ב-"unrelated").
  • ‫LlmAgent: צמתים הצהרתיים שמגדירים משימות מבוססות-LLM עם הוראות ספציפיות, מודלים ופלט מובנה (output_schema).
  • צמתים והקשר: פונקציות Python שמקושטות ב-@node (או פונקציות רגילות) שמבצעות לוגיקה, ניגשות למצב הביצוע באמצעות Context ומחזירות אובייקטים של Event כדי להעביר נתונים ואותות ניתוב לאורך הגרף.
  • ‫Model: המודל `gemini-3.1-flash-lite' משמש כמודל חשיבה רציונלית ברירת המחדל המהיר.
  • ‫App Wrapper: אובייקט App ברמה העליונה שעוטף את תהליך העבודה הבסיסי. כלים חיצוניים כמו סביבת ארגז החול המקומית, כלי הערכה של ADK ו-Agent Runtime מגלים ומבצעים את תהליך העבודה שלכם באמצעות ממשק app סטנדרטי.

6. בדיקת קוד אוטומטית

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

‫👉 הנחיית Antigravity:

Run linting on my agent project to verify its health.

‫Antigravity יפעל agents-cli lint ברקע כדי להריץ בדיקות שהוגדרו מראש, ויאמת את הייבוא, התחביר והעקביות של הפורמט בקבצים.

7. בדיקה אינטראקטיבית באמצעות Playground

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

‫👉 הנחיית Antigravity:

Launch the local development playground for my agent.

הכלי Antigravity יפעיל את שרת הפיתוח המקומי (agents-cli playground). פותחים את כתובת ה-URL שסופקה (בדרך כלל http://127.0.0.1:8080/dev-ui/?app=app) בדפדפן האינטרנט, בוחרים את התיקייה app מהתפריט הנפתח ומתחילים לשוחח עם הסוכן.

מתחילים להתכתב בצ'אט עם הסוכן בממשק האינטרנט. כדאי לנסות לשאול שאלה שקשורה למשלוח:

How much is standard shipping?

שימו לב איך תהליך העבודה מסווג את השאלה ומעביר אותה אל faq_agent כדי לקבל תשובה. כדאי גם לשאול שאלה לא קשורה כדי לוודא שתהליך העבודה מנותב אל handle_unrelated ושהוא מסרב לענות בצורה נכונה:

What is the weather like?

בדיקה של טעינה אוטומטית בזמן אמת

אתם יכולים לראות איך עריכות בזמן אמת של הסוכן משתקפות במגרש המשחקים.

  1. משנים את ההוראה faq_agent ב-app/agent.py באמצעות הנחיה ל-Antigravity: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. כדי לבדוק את הטעינה מחדש האוטומטית, שולחים הודעה חדשה לסוכן במגרש המשחקים: 
    How much is standard shipping?
    סביבת המשחקים נטענת מחדש באופן אוטומטי ומריצה את הקוד המעודכן בזמן אמת, בלי צורך בהפעלה מחדש של השרת. עכשיו אמורים להופיע כמה אמוג'י בתגובה.

8. ביצוע בשורת הפקודה

כדי לבצע בדיקות מהירות, אוטומציה או סקריפטים, אפשר לבקש מ-Antigravity להריץ את הסוכן ישירות מהטרמינל.

‫👉 הנחיית Antigravity:

Run a CLI query asking my agent how long standard delivery takes.

‫Antigravity יבצע את פקודת השאילתה (agents-cli run "How long does standard delivery take?"). הפעולה הזו תריץ הסקה מהירה של תור אחד ותדפיס את התשובה הסופית של הסוכן יחד עם פרטי הביצוע של הכלי.

9. הסרת המשאבים

כדי למנוע השארת משאבים לא רצויים בסביבה המקומית, צריך לבצע את שלבי הניקוי הבאים:

  1. הפסקת שרתים מקומיים: אם שרת agents-cli playground עדיין פועל, מפסיקים אותו במסוף על ידי לחיצה על Ctrl + C.
  2. הסרת קבצים של פרויקט מקומי: מחיקה של ספריית הפרויקט של הסוכן שנוצרה על ידי ה-scaffold מהמחשב המקומי.
rm -rf customer-support-agent

10. סיכום והשלבים הבאים

מעולה! הצלחתם לנהל את מחזור החיים של פיתוח סוכן AI מקומי מקצה לקצה באמצעות Agents CLI ו-ADK 2.0.

מה למדתם

  • הגדרת הכלים: התקנתם את Agents CLI והגדרתם מיומנויות של תהליכי עבודה ספציפיים לדומיין עבור Antigravity.
  • יצירת פרויקט עם תבנית מוכנה מראש: יצירת פרויקט customer-support-agent מובנה לחלוטין באמצעות תבניות סטנדרטיות.
  • ניתוח המבנה של ADK 2.0: תהליכי עבודה של גרפים, סוכני LLM, צמתים, קשתות וניתוב מותנה.
  • ניהול הבריאות של האפליקציה המקומית: הפעלנו בדיקות אוטומטיות של איכות הקוד באמצעות agents-cli lint.
  • התנהגות מאומתת: נבדקה אינטראקטיבית עם טעינה מחדש בזמן אמת באמצעות סביבת המשחקים, והופעלו בדיקות מהירות בשורת הפקודה.

מה השלב הבא?

אחרי שתרגלתם את לולאת הפיתוח המקומית, הנה הסבר איך אפשר להרחיב את הסוכן ולהעביר אותו לסביבת הייצור:

  • הערכה: אפשר להשתמש ב-agents-cli eval run כדי להשוות את הביצועים של הסוכן לביצועים של מערך ההערכה, למדוד את רמת הדיוק ולזהות רגרסיות.
  • ‫Enterprise Cloud Scale: Deployment & Observability: אפשר לארוז ולפרוס את הסוכן בסביבות ייצור כמו Agent Runtime או Cloud Run באמצעות agents-cli deploy. הגדרת טלמטריה של סביבת הייצור כדי להזרים יומנים ועקבות של ביצוע אל Cloud Trace ו-BigQuery.

מקורות מידע נוספים