۱. مقدمه
در این آزمایشگاه کد، شما اولین عامل هوش مصنوعی خود را گام به گام با استفاده از کیت توسعه عامل گوگل (ADK) و Gemini خواهید ساخت. شما یک عامل وبلاگنویسی پایه ایجاد خواهید کرد که محتوا را برنامهریزی و مینویسد و مفاهیم اصلی استدلال و عمل را به نمایش میگذارد.
کاری که انجام خواهید داد
- محیط توسعه خود را برای ADK تنظیم کنید.
- یک سیستم چندعامله با یک برنامهریز و یک نویسنده ایجاد کنید.
- عامل را به صورت محلی اجرا کنید و از طریق رابط کاربری وب ADK با آن تعامل داشته باشید.
آنچه نیاز دارید
- یک مرورگر وب مانند کروم .
- پایتون ۳.۱۰ یا بالاتر روی دستگاه شما نصب باشد.
- یک کلید API گوگل هوش مصنوعی استودیو.
این آزمایشگاه کد برای توسعهدهندگان در تمام سطوح، از جمله مبتدیان، مناسب است.
مدت زمان تخمینی: ۳۰ دقیقه.
۲. راهنمای تصویری: عاملهای هوش مصنوعی چه هستند؟
قبل از شروع به ساخت، بیایید به سرعت بفهمیم که عاملهای هوش مصنوعی چیستند و از چه الگوهای رایجی پیروی میکنند.
عامل هوش مصنوعی چیست؟
در سادهترین سطح، یک عامل نرمافزاری است که فقط پاسخ نمیدهد - میتواند تصمیم بگیرد و اقدام کند. به جای تولید یک پاسخ واحد مانند یک چتبات سنتی، به درخواست شما نگاه میکند، مراحلی را که باید انجام شود تشخیص میدهد، شاید یک API را فراخوانی کند، کد را اجرا کند، نتیجه را بررسی کند و سپس تصمیم بگیرد که در مرحله بعد چه کاری انجام دهد.
یکی از واضحترین توضیحات از مقاله تحقیقاتی ReAct: Synergizing Reasoning and Acting in Language Models گرفته شده است. ایده این مقاله ساده اما قدرتمند بود: مدلهای زبانی نباید فقط متن را به صورت یکجا تولید کنند. آنها در واقع میتوانند گام به گام استدلال کنند، اقدامی مانند فراخوانی یک ابزار یا API انجام دهند، نتیجه را مشاهده کنند و سپس تصمیم بگیرند که در مرحله بعد چه کاری انجام دهند.
این چرخه استدلال، عمل، مشاهده و تنظیم، اساس نحوه کار عاملهای هوش مصنوعی مدرن است و با تعریف گوگل کلود از آنها مطابقت دارد: سیستمهایی با استدلال، برنامهریزی و حافظه، با استقلال کافی برای سازگاری و تصمیمگیری از طرف کاربر.
سه الگوی رفتاری عامل
همه عاملها به یک شکل رفتار نمیکنند. یک راه مفید برای بررسی آنها، در نظر گرفتن سه الگوی کلی است:
- عوامل ترتیبی : این عوامل مانند یک خط مونتاژ گام به گام اجرا میشوند: مرحله ۱، سپس مرحله ۲، سپس مرحله ۳. آنها قابل پیشبینی هستند، اما انعطافناپذیرند.
- عوامل واکنشی : این عوامل در لحظه تصمیم میگیرند. آنها به وضعیت فعلی نگاه میکنند و میپرسند: «بعداً چه کاری باید انجام دهم؟» شاید یک بار از ابزار الف و بار دیگر از ابزار ب استفاده کنند. آنها انعطافپذیر هستند، اما از قبل برنامهریزی نمیکنند.
- عوامل مشورتی یا برنامهریزی : این عوامل مکث میکنند تا طرحی را ترسیم کنند، سپس آن را اجرا میکنند. به رزرو سفر فکر کنید - شما فقط یک پرواز را به صورت تصادفی خریداری نمیکنید، تاریخها، هتلها را انتخاب میکنید، مراحل را سفارش میدهید و سپس آن را دنبال میکنید.
کدام یک از اینها «درست» است؟ بستگی به مشکل دارد. برای جریانهای ساده و قابل پیشبینی، ترتیبی خوب است. برای وظایف پویا، واکنشی بهتر عمل میکند. برای اهداف چند مرحلهای با وابستگیها، به عوامل برنامهریزی نیاز دارید.
در این آزمایشگاه، ما در حال ساخت یک عامل مشورتی/برنامهریز هستیم که ابتدا یک طرح کلی ایجاد میکند و سپس پست وبلاگ را مینویسد!
۳. قبل از شروع
ایجاد یک حساب کاربری و پروژه گوگل کلود
برای استقرار عامل خود در Google Cloud Run در ادامه این آزمایش، به یک حساب Google Cloud و یک پروژه با قابلیت پرداخت فعال نیاز دارید.
- وارد کنسول گوگل کلود شوید. یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید. اگر از قبل حساب گوگل ندارید، باید یکی ایجاد کنید .
- در مرحله بعد، برای استفاده از منابع ابری، باید امکان پرداخت صورتحساب را در کنسول ابری فعال کنید. استفاده از این codelab باید کمتر از چند سنت هزینه داشته باشد. کاربران جدید گوگل کلود همچنین ممکن است واجد شرایط برنامه آزمایشی رایگان ۳۰۰ دلاری باشند.
- شناسه پروژه خود (یک نام منحصر به فرد در تمام پروژههای Google Cloud) را یادداشت کنید. برای پیکربندی و استقرار عامل به آن نیاز خواهید داشت.
دریافت کلید API گوگل هوش مصنوعی استودیو
برای استفاده از مدلهای Gemini، به یک کلید API از Google AI Studio نیاز دارید.
- به استودیوی هوش مصنوعی گوگل بروید.
- روی دریافت کلید API کلیک کنید.
- یک کلید جدید ایجاد کنید یا از یک کلید موجود استفاده کنید. کلید را برای استفاده بعدی کپی کنید.
۴. ساختار پروژه نماینده نویسنده وبلاگ را ایجاد کنید
در این مرحله، دایرکتوری و فایلهایی را برای قرار دادن کد عامل وبلاگنویسی خود در دستگاه محلی خود تنظیم خواهید کرد.
۱. فضای کاری مدیر وبلاگنویسی را ایجاد کنید
ترمینال خود را باز کنید و دستورات زیر را اجرا کنید تا یک دایرکتوری اختصاصی برای نماینده وبلاگ نویس خود ایجاد کنید و به آن بروید:
mkdir bloggeragent
cd bloggeragent
۲. فایلهای عامل را مقداردهی اولیه کنید
چارچوب Google ADK گردشهای کاری agent را مستقیماً از دایرکتوری پروژه شما بارگذاری میکند. فایلهای لازم را مستقیماً در ریشه bloggeragent ایجاد کنید:
touch requirements.txt .env __init__.py agent.py
۵. نصب وابستگیها و محیط راهاندازی
در این مرحله، یک محیط مجازی پایتون راهاندازی میکنید، چارچوب Google ADK را نصب میکنید و متغیرهای محیط را برای تأیید اعتبار عامل وبلاگ خود با مدل Gemini پیکربندی میکنید.
۱. پیکربندی الزامات عامل
فایل requirements.txt را در دایرکتوری bloggeragent باز کنید و بستههای مورد نیاز برای عامل نویسندگی وبلاگ را با اضافه کردن موارد زیر به آن مشخص کنید:
google-adk==2.2.0
python-dotenv
۲. یک محیط مجازی برای عامل ایجاد کنید
از دایرکتوری bloggeragent ، یک محیط مجازی پایتون ایجاد و فعال کنید تا بستههای agent را ایزوله کنید:
python3 -m venv .venv
source .venv/bin/activate
۳. چارچوب ADK را نصب کنید
وابستگیهای تعریفشده در requirements.txt خود را نصب کنید تا فضای کاری محلی خود را به Google ADK مجهز کنید:
pip install -r requirements.txt
۴. پیکربندی اعتبارنامههای API عامل
فایل .env که در ریشه پروژه ایجاد کردهاید را باز کنید و کلید API Gemini خود را اضافه کنید:
GOOGLE_API_KEY=your_api_key
به جای your_api_key ، کلیدی که از Google AI Studio کپی کردهاید را قرار دهید.
۶. نویسنده وبلاگ چندعاملی بسازید
در این مرحله، گردش کار اصلی سیستم عامل وبلاگ نویسی خود را پیاده سازی خواهید کرد.
به جای یک چتبات ساده با یک دستور، شما یک سیستم پیچیده چندعاملی خواهید ساخت که از حلقههای خود-تصحیحکننده و تأیید طرح کلی برای نوشتن پستهای فنی با کیفیت بالا استفاده میکند. این از الگوی مشورتی/برنامهریزی که قبلاً در مورد آن صحبت کردیم، پیروی میکند.
نمای کلی معماری
نحوه تعامل کارشناسان متخصص در سیستم شما به شرح زیر است:
پیکربندی init.py
__init__.py را در ویرایشگر متن خود باز کنید و کد زیر را برای نمایش گردش کار عامل به اجراکننده، وارد کنید:
from . import agent
گردش کار نماینده نویسندگی وبلاگ را بنویسید
agent.py در ویرایشگر کد خود باز کنید و کد زیر را که Planner، Writer، Validation Checkers و عامل اصلی بلاگر را تعریف میکند، اضافه کنید:
import os
import sys
from pathlib import Path
import datetime
from dotenv import load_dotenv
from google.adk.agents import Agent, LoopAgent
from google.adk.tools import agent_tool
# env config
load_dotenv()
MODEL = os.getenv("MODEL", "gemini-flash-latest")
# Sub-Agent: Planner
blog_planner = Agent(
name="BlogPlanner",
model=MODEL,
description="Creates a practical, skimmable outline in Markdown.",
instruction="""
You are a technical content strategist. Produce a clear Markdown outline with:
- Title
- Short intro
- 4–6 main sections (each with 2–3 bullets)
- Conclusion
If `codebase_context` exists in state, weave in specific sections/snippets.
Return only the outline in Markdown.
""",
output_key="blog_outline",
)
class OutlineValidationChecker(Agent):
def __init__(self):
super().__init__(
name="OutlineValidationChecker",
model=MODEL,
description="Validates that the outline is usable.",
instruction="""
Check the outline in state `blog_outline`. If it has a title, intro, 4–6 sections, and a conclusion, respond exactly "ok".
Otherwise respond exactly "retry" and list missing pieces.
""",
output_key="validation_result",
)
robust_blog_planner = LoopAgent(
name="RobustBlogPlanner",
description="Retries planning if validation fails.",
sub_agents=[blog_planner, OutlineValidationChecker()],
max_iterations=3,
)
# Sub-Agent: Writer
blog_writer = Agent(
name="BlogWriter",
model=MODEL,
description="Writes a technical blog post from the outline.",
instruction="""
Write a complete Markdown article from the outline in `blog_outline`.
Guidelines:
- Audience: software engineers; skip basics and focus on practical insight.
- Explain both the 'how' and 'why'.
- Include concise code snippets when helpful.
- Follow the outline's structure (H2/H3).
- Output only the final article in Markdown (no fence around the whole post).
""",
output_key="blog_post",
)
class BlogPostValidationChecker(Agent):
def __init__(self):
super().__init__(
name="BlogPostValidationChecker",
model=MODEL,
description="Validates the final post.",
instruction="""
Check `blog_post` for: intro, clear sections matching the outline, conclusion, and technical clarity.
If passes, respond "ok". Else respond "retry" with the specific fixes.
""",
output_key="validation_result",
)
robust_blog_writer = LoopAgent(
name="RobustBlogWriter",
description="Retries writing if validation fails.",
sub_agents=[blog_writer, BlogPostValidationChecker()],
max_iterations=3,
)
# Expose planner/writer as tools so the root agent can call them explicitly
planner_tool = agent_tool.AgentTool(agent=robust_blog_planner)
writer_tool = agent_tool.AgentTool(agent=robust_blog_writer)
# Root Agent: Plan → Write
root_agent = Agent(
name="Blogger",
model=MODEL,
description="Minimal multi-agent blogger that plans and writes.",
instruction=f"""
If the user gives a topic:
1) Call the planner tool to generate the outline.
2) Call the writer tool to produce the full draft.
3) End with 3 alternate titles and 2 tweet-length hooks.
Date: {datetime.datetime.now().strftime("%Y-%m-%d")}
""",
tools=[
planner_tool, # calls RobustBlogPlanner
writer_tool, # calls RobustBlogWriter
],
)
درک معماری عامل
بیایید اجزای اصلی کدی را که به agent.py اضافه کردید، تجزیه کنیم تا بفهمیم که چگونه گردش کار برنامهریزی و نوشتن چندعاملی را پیادهسازی میکند:
۱. زیر-عامل BlogPlanner
عامل blog_planner مسئول برنامهریزی محتوا است. این عامل موضوع ارائه شده توسط کاربر را دریافت کرده و یک طرح کلی ساختاریافته در Markdown (شامل عنوان، مقدمه، ۴-۶ بخش و یک نتیجهگیری) تولید میکند. این طرح کلی در دیکشنری وضعیت مشترک تحت کلید "blog_outline" ذخیره میشود.
۲. بررسیکنندهی اعتبارسنجی رئوس مطالب
عامل OutlineValidationChecker به عنوان یک دروازه کیفیت عمل میکند. "blog_outline" تولید شده در حالت را بررسی میکند. اگر outline معتبر باشد، با "ok" پاسخ میدهد. در غیر این صورت، "retry" را به همراه لیستی از موارد از دست رفته برمیگرداند.
۳. حلقهی قدرتمند وبلاگپلنر
برای جلوگیری از تولید طرحهای نامناسب توسط عامل، برنامهریز و بررسیکننده اعتبارسنجی را درون یک LoopAgent به نام robust_blog_planner قرار میدهیم. اگر اعتبارسنجی با شکست مواجه شود و مقدار "retry" را برگرداند، حلقه به طور خودکار برنامهریز را دوباره، تا ۳ بار، اجرا میکند و قبل از رفتن به مرحله بعدی، از خود-اصلاحی اطمینان حاصل میکند.
۴. نماینده فرعی وبلاگنویس
پس از نهایی شدن طرح کلی، عامل blog_writer "blog_outline" را از حالت خوانده و مقاله فنی کامل را در Markdown تولید میکند، ساختار طرح کلی را مطابقت داده و آن را برای مهندسان نرمافزار تنظیم میکند.
۵. بررسی اعتبارسنجی پستهای وبلاگ و حلقه RobustBlogWriter
درست مانند طرح کلی، مقاله نهایی توسط BlogPostValidationChecker اعتبارسنجی میشود تا از وجود و وضوح تمام بخشهای کلیدی اطمینان حاصل شود. نویسنده و بررسیکننده در حلقه robust_blog_writer قرار دارند و در صورت یافتن مشکل توسط بررسیکننده، تا ۳ بار میتوانند خود را اصلاح کنند.
۶. نمایش حلقهها به عنوان ابزار
ما حلقه برنامهریز ( robust_blog_planner ) و حلقه نویسنده ( robust_blog_writer ) را با استفاده از AgentTool به عنوان ابزار ( planner_tool و writer_tool ) پوشش میدهیم. این به سایر عاملها اجازه میدهد تا این گردشهای کاری پیچیده را طوری فراخوانی کنند که گویی ابزارهای سادهای هستند.
۷. مدیر ریشه وبلاگنویس
root_agent (با نام Blogger ) کل جریان کار را هماهنگ میکند. وقتی موضوعی به آن داده میشود، دستورالعملهای آن را به موارد زیر هدایت میکند:
- برای تولید طرح کلی اعتبارسنجی شده،
planner_toolرا فراخوانی کنید. - برای نوشتن پیشنویس بر اساس آن طرح کلی، از
writer_toolاستفاده کنید. - با ایجاد ۳ عنوان جایگزین و ۲ قلاب توییت، کار را تمام کنید.
این معماری حلقه چندعاملی با تشخیص و اصلاح خطاهای قالببندی یا ساختاری LLM قبل از نمایش خروجی به کاربر، قابلیت اطمینان را تضمین میکند!
۷. اجرا و آزمایش عامل
حالا وقتشه که مامورتون رو در عمل ببینید!
۱. رابط کاربری وب ADK را اجرا کنید
مطمئن شوید که در ترمینال خود در دایرکتوری ریشه پروژه bloggeragent هستید و محیط مجازی شما فعال است ( source .venv/bin/activate )، سپس رابط وب را اجرا کنید:
adk web
۲. با نماینده تعامل داشته باشید
- مرورگر خود را باز کنید و به آدرس
http://127.0.0.1:8000(یا پورتی که مشخص کردهاید) بروید. - شما باید رابط کاربری وب ADK را با عامل
Bloggerبارگذاری شده و طرح بصری آن ببینید (که عامل ریشه Blogger را نشان میدهد که به ابزارهای RobustBlogPlanner و RobustBlogWriter اشاره میکند):
- یک موضوع فنی را در کادر پیام تایپ کنید و Enter را فشار دهید. در اینجا چند نمونه سوال جالب وجود دارد که میتوانید برای ارزیابی نماینده خود استفاده کنید:
-
How to build an AI agent using planning loops -
Explain the difference between REST and gRPC in microservices -
A guide to using Python's asyncio for backend concurrency -
Why developers should use Docker for local database setups
-
- به ردیابی اجرا در رابط کاربری توجه کنید. خواهید دید که
BlogPlannerطرح کلی را ایجاد میکند،OutlineValidationCheckerآن را اعتبارسنجی میکند وBlogWriterپیشنویس نهایی را بر اساس طرح کلی مینویسد:
۸. استقرار در Cloud Run
حالا که تأیید کردید که عامل به صورت محلی کار میکند، بیایید آن را در Google Cloud Run مستقر کنیم تا دیگران هم بتوانند از آن استفاده کنند!
Google Cloud Run یک پلتفرم محاسباتی مدیریتشده است که به شما امکان میدهد کانتینرهای بدون وضعیت (stateless) را اجرا کنید که از طریق درخواستهای وب یا رویدادهای Pub/Sub قابل فراخوانی هستند.
۱. پیشنیازهای استقرار
برای استقرار عامل نوشتن وبلاگ در Cloud Run، باید رابط خط فرمان Google Cloud ( gcloud ) را روی دستگاه محلی خود نصب و تأیید کنید:
- نصب رابط خط فرمان گوگل کلود : اگر آن را نصب نکردهاید، راهنمای نصب رابط خط فرمان گوگل کلود را برای سیستم عامل خود (مک، ویندوز یا لینوکس) دنبال کنید.
- ترمینال محلی خود را تأیید کنید : پس از نصب، دستور زیر را در ترمینال خود اجرا کنید تا به حساب Google Cloud خود وارد شوید:
gcloud auth login - تأیید احراز هویت : تأیید کنید که حساب شما با موفقیت وارد شده است و میتوانید به منابع Google Cloud خود دسترسی داشته باشید:
gcloud auth list
۲. راهاندازی پروژه ابری گوگل
پروژه فعال خود را در ترمینال تنظیم کنید:
gcloud config set project <YOUR_PROJECT_ID>
سرویسهای Google Cloud لازم برای ساخت و استقرار عامل کانتینر شده خود را فعال کنید:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
از آنجایی که دستور ADK deploy از Google Cloud Build برای خودکارسازی فرآیند ساخت استفاده میکند، باید به حساب کاربری پیشفرض سرویس محاسباتی اجازه استفاده از Cloud Build را بدهید.
با اجرای دستور زیر شماره پروژه خود را پیدا کنید:
gcloud projects describe <YOUR_PROJECT_ID> --format="value(projectNumber)"
دستورات زیر را برای اتصال نقشهای IAM مورد نیاز اجرا کنید (جایگزین کنید)
- به Cloud Build اجازه ساخت کانتینر خود را بدهید:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/cloudbuild.builds.builder"
- به Gemini Enterprise اجازه دسترسی بدهید تا agent مستقر شده بتواند مدلهای Gemini را بدون نیاز به کلید API فراخوانی کند:
gcloud projects add-iam-policy-binding <YOUR_PROJECT_ID> \
--member="serviceAccount:<PROJECT_NUMBER>-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
۳. تنظیم متغیرهای محیطی محلی
برای سادهسازی دستور استقرار و جلوگیری از اشتباهات تایپی، شناسه پروژه خود را به عنوان یک متغیر محیطی در بخش ترمینال خود تنظیم کنید:
export PROJECT_ID="<YOUR_PROJECT_ID>"
۴. استقرار با استفاده از ADK CLI
رابط خط فرمان ADK یک دستور ساده برای استقرار عامل شما در Cloud Run ارائه میدهد.
مطمئن شوید که محیط مجازی شما فعال است و در دایرکتوری پروژه bloggeragent قرار دارید، سپس دستور استقرار را اجرا کنید:
# Deploy using ADK
adk deploy cloud_run \
--project=$PROJECT_ID \
--region=us-east1 \
--service_name=bloggeragent \
--with_ui \
. \
-- \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE,MODEL=gemini-3.5-flash,GOOGLE_CLOUD_LOCATION=global
در طول فرآیند استقرار، دو سوال زیر در ترمینال از شما پرسیده خواهد شد:
- تأیید ایجاد مخزن :
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [us-east1] will be created. Do you want to continue (Y/n)?
Yرا تایپ کنید و Enter را فشار دهید. - اجازه دسترسی غیرمجاز :
Allow unauthenticated invocations to [bloggeragent] (y/N)?
yرا تایپ کرده و Enter را فشار دهید (این به شما امکان میدهد به رابط کاربری وب ADK به صورت عمومی در مرورگر خود دسترسی داشته باشید).
۵. به عامل مستقر خود دسترسی پیدا کنید
پس از اتمام استقرار، دستور یک URL را نمایش میدهد. آن URL را در مرورگر خود باز کنید تا به رابط کاربری وب ADK که به صورت زنده و عمومی در دسترس است، دسترسی پیدا کنید!
۹. تمیز کردن
برای جلوگیری از هزینههای مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این codelab را حذف کنید.
۱. سرویس Cloud Run را حذف کنید
سرویس bloggeragent مستقر شده را حذف کنید:
gcloud run services delete bloggeragent --region=us-east1 --quiet
۲. مخزن رجیستری Artifact را حذف کنید
مخزن داکر ایجاد شده برای ذخیره تصاویر کانتینر ساخته شده را حذف کنید:
gcloud artifacts repositories delete cloud-run-source-deploy --location=us-east1 --quiet
۳. سرور محلی را متوقف کنید
برای متوقف کردن سرور محلی ADK، در ترمینالی که سرور در حال اجرا است، CTRL+C را فشار دهید و محیط مجازی را غیرفعال کنید:
deactivate
۱۰. تبریک
تبریک میگویم! شما اولین عامل هوش مصنوعی خود را با استفاده از ADK گوگل و Gemini ساختید.
آنچه آموختهاید
- مفاهیم اصلی عاملهای هوش مصنوعی (استدلال و عمل).
- نحوه استفاده از Google ADK برای ساخت یک سیستم چندعاملی.
- نحوه اجرا و آزمایش عامل خود با استفاده از رابط کاربری وب.
مراحل بعدی
- سعی کنید ابزارهایی را به نماینده خود اضافه کنید (مانند جستجوی وب یا فراخوانیهای API).
- منتظر ویدیوی دوم باشید، جایی که یک سرور MCP را ادغام خواهیم کرد!