سخنرانی کلیدی توسعه‌دهندگان بعدی در سال 26: ساخت عوامل ADK با مهارت‌ها و ابزارها

۱. مقدمه

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

کاری که انجام خواهید داد

  • یک پروژه عامل ADK جدید را آغاز کنید
  • با استفاده از یک سازنده ساختاریافته، یک اعلان سیستم قوی بنویسید
  • ابزارهای MCP گوگل مپ را برای موقعیت مکانی در دنیای واقعی اضافه کنید
  • بارگذاری پویای مهارت‌ها در مجموعه ابزارهای عامل
  • اجرای عامل را به صورت محلی آزمایش کنید
  • عامل را در Agent Engine (Cloud Run) مستقر کنید

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

  • یک مرورگر وب مانند کروم
  • یک پروژه گوگل کلود با قابلیت پرداخت صورتحساب
  • آشنایی اولیه با پایتون

این آزمایشگاه کد برای توسعه‌دهندگان سطح متوسط ​​است که به دنبال ساخت عوامل هوش مصنوعی مولد تخصصی هستند.

مدت زمان تخمینی: ۴۵ دقیقه

منابع ایجاد شده در این آزمایشگاه کد باید کمتر از ۲ دلار هزینه داشته باشند.

۲. قبل از شروع

ایجاد یک پروژه ابری گوگل

  1. در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید .
  2. مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .

شروع پوسته ابری

Cloud Shell یک محیط خط فرمان است که در Google Cloud اجرا می‌شود و ابزارهای لازم از قبل روی آن بارگذاری شده‌اند.

  1. روی فعال کردن Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
  2. پس از اتصال به Cloud Shell، احراز هویت خود را تأیید کنید: 
    gcloud auth list
  3. تأیید کنید که پروژه شما پیکربندی شده است: 
    gcloud config get project
  4. اگر پروژه شما مطابق انتظار تنظیم نشده است، آن را تنظیم کنید: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

تأیید اعتبار:

gcloud auth list

پروژه خود را تایید کنید:

gcloud config get project

در صورت نیاز آن را تنظیم کنید:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

فعال کردن APIها

برای فعال کردن تمام API های مورد نیاز، این دستور را اجرا کنید:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

یک کلید API نقشه گوگل ایجاد کنید

برای استفاده از ابزارهای MCP نقشه‌های گوگل، باید یک کلید API نقشه ایجاد کنید.

  1. در کنسول گوگل کلود، از نوار جستجو برای رفتن به پلتفرم گوگل مپ > اعتبارنامه‌ها استفاده کنید.
  2. در صورت درخواست، پروژه Google Cloud خود را تأیید کنید.
  3. روی ایجاد اعتبارنامه‌ها کلیک کنید و کلید API را انتخاب کنید.
  4. کلید API تولید شده را کپی کنید. در مرحله بعدی به آن نیاز خواهید داشت.

۳. محیط خود را آماده کنید

برای این آزمایشگاه کد، کد در گیت‌هاب میزبانی می‌شود. شما مخزن را که شامل ساختار دایرکتوری و زیرمولفه‌های مورد نیاز (مانند دایرکتوری skills/ ) است، کلون خواهید کرد.

  1. مخزن را کلون کنید و به پوشه پروژه بروید: 
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. یک محیط مجازی پایتون راه‌اندازی کنید و ADK را نصب کنید: 
uv venv
source .venv/bin/activate
uv sync
  1. کلید API نقشه‌های خود را تنظیم کنید. برنامه آن را از یک متغیر محیطی می‌خواند: 
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

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

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

  1. فایل محیط نمونه را کپی کنید: 
cp planner_agent/sample.env planner_agent/.env
  1. planner_agent/.env را باز کنید و فیلد GOOGLE_CLOUD_PROJECT را با شناسه واقعی پروژه Google Cloud خود به‌روزرسانی کنید و فیلد GOOGLE_MAPS_API_KEY را با کلید API نقشه‌های گوگل که ایجاد کرده‌اید، به‌روزرسانی کنید.

فایل باید شبیه به این باشد: 

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

۴. یک عامل ADK جدید ایجاد کنید

