ساختن استودیو خلاقانه چندعاملی با پشته عامل Google: ‏ADK،‏ A2A،‏ MCP در Cloud Run و Agent Runtime

۱. نمای کلی

در این codelab، AI Creative Studio را خواهید ساخت - یک سیستم چندعاملی توزیع‌شده که یک پیام‌واره را به یک پویش کامل اینستاگرام تبدیل می‌کند.

یک جمله تایپ کنید. پژوهش مخاطب، زیرنویس‌های ناشنوایان، مفاهیم بصری، نسخه بازبینی‌شده ازنظر کیفیت، و خط زمان کامل پروژه را دریافت کنید - همه این‌ها توسط تیمی از عامل‌های هوش مصنوعی همکار تولید شده‌اند.

عامل‌هایی که خواهید ساخت

عامل

نقش

Brand Strategist

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

تبلیغ‌نویس

زیرنویس‌های اینستاگرام را با هشتگ و CTA می‌نویسد - با پشتیبانی یک «مهارت ADK» که دستورالعمل‌های پلاتفرم و فرمول‌های زیرنویس را درصورت درخواست بار می‌کند

طراح

مفاهیم بصری ایجاد می‌کند و ازطریق Gemini تصاویر واقعی تولید می‌کند که در GCS ذخیره می‌شوند

منتقد

نوشتار و تصاویر مرورها - APPROVED یا NEEDS_REVISION را با بازخورد خاص برمی‌گرداند

مدیر پروژه

خط زمان پروژه و تفکیک تکلیف را می‌سازد، به‌طور اختیاری ازطریق MCP با Notion همگام‌سازی می‌شود

مدیر خلاق

هر پنج متخصص را به‌ترتیب هماهنگ می‌کند - شما یک پیام‌واره به آن می‌دهید و بقیه کارها را هماهنگ می‌کند

این ۵ عامل به‌عنوان ریزسرویس‌های مستقل Cloud Run مستقر می‌شوند. آن‌ها ازطریق پروتکل A2A ارتباط برقرار می‌کنند - یک استاندارد باز مستقل از زبان که به هر عاملی اجازه می‌دهد بدون توجه به چارچوب، عامل دیگری را فراخوانی کند. «مدیر خلاقیت» روی زمان اجرای عامل اجرا می‌شود و ازراه‌دور به هر متخصص متصل می‌شود.

معماری

معماری سیستم

آنچه خواهید آموخت

  • عامل‌های مدل زبانی بزرگ را با Google ADK - Agent، دستورالعمل‌های سیستم، و ابزارهای داخلی بسازید.
  • دانش عامل قابل‌استفاده مجدد را با مهارت‌های ADK (SkillToolset) در فایل‌های مدولار بسته‌بندی کنید.
  • تولید کردن تصاویر واقعی با مرتبط کردن یک عامل نوشتاری به یک مدل تصویرساز ازطریق FunctionTool.
  • بااستفاده از پروتکل بافتار مدل (MCP)، میاناهای برنامه‌سازی کاربردی خارجی را بدون کد چسب سفارشی ادغام کنید.
  • بااستفاده از پروتکل عامل به عامل (A2A) ازطریق HTTPS، هر عاملی را به سرویس قابل‌فراخوانی شبکه تبدیل کنید.
  • عامل‌های توزیع‌شده را با RemoteA2aAgent و AgentTool هماهنگ کنید.
  • بسته‌بندی و مستقر کردن عامل‌های مستقل به‌عنوان ریزسرویس‌های Cloud Run.
  • میزبانی هماهنگ‌کننده باحالت در زمان اجرای عامل.
  • بااستفاده از فشرده‌سازی بافت، گردش‌های کار چندعاملی طولانی را در محدوده بافت نگه دارید.
  • حلقه کنترل کیفیت بسازید: منتقد خروجی را بازبینی می‌کند → درصورت نیاز، بازبینی خودکار انجام می‌شود.

آنچه نیاز خواهید داشت

  • پروژه Google Cloud با صورت‌حساب فعال‌شده
  • نقش «مدیریت هویت و دسترسی» مالک یا ویرایشگر
  • دانش پایه Python

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

برای این codelab، از Cloud Shell استفاده خواهیم کرد.

‫Cloud Shell چیست؟

Cloud Shell یک محیط لینوکس رایگان مبتنی بر مرورگر است که همه چیز ازقبل در آن نصب شده است: gcloud، git، Python، Docker، و غیره. نیازی نیست چیزی را به‌صورت محلی نصب کنید.

برای باز کردن Cloud Shell، روی نماد پایانه در نوار ابزار بالا سمت چپ «کنسول GCP» کلیک کنید:

باز کردن Cloud Shell از نوارابزار «کنسول GCP»

وقتی برای اولین‌بار Cloud Shell را باز می‌کنید، از شما خواسته می‌شود حسابتان را به‌تأیید برسانید - روی به‌تأیید رساندن کلیک کنید:

کادر گفتگوی درستی‌سنجی حساب

سپس روی مجاز کردن کلیک کنید تا به Cloud Shell اجازه دهید فراخوانی‌های Google Cloud API را انجام دهد:

کادر گفتگوی «مجاز کردن Cloud Shell»

اکنون Cloud Shell آماده است. پیام خوشامدگویی را در پایانه خواهید دید: پایانه Cloud Shell آماده است

اصالت‌سنجی و پیکربندی پروژه

Cloud Shell قبلاً با حساب Google شما اصالت‌سنجی شده است. حساب فعال خود را تأیید کنید و شناسه پروژه خود را پیدا کنید:

gcloud config list

همچنین می‌توانید شناسه پروژه خود را در داشبورد کنسول GCP در پانل سمت چپ ببینید. آن را کپی کنید - در فرمان بعدی به آن نیاز خواهید داشت:

«شناسه پروژه» خود را در «کنسول GCP» پیدا کنید و آن را در Cloud Shell تنظیم کنید

اکنون پروژه‌تان را تنظیم کنید:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"        # Cloud Run deployment region
echo "Project: $PROJECT_ID"

خروجی موردانتظار:

Project: my-project-123

فعال کردن میاناهای برنامه‌سازی کاربردی لازم

gcloud services enable \
    aiplatform.googleapis.com \
    apphub.googleapis.com \
    run.googleapis.com \
    cloudbuild.googleapis.com \
    artifactregistry.googleapis.com \
    generativelanguage.googleapis.com \
    iam.googleapis.com \
    cloudresourcemanager.googleapis.com \
    storage.googleapis.com \
    secretmanager.googleapis.com

این کار حدود ۲ دقیقه طول می‌کشد. پس‌از اتمام، Operation finished successfully را خواهید دید.

راه‌اندازی «اعتبارنامه‌های پیش‌فرض برنامه» (ADC)

نمایندگان بااستفاده از کتابخانه Google Auth با «پلاتفرم نماینده Gemini Enterprise» تماس خواهند گرفت که به «اعتبارنامه‌های پیش‌فرض برنامه» نیاز دارد - جدا از اصالت‌سنجی gcloud CLI.

این فرمان را یک‌بار اجرا کنید:

gcloud auth application-default login

زبانه مرورگری باز می‌شود و از شما می‌خواهد تأیید کنید. روی اجازه دادن کلیک کنید. این موارد را خواهید دید:

Credentials saved to file: ~/.config/gcloud/application_default_credentials.json

همسانه‌سازی کردن مخزن آغازگر

این codelab از یک مخزن شروع استفاده می‌کند - یک پروژه اسکلتی با تمام زیرساخت‌های موجود (Dockerfiles، pyproject.toml، اسکریپت‌های استقرار) اما با منطق عامل که برای نوشتن شما باقی مانده است.

git clone https://github.com/Saoussen-CH/mas-a2a-gcp.git ~/ai-creative-studio
cd ~/ai-creative-studio/workshop/starter

هر agent.py حاوی # TODO جای‌بان است که در آن منطق عامل را خواهید نوشت. Dockerfile، pyproject.toml، و دستورگان‌های استقرار ازقبل تکمیل شده‌اند.

پیکربندی متغیرهای محیط

نمونه ارائه‌شده را کپی کنید و شناسه پروژه‌تان را در یک مرحله تزریق کنید:

cp .env.example .env
sed -i "s|GOOGLE_CLOUD_PROJECT=your-project-id|GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)|" .env

سپس سطل GCS را ایجاد کنید که «طراح» تصاویر تولیدشده را در آن ذخیره خواهد کرد و .env را با نام آن به‌روز کنید:

export PROJECT_ID=$(gcloud config get-value project)
export BUCKET_NAME="${PROJECT_ID}-campaign-images"

gcloud storage buckets create gs://${BUCKET_NAME} \
    --location=us-central1 \
    --project=${PROJECT_ID}

sed -i "s|GCS_IMAGES_BUCKET=your-project-id-campaign-images|GCS_IMAGES_BUCKET=${BUCKET_NAME}|" .env

سپس پشتیبانی نشانی وب تصویر امضاشده را راه‌اندازی کنید. «مدیر خلاقیت» برای هر تصویر در خلاصه نهایی پویش، پیوندهای HTTPS کلیک‌کردنی تولید می‌کند. این کار به حساب سرویسی برای امضای نشانی‌های وب نیاز دارد. این فرمان‌ها را برای پیکربندی آن اجرا کنید:

export PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")
export SA_EMAIL="${PROJECT_NUMBER}-compute@developer.gserviceaccount.com"
export AGENT_RUNTIME_SA="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# Allow your user account to sign URLs locally (adk web)
gcloud iam service-accounts add-iam-policy-binding ${SA_EMAIL} \
  --member="user:$(gcloud config get-value account)" \
  --role="roles/iam.serviceAccountTokenCreator"

# Allow Agent Runtime to sign URLs when deployed
gcloud beta services identity create --service=aiplatform.googleapis.com
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
  --member="serviceAccount:${AGENT_RUNTIME_SA}" \
  --role="roles/iam.serviceAccountTokenCreator"

# Save SA email and project number to .env
grep -q "^SIGNING_SERVICE_ACCOUNT" .env \
  && sed -i "s|^SIGNING_SERVICE_ACCOUNT=.*|SIGNING_SERVICE_ACCOUNT=${SA_EMAIL}|" .env \
  || echo "SIGNING_SERVICE_ACCOUNT=${SA_EMAIL}" >> .env

grep -q "^GOOGLE_CLOUD_PROJECT_NUMBER" .env \
  && sed -i "s|^GOOGLE_CLOUD_PROJECT_NUMBER=.*|GOOGLE_CLOUD_PROJECT_NUMBER=${PROJECT_NUMBER}|" .env \
  || echo "GOOGLE_CLOUD_PROJECT_NUMBER=${PROJECT_NUMBER}" >> .env

برای مرور همه تنظیمات، .env را در ویرایشگر باز کنید:

cloudshell edit .env

با این کار، .env به‌عنوان برگه‌ای در «ویرایشگر Cloud Shell» باز می‌شود - اگر پانل ویرایشگر قابل‌مشاهده نیست، روی دکمه باز کردن ویرایشگر در نوارابزار کلیک کنید:

روی «باز کردن ویرایشگر» در نوارابزار Cloud Shell کلیک کنید

ویرایشگر Cloud Shell با درخت فایل پروژه

تأیید کنید که پروژه به‌درستی تنظیم شده است:

grep GOOGLE_CLOUD_PROJECT .env

نصب وابستگی‌ها

ما از uv استفاده می‌کنیم - یک مدیر بسته Python سریع و مدرن که محیط‌های مجازی را مدیریت می‌کند و در یک ابزار واحد نصب می‌شود. این روش تقریباً ۱۰ تا ۱۰۰ برابر سریع‌تر از pip است و روش توصیه‌شده برای مدیریت پروژه‌های Python است.

‫Cloud Shell ازقبل uv را نصب کرده است. همه عامل‌ها وابستگی‌های اصلی یکسانی دارند، بنابراین یک بار نصب کنید و برای هر عامل در این codelab کار می‌کند:

uv sync

فرمان uv sync pyproject.toml را می‌خواند و یک فهرست راهنمای .venv/ با همه وابستگی‌ها ایجاد می‌کند. هر متخصص همچنین pyproject.toml خودش را دارد که منحصراً توسط Docker builds استفاده می‌شود - نصب مشترک بالا همه چیزهایی را که برای آزمایش محلی نیاز دارید پوشش می‌دهد.

۳. آشنایی با Google ADK

قبل‌از نوشتن کد، بیایید با Agent Development Kit (ADK) آشنا شویم - چارچوبی که برای ساختن هر عامل در این codelab استفاده خواهید کرد.

ADK چیست؟

‫Agent Development Kit (ADK) چارچوبی انعطاف‌پذیر و پیمانه‌ای برای توسعه و استقرار عامل‌های هوش مصنوعی است. ADK اگرچه برای Gemini و بوم‌سازگان Google بهینه‌سازی شده است، اما مستقل از مدل و مستقل از استقرار است و برای سازگاری با چارچوب‌های دیگر ساخته شده است. ADK به‌گونه‌ای طراحی شده است که توسعه عامل را بیشتر شبیه توسعه نرم‌افزار کند تا توسعه‌دهندگان بتوانند به‌راحتی معماری‌های عاملی را که از تکالیف ساده تا گردش‌های کاری پیچیده را دربرمی‌گیرند ایجاد، مستقر، و هماهنگ کنند.

