راهنمای آموزش ساخت ایجنت هوش مصنوعی آماده تولید با Google Cloud و ADK

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

فهرست مطالب

۱. ایجنت هوش مصنوعی چیست و چه تفاوتی با یک مدل زبانی دارد؟
۲. چهار رکن اصلی هر ایجنت آماده تولید
۳. الگوریتم ReAct؛ چرخه فکر – عمل ایجنت
۴. Agent Development Kit (ADK)؛ چارچوب رسمی گوگل
۵. معماری چندعاملی (Multi-Agent Architecture)
۶. مدیریت ابزارها با Function Calling
۷. سیستم حافظه در ایجنت های هوش مصنوعی
۸. RAG و Grounding؛ واقعیت را به ایجنت بیاموزید
۹. ارزیابی سیستماتیک ایجنت ها
۱۰. استقرار روی Vertex AI
۱۱. امنیت، ایمنی و گاردریل ها
۱۲. نظارت و Observability در تولید
۱۳. چک لیست آماده سازی برای تولید

۱. ایجنت هوش مصنوعی چیست و چه تفاوتی با یک مدل زبانی دارد؟

یک ایجنت هوش مصنوعی (AI Agent) اما بسیار فراتر از این است. ایجنت یک سیستم است که می تواند یک هدف کلی دریافت کند، آن را به مراحل کوچک تر تقسیم کند، برای رسیدن به هر مرحله ابزار مناسب را انتخاب و فراخوانی کند، نتیجه را ارزیابی کند و در صورت نیاز مسیر خود را تغییر دهد. این توانایی برنامه ریزی و عمل خودمختار، ایجنت را به چیزی شبیه به یک همکار دیجیتال واقعی تبدیل می کند.

یک مثال ملموس

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

۲. چهار رکن اصلی هر ایجنت آماده تولید

رکن اول: مدل زبانی بزرگ (LLM)

مدل زبانی بزرگ مغز ایجنت است. این مدل وظیفه استدلال، برنامه ریزی، تفسیر خروجی ابزارها و تولید پاسخ نهایی را بر عهده دارد. در اکوسیستم گوگل، مدل های خانواده Gemini به عنوان پایه ایجنت ها استفاده می شوند. انتخاب مدل مناسب بستگی به نوع وظیفه، سرعت پاسخ مورد نیاز و بودجه محاسباتی شما دارد؛ Gemini 2.0 Flash برای وظایف سریع و Gemini 2.0 Pro برای استدلال های پیچیده تر مناسب تر است.

رکن دوم: ابزارها (Tools)

ابزارها دست های ایجنت هستند. بدون ابزار، ایجنت در دنیای کلمات گیر افتاده و هیچ اقدام واقعی ای نمی تواند انجام دهد. ابزارها می توانند توابع پایتون ساده، API های خارجی، کوئری های پایگاه داده، جستجوی وب، اجرای کد یا حتی ایجنت های دیگر باشند. گوگل در ADK سه دسته ابزار را تعریف می کند: ابزارهای از پیش ساخته شده (Built-in Tools) مانند Google Search، ابزارهای سفارشی (Custom Tools) که خودتان تعریف می کنید و ابزارهای مبتنی بر MCP یا Model Context Protocol.

رکن سوم: حافظه (Memory)

حافظه ایجنت از دو لایه تشکیل می شود. لایه اول حافظه کوتاه مدت یا In-Context Memory است که همه اطلاعات جلسه جاری شامل تاریخچه گفتگو، نتایج ابزارها و متن سیستم را در پنجره Context نگه می دارد. لایه دوم حافظه بلند مدت یا External Memory است که با استفاده از پایگاه داده های برداری مانند Vector Search در Vertex AI، اطلاعات را در میان جلسات مختلف حفظ می کند و به ایجنت اجازه می دهد تجربه کسب کند.

رکن چهارم: ارکستریشن (Orchestration)

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

۳. الگوریتم ReAct؛ چرخه فکر – عمل ایجنت

چرخه چهار مرحله ای ReAct

