الگوی عامل ADK با حافظه & MCP

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

به کلاس کارشناسی ارشد ADK خوش آمدید - سفری به درون سیستم‌های چندعاملی

You're about to step into the exciting world of AI agents. Forget simple chatbots that just answer questions. We're diving deep into the Agent Development Kit (ADK) to build sophisticated, autonomous systems that can reason, plan, and use tools to accomplish complex tasks.

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

در پایان این آموزش، شما قادر خواهید بود:

• اولین عامل هوش مصنوعی خود را بسازید : از صفر به یک عامل کاملاً کاربردی تبدیل شوید که می‌تواند نیازهای کاربر را درک کند، از ابزارهایی مانند جستجوی گوگل استفاده کند و پاسخ‌های دقیق و مفیدی تولید کند.
• Construct Multi-Agent Systems : Learn the "Agent-as-a-Tool" pattern, a revolutionary concept where agents delegate tasks to other specialized agents, creating a team of AI experts that work together.
• Orchestrate Complex Workflows : Go beyond simple delegation and master advanced patterns like Routers , Sequential Chains , Loops , and Parallel Execution to build robust, efficient, and intelligent applications that can handle almost any requests.
• Give Your Agents Memory : Understand the critical role of conversational memory, enabling your agents to handle follow-up questions, learn from feedback, and manage multi-step tasks seamlessly.
• اتصال با MCP : با جعبه ابزار MCP متصل شوید.

بیایید شروع کنیم! 🚀

۲. تنظیمات: دریافت کلید API

تنظیم کلید API گوگل AI Studio

This codelab runs entirely on a free Google AI Studio API key. No Google Cloud project, billing account, or credits are required — every session, including Memory (Session 6) and MCP (Session 7), runs locally against your key. Each learner uses their own key, so API quota is per-person, not shared.

آنچه نیاز دارید:

• پایتون ۳.۹ یا بالاتر ( python3 --version برای بررسی)
• یک حساب گوگل (برای ایجاد کلید AI Studio)
• یک ترمینال - دستگاه محلی شما یا Cloud Shell هر دو کار می‌کنند
• حدود ۱۰ دقیقه

برای فعال کردن عامل‌های هوش مصنوعی خود، به یک کلید API Gemini از Google AI Studio نیاز داریم. این سریع‌ترین راه برای شروع است.

مرحله ۱ - کلید API Gemini خود را از AI Studio دریافت کنید (۱ دقیقه)

1. آدرس https://aistudio.google.com/app/apikey را در یک تب جدید مرورگر باز کنید.
2. با حساب گوگل خود وارد شوید.
3. روی «ایجاد کلید API» (بالا سمت راست) کلیک کنید.
4. یک کادر محاوره‌ای با منوی کشویی پروژه باز می‌شود:

• اگر قبلاً یک پروژه گوگل ایجاد کرده‌اید: آن را انتخاب کنید و روی «ایجاد کلید API در پروژه موجود» کلیک کنید.
• اگر در لیست نبود: روی «ایجاد پروژه» کلیک کنید.

5. کلید API نمایش داده شده را کپی کنید . با AIza... شروع می‌شود و حدود ۴۰ کاراکتر دارد.

✏️ آن را در جایی امن پیست کنید - در مرحله ۴ زیر به آن نیاز خواهید داشت.

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

مرحله ۲ - کپی کردن مخزن (۱ دقیقه)

👉💻 ترمینال (یا Cloud Shell) خود را باز کنید و مخزن آموزشی را کپی کنید:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

مرحله ۳ - ایجاد محیط مجازی و نصب متعلقات

👉💻 یک محیط مجازی با نام .adk_env ایجاد و فعال کنید، سپس وابستگی‌ها را نصب کنید:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

شما باید (.adk_env) را در ابتدای اعلان ترمینال خود ببینید.

مرحله ۴ - 🔥 مهم: کلید API خود را اضافه کنید

