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

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

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

מה תלמדו

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

מה צריך

  • ‫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. יצירת פרויקט סוכן

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

‫👉 Prompt 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.

ב-IDE של 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 וזמן הריצה של הסוכן מאתרים את תהליך העבודה ומבצעים אותו דרך ממשק app סטנדרטי.

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

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

‫👉 Prompt Antigravity:

Run linting on my agent project to verify its health.

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

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

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

‫👉 Prompt 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 להריץ את הסוכן ישירות מהטרמינל.

‫👉 Prompt 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, צמתים, קשתות וניתוב מותנה.
  • Managed Local Health: הפעלנו בדיקות אוטומטיות של איכות הקוד באמצעות agents-cli lint.
  • התנהגות מאומתת: בדקתי את הסוכן באופן אינטראקטיבי באמצעות טעינה מחדש בזמן אמת דרך סביבת המשחקים, והרצתי בדיקות מהירות בשורת הפקודה.

מה השלב הבא?

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

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

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