۱. مرور کلی
عاملهای هوش مصنوعی به سرعت در حال افزایش محبوبیت هستند و با توانایی خود در عملکرد خودکار، یادگیری و تعامل با محیط خود برای دستیابی به اهداف، انقلابی در اتوماسیون وظایف و تصمیمگیری ایجاد میکنند.
اما دقیقاً چگونه میتوان یک عامل (agent) ساخت؟ این آزمایشگاه کد با نشان دادن نحوه ساخت یک عامل ارزی که میتواند ارزهای کشورهای مختلف را به هم تبدیل کند، به شما در شروع کار کمک خواهد کرد. با هدف آشنایی با جدیدترین فناوریها برای کمک به شما در درک کلمات اختصاری که ممکن است در اینترنت دیده باشید (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
آنچه نیاز دارید
۲. قبل از شروع
ایجاد یک پروژه
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
- با کلیک روی این لینک، 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های مورد نیاز را فعال کنید. این کار ممکن است چند دقیقه طول بکشد.
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 (برای مدیریت وابستگیها استفاده میشود):
# 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):
با اجرای دستور زیر، یک فایل .env ایجاد کنید:
echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> .env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> .env \
&& echo "GOOGLE_CLOUD_LOCATION=us-central1" >> .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)
شما یک سرور MCP مستقر دارید، اکنون زمان آن رسیده است که عامل ارزی را با استفاده از کیت توسعه عامل (ADK) ایجاد کنید.
کیت توسعه عامل (Agent Development Kit) اخیراً نسخه پایدار v1.0.0 خود را منتشر کرد. این نقطه عطف نشان میدهد که پایتون 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-2.5-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
در مرورگر، به آدرس http://localhost:8000 بروید تا عامل را ببینید و آزمایش کنید!
مطمئن شوید که currency_agent به عنوان عامل در گوشه بالا سمت چپ رابط کاربری وب انتخاب شده باشد.
از نماینده خود در قسمت چت چیزی شبیه به «مبدل ۲۵۰ دلار کانادا به دلار آمریکا» بپرسید. قبل از اینکه نماینده پاسخی بدهد، باید ابزار MCP ما به get_exchange_rate را فراخوانی کند.
ایجنت کار میکند! میتواند کوئریهایی که حول تبدیل ارز میچرخند را مدیریت کند 💸.
۷. پروتکل Agent2Agent (A2A)
پروتکل Agent2Agent (A2A) یک استاندارد باز است که برای ایجاد ارتباط و همکاری یکپارچه بین عاملهای هوش مصنوعی طراحی شده است. این پروتکل به عاملهایی که با استفاده از چارچوبهای متنوع و توسط فروشندگان مختلف ساخته شدهاند، اجازه میدهد تا با یک زبان مشترک با یکدیگر ارتباط برقرار کنند، بخشهای مجزا را از بین ببرند و قابلیت همکاری را تقویت کنند.
A2A به نمایندگان اجازه میدهد تا:
- کشف: با استفاده از کارتهای استاندارد مامور، مامورهای دیگر را پیدا کنید و مهارتها ( AgentSkill ) و قابلیتهای ( AgentCapabilities ) آنها را بیاموزید.
- ارتباط برقرار کنید: پیامها و دادهها را به صورت ایمن تبادل کنید.
- همکاری: وظایف را واگذار کنید و اقدامات را برای دستیابی به اهداف پیچیده هماهنگ کنید.
پروتکل 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.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.A2AClient ارائه میدهد که این کار را برای شما ساده میکند.
فایل currency_agent/test_client.py حاوی کدی است که چندین مورد آزمایشی مختلف را روی سرور A2A اجرا میکند.
# ... see file for full code
# Example test using A2AClient
async def run_single_turn_test(client: A2AClient) -> None:
"""Runs a single-turn non-streaming test."""
send_message_payload = create_send_message_payload(text="how much is 100 USD in CAD?")
request = SendMessageRequest(
id=str(uuid4()), params=MessageSendParams(**send_message_payload)
)
print("--- ✉️ Single Turn Request ---")
# Send Message
response: SendMessageResponse = await client.send_message(request)
print_json_response(response, "📥 Single Turn Request Response")
if not isinstance(response.root, SendMessageSuccessResponse):
print("received non-success response. Aborting get task ")
return
if not isinstance(response.root.result, Task):
print("received non-task response. Aborting get task ")
return
task_id: str = response.root.result.id
print("--- ❔ Query Task ---")
# query the task
get_request = GetTaskRequest(id=str(uuid4()), params=TaskQueryParams(id=task_id))
get_response: GetTaskResponse = await client.get_task(get_request)
print_json_response(get_response, "📥 Query Task Response")
# ----- Main Entrypoint (Create client --> Run tests) -----
async def main() -> None:
"""Main function to run the tests."""
print(f'--- 🔄 Connecting to agent at {AGENT_URL}... ---')
try:
async with httpx.AsyncClient() as httpx_client:
# Create a resolver to fetch the agent card
resolver = A2ACardResolver(
httpx_client=httpx_client,
base_url=AGENT_URL,
)
agent_card = await resolver.get_agent_card()
# Create a client to interact with the agent
client = A2AClient(
httpx_client=httpx_client,
agent_card=agent_card,
)
print('--- ✅ Connection successful. ---')
await run_single_turn_test(client)
await run_multi_turn_test(client)
except Exception as e:
traceback.print_exc()
print(f'--- ❌ An error occurred: {e} ---')
print('Ensure the agent server is running.')
تستها را با استفاده از دستور زیر اجرا کنید:
uv run currency_agent/test_client.py
یک آزمایش موفق منجر به موارد زیر خواهد شد:
--- 🔄 Connecting to agent at http://localhost:10000... ---
--- ✅ Connection successful. ---
--- ✉️ Single Turn Request ---
--- 📥 Single Turn Request Response ---
{"id":"3bc92d7b-d857-4e93-9ff0-b2fb865f6e35","jsonrpc":"2.0","result":{"artifacts":[{"artifactId":"35e89e14-b977-4397-a23b-92c84bc32379","parts":[{"kind":"text","text":"Based on the current exchange rate, 1 USD is equivalent to 1.3704 CAD. Therefore, 100 USD would be 137.04 CAD.\n"}]}],"contextId":"2d66f277-152c-46ef-881d-7fe32866e9f5","history":[{"contextId":"2d66f277-152c-46ef-881d-7fe32866e9f5","kind":"message","messageId":"59819269f7d04849b0bfca7d43ec073c","parts":[{"kind":"text","text":"how much is 100 USD in CAD?"}],"role":"user","taskId":"52ae2392-84f5-429a-a14b-8413d3d20d97"},{"contextId":"2d66f277-152c-46ef-881d-7fe32866e9f5","kind":"message","messageId":"286095c6-12c9-40cb-9596-a9676d570dbd","parts":[],"role":"agent","taskId":"52ae2392-84f5-429a-a14b-8413d3d20d97"}],"id":"52ae2392-84f5-429a-a14b-8413d3d20d97","kind":"task","status":{"state":"completed"}}}
// ...
--- 🚀 First turn completed, no further input required for this test case. ---
کار میکند! شما با موفقیت آزمایش کردید که میتوانید از طریق یک سرور A2A با نماینده ارز ارتباط برقرار کنید! 🎉
برای مشاهده موارد استفاده پیشرفتهتر، مخزن a2a-samples را در گیتهاب بررسی کنید!
آیا به دنبال استقرار عامل خود هستید؟ موتور عامل هوش مصنوعی ورتکس (Vertex AI Agent Engine) یک تجربه مدیریتشده برای استقرار عاملهای هوش مصنوعی در محیط عملیاتی ارائه میدهد!
۹. تبریک
تبریک! شما با موفقیت یک سرور MCP از راه دور ساختید و مستقر کردید، یک عامل ارزی با استفاده از کیت توسعه عامل (ADK) ایجاد کردید که با استفاده از MCP به ابزارها متصل میشود و عامل خود را با استفاده از پروتکل Agent2Agent (A2A) در معرض دید قرار دادید! عامل ارزی اکنون برای تعامل با سایر عاملهای هر چارچوبی که از A2A استفاده میکند، در دسترس است!
این هم لینک مستندات کامل کد.
آنچه ما پوشش دادهایم
- نحوه ایجاد یک سرور محلی MCP
- استقرار سرور MCP در Cloud Run
- نحوه ساخت یک عامل با کیت توسعه عامل که از ابزارهای MCP استفاده میکند
- نحوه نمایش یک عامل ADK به عنوان سرور A2A
- آزمایش سرور A2A با استفاده از کلاینت A2A
تمیز کردن
برای جلوگیری از تحمیل هزینه به حساب Google Cloud خود برای منابع مورد استفاده در این آزمایشگاه، این مراحل را دنبال کنید:
- در کنسول گوگل کلود، به صفحه مدیریت منابع بروید.
- در لیست پروژهها، پروژهای را که میخواهید حذف کنید انتخاب کنید و سپس روی «حذف» کلیک کنید.
- در کادر محاورهای، شناسه پروژه را تایپ کنید و سپس برای حذف پروژه، روی خاموش کردن کلیک کنید.