⚠️ Don't skip this step! Create a .env file in the root of the adk_tutorial folder. This one file powers every session in this codelab — the ADK Web sessions (1–5) and the command-line Memory and MCP sessions (6–7) all read it automatically.

👉💻 فایل .env را با کلید خود ایجاد کنید (به جای your_actual_api_key_here ، کلید مرحله ۱ را قرار دهید):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

~/adk_tutorial/.env شما اکنون باید شامل موارد زیر باشد:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 نکته مهم : your_actual_api_key_here را با کلید API واقعی خود از مرحله ۱ جایگزین کنید (با AIza... شروع می‌شود).

⚠️ مطمئن شوید که GOOGLE_GENAI_USE_VERTEXAI روی FALSE تنظیم شده است. این به ADK می‌گوید که به جای Vertex AI، با کلید API Google AI Studio شما احراز هویت کند.

✅ نقطه بررسی: شما یک فایل .env در ~/adk_tutorial/.env دارید که حاوی کلید AIza... شماست، و اعلان ترمینال شما (.adk_env) را نشان می‌دهد. شما آماده ساخت عامل‌ها هستید!

۳. جلسه ۱: اولین نماینده شما در ADK Web

باز کردن ADK Web با اجرای دستور زیر:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

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

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 سپس، مرورگر خود را باز کنید و آدرس http://localhost:8000 را وارد کنید تا به رابط کاربری ADK Dev دسترسی پیدا کنید.

Running in Cloud Shell instead of locally? Click the Web preview icon in the Cloud Shell toolbar (usually top right), select Change port , set the port to 8000 , and click "Change and Preview" . Cloud Shell will open the ADK Dev UI in a new browser tab.

👉 مراسم احضار شما کامل شده است و اکنون عامل در حال اجرا است. رابط کاربری ADK Dev در مرورگر شما، ارتباط مستقیم شما با Familiar است.

اولین عامل خود را انتخاب کنید. در منوی کشویی بالای رابط کاربری، گزینه a_single_agent را انتخاب کنید.

شما می‌توانید a_single_agent اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

👉 دستور آزمایش:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

۴. جلسه ۲: عامل گردش کار: عامل ترتیبی، عامل موازی، عامل حلقه‌ای

رابط کاربری وب ADK خود را مطابق مراحل جلسه اول باز کنید.

عامل موازی

عامل گردش کار موازی را انتخاب کنید. در منوی کشویی بالای رابط کاربری، b2_parallel_agent را انتخاب کنید.

👉 دستور آزمایش:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

می‌توانید b2_parallel_agent اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

عامل ترتیبی

عامل گردش کار ترتیبی را انتخاب کنید. در منوی کشویی بالای رابط کاربری، b1_sequential_agent را انتخاب کنید.

👉 دستور آزمایش:

Find a good sushi near Standford and tell me how to get there.

می‌توانید b1_sequential_agent اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

عامل حلقه

عامل گردش کار حلقه را انتخاب کنید. در منوی کشویی بالای رابط کاربری، b3_loop_agent را انتخاب کنید.

👉 دستور آزمایش:

Plan a trip from Sunnyvale to San Francisco today.

می‌توانید b3_loop_agent اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

۵. جلسه ۳: عامل سفارشی

رابط کاربری وب ADK خود را مطابق مراحل جلسه اول باز کنید.

پس از باز شدن رابط کاربری وب ADK، از منوی کشویی c_custom_agent را انتخاب کنید.

👉 دستور آزمایش:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

می‌توانید c_custom_agent اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

۶. جلسه ۴: الگوی هماهنگ‌کننده - عامل مسیریابی

رابط کاربری وب ADK خود را مطابق مراحل جلسه اول باز کنید.

پس از باز شدن رابط کاربری وب ADK، از منوی کشویی d_routing_agent را انتخاب کنید.

👉 دستور آزمایش:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

می‌توانید d_routing_agent اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

۷. جلسه ۵: عامل به عنوان ابزار

رابط کاربری وب ADK خود را مطابق مراحل جلسه اول باز کنید.