هر تکرار یا Iteration در یک ایجنت مبتنی بر ReAct از چهار مرحله تشکیل می شود. مرحله اول Thought یا تفکر است: مدل وضعیت فعلی را تحلیل می کند و تصمیم می گیرد گام بعدی چه باشد. مرحله دوم Action یا عمل است: مدل مشخص می کند کدام ابزار باید فراخوانی شود و با چه پارامترهایی. مرحله سوم Observation یا مشاهده است: نتیجه فراخوانی ابزار دریافت می شود. مرحله چهارم ارزیابی است: مدل تصمیم می گیرد آیا به هدف رسیده یا باید چرخه را تکرار کند.

# نمونه ساده یک چرخه ReAct در ADK
from google.adk.agents import Agent
from google.adk.tools import google_search

agent = Agent(
    model="gemini-2.0-flash",
    name="research_agent",
    instruction="تو یک محقق هستی. برای پاسخ به سوالات از جستجوی وب استفاده کن.",
    tools=[google_search]
)

result = agent.run("آخرین تحولات هوش مصنوعی در سال ۲۰۲۵ را خلاصه کن.")

۴. Agent Development Kit (ADK)؛ چارچوب رسمی گوگل

pip install google-adk

ویژگی های کلیدی ADK

ADK چندین قابلیت کلیدی دارد که آن را از رقبا متمایز می کند. اول، پشتیبانی بومی از مدل های Gemini و یکپارچه سازی مستقیم با Vertex AI. دوم، سازگاری با ابزارهای محبوب اکوسیستم مانند LangChain، LlamaIndex و CrewAI از طریق رابط های استاندارد. سوم، پشتیبانی از پروتکل Model Context Protocol یا MCP که یک استاندارد باز صنعتی برای ارتباط ایجنت ها با ابزارهای خارجی است. چهارم، محیط اجرایی داخلی برای آزمایش و دیباگ ایجنت ها قبل از استقرار.

ساختار یک پروژه ADK

my_agent_project/
├── agent.py          # تعریف ایجنت اصلی
├── tools/
│   ├── search_tool.py
│   └── database_tool.py
├── prompts/
│   └── system_prompt.txt
├── tests/
│   └── eval_dataset.json
└── deployment/
    └── vertex_config.yaml

۵. معماری چندعاملی (Multi-Agent Architecture)

الگوهای اصلی معماری چندعاملی

الگوی سلسله مراتبی (Hierarchical): در این الگو یک ایجنت ارکستراتور (Orchestrator Agent) در راس قرار دارد و وظایف را به ایجنت های تخصصی فرعی (Sub-Agents) محول می کند. هر ایجنت فرعی وظیفه خود را انجام داده و نتیجه را به ارکستراتور بازمی گرداند. ارکستراتور نتایج را ترکیب کرده و پاسخ نهایی را تولید می کند. این الگو برای وظایف پیچیده با مراحل مشخص بسیار مناسب است.

الگوی همکارانه (Collaborative): در این الگو چندین ایجنت هم سطح با هم همکاری می کنند و می توانند وظایف را به یکدیگر منتقل کنند. این الگو برای مسائلی مناسب است که نیاز به بازبینی چندمرحله ای یا دیدگاه های مختلف دارند، مانند سیستم های چک و تایید در حسابداری یا گردش کار بازبینی کد.

from google.adk.agents import Agent, AgentOrchestrator

# تعریف ایجنت های تخصصی
research_agent = Agent(
    name="researcher",
    model="gemini-2.0-pro",
    instruction="اطلاعات را از منابع معتبر جمع آوری کن.",
    tools=[google_search, web_scraper]
)

analysis_agent = Agent(
    name="analyst",
    model="gemini-2.0-pro",
    instruction="داده های دریافتی را تحلیل کن و الگوها را شناسایی کن.",
    tools=[code_executor, data_analyzer]
)

writer_agent = Agent(
    name="writer",
    model="gemini-2.0-flash",
    instruction="گزارش نهایی را به فارسی روان بنویس.",
    tools=[document_formatter]
)

