کدنویسی Vibe برای عامل‌های هوش مصنوعی: مدیریت چرخه عمر عامل با Agents CLI و ADK 2.0

۱. مرور کلی

در این آزمایشگاه کد، شما یاد خواهید گرفت که چگونه از Agents CLI برای مدیریت چرخه حیات توسعه محلی کامل یک عامل هوش مصنوعی استفاده کنید. چه در حال بسته‌بندی مدل‌های موجود Gemini باشید و چه در حال ساخت عامل‌های سفارشی از ابتدا با استفاده از کیت توسعه عامل (ADK 2.0)، Agents CLI ابزارهایی را برای داربست‌بندی، ساخت، lint کردن و آزمایش عامل‌های شما به صورت محلی فراهم می‌کند.

آنچه یاد خواهید گرفت

  • نحوه نصب و راه‌اندازی agents-cli و مهارت‌های مرتبط با آن.
  • چگونه یک پروژه عامل جدید را داربست بندی کنیم.
  • ساختار و فایل‌های کلیدی یک پروژه عامل گردش کار گراف ADK 2.0.
  • نحوه اجرای خودکار Linting و پاکسازی کد.
  • نحوه راه‌اندازی و استفاده از زمین بازی وب محلی برای آزمایش تعاملی با بارگذاری مجدد خودکار.

آنچه شما نیاز دارید

  • پایتون ۳.۱۱ یا بالاتر
  • مدیر بسته uv
  • Node.js 18+ (در صورت استفاده از مهارت‌های کدنویسی)
  • Antigravity IDE (نصب و پیکربندی از Google Antigravity )

پیش‌نیازها

این Codelab فرض می‌کند که شما با موارد زیر راحت هستید:

  • با استفاده از ترمینال و خط فرمان.

هیچ تجربه قبلی با عوامل هوش مصنوعی یا ADK 2.0 لازم نیست!

۲. راه‌اندازی احراز هویت و محیط

اطلاعات احراز هویت خود را برای تماس با مدل‌های Gemini در اختیار نماینده قرار دهید.

گزینه ۱: کلید API جمینی (استودیوی هوش مصنوعی گوگل)

اگر از کلید API استاندارد Gemini استفاده می‌کنید (که می‌توانید آن را از Google AI Studio دریافت کنید)، آن را در بخش ترمینال IDE خود صادر کنید:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

گزینه ۲: اعتبارنامه‌های پیش‌فرض برنامه Google Cloud

اگر از Vertex AI در Google Cloud استفاده می‌کنید، با اعتبارنامه‌های پیش‌فرض برنامه Google Cloud (ADC) احراز هویت کنید و پروژه فعال 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

۳. رابط خط فرمان (CLI) و مهارت‌های عامل‌ها را تنظیم کنید

اولین قدم نصب ابزار agents-cli است. این ابزار بخش سنگین مدیریت پروژه agent را بر عهده دارد.

با نصب Antigravity، دستور setup را مستقیماً در ترمینال خود اجرا کنید.

👉 یک ترمینال باز کنید و دستور زیر را اجرا کنید:

uvx google-agents-cli setup

