شروع کار با MCP، ADK و A2A

۱. مرور کلی

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

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

معماری

پروتکل زمینه مدل (MCP)

پروتکل زمینه مدل (MCP) یک پروتکل باز است که نحوه ارائه زمینه توسط برنامه‌ها به LLMها را استاندارد می‌کند. MCP روشی استاندارد برای اتصال مدل‌های هوش مصنوعی به منابع، اعلان‌ها و ابزارها ارائه می‌دهد.

کیت توسعه عامل (ADK)

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

پروتکل عامل به عامل (A2A)

پروتکل Agent2Agent (A2A) یک استاندارد باز است که برای ایجاد ارتباط و همکاری یکپارچه بین عامل‌های هوش مصنوعی طراحی شده است. درست همانطور که MCP روشی استاندارد برای دسترسی LLMها به داده‌ها و ابزارها فراهم می‌کند، A2A نیز روشی استاندارد برای صحبت عامل‌ها با سایر عامل‌ها فراهم می‌کند! در جهانی که عامل‌ها با استفاده از چارچوب‌های متنوع و توسط فروشندگان مختلف ساخته می‌شوند، A2A یک زبان مشترک ارائه می‌دهد، سیلوها را در هم می‌شکند و قابلیت همکاری را تقویت می‌کند.

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

  • نحوه ایجاد یک سرور محلی MCP
  • استقرار سرور MCP در Cloud Run
  • نحوه ساخت یک عامل با کیت توسعه عامل که از ابزارهای MCP استفاده می‌کند
  • نحوه نمایش یک عامل ADK به عنوان سرور A2A
  • آزمایش سرور A2A با استفاده از کلاینت A2A
  • چگونه یک عامل بسازیم که از طریق پروتکل A2A با عامل دیگری صحبت کند

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

  • یک مرورگر، مانند کروم یا فایرفاکس
  • یک پروژه گوگل کلود با قابلیت پرداخت.

۲. قبل از شروع

ایجاد یک پروژه

اگر پروژه گوگل کلود ندارید، یکی ایجاد کنید.

در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.

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

فعال کردن پوسته ابری

گوگل کلود شل (Google Cloud Shell) یک محیط توسعه تعاملی و مبتنی بر مرورگر است که مستقیماً در کنسول گوگل کلود ارائه می‌شود. این ساده‌ترین راه برای شروع کار با گوگل کلود بدون نیاز به نصب ابزارها به صورت محلی است.

با کلیک روی این لینک، Cloud Shell را فعال کنید. می‌توانید با کلیک روی دکمه مربوطه از Cloud Shell، بین Cloud Shell Terminal (برای اجرای دستورات ابری) و Editor (برای ساخت پروژه‌ها) جابجا شوید.

پس از اتصال به Cloud Shell، با استفاده از دستور زیر بررسی می‌کنید که آیا از قبل احراز هویت شده‌اید و پروژه روی شناسه پروژه شما تنظیم شده است یا خیر:

gcloud auth list

دستور زیر را در Cloud Shell اجرا کنید تا تأیید شود که دستور gcloud از پروژه شما اطلاع دارد.

gcloud config list project

برای تنظیم پروژه خود از دستور زیر استفاده کنید:

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

فعال کردن API های ابری

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

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       run.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       aiplatform.googleapis.com \
                       compute.googleapis.com

برای دستورات و نحوه‌ی استفاده از gcloud به مستندات آن مراجعه کنید.

کد را دریافت کنید

مخزن را کلون کنید:

git clone https://github.com/jackwotherspoon/currency-agent.git
cd currency-agent

uv برای مدیریت وابستگی‌ها استفاده می‌شود و از قبل در Cloud Shell نصب شده است، اما اگر codelab را به صورت محلی اجرا می‌کنید، می‌توانید آن را به صورت زیر نصب کنید:

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (uncomment below line)
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

با اجرای دستور زیر، متغیرهای محیطی را با یک فایل .env پیکربندی کنید:

echo "GOOGLE_GENAI_USE_ENTERPRISE=TRUE" >> .env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> .env \
&& echo "GOOGLE_CLOUD_LOCATION=global" >> .env

۳. یک سرور محلی MCP ایجاد کنید

قبل از اینکه به سراغ تنظیم عامل ارزی خود بروید، ابتدا یک سرور MCP برای نمایش ابزار(های) مورد نیاز عامل خود ایجاد خواهید کرد.

یک سرور MCP به شما امکان می‌دهد برنامه‌های سبکی بنویسید که قابلیت‌های خاصی (مانند دریافت نرخ ارز) را به عنوان ابزار در اختیار شما قرار دهند. سپس یک عامل یا حتی چندین عامل می‌توانند با استفاده از پروتکل استاندارد Model Context (MCP) به این ابزارها دسترسی پیدا کنند.

می‌توان از بسته FastMCP پایتون برای ایجاد یک سرور MCP استفاده کرد که ابزاری واحد به نام get_exchange_rate را در معرض نمایش قرار می‌دهد. ابزار get_exchange_rate از طریق اینترنت با رابط برنامه‌نویسی کاربردی Frankfurter تماس برقرار می‌کند تا نرخ ارز فعلی بین دو ارز را دریافت کند.

کد مربوط به سرور MCP را می‌توانید در فایل mcp-server/server.py پیدا کنید:

import logging
import os

import httpx
from fastmcp import FastMCP

# Set up logging
logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

mcp = FastMCP("Currency MCP Server 💵")

@mcp.tool()
def get_exchange_rate(
    currency_from: str = 'USD',
    currency_to: str = 'EUR',
    currency_date: str = 'latest',
):
    """Use this to get current exchange rate.

    Args:
        currency_from: The currency to convert from (e.g., "USD").
        currency_to: The currency to convert to (e.g., "EUR").
        currency_date: The date for the exchange rate or "latest". Defaults to "latest".

    Returns:
        A dictionary containing the exchange rate data, or an error message if the request fails.
    """
    logger.info(f"--- 🛠️ Tool: get_exchange_rate called for converting {currency_from} to {currency_to} ---")
    try:
        response = httpx.get(
            f'https://api.frankfurter.app/{currency_date}',
            params={'from': currency_from, 'to': currency_to},
        )
        response.raise_for_status()

        data = response.json()
        if 'rates' not in data:
            return {'error': 'Invalid API response format.'}
        logger.info(f'✅ API response: {data}')
        return data
    except httpx.HTTPError as e:
        return {'error': f'API request failed: {e}'}
    except ValueError:
        return {'error': 'Invalid JSON response from API.'}

if __name__ == "__main__":
    logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}")
    # Could also use 'sse' transport, host="0.0.0.0" required for Cloud Run.
    asyncio.run(
        mcp.run_async(
            transport="http",
            host="0.0.0.0",
            port=os.getenv("PORT", 8080),
        )
    )