# ایجنت ارکستراتور
orchestrator = AgentOrchestrator(
    name="main_orchestrator",
    agents=[research_agent, analysis_agent, writer_agent],
    model="gemini-2.0-pro"
)

۶. مدیریت ابزارها با Function Calling

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

تعریف یک ابزار سفارشی در ADK

from google.adk.tools import tool

@tool
def get_stock_price(symbol: str) -> dict:
    """
    قیمت فعلی یک سهام را برمی گرداند.
    
    Args:
        symbol: نماد سهام مانند GOOG یا AAPL
    
    Returns:
        دیکشنری حاوی قیمت، تغییر روزانه و حجم معاملات
    """
    # پیاده سازی واقعی با API مالی
    response = financial_api.get_price(symbol)
    return {
        "symbol": symbol,
        "price": response.price,
        "change": response.daily_change,
        "volume": response.volume
    }

نکته مهم در تعریف ابزارها، نوشتن Docstring های دقیق است. مدل زبانی از این توضیحات برای تصمیم گیری درباره زمان و نحوه استفاده از ابزار بهره می برد. Docstring ضعیف مساوی با ابزار ضعیف است، حتی اگر پیاده سازی آن کامل باشد.

۷. انواع سیستم حافظه در ایجنت های هوش مصنوعی

حافظه بلند مدت (Long-Term Memory): این حافظه خارج از مدل ذخیره می شود و معمولاً از یک پایگاه داده برداری (Vector Database) مانند Vertex AI Vector Search استفاده می کند. اطلاعات مهم در قالب بردارهای معنایی ذخیره شده و در زمان نیاز با جستجوی شباهت (Similarity Search) بازیابی می شوند. این مکانیزم پایه اصلی سیستم های RAG است.

حافظه رویه ای (Procedural Memory): این نوع حافظه دانش نحوه انجام کارها را ذخیره می کند و معمولاً در قالب System Prompt یا تعریف ابزارها پیاده سازی می شود. هر بار که ایجنت شروع می کند، این دانش بارگذاری می شود.

۸. RAG و Grounding؛ واقعیت را به ایجنت بیاموزید

Retrieval-Augmented Generation (RAG)

RAG یا تولید تقویت شده با بازیابی یک الگوی معماری است که در آن ایجنت قبل از تولید پاسخ، اطلاعات مرتبط را از یک پایگاه دانش داخلی جستجو می کند و آن ها را به عنوان Context به مدل می دهد. این روش برای سازمان هایی که نیاز دارند ایجنت ها با اسناد داخلی، مستندات فنی یا پایگاه دانش خصوصی کار کنند، ایده آل است.

from google.adk.retrievers import VertexAIRetriever

# پیکربندی بازیاب با Vertex AI Vector Search
retriever = VertexAIRetriever(
    index_endpoint="projects/my-project/locations/us-central1/...",
    deployed_index_id="my_knowledge_base"
)

# ایجنت با قابلیت RAG
rag_agent = Agent(
    name="knowledge_agent",
    model="gemini-2.0-pro",
    instruction="برای پاسخ به سوالات فنی، ابتدا از پایگاه دانش داخلی جستجو کن.",
    tools=[retriever.as_tool()]
)

Google Search Grounding

Grounding با Google Search روشی است که گوگل به صورت بومی در مدل های Gemini ارائه می دهد و به مدل اجازه می دهد پاسخ هایش را با نتایج جستجوی واقعی گوگل تایید کند. برخلاف RAG که نیاز به پایگاه دانش داخلی دارد، این روش برای اطلاعات عمومی و به روز بسیار مناسب است و پیاده سازی آن بسیار ساده تر است.

۹. ارزیابی سیستماتیک ایجنت ها

سه سطح ارزیابی که گوگل توصیه می کند

سطح اول: ارزیابی مسیر (Trajectory Evaluation)
این ارزیابی بررسی می کند که آیا ایجنت مراحل منطقی و صحیحی را برای رسیدن به هدف طی کرده است. مثلاً آیا قبل از نوشتن گزارش، ابتدا اطلاعات را جستجو کرده؟ آیا ابزار درست را برای هر مرحله انتخاب کرده؟ این ارزیابی به شناسایی مشکلات در منطق برنامه ریزی ایجنت کمک می کند.