فایل اصلی که عامل را تعریف می‌کند را بررسی کنید: planner_agent/agent.py .

در مخزن build-agents-with-skills ، عامل با استفاده از کلاس Agent در ADK مقداردهی اولیه می‌شود. این کلاس، مدل زیربنایی، یک نام هویت را مشخص می‌کند و دستورالعمل‌ها و ابزارهای تعریف شده در ماژول‌های دیگر را دریافت می‌کند.

برای بررسی کد مقداردهی اولیه planner_agent/agent.py را باز کنید: 

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

کلاس Agent تاریخچه پیام، تنظیم ابزار و ارتباطات LLM را خلاصه می‌کند و شما را مجبور می‌کند تا روی رفتار agent تمرکز کنید.

در حال حاضر، این عامل بسیار عمومی است. شما می‌توانید مانند هر LLM دیگری با آن تعامل داشته باشید. 

uv run adk run planner_agent

این دستور چتی را با عامل آغاز می‌کند. این دستور از gemini-3-flash-preview به عنوان مدل خود استفاده می‌کند و می‌تواند به سوالات اساسی پاسخ دهد. 

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

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

۵. یک اعلان سیستم ایجاد کنید

دستورات سیستم (دستورالعمل‌ها) رفتار عامل را تعیین می‌کنند. این پروژه به جای یک رشته‌ی غول‌پیکر، از یک PromptBuilder ( planner_agent/utils.py ) برای نوشتن پویای دستورالعمل‌ها استفاده می‌کند.

برای مشاهده‌ی نحوه‌ی ساختاردهی اعلان به بخش‌های منطقی planner_agent/prompts.py را باز کنید: 

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

به planner_agent/agent.py برگردیم، این قبلاً وارد شده است.

بخشی را با TODO: Replace Instruction and Description پیدا کنید و تخصیص مجدد متغیرهای instruction و description را از حالت کامنت خارج کنید.

آن بخش از کد باید به این شکل باشد: 

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

شما در حال وارد کردن نسخه‌ای از اعلان برای عامل هستید که به هیچ ابزاری اشاره نمی‌کند. ابزارها را در مرحله بعدی اضافه خواهید کرد.

می‌توانید این نسخه از agent را امتحان کنید: 

uv run adk run planner_agent

در پنجره چت، عبارت زیر را ارسال کنید: 

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

پس از چند لحظه، باید پاسخی مشابه این دریافت کنید: 

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

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

۶. مهارت‌ها و ابزارها را اضافه کنید

برای فعال کردن مهارت‌ها و ابزارها در planner_agent/agent.py ، بخشی را که TODO: Replaces Tools دارد پیدا کنید و دو خط بعدی را از حالت کامنت خارج کنید. کد شما باید شبیه کد زیر باشد: 

instruction=PLANNER_INSTRUCTION
tools=get_tools()

این تنها تغییر کد مورد نیاز در این مرحله است. بقیه این بخش مفاهیم مربوط به مهارت‌ها و ابزارها را توضیح می‌دهد.

مهارت‌ها

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

برای عامل برنامه‌ریزی ماراتن، ۳ مهارت تعریف شده است:

  1. gis-spatial-engineering - مسئول پردازش داده‌های GeoJSON برای ایجاد مسیر ماراتن.
  2. نقشه‌برداری - از ابزارهای نقشه‌های گوگل برای جستجوی مکان‌ها و اطلاعات آب و هوا استفاده کنید.
  3. مدیر مسابقه - اعتبارسنجی مسیر ماراتن که از دستورالعمل‌های برنامه‌ریزی پیروی می‌کند.

مهارت‌ها می‌توانند شامل اسکریپت، منابع اضافی و ارجاعات باشند.

برنامه تمام مهارت‌ها را بارگذاری کرده و آنها را به عنوان ابزار در planner_agent/tools.py ارائه می‌دهد. توجه کنید که چگونه این کار در تابع get_tools() انجام می‌شود: 

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

جالب‌ترین بخش، متد load_skill_from_dir از ADK است. روش دیگری برای ایجاد مهارت‌ها در ADK وجود دارد و آن روش درون‌خطی است. اگرچه در این کد استفاده نشده است، اما چیزی شبیه به این است: 

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

