این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

ساخت عوامل هوش مصنوعی با ADK: توانمندسازی با ابزارها

1. قبل از شروع

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

برای شروع، این راهنما دو مسیر را ارائه می‌کند: یکی برای کسانی که از « Building AI Agents with ADK: The Foundation » و دیگری برای کسانی که تازه شروع کرده‌اند. هر دو مسیر تضمین می کنند که کد عامل پایه لازم برای شروع را دارید.

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

پیش نیازها

درک مفاهیم هوش مصنوعی مولد
مهارت اولیه در برنامه نویسی پایتون
Building AI Agents را با ADK: The Foundation Codelab یا موارد مشابه تکمیل کرد

چیزی که یاد خواهید گرفت

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

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

یک کامپیوتر کارآمد و وای فای قابل اعتماد
مرورگری مانند Chrome برای دسترسی به Google Cloud Console
یک پروژه Google Cloud با فعال کردن صورت‌حساب
ذهن کنجکاو و اشتیاق به یادگیری

2. مقدمه

یک عامل اساسی که با ADK ساخته شده است دارای مغز قدرتمند LLM است، اما محدودیت هایی نیز دارد: نمی تواند به اطلاعات ایجاد شده پس از تاریخ آموزش دسترسی داشته باشد و نمی تواند با سرویس های خارجی تعامل داشته باشد. این مانند یک دستیار درخشان و هوشمند است که در کتابخانه ای بدون تلفن یا اینترنت قفل شده است. برای اینکه یک عامل واقعاً مفید باشد، باید ابزارهایی به آن بدهیم.

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

ADK سه دسته از ابزارها را ارائه می دهد:

Function Tools: ابزارهای سفارشی که برای برآورده کردن نیازهای منحصر به فرد برنامه خود ایجاد می کنید، مانند توابع و عوامل از پیش تعریف شده.
ابزارهای داخلی: ابزارهای آماده برای استفاده که توسط چارچوب برای عملیات رایج، مانند جستجوی Google و اجرای کد ارائه شده است.
ابزارهای شخص ثالث: کتابخانه های خارجی محبوب مانند Serper و ابزارهای LangChain و CrewAI.

برای کسب اطلاعات بیشتر در مورد استفاده از Tools با ADK Agents، به مستندات رسمی نگاهی بیندازید. در این نرم‌افزار، ابزارهایی را اضافه می‌کنیم تا نماینده ساده خود را به یک دستیار مسافرتی توانا تبدیل کنیم. بیایید شروع کنیم!

3. شروع به کار: عامل پایه شما

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

مسیر A: ادامه از Codelab Foundation

اگر به تازگی « Building AI Agents with ADK: The Foundation » را تکمیل کرده اید، همه چیز آماده است. می توانید به کار در فهرست راهنمای پروژه ai-agents-adk موجود خود ادامه دهید.

مسیر B: شروع تازه

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

پس از تکمیل مراحل، آماده شروع سفر یادگیری خود هستید.

4. یک ابزار سفارشی برای تبادل ارز بسازید

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

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

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

برای رسیدگی به این موضوع، یک تابع پایتون را برای بازیابی نرخ ارز از طریق یک REST API و ادغام آن به عنوان یک ابزار تابع برای عامل پیاده سازی می کنیم.

با استفاده از میانبر صفحه کلید Ctrl + C (برای Windows/Linux) یا Cmd + C (برای macOS) در پنجره ترمینال، فرآیند عامل در حال اجرا را خاتمه دهید.