سطح دوم: ارزیابی خروجی نهایی (Final Answer Evaluation)
این ارزیابی کیفیت پاسخ نهایی را بررسی می کند، صرف نظر از مسیری که طی شده. آیا پاسخ دقیق است؟ آیا کامل است؟ آیا با واقعیت همخوانی دارد؟ برای این ارزیابی می توان از مجموعه داده های Ground Truth استفاده کرد.

سطح سوم: LLM-as-a-Judge
در این روش پیشرفته، از یک مدل زبانی قوی تر (معمولاً Gemini 2.0 Pro) برای ارزیابی خروجی مدل دیگر استفاده می شود. این رویکرد برای ارزیابی جنبه های کیفی مانند سبک نوشتاری، منطق استدلال و طبیعی بودن پاسخ بسیار موثر است.

from google.cloud.aiplatform import EvaluationService

# ایجاد مجموعه داده ارزیابی
eval_dataset = [
    {
        "input": "خلاصه ای از گزارش مالی Q3 شرکت ما آماده کن",
        "expected_tools_used": ["document_retriever", "data_analyzer"],
        "expected_output_contains": ["درآمد", "سود خالص", "رشد"]
    },
    # ...
]

# اجرای ارزیابی
evaluator = EvaluationService()
results = evaluator.evaluate_agent(
    agent=my_agent,
    dataset=eval_dataset,
    metrics=["trajectory_accuracy", "answer_relevance", "tool_usage_correctness"]
)

۱۰. استقرار روی Vertex AI

Vertex AI Agent Engine (مدیریت شده): این گزینه برای تیم هایی مناسب است که می خواهند روی منطق ایجنت تمرکز کنند و زیرساخت را به گوگل بسپارند. Agent Engine به صورت خودکار مقیاس پذیری، مدیریت حالت Session Management، ثبت وقایع و پشتیبان گیری را مدیریت می کند. این گزینه برای اکثر تیم های توسعه توصیه می شود.

Cloud Run (کنترل بیشتر): برای تیم هایی که نیاز به کنترل دقیق بر محیط اجرایی دارند، استقرار روی Cloud Run با استفاده از یک Container Docker گزینه مناسب تری است. این رویکرد انعطاف بیشتری می دهد اما مسئولیت مدیریت زیرساخت را هم به همراه می آورد.

# استقرار روی Vertex AI Agent Engine
from google.cloud import aiplatform

agent_engine = aiplatform.agent_engines.create(
    agent_engine=orchestrator,
    requirements=["google-adk", "google-cloud-bigquery"],
    display_name="production_research_agent",
    description="ایجنت تحقیق و تحلیل داده برای تیم مالی"
)

print(f"ایجنت با موفقیت مستقر شد: {agent_engine.resource_name}")

۱۱. امنیت، ایمنی و گاردریل ها

پیاده سازی گاردریل های موثر

from google.adk.safety import SafetyConfig, ContentFilter

# پیکربندی گاردریل های امنیتی
safety_config = SafetyConfig(
    # فیلتر محتوای مضر
    content_filters=[
        ContentFilter(category="HARM_CATEGORY_DANGEROUS_CONTENT", threshold="BLOCK_MEDIUM_AND_ABOVE"),
        ContentFilter(category="HARM_CATEGORY_HARASSMENT", threshold="BLOCK_LOW_AND_ABOVE"),
    ],
    # محدود کردن دامنه دسترسی ابزارها
    tool_permissions={
        "database_tool": ["READ"],           # فقط خواندن
        "email_tool": ["SEND_TO_APPROVED"],  # فقط به گیرندگان تایید شده
        "file_tool": ["READ", "WRITE_TEMP"]  # فقط پوشه موقت
    },
    # محدودیت نرخ درخواست
    rate_limits={
        "max_tool_calls_per_session": 50,
        "max_tokens_per_request": 8000
    }
)