اضافه کردن ابزارهای نقشه برداری

برنامه‌ریز ماراتن برای ایجاد مسیرها به زمینه مکانی نیاز دارد. شما این کار را با ادغام سرور MCP (پروتکل زمینه مدل) نقشه‌های گوگل فراهم می‌کنید.

در planner_agent/tools.py ، به نحوه ثبت سرور MCP با ابزار ApiRegistry توجه کنید: 

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

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

۷. عامل را به صورت محلی اجرا کنید

حالا که agent، prompt و tools به هم متصل شده‌اند، agent را به صورت محلی اجرا کنید. این بار، از adk web استفاده خواهید کرد تا بتوانید رویدادهای Skill Load و Tool Call را ببینید. 

uv run adk web

شما باید چیزی شبیه به این را ببینید 

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

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

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. مرورگر خود را باز کنید و به آدرس اینترنتی (URL) نمایش داده شده در ترمینال (معمولاً http://localhost:8000 ) بروید.
  2. در منوی کشویی بالا سمت چپ، planner_agent انتخاب کنید.
  3. در پنجره چت، عبارت زیر را ارسال کنید: 
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

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

رابط کاربری شما باید شبیه به این باشد:

رابط کاربری وب ADK

۸. عامل را مستقر کنید

زمانی که از عملکرد محلی عامل راضی بودید، می‌توانید آن را در Agent Engine مستقر کنید که عامل را به طور ایمن در Cloud Run میزبانی می‌کند.

برای استقرار عامل، از دستور استقرار ADK CLI استفاده کنید: 

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

پس از اتمام استقرار، رابط خط فرمان (CLI) یک نقطه پایانی میزبانی‌شده ایمن برای عامل شما ایجاد می‌کند. اکنون می‌توانید این نقطه پایانی را در برنامه‌های frontend، ربات‌های چت یا سایر سیستم‌های backend ادغام کنید. همچنین می‌توانید از Agent Runtime Playground برای آزمایش عامل استفاده کنید.

خروجی به شکل زیر است: 

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

شما می‌توانید از اسکریپت پایتون ارائه شده برای ارتباط با عامل استفاده کنید.

  1. فایل محیط نمونه را کپی کنید: 
cp sample.env .env
  1. فایل .env ‎ را باز کنید و فیلد GOOGLE_CLOUD_PROJECT را با شناسه واقعی پروژه گوگل کلود خود به‌روزرسانی کنید.

فایل باید شبیه شکل زیر باشد: 

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. شما می‌توانید عوامل را در پروژه خود فهرست کنید. 
python main.py list

شما باید چیزی شبیه به این را ببینید 

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

پس از دریافت شناسه عامل مستقر، می‌توانید یک اعلان ارسال کنید: 

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

خروجی‌ای شبیه به زیر دریافت خواهید کرد: 

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

۹. تمیز کردن

برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، منابع ایجاد شده در طول این codelab را حذف کنید.

سرویس Cloud Run ایجاد شده توسط استقرار را حذف کنید: 

python main.py delete --agent-id ${AGENT_ID}

اگر کلید API نقشه‌ها را در Secret Manager ذخیره کرده‌اید، آن راز را حذف کنید: 

gcloud secrets delete maps-api-key --project=$PROJECT_ID

اگر یک پروژه جدید Google Cloud برای این codelab ایجاد کرده‌اید، می‌توانید کل پروژه را حذف کنید تا تمام منابع و APIهای مرتبط با آن حذف شوند: 

gcloud projects delete $PROJECT_ID

۱۰. تبریک

تبریک می‌گویم! شما با استفاده از ADK یک عامل برنامه‌ریزی ماراتن پیشرفته ساخته‌اید.

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

  • راه‌اندازی اولیه پروژه کیت توسعه عامل (ADK)
  • استفاده از PromptBuilder برای اعلان‌های سیستم ماژولار
  • ادغام قابلیت‌های نگاشت با استفاده از ابزارهای MCP و ApiRegistry
  • بارگذاری مشروط مهارت‌ها با استفاده از SkillToolset
  • تست محلی و استقرار در Agent Engine

اسناد مرجع