برای شروع سرور MCP به صورت محلی، یک ترمینال باز کنید و دستور زیر را اجرا کنید (سرور از http://localhost:8080 شروع خواهد شد):

uv run mcp-server/server.py

آزمایش کنید که سرور MCP به درستی کار می‌کند و ابزار get_exchange_rate با استفاده از پروتکل Model Context قابل دسترسی است.

در یک پنجره ترمینال جدید (برای اینکه سرور محلی MCP متوقف نشود) دستور زیر را اجرا کنید: 

uv run mcp-server/test_server.py

شما باید نرخ ارز فعلی ۱ دلار آمریکا (USD) به یورو (EUR) را در خروجی مشاهده کنید: 

--- 🛠️ Tool found: get_exchange_rate ---
--- 🪛 Calling get_exchange_rate tool for USD to EUR ---
--- ✅ Success: {
  "amount": 1.0,
  "base": "USD",
  "date": "2025-05-26",
  "rates": {
    "EUR": 0.87866
  }
} ---

عالی! شما با موفقیت یک سرور MCP فعال با ابزاری که نماینده شما قادر به دسترسی به آن خواهد بود، دارید.

قبل از رفتن به ایستگاه بعدی، سرور MCP که به صورت محلی در حال اجرا است را با اجرای Ctrl+C (یا Command+C در مک) در ترمینالی که آن را شروع کرده‌اید، متوقف کنید.

۴. سرور MCP خود را روی Cloud Run مستقر کنید

اکنون آماده‌اید تا سرور MCP را به عنوان یک سرور MCP از راه دور در Cloud Run 🚀☁️ مستقر کنید.

مزایای اجرای سرور MCP از راه دور

اجرای یک سرور MCP از راه دور در Cloud Run می‌تواند مزایای متعددی داشته باشد:

  • 📈مقیاس‌پذیری : Cloud Run طوری ساخته شده است که بتواند به سرعت مقیاس‌پذیر شود و تمام درخواست‌های ورودی را مدیریت کند . Cloud Run سرور MCP شما را به طور خودکار و بر اساس تقاضا مقیاس‌پذیر می‌کند.
  • 👥سرور متمرکز : شما می‌توانید از طریق امتیازات IAM، دسترسی به یک سرور متمرکز MCP را با اعضای تیم به اشتراک بگذارید و به آنها اجازه دهید به جای اینکه همه سرورهای خود را به صورت محلی اجرا کنند، از طریق دستگاه‌های محلی خود به آن متصل شوند. اگر تغییری در سرور MCP ایجاد شود، همه اعضای تیم از آن بهره‌مند خواهند شد.
  • 🔐امنیت : Cloud Run راهی آسان برای اعمال درخواست‌های احراز هویت شده فراهم می‌کند. این قابلیت فقط امکان اتصال امن به سرور MCP شما را فراهم می‌کند و از دسترسی غیرمجاز جلوگیری می‌کند.

به دایرکتوری mcp-server بروید: 

cd mcp-server

سرور MCP را روی Cloud Run مستقر کنید: 

gcloud run deploy mcp-server --no-allow-unauthenticated --region=us-central1 --source .

اگر سرویس شما با موفقیت مستقر شده باشد، پیامی مانند پیام زیر مشاهده خواهید کرد: 

Service [mcp-server] revision [mcp-server-12345-abc] has been deployed and is serving 100 percent of traffic.

احراز هویت کلاینت‌های MCP

از آنجایی که شما برای احراز هویت --no-allow-unauthenticated مشخص کرده‌اید، هر کلاینت MCP که به سرور MCP از راه دور متصل می‌شود، نیاز به احراز هویت خواهد داشت.

مستندات رسمی مربوط به سرورهای Host MCP در Cloud Run، بسته به محل اجرای کلاینت MCP، اطلاعات بیشتری در این زمینه ارائه می‌دهد.

برای ایجاد یک تونل احراز هویت شده به سرور MCP از راه دور در دستگاه محلی خود، باید پروکسی Cloud Run را اجرا کنید.

به طور پیش‌فرض، URL سرویس‌های Cloud Run مستلزم آن است که همه درخواست‌ها با نقش IAM مربوط به Cloud Run Invoker ( roles/run.invoker ) مجاز شوند. این الزام‌آوری سیاست IAM تضمین می‌کند که از یک مکانیسم امنیتی قوی برای احراز هویت کلاینت محلی MCP شما استفاده می‌شود.

شما باید مطمئن شوید که شما یا هر یک از اعضای تیم که سعی در دسترسی به سرور MCP از راه دور دارید، نقش IAM roles/run.invoker را به حساب اصلی IAM خود (حساب Google Cloud) متصل کرده‌اید.

gcloud run services proxy mcp-server --region=us-central1

شما باید خروجی زیر را ببینید: 

Proxying to Cloud Run service [mcp-server] in project [<YOUR_PROJECT_ID>] region [us-central1]
http://127.0.0.1:8080 proxies to https://mcp-server-abcdefgh-uc.a.run.app

اکنون تمام ترافیک به آدرس http://127.0.0.1:8080 احراز هویت شده و به سرور راه دور MCP ارسال می‌شود.

سرور MCP از راه دور را آزمایش کنید

در یک ترمینال جدید ، به پوشه ریشه برگردید و فایل mcp-server/test_server.py را دوباره اجرا کنید تا مطمئن شوید که سرور مجازی MCP از راه دور کار می‌کند.

cd ..
uv run mcp-server/test_server.py

شما باید خروجی مشابهی را که هنگام اجرای سرور به صورت محلی مشاهده کردید، مشاهده کنید: 

--- 🛠️ Tool found: get_exchange_rate ---
--- 🪛 Calling get_exchange_rate tool for USD to EUR ---
--- ✅ Success: {
  "amount": 1.0,
  "base": "USD",
  "date": "2025-05-26",
  "rates": {
    "EUR": 0.87866
  }
} ---

اگر می‌خواهید تأیید کنید که سرور راه دور واقعاً فراخوانی شده است، می‌توانید گزارش‌های سرور Cloud Run MCP مستقر شده را بررسی کنید: 

gcloud run services logs read mcp-server --region us-central1 --limit 5

شما باید خروجی زیر را در لاگ‌ها مشاهده کنید: 

2025-06-04 14:28:29,871 [INFO]: --- 🛠️ Tool: get_exchange_rate called for converting USD to EUR ---
2025-06-04 14:28:30,610 [INFO]: HTTP Request: GET https://api.frankfurter.app/latest?from=USD&to=EUR "HTTP/1.1 200 OK"
2025-06-04 14:28:30,611 [INFO]: ✅ API response: {'amount': 1.0, 'base': 'USD', 'date': '2025-06-03', 'rates': {'EUR': 0.87827}}

حالا که یک سرور MCP از راه دور دارید، می‌توانید به سراغ ایجاد یک عامل (ایجنت) بروید! 🤖

۵. با ADK یک Agent ایجاد کنید

شما یک سرور MCP مستقر دارید، اکنون زمان آن رسیده است که عامل ارزی را با استفاده از کیت توسعه عامل (ADK) ایجاد کنید.

ADK ایجاد عامل‌ها را بسیار سبک می‌کند و به آنها اجازه می‌دهد تا با پشتیبانی داخلی از ابزارهای MCP به سرورهای MCP متصل شوند. عامل ارزی با استفاده از کلاس MCPToolset ADK به ابزار get_exchange_rate دسترسی پیدا می‌کند.

کد مربوط به عامل ارزی در currency_agent/agent.py قرار دارد: 

import logging
import os

from dotenv import load_dotenv
from google.adk.agents import LlmAgent
from google.adk.a2a.utils.agent_to_a2a import to_a2a
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

load_dotenv()

SYSTEM_INSTRUCTION = (
    "You are a specialized assistant for currency conversions. "
    "Your sole purpose is to use the 'get_exchange_rate' tool to answer questions about currency exchange rates. "
    "If the user asks about anything other than currency conversion or exchange rates, "
    "politely state that you cannot help with that topic and can only assist with currency-related queries. "
    "Do not attempt to answer unrelated questions or use tools for other purposes."
)

logger.info("--- 🔧 Loading MCP tools from MCP Server... ---")
logger.info("--- 🤖 Creating ADK Currency Agent... ---")

root_agent = LlmAgent(
    model="gemini-3.7-flash",
    name="currency_agent",
    description="An agent that can help with currency conversions",
    instruction=SYSTEM_INSTRUCTION,
    tools=[
        MCPToolset(
            connection_params=StreamableHTTPConnectionParams(
                url=os.getenv("MCP_SERVER_URL", "http://localhost:8080/mcp")
            )
        )
    ],
)

برای آزمایش سریع عامل ارزی، می‌توانید از رابط کاربری توسعه‌دهندگان ADK که با اجرای adk web قابل دسترسی است، بهره ببرید: 

uv run adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

در مرورگر، به آدرس http://localhost:8000 بروید تا عامل را ببینید و آزمایش کنید!

مطمئن شوید که currency_agent به عنوان عامل در گوشه بالا سمت چپ رابط کاربری وب انتخاب شده باشد.

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

از نماینده خود در قسمت چت چیزی شبیه به «مبدل ۲۵۰ دلار کانادا به دلار آمریکا» بپرسید. قبل از اینکه نماینده پاسخی بدهد، باید ابزار MCP ما به get_exchange_rate را فراخوانی کند.

کارگزار ارز وب ADK

ایجنت کار می‌کند! می‌تواند کوئری‌هایی که حول تبدیل ارز می‌چرخند را مدیریت کند 💸.

۶. پروتکل Agent2Agent (A2A)

پروتکل Agent2Agent (A2A) یک استاندارد باز است که برای ایجاد ارتباط و همکاری یکپارچه بین عامل‌های هوش مصنوعی طراحی شده است. این پروتکل به عامل‌هایی که با استفاده از چارچوب‌های متنوع و توسط فروشندگان مختلف ساخته شده‌اند، اجازه می‌دهد تا با یک زبان مشترک با یکدیگر ارتباط برقرار کنند، بخش‌های مجزا را از بین ببرند و قابلیت همکاری را تقویت کنند.

پروتکل A2A

A2A به نمایندگان اجازه می‌دهد تا:

  • کشف: با استفاده از کارت‌های استاندارد مامور، مامورهای دیگر را پیدا کنید و مهارت‌ها ( AgentSkill ) و قابلیت‌های ( AgentCapabilities ) آنها را بیاموزید.
  • ارتباط برقرار کنید: پیام‌ها و داده‌ها را به صورت ایمن تبادل کنید.
  • همکاری: وظایف را واگذار کنید و اقدامات را برای دستیابی به اهداف پیچیده هماهنگ کنید.

پروتکل A2A این ارتباط را از طریق مکانیسم‌هایی مانند «کارت‌های عامل» تسهیل می‌کند که به عنوان کارت‌های ویزیت دیجیتال عمل می‌کنند و عامل‌ها می‌توانند از آنها برای تبلیغ قابلیت‌ها و اطلاعات اتصال خود استفاده کنند.

کارت نماینده A2A

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

کیت توسعه نرم‌افزاری پایتون A2A

کیت توسعه نرم‌افزار پایتون A2A مدل‌های Pydantic را برای هر یک از منابع فوق‌الذکر؛ AgentSkill ، AgentCapabilities و AgentCard ارائه می‌دهد. این امر رابطی برای تسریع توسعه و ادغام با پروتکل A2A فراهم می‌کند.

AgentSkill روشی است که شما به سایر عامل‌ها اعلام می‌کنید که عامل ارزی ابزاری برای get_exchange_rate دارد: 

# A2A Agent Skill definition
skill = AgentSkill(
    id='get_exchange_rate',
    name='Currency Exchange Rates Tool',
    description='Helps with exchange values between various currencies',
    tags=['currency conversion', 'currency exchange'],
    examples=['What is exchange rate between USD and GBP?'],
)

سپس به عنوان بخشی از AgentCard مهارت‌ها و قابلیت‌های عامل را در کنار جزئیات اضافی مانند حالت‌های ورودی و خروجی که عامل می‌تواند مدیریت کند، فهرست می‌کند: 

# A2A Agent Card definition
agent_card = AgentCard(
    name='Currency Agent',
    description='Helps with exchange rates for currencies',
    url=f'http://{host}:{port}/',
    version='1.0.0',
    defaultInputModes=["text"],
    defaultOutputModes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    skills=[skill],
)

وقت آن رسیده که همه چیز را با نماینده ارز کنار هم بگذاریم و قدرت A2A را به نمایش بگذاریم!

۷. عامل ارزی را به عنوان سرور A2A نمایش دهید

ADK فرآیند ساخت و اتصال عامل‌ها را با استفاده از پروتکل A2A برای شما ساده می‌کند. در دسترس قرار دادن (در معرض دید قرار دادن) یک عامل ADK موجود به عنوان یک سرور A2A با تابع to_a2a(root_agent) ADK انجام می‌شود (برای جزئیات کامل به مستندات ADK مراجعه کنید).

تابع to_a2a یک عامل موجود را برای کار با A2A تبدیل می‌کند و می‌تواند آن را به عنوان یک سرور از طریق uvicorn در معرض نمایش قرار دهد. این بدان معناست که اگر قصد دارید عامل خود را تولید کنید، کنترل دقیق‌تری بر آنچه می‌خواهید نمایش دهید، دارید. تابع to_a2a() به طور خودکار یک کارت عامل را بر اساس کد عامل شما با استفاده از SDK پایتون A2A در زیر کاپوت تولید می‌کند.

با نگاهی به داخل فایل currency_agent/agent.py می‌توانید نحوه‌ی استفاده از to_a2a و نحوه‌ی نمایش عامل ارزی به عنوان یک سرور A2A تنها با دو خط کد را مشاهده کنید! 

from google.adk.a2a.utils.agent_to_a2a import to_a2a
# ... see file for full code

# Make the agent A2A-compatible
a2a_app = to_a2a(root_agent, port=10000)

برای اجرای سرور A2A، در یک ترمینال جدید دستور زیر را اجرا کنید: 

uv run uvicorn currency_agent.agent:a2a_app --host localhost --port 10000

اگر سرور با موفقیت شروع به کار کند، خروجی به شکل زیر خواهد بود که نشان می‌دهد روی پورت ۱۰۰۰۰ در حال اجرا است: 

[INFO]: --- 🔧 Loading MCP tools from MCP Server... ---
[INFO]: --- 🤖 Creating ADK Currency Agent... ---
INFO:     Started server process [45824]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://localhost:10000 (Press CTRL+C to quit)

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

تأیید کنید که Remote Agent در حال اجرا است

شما می‌توانید با مراجعه به آدرس اینترنتی کارت عامل ارزی که به طور خودکار توسط تابع to_a2a() ایجاد شده است، دوباره بررسی کنید که عامل شما فعال و در حال اجرا است.

در مرورگر خود، به آدرس http://localhost:10000/.well-known/agent-card.json بروید.

شما باید کارت مامور زیر را ببینید: 

{
  "capabilities": {

  },
  "defaultInputModes": [
    "text/plain"
  ],
  "defaultOutputModes": [
    "text/plain"
  ],
  "description": "An agent that can help with currency conversions",
  "name": "currency_agent",
  "preferredTransport": "JSONRPC",
  "protocolVersion": "0.3.0",
  "skills": [
    {
      "description": "An agent that can help with currency conversions I am a specialized assistant for currency conversions. my sole purpose is to use the 'get_exchange_rate' tool to answer questions about currency exchange rates. If the user asks about anything other than currency conversion or exchange rates, politely state that I cannot help with that topic and can only assist with currency-related queries. Do not attempt to answer unrelated questions or use tools for other purposes.",
      "id": "currency_agent",
      "name": "model",
      "tags": [
        "llm"
      ]
    },
    {
      "description": "Use this to get current exchange rate.\n\nArgs:\n    currency_from: The currency to convert from (e.g., \"USD\").\n    currency_to: The currency to convert to (e.g., \"EUR\").\n    currency_date: The date for the exchange rate or \"latest\". Defaults to \"latest\".\n\nReturns:\n    A dictionary containing the exchange rate data, or an error message if the request fails.",
      "id": "currency_agent-get_exchange_rate",
      "name": "get_exchange_rate",
      "tags": [
        "llm",
        "tools"
      ]
    }
  ],
  "supportsAuthenticatedExtendedCard": false,
  "url": "http://localhost:10000",
  "version": "0.0.1"
}

سرور A2A را آزمایش کنید

اکنون می‌توانید با ارسال چند درخواست با استفاده از A2A، سرور را آزمایش کنید!

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

فایل currency_agent/test_a2aclient.py حاوی کدی است که نحوه دریافت کارت مامور و ارسال پیام به سرور A2A را نشان می‌دهد. 

# ... see file for full code

async def get_agent_card():
    """Get the agent card."""
    print(f"🔄 Fetching the agent card at {AGENT_URL}")

    async with httpx.AsyncClient() as httpx_client:
        resolver = A2ACardResolver(
            httpx_client=httpx_client,
            base_url=AGENT_URL,
        )
        public_agent_card = await resolver.get_agent_card()
        print("✅ Successfully fetched the agent card")
    return public_agent_card


async def send_message(text_query: str) -> None:
    """
    Send a text query to the agent and print the response.
    """
    public_agent_card = await get_agent_card()

    print("🔄 Initializing a non-streaming client")
    config = ClientConfig(streaming=False)
    client = await create_client(agent=public_agent_card, client_config=config)

    message = new_text_message(text_query, role=Role.ROLE_USER)
    print("Sending request:")
    request = SendMessageRequest(message=message)
    print(request)

    print("Response:")
    async for chunk in client.send_message(request):
        print(chunk)
    await client.close()

تست‌ها را با استفاده از دستور زیر اجرا کنید: 

uv run currency_agent/test_a2aclient.py

یک آزمایش موفق منجر به موارد زیر خواهد شد: 

🔄 Fetching the agent card at http://localhost:10000
✅ Successfully fetched the agent card
====================================================
                     AgentCard                      
====================================================
--- General ---
Name        : currency_agent
Description : An agent that can help with currency conversions
Version     : 0.0.1

--- Interfaces ---
  [0] http://localhost:10000  (JSONRPC 1.0)

--- Capabilities ---
Streaming           : False
Push notifications  : False
Extended agent card : False

--- I/O Modes ---
Input  : text/plain
Output : text/plain

--- Skills ---
----------------------------------------------------
  ID          : currency_agent
  Name        : model
  Description : An agent that can help with currency conversions
  Tags        : llm
----------------------------------------------------
  ID          : currency_agent-get_exchange_rate
  Name        : get_exchange_rate
  Description : Use this to get current exchange rate.
  Tags        : llm, tools
====================================================
🔄 Fetching the agent card at http://localhost:10000
✅ Successfully fetched the agent card
🔄 Initializing a non-streaming client
Sending request:
message {
  message_id: "5d190c88-336e-4a22-925d-e2af49cf4bad"
  role: ROLE_USER
  parts {
    text: "how much is 100 USD in GBP?"
  }
}

Response:
task {
  id: "e6f311bb-654a-477f-82a9-81c7a48f7b81"
  context_id: "672e351b-0ff3-4aed-a059-868b383c41a0"
  status {
    state: TASK_STATE_COMPLETED
    timestamp {
      seconds: 1787836031
      nanos: 994786000
    }
  }
  artifacts {
    artifact_id: "e0a05ac8-25c7-471c-a33c-1073fe48cbb8"
    parts {
      text: "100 USD is currently equal to approximately **73.37 GBP** (at an exchange rate of 1 USD = 0.73368 GBP)."
    }
  }
  ...

کار می‌کند! شما با موفقیت آزمایش کردید که می‌توانید از طریق پروتکل A2A با یک کلاینت A2A با نماینده ارز ارتباط برقرار کنید! 🎉

برای نمونه‌های بیشتر A2A ، مخزن a2a-samples را در گیت‌هاب بررسی کنید.

۸. از طریق A2A، عامل ارز از راه دور را مصرف کنید

در مرحله قبل، شما از یک کلاینت A2A برای ارتباط با نماینده ارزی از طریق A2A استفاده کردید.

در این مرحله، بیایید ببینیم چگونه می‌توانید از نماینده ارز به عنوان یک نماینده از راه دور از یک آژانس مسافرتی دیگر استفاده کنید.

کد آژانس مسافرتی در travel_agent/agent.py قرار دارد: 

import logging
import os

from dotenv import load_dotenv
from google.adk.agents import LlmAgent
from google.adk.tools.agent_tool import AgentTool
from google.adk.agents.remote_a2a_agent import RemoteA2aAgent, AGENT_CARD_WELL_KNOWN_PATH

logger = logging.getLogger(__name__)
logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO)

load_dotenv()

SYSTEM_INSTRUCTION = (
    "You are a helpful travel assistant. You help users plan trips, recommend places, "
    "and answer travel-related questions. "
    "Whenever a user asks about currency exchange rates or money conversions, "
    "delegate the request to the 'currency_agent' sub-agent."
)

CURRENCY_AGENT_URL = os.getenv("CURRENCY_AGENT_URL", "http://localhost:10000")

logger.info(
    "--- 🔗 Connecting to Remote A2A Currency Agent at %s... ---",
    CURRENCY_AGENT_URL,
)

currency_remote_agent = RemoteA2aAgent(
    name="currency_agent",
    agent_card=f"{CURRENCY_AGENT_URL}{AGENT_CARD_WELL_KNOWN_PATH}",
    description="An agent that can help with currency conversions and exchange rates.",
)

logger.info("--- 🤖 Creating ADK Travel Agent... ---")

root_agent = LlmAgent(
    model="gemini-3.7-flash",
    name="travel_agent",
    description="A travel assistant that can help plan trips and convert currencies via the remote currency agent.",
    instruction=SYSTEM_INSTRUCTION,
    tools=[AgentTool(agent=currency_remote_agent)],
)

توجه کنید که چگونه با استفاده از RemoteA2aAgent به Currency Agent دسترسی پیدا می‌شود.

برای آزمایش آژانس مسافرتی، adk web را اجرا کنید: 

uv run adk web --allow_origins "regex:https://.*\.cloudshell\.dev"

در مرورگر، برای مشاهده و آزمایش عامل، به آدرس http://localhost:8000 بروید.

مطمئن شوید که travel_agent به عنوان عامل در گوشه بالا سمت چپ رابط کاربری وب انتخاب شده باشد.

از نماینده خود در قسمت چت چیزی شبیه به این بپرسید : «مبدل ۲۵۰ دلار کانادا به دلار آمریکا چقدر است؟»

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

کارگزار ارزی از راه دور تحت وب ADK

ایجنت کار می‌کند! می‌تواند با تماس با یک ایجنت از راه دور با استفاده از A2A، به درخواست‌هایی که حول تبدیل ارز می‌چرخند 💸 رسیدگی کند!

۹. تبریک

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

این هم لینک مستندات کامل کد.

آیا به دنبال استقرار عامل خود هستید؟ Agent Runtime پلتفرم Gemini Enterprise Agent، یک تجربه مدیریت‌شده برای استقرار عامل‌های هوش مصنوعی در محیط عملیاتی ارائه می‌دهد!

آنچه ما پوشش داده‌ایم

  • نحوه ایجاد یک سرور محلی MCP
  • استقرار سرور MCP در Cloud Run
  • نحوه ساخت یک عامل با کیت توسعه عامل که از ابزارهای MCP استفاده می‌کند
  • نحوه نمایش یک عامل ADK به عنوان سرور A2A
  • آزمایش سرور A2A با استفاده از کلاینت A2A
  • چگونه یک عامل بسازیم که از طریق پروتکل A2A با عامل دیگری صحبت کند

تمیز کردن

برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع مورد استفاده در این آزمایشگاه، این مراحل را دنبال کنید:

  1. در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
  2. در لیست پروژه‌ها، پروژه‌ای را که می‌خواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
  3. در کادر محاوره‌ای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.