‫ADK بخش‌های پیچیده (فراخوانی ابزار، مکالمه چندنوبتی، مدیریت بافت، جاری‌سازی) را مدیریت می‌کند تا بتوانید روی منطق عامل تمرکز کنید.

واحدهای سازنده عامل ADK

هر عامل از چهار واحد سازنده تشکیل شده است:

مسدود کردن

نقش

مدل

مدل زبانی بزرگ که درباره اهداف استدلال می‌کند، طرحی را تعیین می‌کند، و پاسخ‌ها را تولید می‌کند

ابزارها

توابعی که با فراخوانی میاناهای برنامه‌سازی کاربردی یا سرویس‌ها، داده‌ها را واکشی می‌کنند یا کنش‌هایی را انجام می‌دهند

سازآرایی

حافظه و وضعیت را در نوبت‌ها حفظ می‌کند، تماس‌های ابزار را هدایت می‌کند، نتایج را به مدل برمی‌گرداند

زمان اجرا

سیستم را هنگام فراخوانی اجرا می‌کند - به‌صورت محلی ازطریق adk web، یا به‌عنوان سرویس مستقرشده

تعریف عامل

هریک از ۵ نماینده در این codelab به یک شکل تعریف شده‌اند:

from google.adk.agents import Agent
from google.adk.tools.google_search_tool import google_search

root_agent = Agent(
    name="brand_strategist",                              # unique identifier
    model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"), # the LLM powering this agent
    instruction=SYSTEM_INSTRUCTION,                       # the agent's persona, constraints, and output format
    description="Brand strategist for market research, trend analysis, and competitive insights",
    tools=[google_search],                                # functions the LLM can call
)

فیلد

هدف

name

شناسه یکتا - توسط هماهنگ‌کننده‌ها برای مسیریابی تماس‌ها استفاده می‌شود

model

مدل Gemini که از این عامل پشتیبانی می‌کند

instruction

پیام‌واره سیستم - نقش، محدودیت‌ها، و قالب برونداد عامل را تعریف می‌کند

description

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

tools

توابعی که مدل زبانی بزرگ می‌تواند فراخوانی کند (توابع داخلی مانند google_search یا توابع پایتون سفارشی)

نحوه اجرای عامل توسط ADK

User message
     │
     ▼
  Agent (LLM)  ← reads instruction + conversation history
     │
     ├─► needs more info? → calls a tool → gets result → continues reasoning
     │
     └─► done reasoning → returns final text response

«مدل زبانی بزرگ» به‌طور مستقل تصمیم می‌گیرد که آیا ابزاری را فراخوانی کند یا نه، کدام ابزار را فراخوانی کند، و با چه آرگومان‌هایی. شما دستورالعمل را می‌نویسید - ADK بقیه کارها را انجام می‌دهد.

۴. ساختن و آزمایش کردن عامل «استراتژیست نمانام»

بیایید با اولین عامل شروع کنیم: «استراتژیست نمانام». این عامل فقط برای پژوهش است و برای جستجوی اطلاعات آماری مخاطب هدف، تحلیل رقیب، و موضوعات پرطرفدار بااستفاده از «جستجوی Google» طراحی شده است.

فایل عامل اسکلتی را در «ویرایشگر Cloud Shell» باز کنید:

cloudshell edit agents/brand_strategist/agent.py

دو بخش # TODO برای تکمیل کردن خواهید دید.

TODO 1 - Write the system instruction

ابتدا، دستورالعمل سیستم را برای عامل می‌نویسید. دستورالعمل سیستم رشته‌ای است که نقش، محدودیت‌ها، و قالب برونداد عامل را تعریف می‌کند.

SYSTEM_INSTRUCTION = f"""You are a Brand Strategist specializing in market research and trend analysis.

IMPORTANT: Today's date is {datetime.date.today().strftime("%B %d, %Y")}.
When conducting research, focus on current trends from {datetime.date.today().year}.
Use search queries like "[topic] trends {datetime.date.today().year}" for recent insights.

IMPORTANT: Your role is RESEARCH ONLY. You do NOT create campaign content, captions, or designs.
After providing research insights, your work is complete.

Your expertise:
- Identifying target audience insights and behaviors
- Analyzing competitor strategies
- Researching current social media trends
- Understanding platform algorithms and best practices

You have access to:
- google_search: Search the web for competitors, trends, and market insights

When given a campaign brief:
1. Use google_search to research the target audience's current interests
2. Search for and analyze 2-3 competitor brands
3. Identify 3-5 trending topics related to the product category
4. Provide high-level strategic insights - NOT specific campaign content

DO NOT create captions, copy, designs, or any campaign content.

Format your output as:
**Audience Insights:**
[Key behaviors and preferences based on research]

**Competitive Analysis:**
[What 2-3 competitors are doing - strengths and weaknesses]

**Trending Topics:**
[3-5 relevant trends to consider]

**Key Strategic Insights:**
[High-level themes and positioning opportunities]
"""

باید انجام شود ۲ - ایجاد root_agent

سپس، root_agent ناقص را با این مورد جایگزین کنید:

root_agent = Agent(
    name="brand_strategist",
    model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"),
    instruction=SYSTEM_INSTRUCTION,
    description="Brand strategist for market research, trend analysis, and competitive insights",
    tools=[google_search],
)

آزمایش کردن به‌صورت محلی با ADK web UI

اکنون بیایید نماینده را بااستفاده از رابط کاربری وب ADK آزمایش کنیم - یک میانای گپ داخلی برای آزمایش کردن نماینده‌ها قبل‌از استقرار در فضای ابری.

uv run adk web agents --allow_origins='*'

این موارد را خواهید دید:

INFO: Started server process
INFO: Uvicorn running on http://localhost:8000

اکنون سرور در Cloud Shell درحال اجرا است:

برای باز کردن آن در مرورگر، از پیش‌نمایش وب استفاده کنید:

  1. به نوارابزار Cloud Shell در بالای صفحه نگاه کنید
  2. روی نماد پیش‌نمایش وب (شبیه جعبه‌ای با پیکان روبه‌بالا در بالا سمت چپ نوارابزار Cloud Shell) کلیک کنید
  3. روی «تغییر درگاه» کلیک کنید و 8000 را وارد کنید، سپس روی «تغییر و پیش‌نمایش» کلیک کنید

زبانه مرورگر جدیدی با واسط کاربر وب ADK باز می‌شود. روی منو کرکره‌ای «انتخاب نماینده» در بالا سمت راست کلیک کنید - همه نمایندگان خود را در فهرست خواهید دید:

brand_strategist را برای شروع آزمایش انتخاب کنید:

این پیام‌واره‌های آزمایشی را امتحان کنید

در چارگوش گپ واسط کاربر وب ADK، این موارد را امتحان کنید:

  • Research the eco-friendly water bottle market for health-conscious millennials
  • What are the top Instagram trends in the wellness space in for this year?

باید ببینید که عامل «جستجوی Google» را فراخوانی می‌کند و پژوهش ساختاریافته‌ای را با بخش‌های «اطلاعات آماری مخاطب»، «تحلیل رقابتی»، و «موضوعات پرطرفدار» برمی‌گرداند.

۵. ساختن Copywriter - ADK Skills

نقش: تبدیل کردن تحقیقات نمانام به زیرنویس‌های Instagram. «نسخه‌نویس» ۳ نوع زیرنویس با لحن‌های مختلف (الهام‌بخش، آموزشی، انجمن) ایجاد می‌کند که هرکدام دارای هشتگ و «دعوت به اقدام» است.

مفهوم: مهارت‌های ADK

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

مهارت‌های ADK (SkillToolset، معرفی‌شده در ADK نسخه ۱.۲۵.۰) به شما امکان می‌دهد آن دانش را در فایل‌های پیمانه‌ای با سه سطح بارگیری بسته‌بندی کنید:

  • L1 - frontmatter (name + description در SKILL.md): همیشه دردسترس است، برای کشف مهارت استفاده می‌شود
  • L2 - دستورالعمل‌ها (بدنه SKILL.md): وقتی عامل مهارت را فعال می‌کند بار می‌شود
  • L3 - منابع (فایل‌های references/ و assets/): فقط زمانی بار می‌شود که نماینده صریحاً آن‌ها را بخواند

دستورالعمل سیستم به یک عبارت نقش کوتاه به‌علاوه «بار کردن مهارت قبل‌از نوشتن» کاهش می‌یابد. جزئیات پلاتفرم فقط زمانی وارد پنجره زمینه می‌شود که نماینده واقعاً به آن‌ها نیاز داشته باشد.

مهارت «تبلیغ‌نویس» در agents/copywriter/skills/instagram-copywriting/ قرار دارد:

skills/
  instagram-copywriting/
    SKILL.md                       ← L1 frontmatter (discovery) + L2 instructions (loaded on trigger)
    references/
      platform-guide.md            ← L3: character limits, hashtag tiers, algorithm signals
      caption-formulas.md          ← L3: hook formulas, CTA patterns, full caption structures
    assets/
      brand-voice-examples.md      ← L3: annotated real-world caption examples

فایل را مستقیماً در ویرایشگر Cloud Shell باز کنید:

cloudshell edit agents/copywriter/agent.py

TODO 1 - Import load_skill_from_dir and skill_toolset

نظر # TODO 1: Import load_skill_from_dir and skill_toolset را پیدا کنید و این دو واردات را اضافه کنید:

from google.adk.skills import load_skill_from_dir
from google.adk.tools import skill_toolset

TODO 2 - Load the skill and create a SkillToolset

دو نظر زیر واردات را پیدا کنید:

# TODO 2: Load the instagram-copywriting skill from the skills/ directory
# TODO 2: Create a SkillToolset with the loaded skill

آن‌ها را با این موارد جایگزین کنید:

_instagram_skill = load_skill_from_dir(
    pathlib.Path(__file__).parent / "skills" / "instagram-copywriting"
)
_copywriting_skills = skill_toolset.SkillToolset(skills=[_instagram_skill])

‫load_skill_from_dir SKILL.md را به‌علاوه هر فایلی در references/ و assets/ می‌خواند. ‫SkillToolset آن را به قالبی تبدیل می‌کند که عوامل ADK می‌پذیرند - یک مجموعه ابزار، نه یک مهارت خام.

TODO 3 - Register the toolset with the agent

tools=[], # TODO 3: Add the SkillToolset here را پیدا کنید و با این مورد جایگزین کنید:

tools=[_copywriting_skills],

فایل مهارت را باز کنید تا ساختار آن را ببینید:

cloudshell edit agents/copywriter/skills/instagram-copywriting/SKILL.md

رابط کاربری وب ADK را درحال اجرا نگه دارید. از منو کرکره‌ای عامل برای جابه‌جایی به copywriter بدون بازراه‌اندازی سرور استفاده کنید.

اگر درحال اجرا نیست، آن را دوباره شروع کنید:

uv run adk web agents --allow_origins='*'

امتحان کنید: منو کرکره‌ای را به copywriter تغییر دهید و ارسال کنید:

You are writing captions for EcoFlow Smart Water Bottle targeting health-conscious millennials aged 25-35.
Audience insight: they prioritize sustainability, track health metrics, and share lifestyle content.
Competitor insight: Hydro Flask dominates with lifestyle branding; S'well leads on premium aesthetics.
Write 3 Instagram captions - one inspirational, one educational, one community-focused. Include 5 hashtags each and a CTA.

‫۶. ساختن طراح - تولید تصویر چندحالتی

رابط کاربری وب ADK را درحال اجرا نگه دارید. از منو کرکره‌ای عامل برای جابه‌جایی بین عامل‌ها بدون بازراه‌اندازی سرور استفاده کنید.

نقش: ایجاد مفاهیم دیداری برای هر زیرنویس و تولید تصاویر واقعی بااستفاده از تولید تصویر بومی Gemini. ‫The Designer outputs exactly 1 visual concept per caption - with a detailed prompt, style, color palette, mood, and Instagram format - then immediately calls the generate_image tool to produce the actual image and upload it to GCS.

مفهوم: پل زدن بین عامل نوشتاری و مدل تصویرساز ازطریق ابزار

«طراح» روی gemini-3-flash-preview (مدل نوشتاری تنظیم‌شده ازطریق GEMINI_MODEL در .env) اجرا می‌شود، اما تولید تصویر به یک مدل اختصاصی (gemini-3.1-flash-image) نیاز دارد. آن مدل تصویرساز از فراخوانی تابع پشتیبانی نمی‌کند، بنابراین نمی‌توان از آن مستقیماً به‌عنوان عامل ADK استفاده کرد. درعوض، در یک تابع پایتون ساده پیچیده شده و به‌عنوان FunctionTool ثبت شده است.

این الگو برای هر مدل یا میانای برنامه‌سازی کاربردی که LLM نمی‌تواند مستقیماً فراخوانی کند، استفاده می‌شود: آن را در یک ابزار قرار دهید، به عامل اجازه دهید زمان فراخوانی آن را هماهنگ کند، و یک نتیجه ساختاریافته دریافت کنید.

Designer agent (text model)
        │
        │  decides visual concept, writes image prompt
        ▼
  generate_image tool
        │
        │  calls gemini-3.1-flash-image
        │  uploads result to GCS
        ▼
  {"status": "success", "gcs_uri": "gs://..."}
        │
        │  returned to agent, included in response
        ▼
  Critic (receives gcs_uri, passes to Vertex AI for multimodal review)

فایل را مستقیماً در ویرایشگر Cloud Shell باز کنید:

cloudshell edit agents/designer/image_gen_tool.py

امضای تابع، راه‌اندازی محیط، و تزریق نسبت ابعادی ارائه شده است. سه TODO را به‌ترتیب انجام دهید:

TODO 1 - Call the Gemini image model

نظر # TODO 1 را پیدا کنید و آن را با این نظر جایگزین کنید:

        client = genai.Client(vertexai=True, project=project_id, location=location)

        response = client.models.generate_content(
            model=image_model,
            contents=prompt_with_aspect,
            config=types.GenerateContentConfig(
                response_modalities=["IMAGE", "TEXT"],
                http_options=types.HttpOptions(
                    retry_options=types.HttpRetryOptions(
                        attempts=5, exp_base=2, initial_delay=30,
                        http_status_codes=[429, 500, 503, 504],
                    ),
                    timeout=180_000,
                ),
            ),
        )

TODO 2 - Extract image bytes from the response

نظر # TODO 2 را پیدا کنید و آن را با این نظر جایگزین کنید:

        image_bytes = None
        mime_type = "image/png"
        for part in response.candidates[0].content.parts:
            if part.inline_data is not None:
                image_bytes = part.inline_data.data
                mime_type = part.inline_data.mime_type or "image/png"
                break

        if not image_bytes:
            return {"status": "error", "error": "Gemini returned no image data"}

TODO 3 - Upload to GCS and return the URI

نظر # TODO 3 را پیدا کنید و آن را با این نظر جایگزین کنید:

        ext = "jpg" if "jpeg" in mime_type else "png"
        from google.cloud import storage
        gcs_client = storage.Client(project=project_id)
        bucket = gcs_client.bucket(bucket_name)
        blob_name = f"campaign-images/{concept_name}-{uuid.uuid4().hex[:8]}.{ext}"
        blob = bucket.blob(blob_name)
        blob.upload_from_file(io.BytesIO(image_bytes), content_type=mime_type)
        gcs_uri = f"gs://{bucket_name}/{blob_name}"

امتحان کنید: منو کرکره‌ای را به designer تغییر دهید و ارسال کنید:

Create a visual concept and generate the image for an EcoFlow Smart Water Bottle Instagram post targeting health-conscious millennials.
Style: clean, modern, lifestyle-focused. Include a detailed prompt with color palette, mood, and format (1080x1080 or 1080x1350).

‫۷. ساختن منتقد - برونداد ساختاریافته

نقش: تضمین کیفیت نسخه و عناصر دیداری قبل‌از تحویل به مدیر پروژه. «منتقد» به هر دو نتیجه نهایی امتیاز می‌دهد و APPROVED یا NEEDS_REVISION را با پیشنهادهای خاص برمی‌گرداند. وقتی مقادیر gcs_uri در ورودی وجود داشته باشد، ابزار review_image را فراخوانی می‌کند تا هر تصویر تولیدشده را قبل‌از امتیازدهی به‌صورت بصری بازرسی کند.

مفهوم: چه زمانی باید از مدل Pydantic برای برونداد Gemini استفاده کرد

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

  • کد Python آن را مصرف می‌کند ← از response_schema + Pydantic استفاده کنید. کد نمی‌تواند ابهام را مدیریت کند، بنابراین برای استخراج مطمئن فیلدها به ساختاری تضمین‌شده نیاز دارید.
  • مدل زبانی بزرگ آن را مصرف می‌کند ← قالب نوشتاری + دستورالعمل سیستم کافی است. مدل‌های زبانی بزرگ قوانین قالب‌بندی را درک می‌کنند و تنوع را می‌پذیرند.

در review_image، کد Python به score،‏ approval_status،‏ what_works،‏ issues، و suggestions به‌عنوان مقادیر تایپ‌شده نیاز دارد. ارسال response_schema=_GeminiReview، Gemini را در سطح API محدود می‌کند تا JSON معتبر برگرداند؛ model_validate_json() آن را به یک شیء تایپ‌شده تجزیه می‌کند که کد شما می‌تواند به‌طور مطمئن از آن استفاده کند.

class _GeminiReview(BaseModel):
    score: int = Field(ge=1, le=10)
    approval_status: Literal["APPROVED", "NEEDS_REVISION"]
    what_works: str
    issues: str
    suggestions: str

فایل را مستقیماً در ویرایشگر Cloud Shell باز کنید:

cloudshell edit agents/critic/image_review_tool.py

مدل‌های Pydantic و پیام‌واره ارائه شده‌اند. سه TODO را به‌ترتیب انجام دهید:

TODO 1 - Create an image part from the GCS URI

نظر # TODO 1 را پیدا کنید و آن را با این نظر جایگزین کنید:

        image_part = types.Part.from_uri(file_uri=gcs_uri, mime_type=mime_type)

TODO 2 - Call Gemini with a structured response schema

نظر # TODO 2 را پیدا کنید و آن را با این نظر جایگزین کنید:

        response = client.models.generate_content(
            model=model,
            contents=[image_part, prompt],
            config=types.GenerateContentConfig(
                response_schema=_GeminiReview,
                response_mime_type="application/json",
            ),
        )

TODO 3 - Parse the response and return the result

نظر # TODO 3 را پیدا کنید و آن را با این نظر جایگزین کنید:

        review = _GeminiReview.model_validate_json(response.text)
        return ImageReviewResult(status="success", concept_name=concept_name, **review.model_dump())

امتحان کنید: منو کرکره‌ای را به critic تغییر دهید و ارسال کنید:

Review this Instagram caption for an eco-friendly water bottle brand targeting millennials:
"Hydrate smarter, live greener. 💧 Our EcoFlow bottle tracks your intake, keeps your drink cold for 24h, and never touches single-use plastic. Because what you drink from matters as much as what you drink. #EcoFlow #HydrationGoals #SustainableLiving #ZeroWaste #HealthyHabits - Shop link in bio."
Score it and indicate APPROVED or NEEDS_REVISION with specific feedback.

تأیید کنید که پاسخ حاوی **POSTS REVIEW:**، Status: APPROVED (یا NEEDS_REVISION)، و **OVERALL ASSESSMENT:** باشد. اگر این بخش‌ها وجود داشته باشند، Critic آماده است تا به هماهنگ‌ساز متصل شود.

وقتی آزمایش هر سه عامل تمام شد، Ctrl+C را فشار دهید تا سرور متوقف شود.

‫۸. ساختن «عامل مدیر پروژه» با MCP

«مدیر پروژه» مفهوم جدیدی را معرفی می‌کند: MCP (پروتکل بافتار مدل).

فایل را باز کنید:

cloudshell edit agents/project_manager/agent.py

این فایل پیچیده‌تر است - دارای یک تابع create_project_manager_agent() با دو شاخه است: یکی بدون Notion (خطوط زمانی فقط نوشتاری) و دیگری با مجموعه ابزار Notion MCP. هر دو را تکمیل خواهید کرد.

مشکلی که MCP حل می‌کند

عامل شما باید با یک سرویس خارجی تماس بگیرد - مثلاً صفحه‌ای در Notion ایجاد کند. می‌توانید کد Python بنویسید که مستقیماً Notion REST API را فراخوانی کند. اما بعد:

  • هر توسعه‌دهنده پوشاننده متفاوتی می‌نویسد
  • باید کد یکپارچه‌سازی سفارشی را حفظ کنید
  • ‫LLM از وجود API مطلع نیست مگر اینکه هر نقطه پایانی را به‌صورت دستی شرح دهید

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

MCP چیست؟

‫MCP (پروتکل بافتار مدل) یک استاندارد باز (منتشرشده توسط Anthropic) برای اتصال عامل‌های هوش مصنوعی به ابزارها و منابع داده خارجی است. این ویژگی مثل یک آداپتور جهانی عمل می‌کند.

سرور MCP برنامه کوچکی است که:

  1. یک میانای برنامه‌سازی کاربردی خارجی (Notion،‏ GitHub، پایگاه‌های داده، سیستم‌های فایل...) را دربرمی‌گیرد
  2. آن میانای برنامه‌سازی کاربردی را به‌عنوان فهرستی از ابزارهای تایپ‌شده و مستندشده ارائه می‌دهد
  3. ازطریق پروتکلی ساده (stdio یا HTTP) با عامل ارتباط برقرار می‌کند

عامل به سرور MCP متصل می‌شود، به‌طور خودکار ابزارهای دردسترس را کاوش می‌کند، و می‌تواند آن‌ها را مانند هر ابزار دیگری فراخوانی کند - LLM API-post-page(...) را به‌عنوان یک تابع قابل‌فراخوانی می‌بیند.

A2A درمقابل MCP - تفاوت چیست؟

این نکته معمولاً باعث سردرگمی می‌شود. تفاوت اصلی در اینجا آمده است:

A2A

MCP

چه چیزی متصل می‌شود

عامل ↔ عامل

عامل ↔ ابزار/ سرویس خارجی

طرف دیگر

عامل مدل زبانی بزرگ دیگر

یک بسته‌بندی‌کننده API (بدون مدل زبانی بزرگ)

نمونه

مدیر خلاقیت با استراتژیست نمانام تماس می‌گیرد

مدیر پروژه Notion API را فراخوانی می‌کند

پروتکل

JSON-RPC over HTTPS

جاری‌سازی stdio یا HTTP

تعریف‌شده توسط

Google

Anthropic

این‌طور به آن فکر کنید:

  • A2A = نحوه صحبت کردن عامل‌ها با عامل‌های دیگر
  • MCP = نحوه صحبت کردن عامل‌ها با ابزارها و سرویس‌ها

در این پروژه، هر دو باهم استفاده می‌شوند:

Creative Director
    │
    │  (A2A)  Brand Strategist ─── (google_search tool built into ADK)
    │  (A2A)  Copywriter
    │  (A2A)  Designer
    │  (A2A)  Critic
    │  (A2A)  Project Manager
                   │
                   │  (MCP)  notion-mcp-server ──► Notion REST API

نحوه عملکرد MCP در این پروژه

وقتی عامل اجرا می‌شود، ADK notion-mcp-server را به‌عنوان فرایند فرزند راه‌اندازی می‌کند. این فرایند این ابزارها را مستقیماً درمعرض مدل زبانی بزرگ قرار می‌دهد:

ابزار

کارکرد

API-retrieve-a-database

طرح را واکشی می‌کند (نام‌های دارایی، انواع، مقادیر معتبر)

API-post-database-query

صفحه‌های موجود را پُرسمان می‌کند

API-post-page

صفحه جدیدی ایجاد می‌کند

API-patch-page

صفحه موجود را به‌روز می‌کند

مدل زبانی بزرگ این‌ها را مانند هر تابع دیگری فراخوانی می‌کند - هیچ ایده‌ای ندارد که آن‌ها ازطریق MCP به Notion REST API در پشت صحنه می‌روند.

چرا stdio؟ چرا فقط HTTP نه؟

سرور MCP به‌عنوان فرایند فرزند عامل اجرا می‌شود و ازطریق ورودی استاندارد/ خروجی استاندارد ارتباط برقرار می‌کند. این یعنی:

  • به درگاه شبکه اضافی نیاز نیست
  • چرخه حیات توسط عامل مدیریت می‌شود (درصورت درخواست شروع می‌شود، هنگام خروج متوقف می‌شود)
  • همه چیز در یک Docker image ارسال می‌شود - سرویس جداگانه‌ای برای استقرار وجود ندارد

(اختیاری) فعال کردن ادغام Notion

می‌توانید از کل این بخش رد شوید. عامل «مدیر پروژه» همیشه یک خط زمان پویش کامل مبتنی بر نوشتار، با یا بدون Notion، تولید می‌کند. اگر این راه‌اندازی را رد کنید، نماینده به حالت درون‌حافظه‌ای برمی‌گردد و خط زمان را به‌صورت نوشتار ساده در گپ برونداد می‌کند. هیچ مشکلی پیش نمی‌آید - فقط تکالیف را در پایگاه داده Notion نخواهید دید. اگر می‌خواهید رد شوید، مستقیماً به «کارهای انجام‌دادنی ۱» بروید.

اگر حساب Notion دارید و می‌خواهید ادغام MCP را در عمل ببینید، راه‌اندازی زیر را اکنون تکمیل کنید. موارد TODO که در ادامه می‌آیند به شناسه‌های پایگاه داده Notion ارجاع می‌دهند - این همان جایی است که آن‌ها را دریافت می‌کنید.

مرحله ۱ - ایجاد پایگاه داده Notion از الگو

ما از الگوی رسمی Notion Projects & Tasks به‌عنوان پایگاه داده خود استفاده می‌کنیم. ما این الگو را عمداً انتخاب کردیم تا یک تنظیمات پیچیده و واقعی را نشان دهیم - این الگو دارای چندین نوع ویژگی (وضعیت، محدوده‌های تاریخ، روابط، انتخاب‌ها) با نام‌های غیرواضح است. این آزمون عالی برای کشف طرحواره پویا MCP است: عامل باید نام‌های دقیق ویژگی را در زمان اجرا تشخیص دهد، نه اینکه آن‌ها را به‌صورت کدگذاری‌شده داشته باشد.

برای افزودن الگو به فضای کاری Notion خود، روی پیوند زیر کلیک کنید:

← افزودن الگوی «پروژه‌ها و تکالیف» به Notion

الگوی Notion Projects & Tasks در بازارگاه