پس از باز شدن رابط کاربری وب ADK، از منوی کشویی، e_agent_as_tool را انتخاب کنید.

👉 دستور آزمایش:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

شما می‌توانید e_agent_as_tool اینجا انتخاب کنید:

می‌توانید ردیابی را اینجا ببینید:

۸. جلسه ۶: عامل با حافظه بلندمدت

Runs fully locally. This session stores conversation memory in a local SQLite database (under ~/.adk/ ), so your preferences persist across restarts with no Google Cloud, billing, or credits required. The agent reads your AI Studio key from the ~/adk_tutorial/.env you created in Setup.

👉💻 با رفتن به پوشه و استفاده از runner برای روشن کردن عامل، حافظه بلند مدت خود را آزمایش کنید:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 دستور آزمایش:

I like Art and Italian food.

سپس با فشردن کلیدهای Ctrl+C جلسه را خاتمه دهید. جلسه را مجدداً راه‌اندازی کنید:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 دستور آزمایش:

Plan a trip to San Francisco based on my preference.

✅ نماینده باید «هنر و غذای ایتالیایی» را از اجرای قبلی به خاطر بیاورد - این حافظه بلندمدت است که در طول جلسات کار می‌کند.

۹. جلسه ۷: با MCP به نماینده خود قدرت دهید

Runs fully locally. This session starts a local MCP Toolbox server that reads a local SQLite database ( destinations.db ) — no Google Cloud, billing, or credits required. The only external download is the open-source MCP Toolbox binary.

مرحله ۱: آماده‌سازی پایگاه داده محلی

👉💻 از ریشه مخزن، پایگاه داده نمونه را ایجاد کنید:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

این destinations.db را در ~/adk_tutorial/ ایجاد می‌کند.

⚠️ The sample database only contains four cities — Paris, Rome, New York, and Tokyo (attraction types: Landmark, Museum, Park). Prompts that reference other cities (eg San Francisco or Sunnyvale) will correctly return no results , because those rows don't exist. Use the four cities above when testing this session.

مرحله 2: نصب و اجرای سرور جعبه ابزار MCP

👉💻 فایل باینری MCP Toolbox را برای سیستم عامل خود دانلود کنید:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

پس از اتمام دانلود، و سپس اجرا کنید

chmod +x toolbox

مطمئن نیستید از کدام مک استفاده می‌کنید؟ uname -m — arm64 = ​​Apple Silicon, x86_64 = Intel را اجرا کنید. در ویندوز ، .../windows/amd64/toolbox.exe را دانلود کنید و آن را از PowerShell اجرا کنید.

مرحله ۳

در یک ترمینال، دستور زیر را اجرا کنید (دستور را در حال اجرا بگذارید - عامل از طریق http://127.0.0.1:7001 به آن متصل می‌شود):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

در یک ترمینال دیگر دستور زیر را اجرا کنید

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 دستورالعمل‌های آزمایشی (از شهرهای موجود در پایگاه داده نمونه استفاده کنید - پاریس، رم، نیویورک یا توکیو):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

جلسه هفتم - رفع اشکال

• «اتصال رد شد» / عامل هیچ ابزاری پیدا نمی‌کند: سرور Toolbox در ترمینال اول در حال اجرا نیست - آن را مجدداً راه‌اندازی کنید و تأیید کنید که به پورت 7001 گوش می‌دهد.
• هر پرس‌وجو نتایج خالی برمی‌گرداند: تأیید کنید که مرحله ۱ را اجرا کرده‌اید، بنابراین ~/adk_tutorial/destinations.db وجود دارد و اعلان شما از یکی از چهار شهر (پاریس، رم، نیویورک، توکیو) استفاده می‌کند.
• toolbox: cannot execute binary file در macOS اجرا کند: شما نسخه لینوکس را دانلود کرده‌اید - مرحله ۲ را با OS=darwin/arm64 (سیگنال اپل) یا OS=darwin/amd64 (سیگنال اینتل) دوباره اجرا کنید.