agent = Agent(
    name="secure_agent",
    model="gemini-2.0-pro",
    safety_config=safety_config,
    instruction="..."
)

۱۲. نظارت و Observability در تولید

شاخص های کلیدی که باید رصد کنید

در هر سیستم ایجنتی در محیط تولید، رصد کردن دسته های مختلف معیار ضروری است. معیارهای عملکردی شامل تاخیر پایان به پایان یا End-to-End Latency، تعداد توکن مصرفی به ازای هر درخواست، نرخ موفقیت وظایف یا Task Success Rate و تعداد تکرارهای ReAct لازم برای تکمیل وظیفه می شوند. معیارهای کیفی شامل نمره ارزیابی LLM-as-a-Judge، نرخ استفاده صحیح از ابزارها و رضایت کاربران می شوند. معیارهای هزینه ای نیز شامل هزینه توکن به ازای هر وظیفه و نرخ استفاده از ابزارهای پولی هستند.

from google.cloud import trace, logging
from opentelemetry import trace as otel_trace

# پیکربندی Observability با OpenTelemetry
tracer = otel_trace.get_tracer("agent_tracer")

@tracer.start_as_current_span("agent_execution")
def run_agent_with_tracing(user_input: str):
    span = otel_trace.get_current_span()
    span.set_attribute("user_input_length", len(user_input))
    
    result = agent.run(user_input)
    
    span.set_attribute("tool_calls_count", result.tool_calls_count)
    span.set_attribute("total_tokens", result.usage.total_tokens)
    span.set_attribute("success", result.success)
    
    return result

۱۳. چک لیست آماده سازی برای تولید

بخش معماری و توسعه:

• چهار رکن اصلی (LLM، Tools، Memory، Orchestration) به درستی پیکربندی شده اند
• تمام ابزارها Docstring های دقیق و کامل دارند
• مدیریت خطا برای هر ابزار پیاده سازی شده است
• مکانیزم Timeout برای فراخوانی های طولانی وجود دارد

بخش ارزیابی:

• مجموعه داده ارزیابی با حداقل ۵۰ مثال واقعی ساخته شده است
• هر سه سطح ارزیابی (Trajectory، Final Answer، LLM-as-Judge) اجرا شده است
• آستانه قبولی برای هر معیار تعریف شده است
• آزمایش های Regression Test برای جلوگیری از Regression وجود دارد

بخش امنیت:

• گاردریل های محتوایی پیکربندی شده اند
• کنترل دسترسی IAM برای تمام ابزارها اعمال شده است
• محافظت در برابر Prompt Injection پیاده سازی شده است
• محدودیت های نرخ (Rate Limiting) تعریف شده اند

بخش نظارت:

• Cloud Trace و Cloud Logging فعال هستند
• داشبورد نظارتی برای شاخص های کلیدی ساخته شده است
• هشدارهای Alerting برای خطاهای بحرانی تنظیم شده اند
• فرآیند مشخصی برای بازبینی هفتگی شاخص ها وجود دارد

جمع بندی

این مقاله آموزشی سفری کامل بود از مفاهیم پایه ایجنت هوش مصنوعی تا استقرار امن و پایدار در محیط تولید با استفاده از ابزارهای گوگل کلاد. از درک چهار رکن اصلی ایجنت و الگوریتم ReAct، تا پیاده سازی عملی با ADK، طراحی معماری چندعاملی، مدیریت حافظه و ابزارها، ارزیابی سیستماتیک، تامین امنیت و در نهایت نظارت هوشمند با ابزارهای Observability؛ همه این دانش ها روی هم یک چارچوب کامل و عملی برای تیم های توسعه می سازند.

تیم تحریریه استاد آی تی این راهنما را در کنار منبع اصلی آن در وبلاگ گوگل کلاد به عنوان یکی از مهم ترین منابع مطالعاتی سال برای هر توسعه دهنده ای که با Gemini، Vertex AI، LLMOps یا Agentic AI کار می کند، توصیه می کند.