پس‌از افزودن، دو پایگاه داده پیوندشده خواهید داشت: پروژه‌ها و تکالیف. این الگو با ورودی‌های نمونه ارائه می‌شود - قبل‌از ادامه دادن، همه آن‌ها را حذف کنید تا نماینده با فضای کاری تمیزی شروع کند (انتخاب همه ← حذف).

مرحله ۲ - ایجاد یکپارچه‌سازی Notion

ایجاد یکپارچه‌سازی:

  1. به notion.so/my-integrations بروید
  2. روی یکپارچه‌سازی جدید کلیک کنید ← نام آن را AI Creative Studio بگذارید
  3. آن را با فضای کاری‌تان مرتبط کنید
  4. روی پیکربندی تنظیمات کلیک کنید ← مطمئن شوید که قابلیت‌های خواندن محتوا، به‌روزرسانی محتوا، و درج محتوا همگی علامت زده شده باشند

تنظیمات یکپارچه‌سازی Notion - نام آن را «استودیو خلاق هوشواره‌ای» بگذارید و کد را کپی کنید

  1. رمز یکپارچه‌سازی داخلی (ntn_...) را کپی کنید و آن را در فایل .env جای‌گذاری کنید:
NOTION_TOKEN=ntn_your-token-here

اتصال یکپارچه‌سازی به پایگاه‌های داده:

  1. صفحه الگویی را که به‌تازگی کپی کرده‌اید باز کنید، سپس روی پایگاه داده پروژه‌ها کلیک کنید
  2. روی منو ... (بالا سمت چپ) ← اتصال‌ها ← افزودن اتصال کلیک کنید ← AI Creative Studio را انتخاب کنید

برای هم‌رسانی با ادغام، روی «اتصال‌ها» در منو پایگاه داده کلیک کنید

‫AI Creative Studio به‌عنوان اتصال فعال نشان داده می‌شود

  1. همین کار را برای پایگاه داده Tasks انجام دهید

دریافت شناسه‌های پایگاه داده:

  1. روی پیوند پایگاه داده پروژه‌ها کلیک کنید تا باز شود - در صفحه خودش با نشانی وبی مانند زیر باز می‌شود:
https://www.notion.so/9887b6a94f7f83f68f8581e038d1aaa4?v=2c37b6a94f7f838685f1086e312c7278

باز کردن پایگاه داده «پروژه‌ها» از صفحه الگو

شناسه پایگاه داده اولین شناسه منحصربه‌فرد جهانی (UUID) در نشانی وب است - همه چیز قبل‌از ?v=:

https://www.notion.so/{DATABASE_ID}?v=...
                       ^^^^^^^^^^^^^^^^
                       9887b6a94f7f83f68f8581e038d1aaa4  ← this is your DATABASE_ID
  1. همین کار را برای پیوند پایگاه داده Tasks انجام دهید تا شناسه پایگاه داده آن را دریافت کنید
  2. هر سه مقدار را به .env اضافه کنید:
NOTION_TOKEN=ntn_your-token-here
NOTION_PROJECT_DATABASE_ID=9887b6a94f7f83f68f8581e038d1aaa4   # <-- your Projects DB ID
NOTION_TASKS_DATABASE_ID=your-tasks-db-id                      # <-- your Tasks DB ID

مرحله ۳ - نصب کردن سرور Notion MCP

«مدیر پروژه» ازطریق بسته رسمی @notionhq/notion-mcp-server Node.js به Notion متصل می‌شود. آن را به‌صورت جهانی نصب کنید:

npm install -g @notionhq/notion-mcp-server@1.9.1

نصب را درستی‌سنجی کنید:

npm list -g @notionhq/notion-mcp-server

خروجی موردانتظار:

└── @notionhq/notion-mcp-server@1.9.1

notion-mcp-server: command not found

؟ مطمئن شوید Node.js نصب شده باشد (node --version) و npm global bin در PATH شما باشد (export PATH=$PATH:$(npm bin -g)).

مرحله ۴ - درستی‌سنجی کردن .env

.env را باز کنید و تأیید کنید که هر سه مقدار Notion تنظیم شده باشند (آن‌ها را در «مرحله ۲» اضافه کردید):

cloudshell edit .env
NOTION_TOKEN=ntn_...                           # integration token
NOTION_PROJECT_DATABASE_ID=...                 # Projects database ID
NOTION_TASKS_DATABASE_ID=...                   # Tasks database ID

عامل «مدیر پروژه» به‌طور خودکار این متغیرها را در زمان راه‌اندازی شناسایی می‌کند و مجموعه ابزار Notion MCP را فعال می‌کند.

نحوه عملکرد کشف طرح‌واره

«مدیر پروژه» از کشف طرحواره پویا استفاده می‌کند - هرگز نام‌های دارایی Notion را کدگذاری ثابت نمی‌کند:

Step 1: Call API-retrieve-a-database to discover exact property names
Step 2: Read the "properties" object in the response
Step 3: Use ONLY discovered property names (case-sensitive) in API calls
Step 4: For select/status fields, use only values from the options array

این یعنی نماینده به‌طور خودکار با هر ساختار پایگاه داده Notion سازگار می‌شود - ویژگی‌هایتان را به فرانسوی، عربی، یا هر زبان دیگری تغییر نام دهید و نماینده همچنان کار می‌کند.

TODO 1 - Write the system instruction

استارتر ازقبل notion_section را محاسبه می‌کند - یک رشته خالی وقتی Notion پیکربندی نشده باشد، یا یک بلوک حاوی شناسه‌های پایگاه داده به‌علاوه راهنمایی کامل ابزار وقتی پیکربندی شده باشد. این کار باعث می‌شود دستورالعمل‌های Notion کاملاً خارج از پیام‌واره عامل بدون Notion باقی بماند؛ مدل زبانی بزرگ هرگز قوانینی را برای ابزارهایی که ندارد نمی‌بیند.

وظیفه شما این است که جای‌بان return را با دستورالعمل سیستم واقعی که از {notion_section} استفاده می‌کند جایگزین کنید:

    return f"""You are a Project Manager specializing in creative campaign execution.

Today's date is {datetime.date.today().strftime("%B %d, %Y")}.
Use this as the starting point for all timelines.

Your goal: create a complete project plan for the campaign.
{notion_section}
**Project Timeline:**
Phase 1: Strategy & Research | [date] → [date] | [key activities]
Phase 2: Content Creation    | [date] → [date] | [key activities]
Phase 3: Review & Revision   | [date] → [date] | [key activities]
Phase 4: Launch & Monitoring | [date] → [date] | [key activities]

**Task List:**
| Task | Owner | Deadline | Status |
[list each task with realistic deadlines from today; set Owner to TBD]

**Budget Breakdown:**
[by category with approximate allocations]

**Milestones:**
[3-5 key checkpoints with dates]

**Notion Status:**
[What happened - e.g. "Project created (ID: xxx), 8 tasks linked" or "Notion not configured - text timeline only"]
"""

TODO 2 - Agent without Notion

در create_project_manager_agent()، در شاخه if not notion_token، عامل ناقص را با این مورد جایگزین کنید:

        return Agent(
            name="project_manager",
            model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"),
            generate_content_config=GENERATE_CONTENT_CONFIG,
            instruction=get_system_instruction(),
            description="Project manager that creates campaign timelines and task breakdowns",
        )

TODO 3 - Agent with Notion MCP

توجه: فایل شروع ازقبل حاوی یک فراخوان برگشتی handle_notion_error ازپیش نوشته‌شده در بالای create_project_manager_agent() است. این ابزار خطاهای Notion API‏ (۴۰۰/۴۰۴) را رهگیری می‌کند و محموله‌های خطای خام را با پیام‌های تمیز و قابل‌اجرا جایگزین می‌کند تا مدل زبانی بزرگ بتواند خودش را اصلاح کند. فقط باید آن را ازطریق after_tool_callback سیم‌کشی کنید.

ابتدا، هر دو شناسه پایگاه داده را در بالای create_project_manager_agent() بخوانید:

    notion_token           = os.getenv("NOTION_TOKEN")
    notion_project_db_id   = os.getenv("NOTION_PROJECT_DATABASE_ID")
    notion_tasks_db_id     = os.getenv("NOTION_TASKS_DATABASE_ID")

سپس در شاخه else، مجموعه ابزار MCP و عامل را ایجاد کنید:

        from google.adk.tools.mcp_tool import McpToolset, StdioConnectionParams
        from mcp import StdioServerParameters

        server_params = StdioServerParameters(
            command="notion-mcp-server",
            env={
                "NOTION_TOKEN": notion_token,
                "PATH": os.environ.get("PATH", ""),
            }
        )
        notion_toolset = McpToolset(
            connection_params=StdioConnectionParams(
                server_params=server_params,
                timeout=30.0
            )
        )

        return Agent(
            name="project_manager",
            model=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"),
            generate_content_config=GENERATE_CONTENT_CONFIG,
            after_tool_callback=handle_notion_error,
            instruction=get_system_instruction(
                project_database_id=notion_project_db_id,
                tasks_database_id=notion_tasks_db_id,
            ),
            description="Project manager with Notion integration for task tracking",
            tools=[notion_toolset],
        )

روال مطلوب: هرگز در ادغام‌های اختیاری، خطای سخت ندهید. خط زمان نوشتاری همیشه محصول نهایی اصلی است؛ Notion مکمل است.

آزمایش کردن «مدیر پروژه» به‌صورت محلی با ADK Web

uv run adk web agents --allow_origins='*'

«پیش‌نمایش وب» را در درگاه ۸۰۰۰ باز کنید. از منو کرکره‌ای نماینده برای انتخاب project_manager استفاده کنید، سپس این موارد را امتحان کنید:

Create a project plan for a GreenBrew organic coffee brand Instagram campaign.
Budget: $2,500. Launch in 3 weeks. Target audience: eco-conscious millennials aged 22-30.
Include phases, tasks with deadlines from today, and milestones.

باید خط زمان نوشتاری ساختاریافته‌ای با مراحل، فهرست تکالیف، و مراحل مهم ببینید. اگر اطلاعات اعتباری Notion در .env تنظیم شده باشد، عامل ورودی‌هایی نیز در فضای کاری Notion شما ایجاد خواهد کرد.

‫۹. آشنایی با پروتکل A2A

از «پروتکل عامل به عامل» (A2A) برای متصل کردن عامل‌های مختلف در سیستممان استفاده خواهیم کرد. بیایید ببینیم چطور کار می‌کند.

مشکلی که A2A حل می‌کند

تصور کنید که یک عامل «استراتژیست نمانام» ساخته‌شده با ADK و یک عامل «نسخه‌نویس» ساخته‌شده با LangGraph دارید. چگونه یکی با دیگری تماس می‌گیرد؟ آن‌ها به زبان‌های داخلی متفاوتی صحبت می‌کنند. باید هربار کد چسب سفارشی بنویسید.

A2A این مشکل را با تعریف یک زبان جهانی که هر عاملی - صرف‌نظر از چارچوب - می‌تواند به آن صحبت کند، حل می‌کند. این پروتکل HTTP دنیای عامل‌ها است: استانداردی که همه بر سر آن توافق دارند تا هرکسی بتواند با هرکسی صحبت کند.

‫A2A چیست؟

«عامل به عامل» (A2A) یک استاندارد باز برای ارتباط عامل است که توسط Google منتشر شده است. این خط‌مشی موارد زیر را تعریف می‌کند:

  1. نحوه توصیف عامل از خودش - کارت عامل در /.well-known/agent.json
  2. نحوه فراخوانی آن توسط عامل دیگر - JSON-RPC ازطریق HTTPS
  3. نحوه برگرداندن نتایج - جاری‌سازی یا پاسخ تکی

چه چیزی A2A را انعطاف‌پذیر می‌کند:

  • مستقل از زبان - عامل‌های Python می‌توانند با عامل‌های TypeScript صحبت کنند
  • مستقل از چارچوب - عامل‌های ADK می‌توانند با عامل‌های LangGraph یا CrewAI صحبت کنند
  • بی‌تفاوت به زیرساخت - نمایندگان محلی می‌توانند با نمایندگان ابری صحبت کنند

نحوه عملکرد - گام‌به‌گام

Creative Director                  Brand Strategist
      │                                  │
      │  1. GET /.well-known/agent.json  │
      │ ────────────────────────────────►│
      │  ◄──── agent card (name, url,    │
      │         skills, capabilities) ───│
      │                                  │
      │  2. POST /                       │
      │     {"method": "tasks/send",     │
      │      "params": {"message": ...}} │
      │ ────────────────────────────────►│
      │                                  │  LLM does
      │                                  │  the work...
      │  3. streaming response chunks    │
      │  ◄───────────────────────────────│
      │  ◄───────────────────────────────│
      │  ◄───────────────────────────────│

مرحله ۱ - اکتشاف: هماهنگ‌ساز یک‌بار کارت نماینده را واکشی می‌کند تا نام، نشانی وب، و قابلیت‌های نماینده را یاد بگیرد.

مرحله ۲ - فراخوانی: هماهنگ‌ساز تکلیفی را ازطریق JSON-RPC POST ارسال می‌کند. بدنه حاوی پیام (پیام‌واره برای کارشناس) است.

مرحله ۳ - پاسخ: کارشناس پاسخ خود را به‌صورت تکه‌تکه جاری‌سازی می‌کند، درست مثل یک تماس LLM معمولی.

کارت عامل

