۱. قبل از شروع
به بخش دوم مجموعه «ساخت عامل‌های هوش مصنوعی با ADK» خوش آمدید! در این آزمایشگاه کد عملی، شما یک عامل هوش مصنوعی پایه را با ابزارهای متنوعی توانمند خواهید کرد.
برای شروع، این راهنما دو مسیر ارائه می‌دهد: یکی برای کسانی که از آزمایشگاه کد « ساخت عامل‌های هوش مصنوعی با ADK: The Foundation » ادامه می‌دهند، و دیگری برای کسانی که تازه شروع کرده‌اند. هر دو مسیر تضمین می‌کنند که شما کد عامل پایه لازم را برای شروع دارید.
در پایان این آزمایشگاه کد، شما دستیار شخصی خود را با ابزارهایی برای اهداف مختلف توانمند خواهید کرد، و یک قدم به گسترش آن در بخش‌های بعدی این مجموعه نزدیک‌تر خواهید شد، زیرا آن را به یک سیستم چندعاملی (MAS) پیچیده تبدیل می‌کنیم.
همچنین می‌توانید از طریق این آدرس کوتاه‌شده‌ی goo.gle/adk-using-tools به این آزمایشگاه کد دسترسی پیدا کنید.
پیش‌نیازها
- درک مفاهیم هوش مصنوعی مولد
- تسلط اولیه به برنامه نویسی پایتون
- ساخت عامل‌های هوش مصنوعی را با ADK: The Foundation codelab یا مشابه آن تکمیل کردم.
آنچه یاد خواهید گرفت
- با ساخت توابع پایتون سفارشی به عنوان ابزار، به عامل خود مهارت‌های جدیدی بدهید.
- با استفاده از ابزارهای داخلی مانند جستجوی گوگل، نماینده خود را به اطلاعات بلادرنگ متصل کنید.
- با ایجاد زیرعامل‌های تخصصی برای وظایف پیچیده، یک عامل چندابزاری بسازید.
- ابزارهایی از چارچوب‌های هوش مصنوعی محبوب مانند LangChain را برای گسترش سریع قابلیت‌ها ادغام کنید.
آنچه نیاز دارید
- یک کامپیوتر سالم و وای فای قابل اعتماد
- یک مرورگر، مانند کروم ، برای دسترسی به کنسول ابری گوگل
- ذهن کنجکاو و اشتیاق به یادگیری
۲. مقدمه
یک عامل پایه که با ADK ساخته شده است، مغز LLM قدرتمندی دارد، اما محدودیت‌هایی نیز دارد: نمی‌تواند به اطلاعات ایجاد شده پس از تاریخ آموزش خود دسترسی پیدا کند و نمی‌تواند با سرویس‌های خارجی تعامل داشته باشد. مانند یک دستیار باهوش و کتابخوان است که در کتابخانه‌ای بدون تلفن یا اینترنت حبس شده است. برای اینکه یک عامل واقعاً مفید باشد، باید به آن ابزار بدهیم.
ابزارها را به عنوان دسترسی دستیار هوش مصنوعی به دنیای خارج در نظر بگیرید: یک ماشین حساب، یک مرورگر وب یا دسترسی به پایگاه داده یک شرکت خاص. در ADK، یک ابزار یک قطعه کد ماژولار است که به عامل اجازه می‌دهد اقدامات خاصی مانند جستجوی داده‌های بلادرنگ یا فراخوانی یک API خارجی را انجام دهد. استفاده از ابزارها قابلیت‌های آن را بسیار فراتر از یک مکالمه ساده گسترش می‌دهد.
ADK سه دسته ابزار ارائه می‌دهد:
- ابزارهای تابعی: ابزارهای سفارشی که شما برای برآورده کردن نیازهای منحصر به فرد برنامه خود، مانند توابع و عامل‌های از پیش تعریف شده، توسعه می‌دهید.
- ابزارهای داخلی: ابزارهای آماده برای استفاده که توسط چارچوب برای عملیات رایج، مانند جستجوی گوگل و اجرای کد، ارائه شده‌اند.
- ابزارهای شخص ثالث: کتابخانه‌های خارجی محبوب مانند Serper و ابزارهایی از LangChain و CrewAI.
برای کسب اطلاعات بیشتر در مورد استفاده از ابزارها با ADK Agents، به مستندات رسمی نگاهی بیندازید. در این آزمایشگاه کد، ابزارهایی را برای تبدیل Agent ساده خود به یک دستیار شخصی مسافرتی توانمند اضافه خواهیم کرد. بیایید شروع کنیم!
۳. شروع کار: عامل پایه شما
قبل از اینکه بتوانید یک عامل را با ابزارها توانمند کنید، به یک عامل پایه برای کار نیاز دارید. مسیری را انتخاب کنید که به بهترین وجه با پیشرفت شما مطابقت داشته باشد.
مسیر الف: ادامه از بنیاد Codelab
اگر به تازگی بخش « ساخت عامل‌های هوش مصنوعی با ADK: The Foundation » را تکمیل کرده‌اید، همه چیز آماده است. می‌توانید به کار خود در دایرکتوری پروژه ai-agents-adk موجود ادامه دهید.
مسیر ب: شروع تازه
اگر مستقیماً این codelab را شروع می‌کنید، این ۴ مرحله را برای راه‌اندازی محیط خود و ایجاد عامل آغازگر لازم انجام دهید.
- پیکربندی سرویس‌های ابری گوگل
- ایجاد یک محیط مجازی پایتون
- ایجاد یک عامل
- عامل را در رابط کاربری توسعه اجرا کنید
پس از اتمام مراحل، آماده‌اید تا سفر یادگیری خود را آغاز کنید.
۴. یک ابزار سفارشی برای تبادل ارز بسازید
در این مرحله، شما باید از قبل بدانید که چگونه یک عامل هوش مصنوعی ساده را با استفاده از ADK بسازید و آن را روی رابط کاربری توسعه اجرا کنید.
تصور کنید که برای سفر به ژاپن در ماه آینده آماده می‌شوید و باید نرخ ارز فعلی را بررسی کنید. از نماینده بپرسید : «نرخ تبدیل دلار سنگاپور به ین ژاپن چقدر است؟»
خواهید دید که عامل نمی‌تواند نرخ ارز را به صورت آنی دریافت کند. دلیل این امر این است که عامل در حال حاضر به اینترنت و اتصال به سیستم خارجی دسترسی ندارد. حتی اگر عامل با یک مقدار پاسخ دهد، اعتماد به آن مقدار دشوار است زیرا احتمالاً توهم خواهد بود.
برای پرداختن به این موضوع، ما یک تابع پایتون برای بازیابی نرخ ارز از طریق یک REST API پیاده‌سازی خواهیم کرد و آن را به عنوان یک ابزار تابعی برای عامل ادغام خواهیم کرد.
با استفاده از میانبر صفحه کلید Ctrl + C در پنجره ترمینال، فرآیند عامل در حال اجرا را خاتمه دهید.
ایجاد فایل custom_functions.py
با تایپ این دستور در ترمینال، یک فایل پایتون با نام custom_functions.py در پوشه personal_assistant ایجاد کنید .
touch personal_assistant/custom_functions.py
ساختار پوشه‌های شما باید به این شکل باشد:
ai-agents-adk/
└── personal_assistant/
├── .env
├── __init__.py
├── agent.py
└── custom_functions.py
فایل custom_functions.py را در ویرایشگر کد باز کنید. این فایل شامل تابع پایتونی است که مسئول بازیابی داده‌های نرخ ارز از یک API خارجی است.
کد زیر را کپی و داخل آن قرار دهید:
import requests
# define a function to get exchange rate
def get_fx_rate(base: str, target: str):
"""
Fetches the current exchange rate between two currencies.
Args:
base: The base currency (e.g., "SGD").
target: The target currency (e.g., "JPY").
Returns:
The exchange rate information as a json response,
or None if the rate could not be fetched.
"""
base_url = "https://hexarate.paikama.co/api/rates/latest"
api_url = f"{base_url}/{base}?target={target}"
response = requests.get(api_url)
if response.status_code == 200:
return response.json()
حالا، فایل agent.py را ویرایش کنید: تابع get_fx_rate را وارد کنید و آن را به عنوان یک FunctionTool اختصاص دهید.
فایل agent.py را به‌روزرسانی کنید
این کد بلاک را کپی کرده و محتوای موجود فایل agent.py را جایگزین کنید:
from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from .custom_functions import get_fx_rate
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction='Answer user questions to the best of your knowledge',
tools=[FunctionTool(get_fx_rate)]
)
پس از تغییرات، با تایپ دستور زیر، دوباره عامل را شروع کنید:
adk web
وقتی مامور بالا رفت، دوباره همان سوال را بپرسید: «نرخ تبدیل دلار سنگاپور به ین ژاپن چقدر است؟»
این بار باید نرخ واقعی ارز داده شده توسط ابزار get_fx_rate را ببینید.
در صورت تمایل می‌توانید هرگونه سوال مربوط به صرافی را بپرسید.
۵. با ابزار جستجوی داخلی گوگل ادغام شوید
حالا که نماینده قادر به ارائه نرخ ارز است، وظیفه بعدی دریافت پیش‌بینی آب و هوای ماه آینده است. این سوال را از نماینده بپرسید: «پیش‌بینی آب و هوای توکیو، ژاپن برای ماه آینده چیست؟»
همانطور که انتظار می‌رود، پیش‌بینی آب و هوا به اطلاعات بلادرنگ نیاز دارد که عامل ما آن را ندارد. در حالی که می‌توانیم توابع پایتون جدیدی را برای هر مورد استفاده که به داده‌های بلادرنگ نیاز دارد، کدنویسی کنیم، اضافه کردن ابزارهای سفارشی بیشتر و بیشتر به سرعت، عامل را بیش از حد پیچیده و مدیریت آن را دشوار می‌کند.
خوشبختانه، کیت توسعه عامل (ADK) مجموعه‌ای از ابزارهای داخلی ، از جمله جستجوی گوگل را که آماده استفاده هستند، فراهم می‌کند و نحوه تعامل عامل ما با دنیای خارج را ساده می‌کند.
برای تجهیز عامل به ابزار جستجوی گوگل، باید یک الگوی چندعاملی پیاده‌سازی کنید. ابتدا، یک عامل تخصصی ایجاد می‌کنید که تنها وظیفه آن انجام جستجوهای گوگل است. سپس، این عامل جستجوی گوگل جدید را به عنوان یک ابزار به personal_assistant اصلی ما اختصاص می‌دهید. مراحل زیر را دنبال کنید:
فایل custom_agents.py را ایجاد کنید
اکنون، با اجرای این دستور در ترمینال، یک فایل پایتون با نام custom_agents.py در پوشه personal_assistant ایجاد کنید:
touch personal_assistant/custom_agents.py
ساختار پوشه‌های شما الان باید به این شکل باشد:
ai-agents-adk/
└── personal_assistant/
├── .env
├── __init__.py
├── agent.py
├── custom_functions.py
└── custom_agents.py
این فایل شامل کد مربوط به google_search_agent تخصصی خواهد بود. کد زیر را با استفاده از ویرایشگر کد در فایل custom_agents.py کپی کنید.
from google.adk.agents import Agent
from google.adk.tools import google_search
# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
model='gemini-2.5-flash',
name='google_search_agent',
description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
instruction='Use google search to answer user questions about real-time, logistical information.',
tools=[google_search],
)
پس از ایجاد فایل، فایل agent.py را مطابق شکل زیر به‌روزرسانی کنید.
فایل agent.py را به‌روزرسانی کنید
این کد بلاک را کپی کرده و محتوای موجود فایل agent.py را جایگزین کنید:
from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
tools=[
FunctionTool(get_fx_rate),
AgentTool(agent=google_search_agent),
]
)
بیایید الگوی جدید و قدرتمند موجود در کد را بررسی کنیم:
- یک متخصص جدید : ما یک عامل کاملاً جدید به نام
google_search_agentتعریف کرده‌ایم. به توضیحات خاص آن و اینکه تنها ابزار آنgoogle_searchاست توجه کنید. این یک متخصص جستجو است. -
agent_tool.AgentTool: این یک پوشش ویژه از ADK است. کل یک عامل (google_search_agent ما) را می‌گیرد و آن را طوری بسته‌بندی می‌کند که مانند یک ابزار استاندارد به نظر برسد و عمل کند. - یک
root_agentهوشمندتر :root_agentما اکنون یک ابزار جدید دارد:AgentTool(agent=google_search_agent). این ابزار نمی‌داند چگونه در وب جستجو کند، اما می‌داند ابزاری دارد که می‌تواند وظایف جستجو را به آن واگذار کند.
توجه داشته باشید که فیلد دستورالعمل از root_agent حذف شده است. دستورالعمل‌های آن اکنون به طور ضمنی توسط ابزارهای موجود تعریف می‌شوند.
root_agent به یک هماهنگ‌کننده یا روتر تبدیل شده است که وظیفه اصلی آن درک درخواست کاربر و ارسال آن به ابزار صحیح، یا تابع get_fx_rate یا google_search_agent ، است. این طراحی غیرمتمرکز، کلید ساخت سیستم‌های عامل پیچیده و قابل نگهداری است.
حالا، تایپ کنید
adk web
در ترمینال برای شروع نمونه و پرسیدن دوباره این سوال از عامل، "پیش‌بینی آب و هوای توکیو، ژاپن برای ماه آینده چیست؟"
اکنون نماینده از google_search_agent برای دریافت آخرین اطلاعات استفاده می‌کند.
شما می‌توانید یک سوال مربوط به تبادل اطلاعات را نیز امتحان کنید. اکنون کارشناس باید بتواند از ابزار مناسب برای سوال مربوطه استفاده کند.
می‌توانید سوالات دیگری که نیاز به اطلاعات بلادرنگ دارند را از کارشناس بپرسید و مشاهده کنید که چگونه با استفاده از ابزارهایی که در اختیار دارد، به سوالات پاسخ می‌دهد.
6. از ابزار ویکی‌پدیای LangChain استفاده کنید
نماینده ما در حال تبدیل شدن به یک دستیار مسافرتی عالی است. می‌تواند با ابزار get_fx_rate خود، تبدیل ارز را انجام دهد و با ابزار google_search_agent خود، تدارکات را مدیریت کند. اما یک سفر عالی فقط مربوط به تدارکات نیست؛ بلکه مربوط به درک فرهنگ و تاریخ مقصد شماست.
در حالی که google_search_agent می‌تواند حقایق فرهنگی و تاریخی را پیدا کند، اطلاعات از یک منبع اختصاصی مانند ویکی‌پدیا اغلب ساختاریافته‌تر و قابل اعتمادتر است.
خوشبختانه، ADK به گونه‌ای طراحی شده است که بسیار توسعه‌پذیر باشد و به شما امکان می‌دهد ابزارهای سایر چارچوب‌های عامل هوش مصنوعی مانند CrewAI و LangChain را به طور یکپارچه ادغام کنید. این قابلیت همکاری بسیار مهم است زیرا زمان توسعه سریع‌تر را فراهم می‌کند و به شما امکان می‌دهد از ابزارهای موجود دوباره استفاده کنید. برای این مورد استفاده، ما از ابزارهای ویکی‌پدیا از LangChain استفاده خواهیم کرد.
ابتدا، فرآیند عامل در حال اجرا را متوقف کنید ( Ctrl + C ) و با تایپ دستورات زیر در ترمینال ، کتابخانه‌های اضافی را در محیط مجازی فعلی پایتون نصب کنید.
uv pip install langchain-community wikipedia
فایل third_party_tools.py را ایجاد کنید
حالا، با اجرای دستور زیر در ترمینال، یک فایل پایتون با نام third_party_tools.py در پوشه personal_assistant ایجاد کنید:
touch personal_assistant/third_party_tools.py
ساختار پوشه‌های شما الان باید به این شکل باشد:
ai-agents-adk/
└── personal_assistant/
├── .env
├── __init__.py
├── agent.py
├── custom_functions.py
├── custom_agents.py
└── third_party_tools.py
این فایل شامل پیاده‌سازی ابزار ویکی‌پدیای LangChain خواهد بود. کد زیر را با استفاده از ویرایشگر ابری در third_party_tools.py کپی کنید :
from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper
# Configure the Wikipedia LangChain tool to act as our cultural guide
langchain_wikipedia_tool = WikipediaQueryRun(
api_wrapper=WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=3000)
)
# Give the tool a more specific description for our agent
langchain_wikipedia_tool.description = (
"Provides deep historical and cultural information on landmarks, concepts, and places."
"Use this for 'tell me about' or 'what is the history of' type questions."
)
فایل agent.py را به‌روزرسانی کنید
حالا فایل agent.py را با محتوای زیر به‌روزرسانی کنید:
from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.langchain_tool import LangchainTool
from .custom_functions import get_fx_rate
from .custom_agents import google_search_agent
from .third_party_tools import langchain_wikipedia_tool
root_agent = Agent(
model='gemini-2.5-flash',
name='root_agent',
description='A helpful assistant for user questions.',
tools=[
FunctionTool(get_fx_rate),
AgentTool(agent=google_search_agent),
LangchainTool(langchain_wikipedia_tool),
]
)
حالا، تایپ کنید
adk web
در ترمینال برای شروع نمونه و پرسیدن این سوال از عامل، «درباره تاریخچه کیوتو به من بگو».
نماینده به درستی این را به عنوان یک پرس و جوی تاریخی شناسایی می‌کند و از ابزار جدید ویکی‌پدیای خود استفاده می‌کند. با ادغام یک ابزار شخص ثالث و دادن نقش خاص به آن، شما نماینده خود را به طور قابل توجهی هوشمندتر و برای هدف برنامه‌ریزی سفرش مفیدتر کرده‌اید.
برای اینکه ببینید اپراتور دقیقاً چگونه این انتخاب را انجام داده است، می‌توانید از بازرس رویداد در رابط کاربری adk web استفاده کنید. روی تب رویدادها و سپس روی جدیدترین رویداد functionCall کلیک کنید.
بازرس فهرستی از تمام ابزارهای موجود را نشان می‌دهد و tool_code مربوط به ابزاری که توسط عامل اجرا شده است را برجسته می‌کند.
۷. تمیز کردن (اختیاری)
از آنجایی که این آزمایشگاه کد شامل هیچ محصول طولانی‌مدتی نمی‌شود، متوقف کردن ساده‌ی جلسات عامل فعال شما (مثلاً نمونه‌ی adk web در ترمینال شما) با فشار دادن Ctrl + C در ترمینال کافی است.
حذف پوشه‌ها و فایل‌های پروژه Agent
اگر فقط می‌خواهید کد را از محیط Cloud Shell خود حذف کنید، از دستورات زیر استفاده کنید:
cd ~
rm -rf ai-agents-adk
غیرفعال کردن API هوش مصنوعی ورتکس
برای غیرفعال کردن Vertex AI API که قبلاً فعال شده بود، این دستور را اجرا کنید:
gcloud services disable aiplatform.googleapis.com
کل پروژه ابری گوگل را تعطیل کنید
اگر می‌خواهید پروژه گوگل کلود خود را به‌طور کامل خاموش کنید، برای دستورالعمل‌های دقیق به راهنمای رسمی مراجعه کنید.
۸. نتیجه‌گیری
تبریک! شما با موفقیت دستیار شخصی را با عملکردهای سفارشی و دسترسی به جستجوی گوگل در لحظه توانمند کردید. این مستندات رسمی در مورد استفاده از ابزارها با Google ADK را مطالعه کنید.
مهم‌تر از آن، شما الگوی معماری اساسی برای ساخت عامل‌های توانمند را آموخته‌اید: استفاده از عامل‌های تخصصی به عنوان ابزار. با ایجاد یک google_search_agent اختصاصی و دادن آن به root_agent خود، اولین قدم خود را از ساخت یک عامل واحد به سمت هماهنگ‌سازی یک سیستم چندعاملی ساده اما قدرتمند برداشته‌اید.
اکنون کاملاً برای آزمایشگاه کد بعدی این مجموعه آماده هستید، جایی که عمیق‌تر به بررسی هماهنگ‌سازی چندین عامل و گردش کار خواهیم پرداخت. آنجا می‌بینمت!