۱. نمای کلی
برآورده کردن درخواست سفر با محدودیت‌های متعدد (مانند طراحی برنامه سفر یک‌روزه به کیوتو با بودجه کمتر از ۱۰۰ دلار با تمرکز بر معابد تاریخی و غذاهای محلی و بدون گالری‌های هنر مدرن) مستلزم استخراج محدودیت‌ها، تحقیق هم‌زمان درباره جاذبه‌ها و غذاخوری‌ها، تنظیم برنامه زمان‌بندی تفکیک‌شده، و بازرسی طرح نهایی است. تکیه بر یک عامل یکپارچه با ابزارهای متعدد می‌تواند مراحل درستی‌سنجی را نادیده بگیرد یا موارد استثنا را نقض کند، بنابراین سازمان‌دهی عوامل فرعی تخصصی را ازطریق کنترل‌کننده‌های گردش کار قطعی هماهنگ می‌کند.
در این بخش سوم از مجموعه ساختن عامل‌های هوشواره‌ای با ADK، یک برنامه‌ریز سفر چندعاملی مستقل در Agent Platform بااستفاده از کنترل‌کننده‌های گردش کار Agent Development Kit (ADK) 2 (SequentialAgent، ParallelAgent، و LoopAgent) می‌سازید. در سه مرحله پیش‌رونده (بدون نیاز به راه‌اندازی فضای کاری بخش ۱ یا بخش ۲)، شش عامل متخصص با پشتیبانی gemini-3.8-flash را با وضعیت جلسه مشترک (output_key)، اجرای هم‌زمان google_search، و یک حلقه پالایش سازنده-بررسی‌کننده تکراری هماهنگ می‌کنید.
پیش‌نیازها
- درک مفاهیم هوش مصنوعی زایا
- مهارت پایه در برنامه‌نویسی Python
- آشنایی با اصول عامل هوش مصنوعی و Google ADK
آنچه می‌آموزید
- نحوه داربست‌بندی پروژه ADK 2 چندعاملی از صفر
- نحوه طراحی تیمی از عامل‌های تخصصی که بااستفاده از
output_keyوضعیت جلسه را هم‌رسانی می‌کنند - نحوه استفاده از
SequentialAgentبرای اجرای زیرعامل‌ها در خط لوله گام‌به‌گام قطعی - نحوه استفاده از
ParallelAgentبرای اجرای هم‌زمان عامل‌های پژوهش مستقل برای تأخیر کمتر - نحوه استفاده از ارجاع
LoopAgentوToolContextبرای پیاده‌سازی حلقه پالایش تکراری سازنده-بررسی‌کننده - نحوه ترکیب کردن الگوهای متوالی، موازی، و حلقه‌ای در گردش کار چندعاملی سلسله‌مراتبی
آنچه نیاز دارید
- حساب Google (اگر اعتبار کارگاه را مطالبه می‌کنید، از حساب شخصی
@gmail.comاستفاده کنید) - پیوند اعتبار کارگاه از مربی (به‌علاوه دوربین تلفن برای اسکن کردن رمزینه پاسخ‌سریع) یا حساب Cloud Billing فعال
- Google Chrome (توصیه می‌شود از پنجره «ناشناس» استفاده کنید تا حساب‌های شخصی و کاری باهم تداخل پیدا نکنند)
۲. مطالبه کردن اعتبارهای Google Cloud (اختیاری)
اگر در کارگاهی با پیوند اعتبار رویداد شرکت می‌کنید، اعتبار Google Developer Program خود را مطالبه کنید تا حساب صورت‌حساب را بدون کارت اعتباری تأمین کنید.
اعتبار رویدادتان را مطالبه کنید
- پیوند اعتبار کارگاه را در پنجره ناشناس باز کنید و با حساب
@gmail.comخود به سیستم وارد شوید. - در مطالبه مزایا، روی مطالبه اعتبار کلیک کنید:
- اگر از شما خواسته شد نمایه Google Developer Program ایجاد کنید، فرم را تکمیل کنید.
- وقتی اسکن برای درستی‌سنجی انسان بودن ظاهر شد، رمزینه پاسخ‌سریع را با تلفنتان اسکن کنید و درستی‌سنجی را تکمیل کنید (اگر رمزینه پاسخ‌سریع ظاهر نشد، صفحه را بازآورید و دوباره روی مطالبه اعتبار کلیک کنید):
- مطمئن شوید اعتبار رویداد شما باموفقیت مطالبه شد! نشان داده شود، سپس روی باز کردن حساب صورت‌حساب کلیک کنید:
🔍 بررسی کردن کارتان
راه‌اندازی حساب صورت‌حساب تا ۳ دقیقه طول می‌کشد:
- Google Cloud Billing را باز کنید (یا نشانی وب را در پنجره «ناشناس» کپی کنید) و حساب‌های صورت‌حساب خود را انتخاب کنید:
https://console.cloud.google.com/billing
- بازآوری کنید تا حساب
GDP Creditشما وضعیت فعال را نشان دهد:
۳. ایجاد پروژه Google Cloud (اختیاری)
یک پروژه Google Cloud اختصاصی ایجاد کنید تا همه منابع این codelab مجزا بمانند و به‌راحتی پاک شوند.
- ایجاد پروژه را باز کنید (یا نشانی وب را در پنجره «ناشناس» کپی کنید):
https://console.cloud.google.com/projectcreate
- جزئیات پروژه را وارد کنید:
- نام پروژه: برای مثال،
google-cloud-workshop - حساب صورت‌حساب (اگر نشان داده شده است):
GDP Credit(یا حساب صورت‌حساب فعال خود) را انتخاب کنید - منبع ولی: بدون سازمان (یا سازمان شما درصورت نیاز)
- نام پروژه: برای مثال،
- شناسه پروژه تولیدشده را در زیر نام پروژه یادداشت کنید، سپس روی ایجاد کلیک کنید:
🔍 بررسی کردن کارتان
روی اعلان‌ها در نوار ابزار بالا سمت چپ کلیک کنید و پس‌از اتمام ایجاد پروژه، روی انتخاب پروژه کلیک کنید:
۴. راه‌اندازی محیط
Google Cloud Shell را پیکربندی کنید، Agent Platform API را فعال کنید، و محیط مجازی Python 3.12 مجزایی با uv ایجاد کنید.
پیکربندی Cloud Shell
- روی فعال کردن Cloud Shell (
>_) در نوارابزار کنسول Google Cloud کلیک کنید، یا Google Cloud Shell را مستقیماً باز کنید (یا نشانی وب را در پنجره «ناشناس» خود کپی کنید):
https://shell.cloud.google.com/?show=ide,terminal
- درصورت درخواست، روی مجاز کردن کلیک کنید:
- شناسه پروژه فعال Google Cloud خود را از منو شماره‌گذاری‌شده در پایانه انتخاب کنید:
unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
[ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done
باید خروجی مشابهی با این ببینید (پروژه‌های بدون برچسب نیز خط اطلاعاتی [environment: untagged] را چاپ می‌کنند):
1) google-cloud-workshop-4210 2) my-cloud-project-8812 Select your project (e.g. 1): 1 Updated property [core/project].
بررسی کنید که شناسه پروژه انتخابی شما در پیام‌واره Cloud Shell با رنگ زرد برجسته شده باشد:
فعال کردن میاناهای برنامه‌سازی کاربردی لازم
Agent Platform API را فعال کنید تا عامل‌های ADK شما بتوانند مدل‌های Gemini را فراخوانی کنند:
gcloud services enable aiplatform.googleapis.com
باید بروندادی مشابه زیر ببینید:
Operation "operations/acat.p2-..." finished successfully.
ایجاد کردن محیط مجازی Python و نصب ADK
فضای کاری ~/adk-agents را ایجاد کنید و محیط مجازی Python 3.12 را فعال کنید:
cd ~
mkdir -p adk-agents && cd ~/adk-agents
which uv >/dev/null 2>&1 || curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv venv .venv --python 3.12
source .venv/bin/activate
مطمئن شوید پیشوند (.venv) در ابتدای پیام‌واره پایانه شما ظاهر می‌شود:
ADK 2 را در محیط مجازی فعال نصب کنید:
uv pip install --no-cache "google-adk==2.14.0"
🔍 بررسی کردن کارتان
نسخه adk CLI نصب‌شده را درستی‌سنجی کنید:
adk --version
باید بروندادی مشابه زیر ببینید:
adk, version 2.14.0
۵. داربست‌بندی عامل برنامه‌ریز سفر
وقتی محیط آماده شد، از فرمان adk create داخلی ADK برای تولید فایل‌های آغازگر برای بسته عامل travel_planner استفاده کنید.
تولید بسته آغازگر
adk create را از دایرکتوری ~/adk-agents اجرا کنید:
cd ~/adk-agents
adk create travel_planner
وقتی در پایانه از شما خواسته شد، گزینه‌های پیکربندی زیر را انتخاب کنید (اگر در اولین اجرا از شما خواسته شد Enable telemetry? [Y/n]: را وارد کنید، کلید ورود را فشار دهید یا n را تایپ کنید و کلید ورود را فشار دهید):
- مدلی برای عامل ریشه انتخاب کنید:
2را تایپ کنید تاgemini-3.8-flashرا انتخاب کنید (گزینه1gemini-3.5-flashرا انتخاب می‌کند) و Enter را فشار دهید. - انتخاب پس‌رانه:
2را تایپ کنید تا پس‌رانه Agent Platform در Google Cloud را انتخاب کنید (گزینه2در منو CLI زیر) و Enter را فشار دهید. - وارد کردن شناسه پروژه Google Cloud: «شناسه پروژه» خود را که در کروشه نشان داده شده است با فشار دادن کلید Enter تأیید کنید.
- منطقه Google Cloud را وارد کنید:
globalرا تایپ کنید و کلید Enter را فشار دهید.
adk create GOOGLE_GENAI_USE_ENTERPRISE=1، شناسه پروژه شما، و GOOGLE_CLOUD_LOCATION=global را در travel_planner/.env می‌نویسد، بنابراین وقتی بعداً agent.py را به‌روزرسانی می‌کنید، اطلاعات اعتباری شما پیکربندی‌شده باقی می‌ماند.
🔍 بررسی کردن کارتان
باید بروندادی مشابه زیر ببینید:
Choose a model for the root agent: 1. gemini-3.5-flash 2. gemini-3.8-flash 3. Other models (fill later) Choose model (1, 2, 3): 2 1. Google AI 2. Vertex AI 3. Login with Google Choose a backend (1, 2, 3): 2 You need an existing Google Cloud account and project, check out this link for details: https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai Enter Google Cloud project ID [google-cloud-workshop-4210]: Enter Google Cloud region [us-central1]: global Agent created in /home/your_username/adk-agents/travel_planner: - .env - .gitignore - __init__.py - agent.py ⚠️ WARNING: Secrets (like GOOGLE_API_KEY) are stored in .env. Next steps: - Chat with your agent in the terminal: adk run travel_planner - Or in the browser: adk web . - Have your coding agent evaluate and deploy it: uvx google-agents-cli setup (other install options: https://adk.dev/get-started/agents-cli/)
پوشه فعلی را در ویرایشگر کد Cloud Shell باز کنید تا بتوانید فایل‌ها را در کنار ترمینال خود بررسی و ویرایش کنید:
which cloudshell >/dev/null 2>&1 && cloudshell workspace ~/adk-agents || true
cd ~/adk-agents
source .venv/bin/activate
آزمایش کردن عامل تکی پیش‌فرض
قبل‌از ساختن گردش‌های کاری چندعاملی، «میانای کاربر توسعه ADK» را راه‌اندازی کنید تا ببینید عامل تکی پیش‌فرض چگونه به پُرسمان گسترده برنامه‌ریزی سفر پاسخ می‌دهد:
cd ~/adk-agents
adk web --allow_origins "*"
بااستفاده از پیش‌نمایش وب Cloud Shell، «رابط کاربری توسعه» را در مرورگرتان باز کنید:
- روی نماد پیش‌نمایش وب در نوار ابزار بالا سمت چپ Cloud Shell کلیک کنید.
- تغییر درگاه را انتخاب کنید،
8000را وارد کنید، و روی تغییر و پیش‌نمایش کلیک کنید.
وقتی ADK Web UI بار شد، سلامی مثل "hello, what can you do?" یا "Help me plan a trip to Japan" بفرستید:
توجه داشته باشید که root_agent تکی مستقیماً در یک مرحله بدون استخراج اولویت ساختاریافته، پژوهش وب زنده، یا درستی‌سنجی بودجه پاسخ می‌دهد.
وقتی آزمایش تمام شد، Ctrl + C را در پایانه Cloud Shell فشار دهید تا سرور adk web متوقف شود و به پیام‌واره فرمان برگردید.
۶. ساختن گردش کار SequentialAgent
اکنون اولین الگوی هماهنگ‌سازی خود را خواهید ساخت: یک گردش کار خطی که توسط SequentialAgent پشتیبانی می‌شود. در خط لوله متوالی، زیرنماینده‌ها به‌ترتیب دقیق اجرا می‌شوند. کارشناس اول پارامترهای ساختاریافته را استخراج می‌کند و آن‌ها را بااستفاده از output_key="user_preferences" در وضعیت جلسه هم‌رسانی‌شده ذخیره می‌کند، و کارشناس دوم {user_preferences} را از وضعیت هم‌رسانی‌شده می‌خواند تا پیش‌نویس برنامه سفر را تهیه کند.
ایجاد متخصصان اولیه (specialists.py)
فایل جدیدی با نام specialists.py در travel_planner/ باز کنید:
cloudshell edit ~/adk-agents/travel_planner/specialists.py
کد زیر را در travel_planner/specialists.py جای‌گذاری کنید تا user_profiler_agent و itinerary_synthesizer_agent را تعریف کنید (ToolContext و google_search را برای مراحل بعدی ازقبل وارد کنید):
from google.adk import Agent
from google.adk.tools import ToolContext, google_search
# --- Specialist 1: The User Profiler ---
user_profiler_agent = Agent(
name="user_profiler_agent",
description="Extracts travel preferences and constraints from user input.",
instruction="""
Extract destination, duration (default 1 day), budget, interests, and exclusions.
Return a single JSON object with keys: "destination", "duration", "budget", "interests", "exclusions".
""",
output_key="user_preferences", # Saves output to state['user_preferences']
)
# --- Specialist 2: The Synthesizer ---
itinerary_synthesizer_agent = Agent(
name="itinerary_synthesizer_agent",
description="Compiles preferences and research into a final Markdown itinerary.",
instruction="""
You are an elite Travel Concierge. Write a Markdown itinerary with an itemized USD and local currency cost breakdown using:
- User Preferences: {user_preferences}
- Activities (if available): {activity_recommendations?}
- Restaurants (if available): {restaurant_recommendations?}
""",
output_key="final_itinerary",
)
سیم‌کشی خط لوله متوالی (workflows.py)
فایل جدیدی با نام workflows.py در travel_planner/ ایجاد کنید تا متخصصان را هماهنگ کنید:
cloudshell edit ~/adk-agents/travel_planner/workflows.py
این تعریف SequentialAgent به travel_planner/workflows.py اضافه شود:
from google.adk.agents import SequentialAgent
from .specialists import (
user_profiler_agent,
itinerary_synthesizer_agent,
)
# 1. SEQUENTIAL PHASE: A linear two-step workflow
master_travel_agent = SequentialAgent(
name="master_travel_agent",
description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
sub_agents=[
user_profiler_agent, # Step 1: Extract constraints into user_preferences
itinerary_synthesizer_agent, # Step 2: Draft itinerary from user_preferences
],
)
متصل کردن گردش کار به root_agent (agent.py)
اکنون master_travel_agent را به‌عنوان نماینده فرعی root_agent ثبت کنید. باز کردن travel_planner/agent.py:
cloudshell edit ~/adk-agents/travel_planner/agent.py
محتویات travel_planner/agent.py را با کد زیر جایگزین کنید:
from google.adk import Agent
from .workflows import master_travel_agent
MODEL = "gemini-3.8-flash"
root_agent = Agent(
model=MODEL,
name="root_agent",
description="A helpful assistant for user questions.",
instruction=(
"Greet the user and delegate any travel or trip planning requests "
"to master_travel_agent."
),
sub_agents=[master_travel_agent],
)
🔍 بررسی کردن کارتان
رابط کاربری وب ADK را از پایانه خود شروع کنید:
cd ~/adk-agents
adk web --allow_origins "*"
«پیش‌نمایش وب» را در درگاه 8000 باز کنید و پیام‌واره را وارد کنید:
Help me plan a trip to Kyoto
باید بروندادی مشابه با جریان اجرای زیر در نمای رویدادها ببینید:
1. root_agent -> calls transfer_to_agent(agent_name="master_travel_agent")
2. user_profiler_agent -> outputs JSON {"destination": "Kyoto", "duration": "1 day", ...} to state['user_preferences']
3. itinerary_synthesizer_agent -> reads {user_preferences} and outputs the formatted Markdown itinerary
روی هر نشان رویداد (یا تراشه State: final_itinerary) کلیک کنید و به برگه وضعیت در پانل بازرس سمت راست بروید تا مطمئن شوید که user_preferences و final_itinerary هر دو در وضعیت جلسه پر شده‌اند.
وقتی بازرسی ردیابی تمام شد، Ctrl + C را در پایانه فشار دهید تا adk web متوقف شود.
۷. اجرای پژوهش با ParallelAgent
اگرچه گردش کار متوالی به‌طور واضح استخراج اولویت‌ها را از پیش‌نویس برنامه سفر جدا می‌کند، توصیه‌های آن همچنان صرفاً به دانش آموزشی ایستا مدل متکی است. می‌توانید با افزودن دو پژوهشگر اختصاصی که از ابزار داخلی google_search بهره می‌برند، برنامه سفر را براساس داده‌های زنده وب پایه‌ریزی کنید:
activity_finder_agent: سه جاذبه خاص را که با مقصد و علایق کاربر مطابقت دارد، به‌همراه قیمت تخمینی بلیت پیدا می‌کند.-
restaurant_finder_agent: ۳ رستوران محلی با رتبه‌بندی بالا و هزینه تخمینی برای هر نفر را پیدا می‌کند.
چون تحقیق درباره جاذبه‌ها و تحقیق درباره رستوران‌ها به یکدیگر وابسته نیستند، اجرای آن‌ها یکی پس‌از دیگری باعث اتلاف وقت می‌شود. درعوض، هر دو پژوهشگر را در یک ParallelAgent (parallel_research_agent) قرار می‌دهید تا ADK هر دو گردش کار «جستجوی Google» را به‌طور هم‌زمان اجرا کند و {activity_recommendations?} و {restaurant_recommendations?} را قبل‌از واگذاری به itinerary_synthesizer_agent پر کند.
افزودن متخصصان پژوهش موازی به specialists.py
باز کردن travel_planner/specialists.py:
cloudshell edit ~/adk-agents/travel_planner/specialists.py
دو متخصص «جستجوی Google» زیر را به پایین travel_planner/specialists.py (درست زیر itinerary_synthesizer_agent) اضافه کنید:
# --- Specialist 3: The Activity Finder ---
activity_finder_agent = Agent(
name="activity_finder_agent",
description="Finds 3 attractions matching the user's destination and interests.",
instruction="""
Based on {user_preferences}, use google_search to find 3 specific attractions (including budget-friendly options).
Return a JSON list with keys: "attraction_name", "estimated_cost_local", "estimated_cost_usd", "notes".
""",
tools=[google_search],
output_key="activity_recommendations",
)
# --- Specialist 4: The Restaurant Finder ---
restaurant_finder_agent = Agent(
name="restaurant_finder_agent",
description="Finds 3 restaurants matching the destination and budget.",
instruction="""
Based on {user_preferences}, use google_search to find 3 highly-rated restaurants across price points.
Return a JSON list with keys: "restaurant_name", "cuisine", "estimated_cost_local", "estimated_cost_usd".
""",
tools=[google_search],
output_key="restaurant_recommendations",
)
ParallelAgent را در workflows.py درج کن
باز کردن travel_planner/workflows.py:
cloudshell edit ~/adk-agents/travel_planner/workflows.py
travel_planner/workflows.py را به‌روز کنید تا parallel_research_agent را بااستفاده از ParallelAgent تعریف کنید و آن را بین user_profiler_agent و itinerary_synthesizer_agent قرار دهید:
from google.adk.agents import ParallelAgent, SequentialAgent
from .specialists import (
activity_finder_agent,
itinerary_synthesizer_agent,
restaurant_finder_agent,
user_profiler_agent,
)
# Parallel branch: Run activity and restaurant research simultaneously
parallel_research_agent = ParallelAgent(
name="parallel_research_agent",
description="Runs activity and restaurant research concurrently.",
sub_agents=[
activity_finder_agent,
restaurant_finder_agent,
],
)
# Master pipeline: Profile -> Parallel Research -> Synthesize
master_travel_agent = SequentialAgent(
name="master_travel_agent",
description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
sub_agents=[
user_profiler_agent, # Step 1: Extract constraints
parallel_research_agent, # Step 2: Research activities & restaurants in parallel
itinerary_synthesizer_agent, # Step 3: Synthesize into an itinerary
],
)
🔍 بررسی کردن کارتان
adk web را دوباره راه‌اندازی کنید تا خط لوله پژوهش موازی را آزمایش کنید:
cd ~/adk-agents
adk web --allow_origins "*"
در میانای کاربری «پیش‌نمایش وب»، پیام‌واره زیر را ارسال کنید:
Help me plan a trip to Kyoto focused on historic temples and ramen
باید خروجی مشابه با توالی زیر را در نمای رویدادها ببینید:
1. user_profiler_agent -> writes state['user_preferences'] 2. parallel_research_agent -> fans out concurrently: - activity_finder_agent invokes google_search -> writes state['activity_recommendations'] - restaurant_finder_agent invokes google_search -> writes state['restaurant_recommendations'] 3. itinerary_synthesizer_agent -> merges all three state keys into state['final_itinerary']
- نمای ردگیری‌ها: روی ردگیری‌ها در بالای قاب مکالمه (کنار رویدادها) کلیک کنید و نوبت خود را بررسی کنید. بازه زمانی هم‌پوشانی‌شده‌ای را برای
activity_finder_agentوrestaurant_finder_agentدرparallel_research_agentخواهید دید که تأخیر کل پژوهش وب را درمقایسه با اجرای متوالی آن‌ها تقریباً به نصف کاهش می‌دهد. - برگه State (وضعیت): روی برگه State (وضعیت) در پانل بازرس سمت راست کلیک کنید تا واژه‌نامه جلسه زنده (
user_preferences،activity_recommendations،restaurant_recommendations، وfinal_itinerary) را بازرسی کنید.
وقتی آزمایش تمام شد، Ctrl + C را در پایانه فشار دهید تا adk web متوقف شود.
۸. پالایش کردن پیش‌نویس‌ها با LoopAgent
حتی با نتایج جستجوی زنده، پیش‌نویس اولیه‌ای که itinerary_synthesizer_agent تولید می‌کند ممکن است از کل بودجه کاربر فراتر رود یا به‌طور تصادفی شامل دسته‌ای شود که کاربر آن را مستثنی کرده است (مثلاً گالری هنر مدرن، درحالی‌که کاربر خواسته است چنین گالری‌ای در نتایج نباشد).
برای تضمین رعایت محدودیت، بااستفاده از LoopAgent یک حلقه پالایش سازنده-بررسی‌کننده به انتهای خط لوله اضافه خواهید کرد:
-
itinerary_critic_agent(بررسی‌کننده):{final_itinerary}را درمقابل{user_preferences}ممیزی می‌کند. این عامل هزینه‌های تخمینی را جمع می‌زند، هر محدودیت منفی را بررسی می‌کند، و یا دستورالعمل‌های بازبینی خاصی را برایcritique_feedbackمی‌نویسد یا با عبارت دقیق"APPROVED"پاسخ می‌دهد. itinerary_refiner_agent(سازنده / خارج‌شونده):{critique_feedback}را می‌خواند. اگر نقد برابر با"APPROVED"باشد، ابزارexit_loop(tool_context.actions.escalate = True) را فراخوانی می‌کند تا فوراً ازLoopAgentخارج شود. درغیراین‌صورت،{final_itinerary}را برای رفع مشکلات پرچم‌گذاری‌شده بازبینی می‌کند وfinal_itineraryرا برای مرحله بعدی بازنویسی می‌کند.
افزودن exit_loop، «منتقد»، و «پالایشگر» به specialists.py
باز کردن travel_planner/specialists.py:
cloudshell edit ~/adk-agents/travel_planner/specialists.py
ابزار exit_loop (ToolContext)، itinerary_critic_agent، و itinerary_refiner_agent را به پایین travel_planner/specialists.py اضافه کنید:
def exit_loop(tool_context: ToolContext) -> dict:
"""Call ONLY when the critique is APPROVED to exit the refinement loop."""
print(f"[Tool Call] exit_loop triggered by {tool_context.agent_name}")
tool_context.actions.escalate = True
return {"status": "approved", "message": "Itinerary approved. Exiting refinement loop."}
# --- Specialist 5: The Budget & Constraint Critic (Inside LoopAgent) ---
itinerary_critic_agent = Agent(
name="itinerary_critic_agent",
include_contents="none",
description="Audits the itinerary draft against budget and negative constraints.",
instruction="""
Audit Current Itinerary ({final_itinerary}) against User Preferences ({user_preferences}).
Verify that the USD total stays within the user's budget and no excluded venue types appear.
If all checks pass, respond EXACTLY with the single word "APPROVED".
Otherwise, output 1-2 concise revision instructions explaining what to swap or adjust.
""",
output_key="critique_feedback",
)
# --- Specialist 6: The Itinerary Refiner / Exiter (Inside LoopAgent) ---
itinerary_refiner_agent = Agent(
name="itinerary_refiner_agent",
include_contents="none",
description="Refines the itinerary from critique feedback, or calls exit_loop when APPROVED.",
instruction="""
Review Auditor Critique ({critique_feedback}) for Current Itinerary ({final_itinerary}).
If the critique is EXACTLY "APPROVED", call `exit_loop` immediately and return the itinerary unchanged.
Otherwise, revise the draft using {activity_recommendations} and {restaurant_recommendations}
so all USD budget and exclusion rules pass, and output ONLY the updated Markdown itinerary.
""",
tools=[exit_loop],
output_key="final_itinerary",
)
افزودن LoopAgent به workflows.py
باز کردن travel_planner/workflows.py:
cloudshell edit ~/adk-agents/travel_planner/workflows.py
travel_planner/workflows.py را به‌روز کنید تا itinerary_critic_agent و itinerary_refiner_agent را در LoopAgent (max_iterations=3) قرار دهد و آن را به‌عنوان مرحله چهارم master_travel_agent اضافه کند:
from google.adk.agents import LoopAgent, ParallelAgent, SequentialAgent
from .specialists import (
activity_finder_agent,
itinerary_critic_agent,
itinerary_refiner_agent,
itinerary_synthesizer_agent,
restaurant_finder_agent,
user_profiler_agent,
)
# Stage 2: Parallel research branch
parallel_research_agent = ParallelAgent(
name="parallel_research_agent",
description="Runs activity and restaurant research concurrently.",
sub_agents=[
activity_finder_agent,
restaurant_finder_agent,
],
)
# Stage 4: Iterative Maker-Checker refinement loop
refinement_loop_agent = LoopAgent(
name="refinement_loop_agent",
description="Iteratively audits and refines the itinerary until constraints and budget are approved.",
sub_agents=[
itinerary_critic_agent,
itinerary_refiner_agent,
],
max_iterations=3,
)
# Master pipeline: Profile -> Parallel Research -> Synthesize -> Refinement Loop
master_travel_agent = SequentialAgent(
name="master_travel_agent",
description="Orchestrates the end-to-end travel planning process for trip and itinerary requests.",
sub_agents=[
user_profiler_agent, # Stage 1: Extract constraints
parallel_research_agent, # Stage 2: Research activities & restaurants in parallel
itinerary_synthesizer_agent, # Stage 3: Draft initial itinerary
refinement_loop_agent, # Stage 4: Audit and refine until approved
],
)
🔍 بررسی کردن کارتان
برای آزمایش گردش کار کامل چندعاملی، adk web را شروع کنید:
cd ~/adk-agents
adk web --allow_origins "*"
رابط کاربری «پیش‌نمایش وب» را در درگاه 8000 باز کنید، جلسه جدیدی شروع کنید، و کل سیستم را با این پیام‌واره چندمحدودیتی کیوتو آزمایش کنید:
Design a full-day itinerary for Kyoto with a total budget of $100. My main interests are historical landmarks, temples, and authentic local cuisine. Please do not include any modern art museums or galleries.
باید خروجی مشابه با توالی اجرای زیر را در نمای رویدادها و گزارش‌های پایانه ببینید:
1. user_profiler_agent -> writes JSON with destination="Kyoto", budget="$100", exclusions=["modern art museums", "galleries"] 2. parallel_research_agent -> runs activity_finder_agent and restaurant_finder_agent in parallel 3. itinerary_synthesizer_agent -> produces initial draft in state['final_itinerary'] 4. refinement_loop_agent: - itinerary_critic_agent -> audits USD budget and exclusions -> outputs "APPROVED" (or revision notes) - itinerary_refiner_agent -> triggers [Tool Call] exit_loop triggered by itinerary_refiner_agent and outputs the approved itinerary
- نمای رویدادها: روی هر تراشه رویداد از
itinerary_critic_agentیاitinerary_refiner_agentکلیک کنید تا بار مفید آن را در برگه اطلاعات سمت راست بررسی کنید. وقتیitinerary_refiner_agentexit_loopرا فراخوانی می‌کند، رویداد را بررسی کنید تاactions.escalate: trueرا ببینید - سیگنالی که بهLoopAgentمی‌گوید قبل‌از رسیدن بهmax_iterations=3تکرار را متوقف کند. - زبانه State (وضعیت): روی زبانه State (وضعیت) کلیک کنید تا
state['critique_feedback']وstate['final_itinerary']را در مجوزها تماشا کنید. اگر پیش‌نویس اولیه از$100 USDفراتر رفت،critique_feedbackدستورالعمل‌های بازبینی حسابرس را در مرحله ۱ نگه می‌دارد، سپسfinal_itineraryبا گزینه‌های کم‌هزینه‌تر به‌روزرسانی می‌شود وcritique_feedbackدر مرحله ۲ به"APPROVED"تغییر می‌کند.
وقتی آزمایش تمام شد، Ctrl + C را در پایانه فشار دهید تا adk web متوقف شود.
۹. مرتب‌سازی
حذف کردن فایل‌های پروژه محلی
برای برداشتن دایرکتوری پروژه adk-agents و محیط مجازی از پوشه اصلی Cloud Shell، این دستور را اجرا کنید:
cd ~
rm -rf ~/adk-agents
غیرفعال کردن Agent Platform API
اگر دیگر به Agent Platform API فعال‌شده در پروژه‌تان نیاز ندارید، آن را با gcloud غیرفعال کنید:
gcloud services disable aiplatform.googleapis.com --quiet
حذف کل پروژه Google Cloud (اختیاری)
PROJECT_ID=$(gcloud config get-value project)
gcloud projects delete "$PROJECT_ID" --quiet
🔍 بررسی کردن کارتان
تأیید کنید که ~/adk-agents برداشته شده است:
test ! -d ~/adk-agents && echo "Workspace ~/adk-agents removed"
باید بروندادی مشابه زیر ببینید:
Workspace ~/adk-agents removed
۱۰. تبریک می‌گوییم
تبریک! شما یک سیستم چندعاملی سلسله‌مراتبی با Google Agent Development Kit (ADK) ساخته‌اید که تیمی متشکل از شش عامل تخصصی را در گردش‌های کاری متوالی، موازی، و حلقه‌ای تکرارشونده هماهنگ می‌کند.
آنچه انجام داده‌اید
- ارتباط ساختاریافته بین‌عاملی ازطریق حالت جلسه مشترک (تزریق الگو
output_keyو{state_variable}) - ساخت خط لوله گام‌به‌گام قطعی بااستفاده از
SequentialAgent - اجرای هم‌زمان عامل‌های پژوهشی مستقل «جستجوی Google» بااستفاده از
ParallelAgent - حلقه درستی‌سنجی سازنده-بررسی‌کننده خودکارشده را بااستفاده از
LoopAgentوtool_context.actions.escalate = Trueپیاده‌سازی کرد
مراحل بعدی
- برای بازسازی این برنامه‌ریز سفر با
Workflow،JoinNode، و چرخه‌های قطعیEvent(route=...)یکپارچه ADK 2، به بخش ۴ از این مجموعه، ساختن عامل‌های هوش مصنوعی با ADK: هماهنگ‌سازی گردش کارهای Graph، بروید - اسناد رسمی ADK Workflow Agents را بخوانید
- کاوش سیستم‌های چندعاملی در ADK
- برای شرکت در کارگاه‌های عملی و مسیرهای یادگیری، به برنامه GEAR (Gemini Enterprise Agent Ready) و برنامه Get Certified بپیوندید