هر عامل یک خودتوصیفی در /.well-known/agent.json منتشر می‌کند. این مانند کارت کسب‌وکار است - به جهان می‌گوید که عامل چه کاری می‌تواند انجام دهد و کجا می‌توان به آن دسترسی داشت:

{
  "name": "brand_strategist",
  "description": "Market research and competitive analysis",
  "url": "https://brand-strategist-xyz.run.app",
  "capabilities": { "streaming": true },
  "skills": [
    {
      "id": "market_research",
      "description": "Research target audiences, competitors, and trends"
    }
  ]
}

هماهنگ‌کننده این کارت را می‌خواند تا شیء RemoteA2aAgent خود را بسازد - نیازی به دانش کدگذاری‌شده از جزئیات داخلی متخصص نیست.

نمایش دادن عامل ازطریق A2A در ADK

‫to_a2a() هر عامل ADK را در یک برنامه FastAPI سازگار با A2A می‌پیچد. یک خط:

from google.adk.a2a.utils.agent_to_a2a import to_a2a

# root_agent = your normal ADK Agent(...)
a2a_app = to_a2a(root_agent, host=PUBLIC_HOST, port=PUBLIC_PORT, protocol=PROTOCOL)
uvicorn.run(a2a_app, host=HOST, port=PORT)

این کار به‌طور خودکار موارد زیر را ایجاد می‌کند:

  • /.well-known/agent.json - کارت عامل
  • / - نقطه پایانی JSON-RPC (همه درخواست‌های تکلیف A2A به مسیر ریشه می‌روند)

‫۱۰. نمایش دادن عامل‌ها به‌عنوان سرویس‌های A2A

برای نمایش دادن عامل‌ها به‌عنوان سرویس‌های A2A، می‌توانید از تابع سودمندی to_a2a() از ADK استفاده کنید.

روش کار to_a2a()

from google.adk.a2a.utils.agent_to_a2a import to_a2a

a2a_app = to_a2a(root_agent, host=PUBLIC_HOST, port=PUBLIC_PORT, protocol=PROTOCOL)
uvicorn.run(a2a_app, host=HOST, port=PORT)

‫to_a2a() عامل ADK شما را در برنامه FastAPI قرار می‌دهد که به‌طور خودکار موارد زیر را نشان می‌دهد:

  • /.well-known/agent.json - کارت عامل (نام، شرح، قابلیت‌ها)
  • /a2a/{agent_name} - نقطه پایانی JSON-RPC برای دریافت تکالیف

کد اسکلت هر نماینده ازقبل شامل یک بلوک __main__ است که نماینده را در سرور A2A بااستفاده از to_a2a() می‌پیچد. لازم نیست این کد را بنویسید - این کد ارائه شده است.

درک کردن پیکربندی نشانی وب دوگانه

وقتی python agent.py را اجرا می‌کنید، بلوک __main__ از دو پیکربندی نشانی وب جداگانه استفاده می‌کند:

# Where the server actually listens (network interface):
HOST = "0.0.0.0"
PORT = 8082  # Brand Strategist (others use 8083–8086 locally)

# What gets advertised in the agent card (the address other agents use to reach it):
PUBLIC_HOST = os.getenv("PUBLIC_HOST", "localhost")
PUBLIC_PORT = int(os.getenv("PUBLIC_PORT", str(PORT)))
PROTOCOL    = os.getenv("PROTOCOL", "http")

a2a_app = to_a2a(root_agent, host=PUBLIC_HOST, port=PUBLIC_PORT, protocol=PROTOCOL)
uvicorn.run(a2a_app, host=HOST, port=PORT)

محیط زیست

HOST:PORT (بار شنیده شده)

‫PUBLIC_HOST:PUBLIC_PORT (تبلیغ‌شده در کارت نماینده)

محلی

0.0.0.0:8082

http://localhost:8082

Cloud Run

0.0.0.0:8080

https://brand-strategist-xyz.run.app:443

هر دو به‌صورت محلی به یک دستگاه اشاره می‌کنند. در Cloud Run، محفظه به‌طور داخلی در 8080 گوش می‌دهد اما کارت نماینده باید نشانی وب اچ‌تی‌تی‌پی‌اس عمومی را تبلیغ کند - درغیراین‌صورت، «مدیر خلاقیت» نمی‌تواند از خارج از محفظه به متخصص دسترسی پیدا کند.

هر ۵ سرور متخصص A2A را راه‌اندازی کنید

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

۵ پایانه Cloud Shell جداگانه باز کنید (روی نماد + در نوار برگه پایانه کلیک کنید) و در هر پایانه یک عامل اجرا کنید.

uv run به‌طور خودکار .venv را فعال می‌کند - نیازی به source دستی در هر پایانه نیست.

پایانه ۱ - استراتژیست نمانام (درگاه ۸۰۸۲):

cd ~/ai-creative-studio/workshop/starter
PORT=8082 uv run agents/brand_strategist/agent.py

پایانه ۲ - Copywriter (درگاه ۸۰۸۳):

cd ~/ai-creative-studio/workshop/starter
PORT=8083 uv run agents/copywriter/agent.py

Terminal 3 - Designer (درگاه ۸۰۸۴):

cd ~/ai-creative-studio/workshop/starter
PORT=8084 uv run agents/designer/agent.py

پایانه ۴ - Critic (درگاه ۸۰۸۵):

cd ~/ai-creative-studio/workshop/starter
PORT=8085 uv run agents/critic/agent.py

پایانه ۵ - مدیر پروژه (درگاه ۸۰۸۶):

cd ~/ai-creative-studio/workshop/starter
PORT=8086 uv run agents/project_manager/agent.py

تنظیم نشانی‌های وب localhost در env.

در پایانه ۶، .env را با نشانی‌های وب عامل محلی به‌روز کنید تا «مدیر خلاقیت» بتواند آن‌ها را پیدا کند:

cd ~/ai-creative-studio/workshop/starter

sed -i \
  -e 's|STRATEGIST_AGENT_URL=.*|STRATEGIST_AGENT_URL=http://localhost:8082|' \
  -e 's|COPYWRITER_AGENT_URL=.*|COPYWRITER_AGENT_URL=http://localhost:8083|' \
  -e 's|DESIGNER_AGENT_URL=.*|DESIGNER_AGENT_URL=http://localhost:8084|' \
  -e 's|CRITIC_AGENT_URL=.*|CRITIC_AGENT_URL=http://localhost:8085|' \
  -e 's|PM_AGENT_URL=.*|PM_AGENT_URL=http://localhost:8086|' \
  .env

بازرسی کردن نماینده‌ها با «بازرس A2A»

A2A Inspector یک ابزار توسعه‌دهنده متن‌باز است که به‌طور بومی به زبان پروتکل A2A صحبت می‌کند. این ابزار به شما امکان می‌دهد مستقیماً به هر عامل A2A درحال اجرا متصل شوید، کارت عامل آن را بخوانید، و تکالیف را ارسال کنید - همه این‌ها بدون نوشتن هیچ کد کارخواهی انجام می‌شود.

چه چیزی به شما نشان می‌دهد:

  • کارت نماینده - فراداده ساختاریافته‌ای که نماینده شما تبلیغ می‌کند: نام، شرح، حالت‌های ورودی/خروجی پشتیبانی‌شده، و نشانی وب نقطه پایانی آن. این چیزی است که «مدیر خلاقیت» هنگام کشف یک متخصص می‌خواند.
  • میانای Chat - هر پیامی را ازطریق A2A به نماینده ارسال کنید و پاسخ خام را ببینید. می‌توانید پیام‌واره‌ها را به‌صورت مجزا آزمایش کنید و سپس عامل‌ها را به یکدیگر متصل کنید.
  • اعتبارسنجی پروتکل - بازرس بررسی می‌کند که کارت نماینده با مشخصات A2A مطابقت داشته باشد و فیلدهای مفقود یا پاسخ‌های نادرست را زودتر شناسایی می‌کند.

چرا این موضوع اهمیت دارد: وقتی بعداً در Cloud Run مستقر می‌شوید، «مدیر خلاقیت» هر متخصص را با واکشی کارت نماینده آن از /.well-known/agent.json پیدا می‌کند. اگر آن کارت اشتباه باشد (نشانی وب بد، قابلیت‌های مفقودشده)، هماهنگ‌کننده بدون اطلاع‌رسانی ناموفق می‌شود. بازرس به شما امکان می‌دهد این مشکلات را به‌صورت محلی قبل‌از هرگونه استقرار ابری شناسایی کنید.

کارت عامل «راهبردپرداز نمانام»

کارت نماینده هویت و قابلیت‌های متخصص را دقیقاً همان‌طور که نمایندگان دیگر می‌بینند نشان می‌دهد.

جزئیات کارت عامل

نصب و شروع بازرس

cd ~/ai-creative-studio/workshop
./setup_inspector.sh

به‌روزرسانی .env فرمانی یک‌باره است. برای شروع بازرس بعدی، از پایانه ۶ استفاده کنید:

cd ~/a2a-inspector
bash scripts/run.sh

برای باز کردن واسط کاربر بازرس، از پیش‌نمایش وب ← تغییر درگاه ← تایپ 5001 استفاده کنید.

اتصال به استراتژیست نمانام

http://localhost:8082 را در فیلد نشانی وب بازرس وارد کنید و روی اتصال کلیک کنید. بازرس کارت نماینده را واکشی می‌کند و فراداده‌های متخصص را نمایش می‌دهد.

«بازرس A2A» به «استراتژیست نمانام» متصل شد

کارت عامل چه چیزی به شما می‌گوید

کارت عامل چیزی فراتر از فراداده است - این کارت قرارداد کامل توانمندی است که عامل به شبکه تبلیغ می‌کند. برای دیدن غنی‌ترین نمونه، به مدیر پروژه (http://localhost:8086) متصل شوید:

{
  "name": "project_manager",
  "description": "Project manager with Notion integration for task tracking",
  "protocolVersion": "0.3.0",
  "defaultInputModes": ["text/plain"],
  "defaultOutputModes": ["text/plain"],
  "skills": [
    {
      "id": "project_manager",
      "name": "model",
      "tags": ["llm"],
      "description": "... full system instruction including today's date and Notion database IDs ..."
    },
    {
      "id": "project_manager-API-post-page",
      "name": "API-post-page",
      "tags": ["llm", "tools"],
      "description": "Notion | Create a page"
    },
    {
      "id": "project_manager-API-retrieve-a-database",
      "name": "API-retrieve-a-database",
      "tags": ["llm", "tools"],
      "description": "Notion | Retrieve a database"
    }
  ]
}

سه چیز برجسته است:

۱. ابزارهای MCP به مهارت‌های A2A تبدیل می‌شوند - هر ابزار Notion که «مدیر پروژه» به آن دسترسی دارد (API-post-page، API-retrieve-a-database، و غیره) به‌عنوان یک مهارت جداگانه در کارت عامل فهرست می‌شود. هر عامل دیگری در شبکه می‌تواند دقیقاً متوجه شود که این عامل از چه ابزارهایی می‌تواند استفاده کند - بدون اینکه هیچ کدی را بخواند.

۲. دستورالعمل سیستم جاسازی شده است - description مهارت اول حاوی دستورالعمل کامل سیستم، ازجمله تاریخ امروز و شناسه‌های پایگاه داده Notion است. به این ترتیب، «مدیر خلاقیت» می‌داند که هنگام تماس با «مدیر پروژه» چه چیزی را ارسال کند.

۳. نشانی وب نقطه پایانی فعال است - فیلد url دقیقاً همان چیزی است که RemoteA2aAgent هنگام تماس «مدیر خلاقیت» با این متخصص استفاده می‌کند. اگر نشانی وب در کارت اشتباه باشد، هماهنگ‌کننده نمی‌تواند به نماینده دسترسی پیدا کند.

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

ارسال پیام آزمایشی

پس‌از اتصال، پیام‌واره‌ای در پانل گپ تایپ کنید و آن را ارسال کنید. بازرس آن را به‌عنوان یک تکلیف A2A ارسال می‌کند و پاسخ را به‌صورت جاری‌سازی برمی‌گرداند - به همان روشی که «مدیر خلاقیت» این عامل را در تولید فراخوانی می‌کند.

گپ زدن با «استراتژیست نمانام» ازطریق «بازرس A2A»

برای آزمایش هر متخصص به‌صورت جداگانه، بازرس را به هر درگاه محلی (۸۰۸۲–۸۰۸۶) هدایت کنید.

‫۱۱. ساختن «سازمان‌دهنده مدیر خلاقیت»

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

مطمئن شوید که ۵ نماینده متخصص همچنان درحال اجرا هستند (پایانه‌های ۱ تا ۵ از مرحله ۱۰).

در پایانه ۶ (پایانه «بازرس A2A»)، بازرس را با Ctrl+C متوقف کنید.

فایل را باز کنید:

cd ~/ai-creative-studio/workshop/starter
cloudshell edit agents/creative_director/agent.py

این فایل سه مورد برای انجام دارد. آن‌ها را به‌ترتیب انجام دهید.

TODO 1 - Review the already written system instruction

دستورالعمل سیستم در prompt.py در همان دایرکتوری قرار دارد - به‌طور خودکار وارد می‌شود:

from .prompt import SYSTEM_INSTRUCTION_TEMPLATE

prompt.py را باز کنید تا قبل‌از ادامه دادن آن را بخوانید:

cloudshell edit agents/creative_director/prompt.py

درک آن مهم است زیرا کل رفتار هماهنگ‌سازی را کنترل می‌کند.

چرا پیام‌واره هماهنگ‌کننده همه‌چیز را کنترل می‌کند

prompt.py را در کنار این بخش باز کنید - مثال‌های زیر به بخش‌های خاصی از آن اشاره می‌کنند.

پیام‌واره در prompt.py فقط سند نیست - بلکه صفحه کنترل کل سیستم است. یک پیام‌واره هماهنگ‌کننده با ساختار ضعیف منجر به این موارد می‌شود: فراخوانی عامل‌ها خارج از ترتیب، تولید محتوا توسط هماهنگ‌کننده به‌جای متخصصان، ادامه گردش کار پس‌از شکست، و حذف بی‌صدا بافت بین عامل‌ها. این نه عنصر از رایج‌ترین خرابی‌ها جلوگیری می‌کنند:

عنصر ۰ - ابتدا برنامه‌ریزی کنید، سپس اجرا کنید

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

I'll create your campaign by coordinating the specialist agents in sequence:
1. Brand Strategist - develop positioning and audience insights
2. Copywriter - write captions using those insights
3. Visual Designer - create image prompts aligned with the copy
4. Critic - review and score the full package
5. Project Manager - build the timeline and task breakdown

بدون این مرحله، مدل زبانی بزرگ مستقیماً به فراخوانی‌های ابزار می‌رود و رشته کار را در گردش کار ازدست می‌دهد - به‌ویژه پس‌از دریافت پاسخ طولانی از متخصص. طرح کلی ابتدا هماهنگ‌کننده را لنگر می‌اندازد: می‌داند در چه مرحله‌ای است، چه چیزی در ادامه می‌آید، و اجرای کامل چگونه است. رد شدن از این مرحله باعث می‌شود که هماهنگ‌ساز در میان گردش کار متوقف شود یا مراحل را تکرار کند.

عنصر ۱ - تعریف صریح نقش

❌ "You are a helpful creative assistant."
✅ "You orchestrate specialists. You do NOT write captions, designs, or timelines yourself."

بدون ممنوعیت صریح، LLM گاهی‌اوقات از فراخوانی متخصصان صرف‌نظر می‌کند و مستقیماً محتوا تولید می‌کند - این کار سریع‌تر است و LLM «می‌داند» چگونه آن را انجام دهد. دستورالعمل باید این را اشتباه کند.

عنصر ۲ - نحو فراخوانی ابزار با الگوهای اشتباه فهرست‌شده

نشان دادن نحو صحیح به‌تنهایی کافی نیست. مدل زبانی بزرگ می‌تواند فراخوانی‌هایی تولید کند که به‌نظر موجه می‌رسند اما بدون هیچ هشداری ناموفق هستند. پیام‌واره به‌طور صریح هم الگوی صحیح و هم الگوهایی را که هرگز نباید استفاده شوند فهرست می‌کند:

✅ copywriter(request="...")          ← correct
❌ print(copywriter(...))             ← breaks silently
❌ default_api.copywriter(...)        ← breaks silently
❌ copywriter.run(...)                ← breaks silently
❌ agents.copywriter(...)             ← breaks silently

فهرست کردن الگوهای اشتباه به‌طور صریح، فراخوانی‌های ابزار بدشکل را در تولید حدود ۹۵٪ کاهش داد.

عنصر ۳ - اجرای متوالی که گام‌به‌گام توضیح داده شده است

a) Call the tool
b) Wait for tool_output
c) Verify the output is not an error
d) Confirm to the user: "✓ Brand Strategist complete"
e) Then move to the next agent