ایجاد فایل `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)]
)

پس از تغییرات، عامل را دوباره با تایپ کردن راه اندازی کنید:

uv run adk web

وقتی نماینده فعال شد دوباره همین سوال را بپرسید "نرخ تبدیل دلار سنگاپور به ین ژاپن چقدر است؟"

این بار باید نرخ واقعی ارز داده شده توسط ابزار get_fx_rate را ببینید.

هر گونه سوال مربوط به مبادلات ارزی را هر طور که می خواهید بپرسید.

5. با ابزار جستجوی داخلی گوگل ادغام شوید

با توجه به اینکه نماینده اکنون قادر به ارائه نرخ ارز است، وظیفه بعدی دریافت پیش بینی آب و هوا در ماه آینده است. این سوال را از نماینده بپرسید: "پیش بینی آب و هوا در توکیو ژاپن برای ماه آینده چگونه است؟"

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

خوشبختانه، Agent Development Kit (ADK) مجموعه‌ای از ابزارهای داخلی ، از جمله جستجوی Google را ارائه می‌کند که آماده استفاده هستند و نحوه تعامل نماینده ما با دنیای خارج را ساده می‌کند. بیایید یک ابزار جستجوی Google را به نماینده خود اضافه کنیم.

برای این کار باید فایل agent.py را به صورت زیر ویرایش کنید:

from google.adk.agents import Agent
from google.adk.tools import FunctionTool
from google.adk.tools import google_search

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), 
        google_search,
    ]
)

پس از ویرایش فایل، نمونه adk web مجددا راه اندازی کنید. در صورت فراموشی،

روی ترمینال کلیک کنید، Ctrl + C یا Cmd + C را فشار دهید تا نمونه متوقف شود
uv run adk web
همین سوال را بپرسید: "پیش بینی آب و هوا در توکیو، ژاپن برای ماه آینده چیست؟"

رویکرد توصیه شده پذیرش یک الگوی چند عاملی است: یک نماینده تخصصی ایجاد کنید که تنها کارش انجام جستجوهای گوگل است. سپس، این عامل جستجوی جدید Google را به عنوان ابزار به 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 import agent_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
    ]
)

بیایید الگوی قدرتمند جدید در کد را تجزیه کنیم:

یک نماینده متخصص جدید : ما یک نماینده کاملاً جدید، google_search_agent تعریف کرده‌ایم. به توضیحات خاص آن توجه کنید و اینکه تنها ابزار آن google_search است. این یک متخصص جستجو است.
agent_tool.AgentTool : این یک پوشش مخصوص از ADK است. این یک نماینده کامل (Google_search_agent ما) را می گیرد و آن را بسته بندی می کند تا مانند یک ابزار استاندارد به نظر برسد و عمل کند.
یک root_agent هوشمندتر **: root_agent ما اکنون یک ابزار جدید دارد: agent_tool.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 یا Cmd + C ) را متوقف کنید و با تایپ دستورات زیر در ترمینال ، کتابخانه‌های اضافی را در محیط مجازی پایتون فعلی نصب کنید.

uv add langchain-community
uv add 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 import agent_tool
from google.adk.tools import langchain_tool

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), 
        agent_tool.AgentTool(agent=google_search_agent),
        langchain_tool.LangchainTool(langchain_wikipedia_tool),
    ]
)

اکنون نمونه adk web را مجدداً راه اندازی کنید و این سؤال را از نماینده بپرسید: "درباره تاریخچه کیوتو به من بگویید".

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

برای اینکه ببینید نماینده دقیقا چگونه این انتخاب را انجام داده است، می‌توانید از بازرس رویداد در adk web UI استفاده کنید. روی تب Events و سپس روی آخرین رویداد functionCall کلیک کنید.

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

7. پاکسازی (اختیاری)

از آنجایی که این کد لبه هیچ محصول طولانی مدتی را شامل نمی شود، صرفاً توقف جلسات عامل فعال شما (مثلاً نمونه adk web در ترمینال شما) با فشار دادن Ctrl + C در ترمینال کافی است.

پوشه ها و فایل های Agent Project را حذف کنید

اگر فقط می خواهید کد را از محیط Cloud Shell خود حذف کنید، از دستورات زیر استفاده کنید:

cd ~
rm -rf ai-agents-adk

Vertex AI API را غیرفعال کنید

برای غیرفعال کردن Vertex AI API که قبلاً فعال شده بود، این دستور را اجرا کنید:

gcloud services disable aiplatform.googleapis.com

کل پروژه Google Cloud را خاموش کنید

اگر می خواهید پروژه Google Cloud خود را به طور کامل تعطیل کنید، برای دستورالعمل های دقیق به راهنمای رسمی مراجعه کنید.

8. نتیجه گیری

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

مهمتر از آن، الگوی اساسی معماری برای ساخت عوامل توانمند را آموخته اید: استفاده از عوامل تخصصی به عنوان ابزار. با ایجاد یک google_search_agent اختصاصی و دادن آن به root_agent خود، اولین قدم خود را از ساختن یک عامل واحد تا سازماندهی یک سیستم ساده و در عین حال قدرتمند چند عاملی برداشته‌اید.

شما اکنون کاملاً برای کدهای بعدی این مجموعه آماده هستید، جایی که ما عمیق‌تر به هماهنگ کردن چندین عامل و گردش کار خواهیم پرداخت. آنجا می بینمت!

ساخت عوامل هوش مصنوعی با ADK: توانمندسازی با ابزارها

1. قبل از شروع

پیش نیازها

چیزی که یاد خواهید گرفت

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

2. مقدمه

3. شروع به کار: عامل پایه شما

4. یک ابزار سفارشی برای تبادل ارز بسازید

ایجاد فایل custom_functions.py **:**

به روز رسانی فایل agent.py **:**

5. با ابزار جستجوی داخلی گوگل ادغام شوید

فایل custom_agents.py ایجاد کنید

فایل agent.py را به روز کنید

6. از ابزار ویکی‌پدیای LangChain استفاده کنید

فایل third_party_tools.py ایجاد کنید

فایل agent.py را به روز کنید

7. پاکسازی (اختیاری)

پوشه ها و فایل های Agent Project را حذف کنید

Vertex AI API را غیرفعال کنید

کل پروژه Google Cloud را خاموش کنید

8. نتیجه گیری

ایجاد فایل `custom_functions.py` :

به روز رسانی فایل `agent.py` :

فایل `custom_agents.py` ایجاد کنید

فایل `agent.py` را به روز کنید

فایل `third_party_tools.py` ایجاد کنید

فایل `agent.py` را به روز کنید