این دستور به طور خودکار نصب می‌کند:

  1. ابزار Agents CLI به صورت سراسری روی سیستم شما.
  2. هفت مهارت دستیار کدنویسی مختص هر دامنه که 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`

۴. پروژه عامل خود را ایجاد کنید

در این بخش، شما با استفاده از الگوی نمونه اولیه، یک دایرکتوری پروژه کاملاً ساختاریافته ایجاد خواهید کرد.

👉 ضد جاذبه سریع:

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.

آنتی‌گراویتی به‌طور خودکار دستور scaffolding ( agents-cli scaffold create customer-support-agent --prototype --yes ) را اجرا کرده و فایل‌های پروژه را برای شما تنظیم می‌کند.

۵. کد عامل را بررسی کنید

👉 از 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 را در آنجا مشاهده کنید، یا آن را از کاوشگر فایل IDE باز کنید تا کد scaffolded را بررسی کنید.

# 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 ) مشخص تعریف می‌کنند.
  • گره‌ها و متن : توابع پایتون که با @node (یا توابع استاندارد) تزئین شده‌اند و منطق را انجام می‌دهند، از طریق Context به وضعیت اجرا دسترسی دارند و اشیاء Event را برای انتقال داده‌ها و سیگنال‌های مسیریابی در امتداد گراف ارائه می‌دهند.
  • مدل : `gemini-3.1-flash-lite` به عنوان مدل استدلال سریع پیش‌فرض استفاده می‌شود.
  • بسته‌بندی برنامه : شیء سطح بالای App گردش کار ریشه را در بر می‌گیرد. ابزارهای خارجی مانند زمین بازی محلی، مهارهای ارزیابی ADK و Agent Runtime گردش کار شما را از طریق این رابط app استاندارد کشف و اجرا می‌کنند.

۶. لایه‌بندی خودکار

قبل از اجرا یا آزمایش عامل خود، بهتر است از تمیز بودن و قالب‌بندی صحیح کد خود اطمینان حاصل کنید.

👉 ضد جاذبه سریع:

Run linting on my agent project to verify its health.

آنتی‌گراویتی در پشت صحنه agents-cli lint اجرا می‌کند تا بررسی‌های از پیش پیکربندی‌شده را انجام دهد و ایمپورت‌ها، سینتکس و سازگاری قالب‌بندی را در فایل‌های شما تأیید کند.

۷. تست تعاملی با زمین بازی

محیط وب محلی سریع‌ترین راه برای تأیید رفتار عامل شماست. این محیط یک رابط چت تعاملی فراهم می‌کند که در آن می‌توانید با عامل خود چت کنید و اجرای ابزارها را به صورت بلادرنگ بررسی کنید.

👉 ضد جاذبه سریع:

Launch the local development playground for my agent.

آنتی‌گراویتی سرور توسعه محلی ( 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?

تست بارگذاری خودکار بلادرنگ

می‌توانید ببینید که چگونه ویرایش‌های بلادرنگ روی نماینده شما در Playground منعکس می‌شوند.

  1. با پرسیدن از Antigravity، دستورالعمل faq_agent را در app/agent.py تغییر دهید: 
    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?
    زمین بازی به طور خودکار کد به‌روزرسانی شده شما را به صورت بلادرنگ و بدون نیاز به راه‌اندازی مجدد سرور، بارگذاری مجدد و اجرا می‌کند! اکنون باید چند ایموجی در پاسخ ببینید.

۸. اجرای خط فرمان

برای تست‌های سریع، خودکارسازی یا اسکریپت‌نویسی، می‌توانید از Antigravity بخواهید که عامل شما را مستقیماً از ترمینال اجرا کند.

👉 ضد جاذبه سریع: 

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

Antigravity دستور پرس‌وجو را اجرا می‌کند ( agents-cli run "How long does standard delivery take?" ). این یک استنتاج سریع تک‌نوبتی اجرا می‌کند و پاسخ نهایی عامل را به همراه جزئیات اجرای ابزار چاپ می‌کند.

۹. پاکسازی

برای جلوگیری از به جا گذاشتن منابع ناخواسته در محیط محلی خود، این مراحل پاکسازی را دنبال کنید:

  1. توقف سرورهای محلی : اگر سرور agents-cli playground شما هنوز در حال اجرا است، با فشردن Ctrl + C آن را در ترمینال خود متوقف کنید.
  2. حذف فایل‌های پروژه محلی : دایرکتوری پروژه عامل scaffolded را از دستگاه محلی خود حذف کنید. 
rm -rf customer-support-agent

۱۰. خلاصه و مراحل بعدی

تبریک! شما با موفقیت چرخه حیات توسعه محلی سرتاسری یک عامل هوش مصنوعی را با استفاده از Agents CLI و ADK 2.0 مدیریت کردید.

آنچه آموختید

  • ابزارهای خود را تنظیم کنید : رابط خط فرمان Agents را نصب کرده و مهارت‌های گردش کار مختص دامنه را برای Antigravity پیکربندی کنید.
  • یک پروژه را داربست‌بندی کرد : یک پروژه کاملاً ساختاریافته customer-support-agent با استفاده از قالب‌های استاندارد ایجاد کرد.
  • ساختار ADK 2.0 مورد تجزیه و تحلیل قرار گرفت : گردش‌های کاری گراف، عامل‌های LLM، گره‌ها، لبه‌ها و مسیریابی شرطی بررسی شدند.
  • مدیریت سلامت محلی : بررسی‌های خودکار کیفیت کد را با استفاده از agents-cli lint اجرا کرد.
  • رفتار تأیید شده : عامل را به صورت تعاملی با قابلیت بارگذاری مجدد در لحظه (hot-reloading) از طریق playground آزمایش کردم و تست‌های سریعی را در خط فرمان اجرا کردم.

قدم بعدی چیست؟

حالا که بر حلقه توسعه محلی مسلط شدید، در اینجا نحوه گسترش و تولید عامل خود را مشاهده می‌کنید:

  • ارزیابی : با استفاده از agents-cli eval run به عامل خود در برابر یک مجموعه ارزیابی امتیاز دهید تا دقت آن اندازه‌گیری شود و رگرسیون‌ها پیدا شوند.
  • مقیاس ابری سازمانی: استقرار و قابلیت مشاهده : عامل خود را با استفاده agents-cli deploy بسته‌بندی و در محیط‌های تولیدی مانند Agent Runtime یا Cloud Run مستقر کنید. تله‌متری تولید را برای پخش گزارش‌ها و ردیابی‌های اجرا به Cloud Trace و BigQuery تنظیم کنید.

منابع اضافی