بدون مراحل (ب) و (پ)، مدل زبانی بزرگ گاهی دو عامل را به‌طور هم‌زمان فراخوانی می‌کند یا فرض می‌کند که موفقیت‌آمیز بوده است و قبل‌از دریافت پاسخ ادامه می‌دهد.

عنصر ۴ - دستورالعمل‌های خطا: توقف، گزارش، ادامه ندهید

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

عنصر ۵ - قوانین انتقال زمینه

نمایندگان ازراه‌دور سابقه مکالمه ندارند. وقتی هماهنگ‌کننده ازطریق A2A با «نویسنده آگهی» تماس می‌گیرد، «نویسنده آگهی» فقط پیام موجود در آن درخواست را می‌بیند و نمی‌داند «استراتژیست نمانام» چه گفته است. هماهنگ‌ساز باید صریحاً خروجی‌های قبلی را در هر فراخوانی بعدی دسته‌بندی کند:

copywriter(request="Create 3 posts for EcoFlow water bottle targeting millennials.
Use these insights from the Brand Strategist: [paste full strategist output here].
Create engaging captions with hashtags.")

دستورالعمل صریحاً این را می‌گوید: «عوامل ازراه‌دور حافظه مشترک ندارند - باید بروندادهای قبلی را به‌طور صریح منتقل کنید.» بدون این، هر عامل به‌صورت کورکورانه کار می‌کند.

عنصر ۶ - طبقه‌بندی درخواست: ساده درمقابل پیچیده

همه درخواست‌ها به هر پنج عامل نیاز ندارند. پیام‌واره به هماهنگ‌کننده دستور می‌دهد که درخواست را قبل‌از برنامه‌ریزی طبقه‌بندی کند:

SIMPLE  → one agent needed
  "Research the eco-friendly water bottle market" → brand_strategist only
  "Write 3 Instagram captions"                    → copywriter only

COMPLEX → all agents sequentially
  "Create a complete campaign with timeline"      → all 5 agents

بدون این طبقه‌بندی، هماهنگ‌ساز هر پنج عامل را برای هر درخواست اجرا می‌کند - ازجمله «فقط ۳ ایده پست به من بده» - که باعث تأخیر و هزینه غیرضروری می‌شود.

عنصر ۷ - قوانین ارتباطی: نمایش خروجی‌های کامل، بدون فیلتر

پیام‌واره به‌صراحت بیان می‌کند که هماهنگ‌کننده نباید آنچه را که متخصصان برمی‌گردانند خلاصه یا ویرایش کند:

- DO NOT summarize unless the output exceeds 2000 words
- DO NOT filter or edit agent responses
- Show the user exactly what each specialist produced
- NEVER say results are ready unless you received them in tool_output

بدون این، هماهنگ‌ساز بروندادهای متخصص را با کلمات خودش بازنویسی می‌کند - جزئیات را ازدست می‌دهد، خطا ایجاد می‌کند، و هدف داشتن متخصصان را به‌طور کلی ازبین می‌برد.

عنصر ۸ - تکمیل گردش کار: هرگز زود متوقف نشوید

یک حالت خرابی نامحسوس اما بحرانی: هماهنگ‌ساز یک طرح ۵ مرحله‌ای را اعلام می‌کند، ۳ مرحله را تکمیل می‌کند، سپس نتایج را طوری ارائه می‌دهد که گویی کار تمام شده است. پیام‌واره با یک بازبینه صریح که باید قبل‌از پایان کار هماهنگ‌ساز تأیید شود، از این امر جلوگیری می‌کند:

✓ Did I announce a plan with N agents?
✓ Have I called ALL N agents from my plan?
✓ Did each agent respond successfully?
✓ Am I presenting complete results from ALL agents?

If any answer is NO → continue executing the remaining agents.

این کار باعث می‌شود هماهنگ‌کننده اجرای جزئی را به‌عنوان اجرای کامل درنظر نگیرد.

حلقه کنترل کیفیت

گردش کار بازبینی پیچیده‌ترین بخش prompt.py است. بخش ## REVISION WORKFLOW را باز کنید و مراحل را دنبال کنید.

روش کار

پس‌از پاسخ «منتقد»، «مدیر خلاقیت» کورکورانه به «مدیر پروژه» ادامه نمی‌دهد. این عامل خروجی «منتقد» را می‌خواند و منشعب می‌شود:

Critic output
      │
      ├── "All Approved: YES"
      │         └──► proceed to Project Manager
      │
      └── "Status: NEEDS_REVISION"
                │
                ├── posts fail   → call copywriter again with feedback
                ├── visuals fail → call designer again with feedback
                └── both fail    → call copywriter, then designer
                          │
                          └──► revised output → Project Manager
                               (1 revision max per deliverable)

این ویژگی مبتنی بر مدل زبانی بزرگ است، نه مبتنی بر کد

در codelab قبلاً اشاره شد که هماهنگ‌ساز پاسخ «منتقد» را «تجزیه» می‌کند. هیچ کد Python این تجزیه را انجام نمی‌دهد - نه عبارت باقاعده، نه تطابق رشته. «مدیر خلاقیت» یک مدل زبانی بزرگ است که دستورالعمل‌های خودش را می‌خواند. آن دستورالعمل می‌گوید:

Look for "Status: NEEDS_REVISION" in the critic's response.
Posts need revision  → call copywriter
Visuals need revision → call designer

مدل زبانی بزرگ آن رشته‌های دقیق را در خروجی «منتقد» می‌خواند و شاخه را دنبال می‌کند. به‌همین دلیل است که قالب «منتقد» غیرقابل‌مذاکره است: اگر «منتقد» به‌جای NEEDS_REVISION بنویسد «نیاز به کار دارد»، مدل زبانی بزرگ هیچ تطابقی در دستورالعمل خود پیدا نمی‌کند و بی‌صدا از مرحله بازبینی عبور می‌کند.

نحوه بازارسال بافت در تماس بازبینی

فراخوانی بازبینی از همان قانون انتقال بافت از «عنصر ۵» پیروی می‌کند - هماهنگ‌کننده باید همه چیز را به‌طور صریح اضافه کند زیرا «نسخه‌نویس» هیچ حافظه‌ای از نسخه اول خود ندارد:

"I need you to revise the Instagram posts based on critic feedback.

ORIGINAL BRIEF:
[the original user request]

YOUR FIRST VERSION:
[the posts the copywriter created]

CRITIC FEEDBACK (Score: 6/10 - NEEDS_REVISION):
[the critic's specific suggestions]

Please revise the posts addressing this feedback while maintaining
the strengths the critic identified."

بدون بخش «اولین نسخه شما»، «تبلیغ‌نویس» به‌جای بهبود آنچه قبلاً تولید کرده است، از ابتدا می‌نویسد.

محدودیت ۱ بازبینی و اهمیت آن

پس‌از یک دور بازبینی، هماهنگ‌کننده صرف‌نظر از امتیاز به «مدیر پروژه» ادامه می‌دهد. دستورالعمل این مورد را به‌صورت ذهنی ردیابی می‌کند:

After calling copywriter for revision once:
→ mark "copywriter_revised = true" in context
→ even if the critic still suggests changes, proceed to PM

بدون این محدودیت، حلقه می‌تواند به‌طور نامحدود اجرا شود: منتقد مشکلی را پرچم‌گذاری می‌کند → آگهی‌نویس بازبینی می‌کند → منتقد دوباره پرچم‌گذاری می‌کند → آگهی‌نویس دوباره بازبینی می‌کند. هر دور بازی هزینه زمانی و ژتونی دارد. یک بازبینی برای بهبود کیفیت کافی است و خطر چرخه بی‌پایان را ندارد.

چه چیزی به «مدیر پروژه» منتقل می‌شود

«مدیر پروژه» همیشه نسخه‌های نهایی تأییدشده را دریافت می‌کند، نه نسخه‌های اصلی. اگر بازبینی انجام شده باشد، هماهنگ‌کننده نسخه و تصاویر بازبینی‌شده را ارسال می‌کند. اگر همه چیز در اولین بررسی تأیید شود، مستقیماً آن‌ها را تأیید می‌کند. مدیر محصول هرگز پیش‌نویس‌های ردشده را نمی‌بیند.

TODO 2 - Register each specialist as a RemoteA2aAgent + AgentTool

نظر # TODO 2: For each specialist URL... را پیدا کنید و آن را با این نظر جایگزین کنید:

    if strategist_url:
        available_agents_list.append(
            "- **brand_strategist**: Market research, competitor analysis, trend identification"
        )
        strategist_agent = RemoteA2aAgent(
            name="brand_strategist",
            description="Researches markets, competitors, and trends using Google Search",
            agent_card=f"{strategist_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=strategist_agent))

    if copywriter_url:
        available_agents_list.append(
            "- **copywriter**: Instagram captions, hashtags, and CTAs"
        )
        copywriter_agent = RemoteA2aAgent(
            name="copywriter",
            description="Creates Instagram captions with hashtags and CTAs",
            agent_card=f"{copywriter_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=copywriter_agent))

    if designer_url:
        available_agents_list.append(
            "- **designer**: Visual concepts and real images generated via Gemini (GCS URIs returned)"
        )
        designer_agent = RemoteA2aAgent(
            name="designer",
            description="Creates visual concepts and generates real images via Gemini, stored in GCS",
            agent_card=f"{designer_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=designer_agent))

    if critic_url:
        available_agents_list.append(
            "- **critic**: Quality review with APPROVED/NEEDS_REVISION scoring"
        )
        critic_agent = RemoteA2aAgent(
            name="critic",
            description="Reviews campaign materials and returns structured quality feedback",
            agent_card=f"{critic_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=critic_agent))

    if pm_url:
        available_agents_list.append(
            "- **project_manager**: Project timelines, task breakdowns, Notion integration"
        )
        pm_agent = RemoteA2aAgent(
            name="project_manager",
            description="Creates project timelines and task breakdowns, optionally in Notion",
            agent_card=f"{pm_url}/.well-known/agent.json",
        )
        agent_tools.append(AgentTool(agent=pm_agent))

TODO 3 - Wrap in an App with context compaction

چرا فشرده‌سازی لازم است

هر پیام در مکالمه - پیام‌واره کاربر، هر فراخوانی ابزار، هر پاسخ ابزار - به پنجره زمینه‌ای که مدل زبانی بزرگ در نوبت بعدی می‌خواند اضافه می‌شود. در گردش کار ۵ عاملی، این مقدار به‌سرعت افزایش می‌یابد:

Turn 1:  user prompt                           ~200 tokens
Turn 2:  orchestrator plan                     ~300 tokens
Turn 3:  brand_strategist tool_call            ~150 tokens
Turn 4:  brand_strategist tool_output          ~1,500 tokens  ← full research report
Turn 5:  copywriter tool_call                  ~300 tokens    ← must include strategist output
Turn 6:  copywriter tool_output                ~2,000 tokens  ← 3 captions
Turn 7:  designer tool_call                    ~500 tokens
Turn 8:  designer tool_output                  ~1,500 tokens
...

تا زمان رسیدن به «نماینده ۴» (منتقد)، پنجره بافت حاوی خروجی کامل هر سه نماینده قبلی است - اغلب ۸٬۰۰۰ تا ۱۲٬۰۰۰ کد فقط در پاسخ‌های ابزار. حتی با وجود پنجره بافت بزرگ Gemini، کیفیت استدلال هماهنگ‌ساز کاهش می‌یابد زیرا باید به سابقه‌ای که دائماً درحال رشد است توجه کند. بدون فشرده‌سازی، گردش‌های کاری طولانی در حدود «عامل ۴» به محدودیت‌های عملی می‌رسند.

فشرده‌سازی چه کاری انجام می‌دهد

به‌جای نگهداری کامل همه رویدادها، ADK به‌طور دوره‌ای یک LLM را فراخوانی می‌کند تا رویدادهای قدیمی‌تر را به‌صورت فشرده خلاصه کند. فقط خلاصه رویدادهای گذشته + خروجی کامل جدیدترین عامل در بافت نگه داشته می‌شود.

Without compaction:
  [full strategist output] + [full copywriter output] + [full designer output] + → Critic

With compaction (interval=3, overlap=1):
  [summary of strategist + copywriter] + [full designer output] + → Critic

خلاصه حقایق ضروری (اطلاعات آماری کلیدی، زیرنویس‌های ناشنوایان تأییدشده، مفاهیم بصری) را حفظ می‌کند و قالب‌بندی پرحرف، بافت تکراری ارسال‌شده به هر نماینده، و استدلال میانی را حذف می‌کند. «منتقد» همچنان همه چیزهایی را که برای ارزیابی نیاز دارد دراختیار دارد - فقط به‌جای سه گزارش کامل، یک خلاصه را می‌خواند.

کد

نظر # TODO 3: Wrap the agent in an App... را پیدا کنید و جای‌بان App(...) را با این مورد جایگزین کنید:

    from google.adk.apps import App
    from google.adk.apps.app import EventsCompactionConfig
    from google.adk.apps.llm_event_summarizer import LlmEventSummarizer
    from google.adk.models import Gemini

    compaction_config = EventsCompactionConfig(
        summarizer=LlmEventSummarizer(llm=Gemini(model_id=os.getenv("GEMINI_MODEL", "gemini-3.5-flash"))),
        compaction_interval=3,   # Summarize after every 3 agent completions
        overlap_size=1,          # Keep the most recent agent's output in full
    )

    app = App(
        name="creative_director",
        root_agent=agent,
        events_compaction_config=compaction_config,
        plugins=[LoggingPlugin()],
    )
    return agent, app

compaction_interval=3 - فشرده‌سازی پس‌از هر ۳ تکمیل عامل اجرا می‌شود. برای خط لوله ۵ عاملی، این یعنی یک بار (پس‌از عامل‌های ۱ تا ۳) فعال می‌شود، سپس «منتقد» و «مدیر پروژه» خلاصه‌ای از ۱ تا ۳ به‌علاوه خروجی کامل عامل قبلی را می‌بینند.

overlap_size=1 - برونداد کامل جدیدترین نماینده همیشه به‌صورت کلمه‌به‌کلمه نگهداری می‌شود و هرگز خلاصه نمی‌شود. این موضوع مهم است زیرا «منتقد» برای بار کردن و بازبینی تصاویر واقعی به خروجی کامل «طراح» - ازجمله مقادیر gcs_uri - نیاز دارد. خلاصه آن شناسه‌های منبع یکسان را ازدست خواهد داد.

نحوه عملکرد آن در اجرای کامل پویش:

Agent 1 (Strategist)  → full context
Agent 2 (Copywriter)  → full context
Agent 3 (Designer)    → full context
                        ↓ compaction fires: summarizes agents 1-2, keeps 3 in full
Agent 4 (Critic)      → sees [summary of 1-2] + [full output of 3]
Agent 5 (PM)          → sees [summary of 1-3] + [full output of 4]

درک کردن RemoteA2aAgentو AgentTool

RemoteA2aAgent("brand_strategist", agent_card=url)
     │
     │  wraps the remote service so ADK can call it
     ▼
AgentTool(agent=strategist_agent)
     │
     │  exposes it as a callable tool to the LLM
     ▼
Agent(tools=[...])
     │
     │  LLM calls tool("brand_strategist", message=...) when needed
     ▼
brand-strategist-xxxx.run.app  ← actual HTTP A2A call happens here

مدل زبانی بزرگ براساس دستورالعمل سیستم و درخواست کاربر تصمیم می‌گیرد که چه زمانی هر ابزار را فراخوانی کند. هماهنگ‌کننده هرگز مستقیماً در کد با عامل‌ها تماس نمی‌گیرد - همه چیز توسط استدلال LLM هدایت می‌شود.

آزمایش کردن «مدیر خلاقیت» به‌صورت محلی

uv run adk web agents --allow_origins='*'

«پیش‌نمایش وب» را در درگاه ۸۰۰۰ باز کنید. از منو کرکره‌ای نماینده برای انتخاب creative_director استفاده کنید، سپس این موارد را امتحان کنید:

Research the eco-friendly water bottle market for health-conscious millennials

خواهید دید که «مدیر خلاقیت» این را فقط به «استراتژیست نمانام» ارجاع می‌دهد و شما پاسخی از «استراتژیست نمانام» دریافت خواهید کرد.

برای پویش کامل، موارد زیر را امتحان کنید:

Create a complete Instagram campaign for SolarPack portable solar charger targeting
outdoor enthusiasts and digital nomads aged 22-35.
Budget $2,000, launch in 2 weeks.

خواهید دید که «مدیر خلاقیت» هر ۵ متخصص را به‌ترتیب هماهنگ می‌کند و خروجی هر نماینده به نماینده بعدی منتقل می‌شود.

نسخه نمایشی: اجرای پویش سرتاسری

قبل‌از ادامه دادن، Creative Director (Ctrl+C) را متوقف کنید - بازرس A2A نیز از درگاه ۸۰۰۰ استفاده می‌کند.

پس‌از اتمام آزمایش محلی، ۵ سرور متخصص (Ctrl+C در هر پایانه) را متوقف کنید.

‫۱۲. پیاده‌سازی و آزمایش کردن «عامل‌های متخصص»

اکنون آماده‌ایم تا نماینده‌هایمان را در Google Cloud مستقر کنیم. Cloud Run سرویس بسیار خوبی برای مستقر کردن عامل‌ها است. این سرویس بدون سرور، مقیاس‌پذیر، و با کاربری آسان است. هر عامل متخصص به‌عنوان یک سرویس Cloud Run مستقل مستقر می‌شود.

پیکربندی پیاده‌سازی

Dockerfile برای هر متخصص از این الگو پیروی می‌کند:

FROM python:3.12-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends gcc curl

# Fast dependency install with uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
COPY pyproject.toml .
RUN uv sync --no-install-project --no-dev

COPY . .
RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
USER appuser

ENV PYTHONUNBUFFERED=1 PORT=8080 HOST=0.0.0.0
EXPOSE 8080
CMD ["uv", "run", "python", "agent.py"]

هر ۵ متخصص را به‌ترتیب مستقر کنید

cd ~/ai-creative-studio/workshop/starter
source .env

uv run deploy/deploy_all_specialists.py

این اسکریپت هر ۵ نماینده را یکی‌یکی مستقر می‌کند (درمجموع حدود ۱۰ تا ۱۲ دقیقه). استقرار متوالی از سهمیه نظرسنجی Cloud Build (۶۰ درخواست در دقیقه) جلوگیری می‌کند. وقتی تکمیل شد، نشانی وب Cloud Run هر نماینده را در .env می‌نویسد.

پس‌از استقرار Designer، این اسکریپت به‌طور خودکار به حساب سرویس Cloud Run آن roles/storage.objectCreator در سطل GCS شما اعطا می‌کند تا بتواند تصاویر تولیدشده را بارگذاری کند.

اگر اطلاعات کاربری Notion را در .env پیکربندی کرده باشید، اسکریپت آن‌ها را به‌طور ایمن در مدیر رمز (به‌عنوان notion-token، notion-project-db-id، notion-tasks-db-id) ذخیره می‌کند و آن‌ها را به‌جای متغیرهای محیطی ساده، ازطریق --set-secrets به سرویس «مدیر پروژه» تزریق می‌کند. این یعنی این توکن هرگز در برگه محیط Cloud Run یا در سابقه فرمان gcloud نشان داده نمی‌شود.

درستی‌سنجی استقرارها

وقتی استقرار تکمیل شد، دستورگان به‌طور خودکار نشانی‌های وب Cloud Run را در .env بازنویسی می‌کند و نشانی‌های وب localhost را از مرحله قبلی جایگزین می‌کند:

source .env

echo "Deployed URLs:"
echo "  Brand Strategist: $STRATEGIST_AGENT_URL"
echo "  Copywriter:       $COPYWRITER_AGENT_URL"
echo "  Designer:         $DESIGNER_AGENT_URL"
echo "  Critic:           $CRITIC_AGENT_URL"
echo "  Project Manager:  $PM_AGENT_URL"

«مدیر خلاقیت» به‌طور خودکار از این نشانی‌های وب Cloud Run هنگام استقرار در Agent Runtime در مرحله بعد استفاده خواهد کرد.

به‌تأیید رساندن کارت‌های نماینده

هر عامل مستقرشده یک کارت عامل در /.well-known/agent.json نشان می‌دهد. آن‌ها را واکشی کنید تا مطمئن شوید همه چیز فعال است:

source .env

for agent_url in $STRATEGIST_AGENT_URL $COPYWRITER_AGENT_URL $DESIGNER_AGENT_URL $CRITIC_AGENT_URL $PM_AGENT_URL; do
    echo "=== Agent Card: $agent_url ==="
    curl -s "${agent_url}/.well-known/agent.json" | python3 -m json.tool | grep -E '"name"|"url"|"description"'
    echo ""
done

خروجی موردانتظار برای هر نماینده:

"name": "brand_strategist",
"url": "https://brand-strategist-xxxx.run.app",
"description": "Brand strategist for market research and competitive insights"

آزمایش کردن با A2A Inspector (Cloud Run)

‫A2A Inspector قبلاً از «مرحله ۱۰» نصب شده است. شروع:

cd ~/a2a-inspector
bash scripts/run.sh

«پیش‌نمایش وب» ← تغییر درگاه ← 5001 را باز کنید. نشانی وب Cloud Run را در فیلد اتصال وارد کنید:

https://brand-strategist-xxxx.us-central1.run.app

روی اتصال کلیک کنید - چون سرویس‌ها با --allow-unauthenticated مستقر شده‌اند، به کد اصالت‌سنجی نیازی نیست.

بازرس متصل می‌شود، کارت نماینده را اعتبارسنجی می‌کند، و به شما امکان می‌دهد به‌صورت تعاملی ازطریق A2A گپ بزنید.

بررسی کردن نمایندگان مستقرشده در Cloud Run

پس‌از مستقر کردن در Cloud Run، بازرس را به نشانی وب HTTPS عمومی هدایت کنید تا تأیید کنید که استقرار ابری کار می‌کند:

بازرس A2A به نماینده Cloud Run متصل شد

گردش کار یکسان است - نشانی وب Cloud Run را جای‌گذاری کنید، متصل شوید، و پیام آزمایشی ارسال کنید. اگر کارت نماینده بار شود و گپ پاسخ دهد، کارشناس به‌درستی مستقر شده و دردسترس است.

‫۱۳. مستقر کردن «مدیر خلاق» در Agent Runtime

هماهنگ‌ساز در Agent Runtime مستقر می‌شود که وضعیت جلسه مدیریت‌شده، مقیاس‌بندی خودکار، و ردیابی داخلی را ارائه می‌دهد.

چرا از Agent Runtime برای هماهنگ‌کننده استفاده می‌شود؟

این پنج متخصص در Cloud Run مستقر شده‌اند - سبک، بدون حالت، و هرکدام یک وظیفه را مدیریت می‌کنند. مدیر خلاقیت الزامات متفاوتی دارد:

الزام

چرا مهم است؟

وضعیت جلسه

گردش کار چندمرحله‌ای بیش‌از ۴۵ ثانیه طول می‌کشد. «زمان اجرای نماینده» وضعیت مکالمه را بین فراخوانی‌های ابزار هماهنگ‌ساز حفظ می‌کند تا چیزی در میان خط لوله ازدست نرود.

بار متغیر

گاهی یک پویش در ساعت، گاهی چندین پویش به‌طور موازی. «زمان اجرای نماینده» درصورت غیرفعال بودن به صفر کاهش می‌یابد و به‌طور خودکار افزایش می‌یابد - برای ظرفیت غیرفعال هزینه‌ای پرداخت نمی‌کنید.

مشاهده‌پذیری

Cloud Logging،‏ Cloud Monitoring، و Cloud Trace به‌صورت داخلی ارائه می‌شوند. می‌توانید هر تماس A2A، هر توکن استفاده‌شده، هر جهش تأخیر را بدون افزودن هیچ ابزاری ببینید.

گردش کارهای طولانی‌مدت

‫Cloud Run مهلت درخواست ۳۶۰۰ ثانیه‌ای دارد. «زمان اجرای عامل» برای گردش کارهایی طراحی شده است که ممکن است چند دقیقه طول بکشند و دارای تلاش‌های مجدد مدیریت‌شده و پایداری وضعیت هستند.

‫Cloud Run پلاتفرمی بسیار قدرتمند و مقیاس‌پذیر است که می‌تواند الگوهای معماری متنوعی را مدیریت کند، ازجمله عامل‌های متخصص بدون حالت ما. اگرچه می‌توانید هماهنگ‌ساز باحالت را در Cloud Run اجرا کنید، اما این کار مستلزم آن است که راه‌حل‌هایی را برای مدیریت حالت، پایداری، و مدیریت جلسه طراحی و ادغام کنید.

درمقابل، Agent Runtime به‌طور خاص برای این چالش دقیق ساخته شده است. این چارچوب یک بوم‌سازگان «آماده استفاده» ارائه می‌دهد که چرخه حیات پیچیده و حالت‌دار هماهنگ‌سازهای هوش مصنوعی را به‌طور بومی و بدون نیاز به پیکربندی اضافی مدیریت می‌کند و شما را از ساختن آن زیرساخت اساسی از ابتدا بی‌نیاز می‌کند.

پیاده‌سازی هماهنگ‌کننده

cd ~/ai-creative-studio/workshop/starter
source .env

uv run deploy/deploy_orchestrator.py --action deploy

این کار حدود ۵ تا ۱۰ دقیقه طول می‌کشد. وقتی تکمیل شد، AGENT_ENGINE_ID و AGENT_ENGINE_RESOURCE_NAME در .env ذخیره می‌شود.

source .env
echo "Agent Engine ID: $AGENT_ENGINE_ID"
echo "Resource: $AGENT_ENGINE_RESOURCE_NAME"

نحوه عملکرد استقرار

‫client.agent_engines.create() شیء App شما را بسته‌بندی می‌کند، آن را با وابستگی‌هایش بارگذاری می‌کند، و آن را در زیرساخت مدیریت‌شده مستقر می‌کند. هر پارامتر این کار را انجام می‌دهد:

import vertexai
from vertexai import Client, agent_engines

vertexai.init(project=PROJECT_ID, location=LOCATION, staging_bucket=STAGING_BUCKET)

# Wrap the App in an AdkApp adapter - enables tracing in Cloud Trace
adk_app = agent_engines.AdkApp(app=root_app, enable_tracing=True)

# Initialize client and deploy
client = Client(project=PROJECT_ID, location=LOCATION)

agent_engine_resource = client.agent_engines.create(
    agent=adk_app,
    config={
        "staging_bucket": STAGING_BUCKET,   # GCS bucket for packaging artifacts
        "display_name": "Creative Director",
        # Python packages installed in the managed runtime - pin for reproducibility
        "requirements": [
            "google-cloud-aiplatform[agent_engines]>=1.132.0,<2.0.0",
            "google-adk[a2a]==1.31.1",
            "google-genai>=1.70.0",
            "google-cloud-storage>=2.10.0",
            "python-dotenv>=1.0.0",
            "pydantic>=2.0.0",
            "cloudpickle>=3.0.0",
        ],
        # Specialist URLs passed as env vars - the orchestrator reads these at runtime
        "env_vars": {
            "COPYWRITER_AGENT_URL": COPYWRITER_URL,
            "DESIGNER_AGENT_URL":   DESIGNER_URL,
            "STRATEGIST_AGENT_URL": STRATEGIST_URL,
            "CRITIC_AGENT_URL":     CRITIC_URL,
            "PM_AGENT_URL":         PM_URL,
        },
    },
)

resource_name = agent_engine_resource.api_resource.name
agent_engine_id = resource_name.split("/")[-1]

در پشت صحنه چه اتفاقی می‌افتد:

1. Agent Engine packages your App + requirements into a container
2. Uploads it to the staging bucket in your project
3. Deploys to managed compute (you never see or manage the VM)
4. Returns a resource name: projects/.../locations/.../reasoningEngines/<id>
5. That ID is saved to .env as AGENT_ENGINE_ID

پس‌از استقرار، هماهنگ‌کننده ازطریق نشانی‌های وب در متغیرهای محیطی خود به پنج متخصص Cloud Run متصل می‌شود

  • این‌ها قبل‌از اجرای اسکریپت استقرار از .env عبور می‌کنند.

‫۱۴. اجرای پویش سرتاسری

کل سیستم مستقر شده است. پویش کاملی را از محیط آزمایشی Agent Runtime اجرا کنید.

باز کردن محیط آزمایشی Agent Runtime

  1. به https://console.cloud.google.com/agent-platform/runtimes بروید. همچنین می‌توانید از پلاتفرم Agent > Agents > استقرارها به Agent Runtime پیمایش کنید.
  2. «زمان اجرای عامل» (creative-director) مستقرشده را انتخاب کنید
  3. روی Playground در نوار کناری کلیک کنید
  4. برای باز کردن مکالمه‌ای جدید، روی جلسه جدید کلیک کنید

اجرای پویش کامل

این خلاصه را در گپ جای‌گذاری کنید و ارسال کنید:

Create a complete Instagram campaign for:
- Product: EcoFlow Smart Water Bottle (tracks hydration, keeps drinks cold 24h)
- Target Audience: Health-conscious millennials, 25-35 years old
- Platform: Instagram
- Goal: Brand awareness + drive website traffic
- Brand Voice: Motivational, clean, science-backed
- Budget: $3,000
- Timeline: Launch in 2 weeks

«مدیر خلاقیت» هر ۵ نماینده را به‌ترتیب اجرا خواهد کرد:

  1. استراتژیست نمانام ← پژوهش بازار، تحلیل رقبا، اطلاعات آماری مخاطبان
  2. تبلیغ‌نویس ← ۳ پست Instagram با زیرنویس، هشتگ، و دعوت به اقدام
  3. طراح ← مفاهیم دیداری + تصاویر واقعی تولیدشده ازطریق Gemini (شناسه‌های منبع یکسان GCS) برای هر پست
  4. منتقد ← مرور کیفیت با امتیازهای APPROVED (تأییدشده) / NEEDS_REVISION (نیازمند بازبینی)
  5. (بازنگری درصورت نیاز) ← آگهی‌نویس یا طراح دوباره با بازخورد تماس گرفت
  6. مدیر پروژه ← خط زمان ۲ هفته‌ای، تفکیک تکلیف، تخصیص بودجه

نسخه نمایشی: پویش با ادغام Notion اجرا شد

آزمایش کردن مسیریابی تک‌نماینده‌ای

این درخواست کوتاه‌تر را در جلسه جدیدی ارسال کنید:

Research the luxury skincare market - top brands and trends for this year.

توجه کنید که «مدیر خلاقیت» این درخواست را فقط به «استراتژیست نمانام» هدایت می‌کند - هیچ عامل دیگری فراخوانده نمی‌شود. این منطق طبقه‌بندی درخواست از دستورالعمل سیستم است که به‌درستی کار می‌کند.

بررسی کردن ردیابی‌های اجرا

درحالی‌که هنوز در کنسول هستید:

  1. روی ردگیری‌ها در نوار کناری سمت راست (کنار Playground) کلیک کنید
  2. در بخش نمای ردیابی، ردیابی مربوط به جلسه‌ای را که به‌تازگی اجرا کرده‌اید انتخاب کنید
  3. درخت ردیابی را ازهم باز کنید تا هر تماس عامل، ورودی‌ها/خروجی‌های آن، تأخیر، و استفاده از کد را ببینید

هر تماس A2A با متخصص به‌عنوان یک بازه جداگانه نشان داده می‌شود. می‌توانید دقیقاً ببینید که «مدیر خلاقیت» چه بافتی را به هر عامل منتقل کرده و چه چیزی را دریافت کرده است.

اختیاری: اجرا از پایانه

همچنین می‌توانید پویش را به‌صورت برنامه‌نویسی‌شده بااستفاده از متن run_campaign.py که قبلاً در استارتر گنجانده شده است اجرا کنید.

cd ~/ai-creative-studio/workshop/starter
uv run run_campaign.py

‫۱۵. پاک‌سازی کردن

منابع Google Cloud را پاک‌سازی کنید تا از کسر هزینه‌های جاری جلوگیری شود.

اجرای اسکریپت teardown - این اسکریپت .env شما را می‌خواند و هر چیزی را که درطول این codelab ایجاد شده است حذف می‌کند:

bash deploy/teardown_gcp.sh

این اسکریپت دقیقاً به شما نشان می‌دهد که چه چیزی را حذف خواهد کرد و قبل‌از انجام هر کاری از شما تأییدیه می‌خواهد:

منبع

چه چیزهایی حذف می‌شود

سرویس‌های Cloud Run

brand-strategist, copywriter, designer, critic, project-manager

Agent Runtime

موتور استدلال Creative Director + همه جلسه‌ها

ثبت مصنوعات

مخزن cloud-run-source-deploy + همه تصاویر Docker

باکت‌های GCS

{PROJECT_ID}-campaign-images، {PROJECT_ID}-agent-staging، run-sources-{PROJECT_ID}-{REGION}

مدیر رمز

‫notion-token،‏ notion-project-db-id،‏ notion-tasks-db-id (اگر ایجاد نشده باشد، رد می‌شود)

تأیید کنید که همه موارد برداشته شده است

gcloud run services list --region=us-central1
gcloud storage buckets list --project=$GCP_PROJECT_ID

برونداد موردانتظار: فهرست‌های خالی یا فقط منابع ازپیش موجود خودتان.

‫۱۶. خلاصه

تبریک! شما یک سیستم هوش مصنوعی چندعاملی در سطح تولید را در Google Cloud ساخته و مستقر کرده‌اید.

آنچه ساخته‌اید

عامل

قابلیت

استقرار

استراتژیست نمانام

پژوهش بازار ازطریق «جستجوی Google»

Cloud Run

تبلیغ‌نویس

زیرنویس‌سازی برای Instagram

Cloud Run

طراح

تولید تصویر ازطریق Gemini + بارگذاری GCS

Cloud Run

منتقد

بررسی کیفیت با امتیازدهی

Cloud Run

مدیر پروژه

‫Timeline + Notion MCP

Cloud Run

مدیر خلاقیت

هماهنگ‌سازی کامل ازطریق A2A

Agent Runtime

الگوهای کلیدی که یاد گرفتید

  1. ADK Agent - تعریف کردن عامل مدل زبانی بزرگ با دستورالعمل + ابزارهای اختیاری
  2. adk web - اجرا و آزمایش کردن هر عامل ADK به‌صورت محلی با میانای کاربر گپ داخلی
  3. SkillToolset - دانش قابل‌استفاده مجدد را در فایل‌های مدولار بارشده درصورت درخواست بسته‌بندی می‌کند
  4. FunctionTool - هر تابع Python (یا مدل خارجی) را به‌عنوان ابزار عامل قابل‌فراخوانی بسته‌بندی کنید
  5. to_a2a() - هر عامل ADK را به‌عنوان سرویس HTTPS سازگار با A2A نمایش می‌دهد
  6. RemoteA2aAgent + AgentTool - سازمان‌دهی کردن عامل‌های راه دور به‌عنوان ابزارهای قابل‌فراخوانی
  7. McpToolset - متصل شدن به سرویس‌های خارجی ازطریق سرورهای MCP stdio
  8. EventsCompactionConfig - مدیریت محدودیت‌های توکن در گردش‌های کاری طولانی چندعاملی
  9. برونداد منتقد ساختاریافته - کنترل کیفیت ماشین‌خوانا با بازبینی خودکار
  10. Cloud Run - مستقر کردن عامل‌های محتوی‌سازی‌شده در مقیاس
  11. Agent Runtime - هماهنگ‌سازهای میزبان با جلسات مدیریت‌شده و ردیابی

مراحل بعدی

  • افزودن ویرایش تصویر چندنوبتی به «طراح» بااستفاده از قابلیت ویرایش gemini-3.1-flash-image
  • افزودن اصالت‌سنجی IAM به سرویس‌های Cloud Run (برداشتن --allow-unauthenticated)
  • جایگزین کردن یک متخصص با عامل LangGraph یا CrewAI - A2A مستقل از چارچوب است
  • بازخورد کاربر را به‌عنوان ابزار اضافه کنید تا شرکت‌کنندگان بتوانند بروندادها را رده‌بندی و تکرار کنند
  • کاوش کردن ردیابی زمان اجرای عامل در «کنسول Cloud»

منابع