Tools Make an Agent: از صفر تا دستیار با ADK

۱. مقدمه

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

ابزارها یک نماینده بسازید

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

  • نحوه راه‌اندازی یک پروژه پایتون برای توسعه ADK.
  • چگونه یک عامل ADK پایه ایجاد کنیم.
  • نحوه پیاده‌سازی و استفاده از ابزارهای تابعی
  • نحوه ادغام ابزارهای داخلی مانند جستجوی گوگل.
  • چگونه می‌توان از ابزارهای شخص ثالث از چارچوب‌هایی مانند LangChain در ADK استفاده کرد.
  • نحوه استفاده از ابزارهای MCP برای تعامل با پایگاه‌های داده (Cloud SQL) و APIها.

۲. مرور کلی

تصور کنید که شما مدیر پروژه در QuantumRoast، یک شرکت جهانی تولیدکننده دستگاه‌های قهوه‌ساز، هستید.

رست کوانتومی

شما به هم‌تیمی‌هایتان کمک می‌کنید تا در دریایی از نقشه‌های راه مهندسی، چرخش‌های ناگهانی استراتژی (الان داریم ماچا می‌خوریم!)، و تیکت‌های دریافتی از مشتریان - از سیستم‌های فاکتور خراب گرفته تا دستگاه قهوه‌سازی که ۲۴ ساعته و ۷ روز هفته صدای بلندی تولید می‌کند - راه خود را پیدا کنند.

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

مدیر پروژه کلافه

چه می‌شد اگر می‌توانستیم یک دستیار بسازیم که به شما در ایجاد و ارزیابی تیکت‌های نرم‌افزاری و اشکال‌زدایی مشکلات کمک کند؟ یک عامل هوش مصنوعی این کار را ممکن می‌سازد.

عامل هوش مصنوعی

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

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

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

نمودار عامل

ابزارها ۱۰۱

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

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

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

ابزارها چگونه کار می‌کنند؟

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

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

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

برای مشاهده‌ی همه این موارد در عمل، وقت آن رسیده که با استفاده از ADK Python، عامل دستیار باگ QuantumRoast را بسازیم.

دستیار رفع اشکال QuantumRoast

۳. قبل از شروع

راه‌اندازی پروژه گوگل کلود

  1. اگر از قبل حساب گوگل ندارید، باید یک حساب گوگل ایجاد کنید .
    • به جای حساب کاری یا تحصیلی از یک حساب شخصی استفاده کنید. حساب‌های کاری و تحصیلی ممکن است محدودیت‌هایی داشته باشند که مانع از فعال کردن APIهای مورد نیاز برای این آزمایشگاه توسط شما شود.
  2. وارد کنسول ابری گوگل شوید.
  3. فعال کردن پرداخت در کنسول ابری
    • تکمیل این آزمایشگاه باید کمتر از ۱ دلار آمریکا از طریق منابع ابری هزینه داشته باشد.
    • شما می‌توانید مراحل انتهای این آزمایش را برای حذف منابع دنبال کنید تا از هزینه‌های بیشتر جلوگیری شود.
    • کاربران جدید واجد شرایط استفاده از دوره آزمایشی رایگان ۳۰۰ دلاری هستند.
  4. یک پروژه جدید ایجاد کنید یا از یک پروژه موجود دوباره استفاده کنید.

ویرایشگر Cloud Shell را باز کنید

  1. به ویرایشگر Cloud Shell بروید
  2. اگر ترمینال در پایین صفحه نمایش داده نشد، آن را باز کنید:
    • روی منوی همبرگری کلیک کنید آیکون منوی همبرگری
    • روی ترمینال کلیک کنید
    • روی ترمینال جدید کلیک کنید باز کردن ترمینال جدید در ویرایشگر Cloud Shell
  3. در ترمینال، پروژه خود را با این دستور تنظیم کنید (به جای YOUR_PROJECT_ID ):
    • قالب: 
      gcloud config set project YOUR_PROJECT_ID
    • مثال: 
      gcloud config set project lab-project-id-example
    • اگر نمی‌توانید شناسه پروژه خود را به خاطر بیاورید:
      • شما می‌توانید تمام شناسه‌های پروژه خود را با موارد زیر فهرست کنید: 
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      شناسه پروژه را در ترمینال ویرایشگر Cloud Shell تنظیم کنید
  4. اگر از شما خواسته شد که مجوز دهید، برای ادامه روی تأیید کلیک کنید. برای تأیید Cloud Shell کلیک کنید
  5. شما باید این پیام را ببینید:
    Updated property [core/project].
    اگر یک WARNING مشاهده کردید و از شما پرسیده شد Do you want to continue (Y/N)? احتمالاً شناسه پروژه را اشتباه وارد کرده‌اید. N را فشار دهید، Enter را بزنید و دوباره سعی کنید دستور gcloud config set project اجرا کنید.
  6. در ترمینال، متغیر محیطی PROJECT_ID را برای استفاده در مراحل بعدی تنظیم کنید. 
    export PROJECT_ID=$(gcloud config get project)

فعال کردن APIها

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

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

ایجاد یک Cloud SQL برای نمونه PostgreSQL

QuantumRoast یک پایگاه داده‌ی تیکت‌های باگ دارد که تمام تیکت‌های داخلی را در خود جای داده است. بیایید با ایجاد یک نمونه‌ی Cloud SQL برای PostgreSQL، آن را راه‌اندازی کنیم.

gcloud sql instances create software-assistant \
   --database-version=POSTGRES_16 \
   --tier=db-custom-1-3840 \
   --region=us-central1 \
   --edition=ENTERPRISE \
   --enable-google-ml-integration \
   --database-flags cloudsql.enable_google_ml_integration=on \
   --root-password=admin

منتظر بمانید تا نمونه ایجاد شود (ممکن است چند دقیقه طول بکشد).

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

ایجاد یک پایگاه داده SQL ابری

یک پایگاه داده SQL ( tickets-db ) ایجاد کنید و به حساب سرویس Cloud SQL دسترسی به Vertex AI را بدهید (تا بتوانیم جاسازی‌هایی برای انجام جستجوی شباهت ایجاد کنیم).

gcloud sql databases create tickets-db --instance=software-assistant

SERVICE_ACCOUNT_EMAIL=$(gcloud sql instances describe software-assistant --format="value(serviceAccountEmailAddress)")
echo $SERVICE_ACCOUNT_EMAIL

gcloud projects add-iam-policy-binding $PROJECT_ID --member="serviceAccount:$SERVICE_ACCOUNT_EMAIL" --role="roles/aiplatform.user"

میز tickets را تنظیم کنید

از کنسول ابری (Cloud SQL)، برای نمونه software-assistant Cloud SQL Studio را باز کنید.

با استفاده از نام کاربری postgres و رمز عبور admin ، وارد پایگاه داده tickets-db شوید.

استودیوی ابری SQL

یک برگه Editor جدید باز کنید.

ویرایشگر استودیوی ابری SQL

سپس، کد SQL زیر را برای تنظیم جدول و ایجاد جاسازی‌های برداری وارد کنید. برای اجرای دستور، دکمه‌ی Run را بزنید. 

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector CASCADE;
GRANT EXECUTE ON FUNCTION embedding TO postgres;

CREATE TABLE tickets (
    ticket_id SERIAL PRIMARY KEY,             -- PostgreSQL's auto-incrementing integer type (SERIAL is equivalent to INT AUTO_INCREMENT)
    title VARCHAR(255) NOT NULL,              -- A concise summary or title of the bug/issue.
    description TEXT,                         -- A detailed description of the bug.
    assignee VARCHAR(100),                    -- The name or email of the person/team assigned to the ticket.
    priority VARCHAR(50),                     -- The priority level (e.g., 'P0 - Critical', 'P1 - High').
    status VARCHAR(50) DEFAULT 'Open',        -- The current status of the ticket (e.g., 'Open', 'In Progress', 'Resolved'). Default is 'Open'.
    creation_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, -- Timestamp when the ticket was first created. 'WITH TIME ZONE' is recommended for clarity and compatibility.
    updated_time TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP  -- Timestamp when the ticket was last updated. Will be managed by a trigger.
);

جدول tickets ایجاد شده است، برای پاک کردن پرس‌وجوی قدیمی، Clear کلیک کنید.

حالا داده‌های نمونه را وارد کنید و دوباره دکمه‌ی Run را بزنید. 

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Login Page Freezes After Multiple Failed Attempts', 'Users are reporting that after 3 failed login attempts, the login page becomes unresponsive and requires a refresh. No specific error message is displayed.', 'samuel.green@example.com', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Dashboard Sales Widget Intermittent Data Loading Failure', 'The "Sales Overview" widget on the main dashboard intermittently shows a loading spinner but no data. Primarily affects Chrome browser users.', 'maria.rodriguez@example.com', 'P1 - High', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Broken Link in Footer - Privacy Policy', 'The "Privacy Policy" hyperlink located in the website footer leads to a 404 "Page Not Found" error.', 'maria.rodriguez@example.com', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('UI Misalignment on Mobile Landscape View (iOS)', 'On specific iOS devices (e.g., iPhone 14 models), the top navigation bar shifts downwards when the device is viewed in landscape orientation, obscuring content.', 'maria.rodriguez@example.com', 'P2 - Medium', 'In Progress');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Critical XZ Utils Backdoor Detected in Core Dependency (CVE-2024-3094)', 'Urgent: A sophisticated supply chain compromise (CVE-2024-3094) has been identified in XZ Utils versions 5.6.0 and 5.6.1. This malicious code potentially allows unauthorized remote SSH access by modifying liblzma. Immediate investigation and action required for affected Linux/Unix systems and services relying on XZ Utils.', 'frank.white@example.com', 'P0 - Critical', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Database Connection Timeouts During Peak Usage', 'The application is experiencing frequent database connection timeouts, particularly during peak hours (10 AM - 12 PM EDT), affecting all users and causing service interruptions.', 'frank.white@example.com', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Export to PDF Truncates Long Text Fields in Reports', 'When generating PDF exports of reports containing extensive text fields, the text is abruptly cut off at the end of the page instead of wrapping or continuing to the next page.', 'samuel.green@example.com', 'P1 - High', 'Open');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Search Filter "Date Range" Not Applying Correctly', 'The "Date Range" filter on the search results page does not filter records accurately; results outside the specified date range are still displayed.', 'samuel.green@example.com', 'P2 - Medium', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Typo in Error Message: "Unathorized Access"', 'The error message displayed when a user attempts an unauthorized action reads "Unathorized Access" instead of "Unauthorized Access."', 'maria.rodriguez@example.com', 'P3 - Low', 'Resolved');

INSERT INTO tickets (title, description, assignee, priority, status) VALUES
('Intermittent File Upload Failures for Large Files', 'Users are intermittently reporting that file uploads fail without a clear error message or explanation, especially for files exceeding 10MB in size.', 'frank.white@example.com', 'P1 - High', 'Open');

در QuantumRoast، ممکن است بخواهیم بدانیم که یک باگ/تیکت آخرین بار چه زمانی به‌روزرسانی شده است.

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

روی Clear کلیک کنید و سپس SQL زیر را برای پیاده‌سازی یک trigger جایگذاری کنید.

برای اجرا، دکمه‌ی Run را بزنید. 

CREATE OR REPLACE FUNCTION update_updated_time_tickets()
RETURNS TRIGGER AS $$
BEGIN
    NEW.updated_time = NOW();  -- Set the updated_time to the current timestamp
    RETURN NEW;                -- Return the new row
END;
$$ language 'plpgsql';        

CREATE TRIGGER update_tickets_updated_time
BEFORE UPDATE ON tickets
FOR EACH ROW                  -- This means the trigger fires for each row affected by the UPDATE statement
EXECUTE PROCEDURE update_updated_time_tickets();

جاسازی‌های برداری را از فیلد description ایجاد کنید. این به عامل ما این امکان را می‌دهد که جستجوی شباهت را در پایگاه داده ما انجام دهد. به عنوان مثال، "آیا مسائل باز مربوط به صفحه اصلی وب‌سایت‌ها وجود دارد؟". 

ALTER TABLE tickets ADD COLUMN embedding vector(768) GENERATED ALWAYS AS (embedding('text-embedding-005',description)) STORED;

اکنون می‌توانید از پایگاه داده پرس‌وجو کنید تا مطمئن شوید که آماده است. 

SELECT * FROM tickets;

شما باید 10 ردیف برگردانده شده را ببینید که شبیه به موارد زیر است:

تأیید پایگاه داده ابری SQL

حالا آماده‌اید تا به بخش جذاب، یعنی کدنویسی، بروید!

۴. راه‌اندازی پروژه پایتون

قبل از اینکه بتوانیم به ساخت عامل خود بپردازیم، باید مطمئن شویم که یک پروژه پایتون مناسب راه‌اندازی کرده‌ایم. ما همه این کارها را در Cloud Shell انجام خواهیم داد!

ابتدا، یک پوشه‌ی quantum-roast ایجاد کنید و cd به آن وارد شوید: 

mkdir quantum-roast && cd quantum-roast

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

ما از uv (بسته‌ی بسیار سریع پایتون و مدیر پروژه) که به صورت پیش‌فرض در Cloud Shell برای مدیریت پروژه و وابستگی‌های ما نصب شده است، استفاده خواهیم کرد. uv به ما در راه‌اندازی برخی از فایل‌ها و همچنین مدیریت محیط‌های مجازی، وابستگی‌ها و غیره کمک خواهد کرد تا مجبور به این کار نباشیم!

یک پروژه جدید را با uv init مقداردهی اولیه کنید: 

uv init --description "QuantumRoast Software Bug Assistant with ADK" --bare --python 3.10

پس از اجرای دستور، باید یک فایل pyproject.toml برای پروژه خود داشته باشیم. برای تأیید، cat pyproject.toml را در ترمینال Cloud Shell اجرا کنید: 

cat pyproject.toml

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

[project]
name = "quantum-roast"
version = "0.1.0"
description = "QuantumRoast Software Bug Assistant with ADK"
requires-python = ">=3.10"
dependencies = []

وقت آن رسیده که google-adk (ADK) را به عنوان یک وابستگی با استفاده از uv add به پروژه خود اضافه کنیم. 

uv add google-adk==1.11.0

این google-adk را به لیست dependencies در pyproject.toml ما اضافه می‌کند.

ADK برای دستیابی به بهترین نتایج، ساختار پروژه مشخصی را پیش‌بینی می‌کند. 

quantum-roast/
    software_bug_assistant/
        __init__.py
        agent.py
        .env

پوشه software_bug_assistant و فایل‌های درون آن را ایجاد کنید: 

mkdir software_bug_assistant && touch software_bug_assistant/__init__.py \
software_bug_assistant/agent.py \
software_bug_assistant/tools.py \
software_bug_assistant/.env

با استفاده از ls ایجاد فایل‌ها را تأیید کنید: 

ls -a software_bug_assistant/

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

__init__.py	 .  ..	 .env	 agent.py    tools.py

وقت آن رسیده که فایل .env را با متغیرهای محیطی مورد نیاز برای فراخوانی صحیح مدل‌های Gemini توسط ADK پر کنیم. ما از طریق API Vertex به Gemini دسترسی خواهیم داشت. 

echo "GOOGLE_GENAI_USE_VERTEXAI=TRUE" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_PROJECT=$PROJECT_ID" >> software_bug_assistant/.env \
&& echo "GOOGLE_CLOUD_LOCATION=us-central1" >> software_bug_assistant/.env

برای تأیید اینکه فایل .env به درستی پر شده است، دستور زیر را اجرا کنید: 

cat software_bug_assistant/.env

شما باید عبارت زیر را ببینید که در آن your-project-id شناسه پروژه شما است: 

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1

اکنون قرار است ایجاد عامل ADK خود را شروع کنیم.

۵. عامل ADK پایه

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

agent.py در ویرایشگر Cloud Shell باز کنید: 

cloudshell edit software_bug_assistant/agent.py

کد زیر را در agent.py قرار دهید و فایل را Ctrl + s ذخیره کنید: 

from google.adk.agents import Agent

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[],
)

با اجرای رابط کاربری توسعه‌دهندگان ADK ( adk web )، عامل تازه ایجاد شده خود را اجرا کنید. انجام این کار با uv run به طور خودکار یک محیط مجازی با ADK نصب شده ایجاد می‌کند.

uv run adk web --port 8080 --reload_agents

در کنسول باید شاهد راه‌اندازی موفقیت‌آمیز وب سرور ADK باشید. 

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

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

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)

برای مشاهده رابط کاربری، پیش‌نمایش وب Cloud Shell را باز کنید.

پیش‌نمایش وب Cloud Shell

شما باید رابط کاربری وب ADK را ببینید.

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

ادامه دهید و سعی کنید با نماینده ADK چت کنید.

از مامور بپرسید What day is it today?

مثال وب ADK

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

وقت آن رسیده که اولین نوع ابزار ADK، یعنی Function Tool را پیاده‌سازی کنیم.

۶. ابزار تابع

اولین و ساده‌ترین نوع ابزار ADK، ابزار تابع است. این ابزار دقیقاً همان چیزی است که از اسمش پیداست، یک تابع پایتون که توسط عامل فراخوانی می‌شود!

ابزار عملکرد

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

در QuantumRoast ما می‌خواهیم یک تابع پایه برای دریافت تاریخ روز جاری تعریف کنیم تا بعداً در این آزمایش بتوانیم به پرس‌وجوهایی مانند «اشکالات هفته گذشته را به من نشان بده» یا «امروز چه روزی است؟» (که برای همه ما اتفاق می‌افتد) رسیدگی کنیم.

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

با کلیک روی آیکون + یک ترمینال جدید باز کنید.

ترمینال جدید

اکنون در ترمینال جدید، PROJECT_ID را تنظیم کرده و tools.py باز کنید: 

cd quantum-roast
export PROJECT_ID=$(gcloud config get project)
cloudshell edit software_bug_assistant/tools.py

اکنون تابع get_current_date را تعریف کنید که به عنوان یک ابزار تابع (Function tool) استفاده خواهد شد. 

from datetime import datetime

# ----- Example of a Function tool -----
def get_current_date() -> dict:
    """
    Get the current date in the format YYYY-MM-DD
    """
    return {"current_date": datetime.now().strftime("%Y-%m-%d")}

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

agent.py در ویرایشگر Cloud Shell باز کنید: 

cloudshell edit software_bug_assistant/agent.py

ما می‌خواهیم تابع get_current_date را از tools.py وارد کنیم و این تابع را به آرگومان tools عامل ارسال کنیم.

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

from google.adk.agents import Agent

from .tools import get_current_date

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date],
)

حالا اگر بخواهید به تب پیش‌نمایش وب که رابط کاربری وب ADK را اجرا می‌کند برگردید و دوباره بپرسید What day is it today? ...

ابزار عملکرد وب ADK

عامل می‌تواند با فراخوانی ابزار تابعی get_current_date با موفقیت تاریخ را تشخیص دهد! 🎉

وقت آن است که نوع بعدی ابزار ADK را بررسی کنیم.

۷. ابزار داخلی

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

ابزار داخلی

برای افزودن پشتیبانی از ابزار داخلی جستجوی گوگل، فایل tools.py را باز کنید. 

cloudshell edit software_bug_assistant/tools.py

موارد زیر را به انتهای tools.py اضافه کنید: 

# ----- Built-in Tool Imports -----
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

# ----- Example of a Built-in Tool -----
search_agent = Agent(
    model="gemini-2.5-flash",
    name="search_agent",
    description="A specialist in Google Search.",
    instruction="""
    You're a specialist in Google Search.
    """,
    tools=[google_search],
)

search_tool = AgentTool(search_agent)

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

حالا می‌توانیم search_tool در agent.py ایمپورت کنیم و به عامل ریشه ارسال کنیم: 

cloudshell edit software_bug_assistant/agent.py

شما می‌توانید agent.py با کد زیر جایگزین کنید تا search_tool نیز شامل شود: 

from google.adk.agents import Agent

from .tools import get_current_date, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool],
)

فایل را ذخیره کنید و به فایل باز خود که رابط کاربری وب ADK در آن اجرا می‌شود، برگردید.

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

عبارت زیر را اجرا کنید: Do a web search for 5 of the most recent CVEs?

عامل ما باید برای جستجو در وب، search_agent فراخوانی کند.

مثال ابزار داخلی وب ADK

نماینده ما اکنون با موفقیت امکان جستجو در وب را از طریق ابزار داخلی ADK برای جستجوی گوگل فعال کرده است! 🎉

به سراغ نوع ابزار ADK بعدی می‌رویم.

۸. ابزار شخص ثالث

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

ابزار شخص ثالث

برای اتصال عامل باگ خود به داده‌های قدرتمند پرسش و پاسخ StackOverflow ، می‌توانیم از کتابخانه ابزارهای گسترده LangChain ، به طور خاص ابزار StackExchange API Wrapper ، استفاده کنیم. ADK از ابزارهای شخص ثالث مانند LangChain پشتیبانی می‌کند، بنابراین افزودن این ابزار به عامل ADK ما فقط به چند خط کد نیاز دارد!

ابتدا، باید وابستگی‌های جدیدی برای LangChain و StackOverflow ( langchain-community و stackapi ) به پروژه خود اضافه کنیم: 

uv add langchain-community==0.3.27 stackapi==0.3.1

برای افزودن پشتیبانی از ابزار LangChain StackExchange، فایل tools.py را باز کنید. 

cloudshell edit software_bug_assistant/tools.py

موارد زیر را به انتهای tools.py اضافه کنید: 

# ----- Example of a Third-Party Tool -----
from google.adk.tools.langchain_tool import LangchainTool
from langchain_community.tools import StackExchangeTool
from langchain_community.utilities import StackExchangeAPIWrapper

stack_exchange_tool = StackExchangeTool(api_wrapper=StackExchangeAPIWrapper())
langchain_tool = LangchainTool(stack_exchange_tool)

اکنون می‌توانیم langchain_tool را در agent.py وارد کرده و به عامل ریشه منتقل کنیم: 

cloudshell edit software_bug_assistant/agent.py

شما می‌توانید agent.py با کد زیر جایگزین کنید تا langchain_tool نیز شامل شود: 

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool],
)

فایل را ذخیره کنید و به تب باز شده با رابط کاربری وب ADK برگردید.

سعی کنید از کارشناس در مورد CVE های قبلی بپرسید، "Are there similar issues on stack exchange?" یا چیز جدیدی مانند "Our database queries with SQLAlchemy seem to be timing out, is there anything on StackExchange relevant to this?" .

مثال ابزار شخص ثالث وب ADK

اکنون نماینده ما با موفقیت از ابزار LangChain در ADK برای پرس و جو در StackOverflow استفاده کرده است. 🥳

وقتشه که بریم سراغ ابزار بعدی ADK... ابزارهای MCP!

۹. ابزار MCP (پایگاه داده)

MCP مخفف Model Context Protocol است. این یک پروتکل باز است که توسط Anthropic در سال ۲۰۲۴ معرفی شد . MCP یک لایه انتزاعی بین عامل هوش مصنوعی شما و «backend»های ابزار (APIها، پایگاه‌های داده) فراهم می‌کند.

نحوه عملکرد MCP

MCP مشخصات منحصر به فردی دارد. برخلاف HTTP استاندارد، MCP یک اتصال دوطرفه و با وضعیت مشخص بین کلاینت و سرور فراهم می‌کند. این پروتکل روش خاص خود را برای تعریف ابزارها و پیام‌های خطای مختص به ابزار دارد. سپس یک ارائه‌دهنده ابزار می‌تواند سرورهای MCP را بر روی APIهای خود بسازد و یک یا چند ابزار از پیش ساخته شده را در اختیار توسعه‌دهندگان و کاربران قرار دهد. سپس، چارچوب‌های عامل می‌توانند کلاینت‌های MCP را در داخل یک برنامه عامل مقداردهی اولیه کنند تا آن ابزارها را کشف و فراخوانی کنند.

در QuantumRoast، ما یک پایگاه داده Cloud SQL برای PostgreSQL برای رفع اشکالات نرم‌افزاری داخلی داریم. ما می‌خواهیم ابزارهای ADK ایجاد کنیم تا عامل ما بتواند پرس‌وجوهای خاصی را روی پایگاه داده ما انجام دهد.

پایگاه داده ابزار MCP

ساده‌ترین راه برای انجام این کار استفاده از MCP Toolbox for Databases است، یک سرور MCP متن‌باز برای پایگاه‌های داده! Toolbox از بیش از ۱۵ پایگاه داده پشتیبانی می‌کند که یکی از آنها Cloud SQL است!

جعبه ابزار فراهم می‌کند:

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

ADK از ابزارهای MCP Toolbox برای پایگاه داده پشتیبانی می‌کند که باعث می‌شود ادغام سریع انجام شود.

جعبه ابزار MCP برای پایگاه‌های داده

استقرار جعبه ابزار MCP برای سرور پایگاه داده در Cloud Run

ابتدا، جعبه ابزار MCP برای سرور پایگاه داده را روی Cloud Run مستقر می‌کنیم و آن را به نمونه Cloud SQL خود ارجاع می‌دهیم.

جعبه ابزار برای پیکربندی به یک فایل YAML نیاز دارد، که در آن منبع پایگاه داده و ابزارهای پیکربندی را مشخص می‌کنید.

یک فایل tools.yaml برای استقرار ایجاد کنید. 

cloudshell edit tools.yaml

محتوای زیر را در فایل tools.yaml قرار دهید: 

sources:
  postgresql:
    kind: cloud-sql-postgres
    project: ${PROJECT_ID}
    region: us-central1
    instance: software-assistant
    database: tickets-db
    user: postgres
    password: admin

tools:
  search-tickets:
    kind: postgres-sql
    source: postgresql
    description: Search for similar tickets based on their descriptions.
    parameters:
      - name: query
        type: string
        description: The query to perform vector search with.
    statement: |
      SELECT ticket_id, title, description, assignee, priority, status, (embedding <=> embedding('text-embedding-005', $1)::vector) as distance
      FROM tickets
      ORDER BY distance ASC
      LIMIT 3;
  get-ticket-by-id:
    kind: postgres-sql
    source: postgresql
    description: Retrieve a ticket's details using its unique ID.
    parameters:
      - name: ticket_id
        type: string
        description: The unique ID of the ticket.
    statement: SELECT * FROM tickets WHERE ticket_id = $1;
  get-tickets-by-assignee:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on assignee (email).
    parameters:
      - name: assignee
        type: string
        description: The email of the assignee.
    statement: SELECT * FROM tickets WHERE assignee ILIKE '%' || $1 || '%';
  update-ticket-priority:
    kind: postgres-sql
    source: postgresql
    description: Update the priority of a ticket based on its ID.
    parameters:
      - name: priority
        type: string
        description: The priority of the ticket. Can be one of 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'.
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET priority = $1 WHERE ticket_id = $2;
  update-ticket-status:
    kind: postgres-sql
    source: postgresql
    description: Update the status of a ticket based on its ID.
    parameters:
      - name: status
        type: string
        description: The new status of the ticket (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
      - name: ticket_id
        type: string
        description: The ID of the ticket.
    statement: UPDATE tickets SET status = $1 WHERE ticket_id = $2;
  get-tickets-by-status:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their current status.
    parameters:
      - name: status
        type: string
        description: The status of the tickets to retrieve (e.g., 'Open', 'In Progress', 'Closed', 'Resolved').
    statement: SELECT * FROM tickets WHERE status ILIKE '%' || $1 || '%';
  get-tickets-by-priority:
    kind: postgres-sql
    source: postgresql
    description: Search for tickets based on their priority.
    parameters:
      - name: priority
        type: string
        description: The priority of the tickets to retrieve (e.g., 'P0 - Critical', 'P1 - High', 'P2 - Medium', 'P3 - Low').
    statement: SELECT * FROM tickets WHERE priority ILIKE '%' || $1 || '%';
  create-new-ticket:
    kind: postgres-sql
    source: postgresql
    description: Create a new software ticket.
    parameters:
      - name: title
        type: string
        description: The title of the new ticket.
      - name: description
        type: string
        description: A detailed description of the bug or issue.
      - name: assignee
        type: string
        description: (Optional) The email of the person to whom the ticket should be assigned.
      - name: priority
        type: string
        description: (Optional) The priority of the ticket. Can be 'P0 - Critical', 'P1 - High', 'P2 - Medium', or 'P3 - Low'. Default is 'P3 - Low'.
      - name: status
        type: string
        description: (Optional) The initial status of the ticket. Default is 'Open'.
    statement: INSERT INTO tickets (title, description, assignee, priority, status) VALUES ($1, $2, $3, COALESCE($4, 'P3 - Low'), COALESCE($5, 'Open')) RETURNING ticket_id;
  get-tickets-by-date-range:
    kind: postgres-sql
    source: postgresql
    description: Retrieve tickets created or updated within a specific date range.
    parameters:
      - name: start_date
        type: string
        description: The start date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: end_date
        type: string
        description: The end date (inclusive) for the range (e.g., 'YYYY-MM-DD').
      - name: date_field
        type: string
        description: The date field to filter by ('creation_time' or 'updated_time').
    statement: SELECT * FROM tickets WHERE CASE WHEN $3 = 'creation_time' THEN creation_time ELSE updated_time END BETWEEN $1::timestamp AND $2::timestamp;

toolsets:
  tickets_toolset:
    - search-tickets
    - get-ticket-by-id
    - get-tickets-by-assignee
    - get-tickets-by-status
    - get-tickets-by-priority
    - get-tickets-by-date-range
    - update-ticket-priority
    - update-ticket-status
    - create-new-ticket

فایل YAML، 9 ابزار مرتبط با پایگاه داده بلیط‌های QuantumRoast را تعریف می‌کند.

وقت آن رسیده که یک حساب کاربری سرویس برای سرویس Toolbox Cloud Run پیکربندی کنیم، به آن اجازه دسترسی به Cloud SQL و Secret Manager را بدهیم و یک فایل مخفی Secret Manager برای فایل tools.yaml خود ایجاد کنیم.

Secret Manager جایی است که ما فایل tools.yaml خود را ذخیره خواهیم کرد زیرا حاوی اطلاعات حساس Cloud SQL است. 

gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.secretAccessor

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudsql.client

gcloud secrets create tools --data-file=tools.yaml

زمان آن رسیده که MCP Toolbox for Databases را روی Cloud Run مستقر کنیم. ما از آخرین نسخه منتشر شده از تصویر کانتینر MCP Toolbox استفاده خواهیم کرد. 

gcloud run deploy toolbox \
    --image us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --set-env-vars="PROJECT_ID=$PROJECT_ID" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --labels=dev-tutorial=codelab-toolbox \
    --no-invoker-iam-check

صبر کنید تا عملیات نصب تمام شود...

با بررسی لاگ‌های Cloud Run، از فعال بودن Toolbox اطمینان حاصل کنید: 

gcloud run services logs read toolbox --region us-central1 --limit 10

شما باید ببینید: 

2025-08-20 18:03:55 2025-08-20T18:03:55.465847801Z INFO "Initialized 1 sources."
2025-08-20 18:03:55 2025-08-20T18:03:55.466152914Z INFO "Initialized 0 authServices."
2025-08-20 18:03:55 2025-08-20T18:03:55.466374245Z INFO "Initialized 9 tools."
2025-08-20 18:03:55 2025-08-20T18:03:55.466477938Z INFO "Initialized 2 toolsets."
2025-08-20 18:03:55 2025-08-20T18:03:55.467492303Z INFO "Server ready to serve!"

آدرس اینترنتی Cloud Run را برای سرویس Toolbox به عنوان یک متغیر محیطی ذخیره کنید تا عامل ADK بداند کجا آن را پیدا کند. 

export MCP_TOOLBOX_URL=$(gcloud run services describe toolbox --region us-central1 --format "value(status.url)")
echo MCP_TOOLBOX_URL=$MCP_TOOLBOX_URL >> software_bug_assistant/.env

به‌روزرسانی عامل QuantumRoast

دوم، باید وابستگی مربوط به MCP Toolbox for Databases SDK ( toolbox-core ) را به پروژه خود اضافه کنیم: 

uv add toolbox-core==0.5.0

برای افزودن پشتیبانی از ابزارهای MCP Toolbox، فایل tools.py را باز کنید. 

cloudshell edit software_bug_assistant/tools.py

موارد زیر را به انتهای tools.py اضافه کنید: 

# ----- Example MCP Toolbox for Databases tools -----
import os
from toolbox_core import ToolboxSyncClient

TOOLBOX_URL = os.getenv("MCP_TOOLBOX_URL", "http://127.0.0.1:5000")

# Initialize Toolbox client
toolbox = ToolboxSyncClient(TOOLBOX_URL)
# Load all the tools from toolset
toolbox_tools = toolbox.load_toolset("tickets_toolset")

حالا می‌توانیم toolbox_tools را در agent.py ایمپورت و به عامل ریشه ارسال کنیم: 

cloudshell edit software_bug_assistant/agent.py

شما می‌توانید agent.py با کد زیر جایگزین کنید تا toolbox_tools نیز شامل شود: 

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools],
)

فایل را ذخیره کنید و به تب باز شده با رابط کاربری وب ADK برگردید.

اکنون می‌توانید در مورد تیکت‌های ذخیره شده در پایگاه داده تیکت‌های داخلی Cloud SQL ما سوال بپرسید!

سوالی مانند یکی از موارد زیر بپرسید:

  • I am seeing an issue with database timeouts, has anyone else seen a similar issue?
  • How many bugs are assigned to samuel.green@example.com? Show a table.
  • Can you bump the priority of ticket with ID 6 to to P0 - Critical priority
  • Create a new ticket (اجازه دهید نماینده شما را در ایجاد اشکال راهنمایی کند)

مثال ابزار پایگاه داده MCP

نماینده ADK ما اکنون با موفقیت از طریق ابزارهای MCP Toolbox for Databases به پایگاه داده ما پرس و جو کرده است!🚀

۱۰. اختیاری: ابزار MCP (API)

در مورد اتصال عامل ADK ما به ابزارهای MCP که SDK مخصوص به خود را ندارند، مانند MCP Toolbox for Database، چطور؟

ADK از طریق کلاس MCPToolset خود از ابزارهای عمومی MCP پشتیبانی می‌کند. کلاس MCPToolset مکانیزم اصلی ADK برای ادغام ابزارها از یک سرور MCP است.

ابزار MCP (API)

MCPToolset می‌تواند برای اتصال به سرورهای MCP محلی یا از راه دور استفاده شود، در QuantumRoast ما می‌خواهیم عامل خود را به سرور MCP از راه دور GitHub متصل کنیم - تا به راحتی API های GitHub را فراخوانی کنیم. این به عامل ما اجازه می‌دهد تا اطلاعات مربوط به مشکلات را از مخازن نرم‌افزار عمومی یا حتی پایگاه‌های کد خودمان دریافت کند. سرور GitHub MCP بخش‌های مختلف عملکرد GitHub را در معرض نمایش قرار می‌دهد، از درخواست‌های مشکل و pull گرفته تا اعلان‌ها و امنیت کد.

ابزار MCP گیت‌هاب

توکن دسترسی شخصی گیت‌هاب (PAT)

برای احراز هویت با سرور GitHub MCP، به یک GitHub Personal Access Token نیاز دارید.

برای به دست آوردن یکی از آنها، این مراحل را دنبال کنید:

  1. به تنظیمات توسعه‌دهنده گیت‌هاب خود بروید.
  2. روی «نشانه‌های دسترسی شخصی» -> «نشانه‌ها (کلاسیک)» کلیک کنید.
  3. روی «ایجاد توکن جدید» -> «ایجاد توکن جدید (کلاسیک)» کلیک کنید.
  4. برای توکن خود یک نام توصیفی انتخاب کنید.
  5. برای توکن خود تاریخ انقضا تعیین کنید.
  6. مهم : برای امنیت، به توکن خود محدودترین حوزه‌های لازم را اعطا کنید. برای دسترسی فقط خواندنی به مخازن، حوزه‌های repo:status ، public_repo و read:user اغلب کافی هستند. از اعطای مجوزهای کامل مخزن یا مدیر خودداری کنید، مگر اینکه کاملاً ضروری باشد.
  7. روی Generate token کلیک کنید.
  8. توکن تولید شده را کپی کنید.

در ترمینال Cloud Shell، دستور زیر را اجرا کنید تا GitHub PAT خود را برای استفاده عامل تنظیم کنید. YOUR_GITHUB_PAT را با PAT تولید شده خود جایگزین کنید. 

export GITHUB_PAT=YOUR_GITHUB_PAT

به‌روزرسانی عامل QuantumRoast

برای دستیار باگ خود، ما فقط برخی از ابزارهای گیت‌هاب فقط خواندنی را در معرض نمایش قرار خواهیم داد تا به کارمندان QuantumRoast اجازه دهیم مشکلات مربوط به وابستگی‌های متن‌باز را پیدا کنند و ببینند آیا این می‌تواند به رفع ریشه‌ای باگ‌هایی که در سیستم تیکت داخلی مشاهده می‌کنند، کمک کند یا خیر. ما از MCPToolset ADK به همراه tool_filter برای تنظیم این مورد استفاده خواهیم کرد. tool-filter فقط ابزارهای گیت‌هاب مورد نیاز ما را در معرض نمایش قرار می‌دهد، که نه تنها ابزارهایی را که نمی‌خواهیم کاربران به آنها دسترسی داشته باشند (مثلاً اقدامات حساس مخزن) پنهان می‌کند، بلکه از مدل عامل نیز در برابر سردرگمی هنگام تلاش برای انتخاب ابزار مناسب برای کار محافظت می‌کند.

برای افزودن پشتیبانی از ابزارهای گیت‌هاب، فایل tools.py را باز کنید. 

cloudshell edit software_bug_assistant/tools.py

موارد زیر را به انتهای tools.py اضافه کنید: 

# ----- Example MCP Tools with MCPToolset (GitHub) -----
from google.adk.tools.mcp_tool import MCPToolset, StreamableHTTPConnectionParams

mcp_tools = MCPToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://api.githubcopilot.com/mcp/",
        headers={
            "Authorization": "Bearer " + os.getenv("GITHUB_PAT"),
        },
    ),
    # Read only tools
    tool_filter=[
        "search_repositories",
        "search_issues",
        "list_issues",
        "get_issue",
        "list_pull_requests",
        "get_pull_request",
    ],
)

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

اکنون می‌توانیم mcp_tools را در agent.py وارد کرده و به عامل ریشه منتقل کنیم: 

cloudshell edit software_bug_assistant/agent.py

شما می‌توانید agent.py با کد زیر جایگزین کنید تا mcp_tools نیز شامل شود: 

from google.adk.agents import Agent

from .tools import get_current_date, langchain_tool, mcp_tools, search_tool, toolbox_tools

# --- Agent Definition (model, instructions, tools) ---
root_agent = Agent(
    model="gemini-2.5-flash",
    name="software_assistant",
    instruction="""
    You are a skilled expert in triaging and debugging software issues for a
    coffee machine company, QuantumRoast.
    """,
    tools=[get_current_date, search_tool, langchain_tool, *toolbox_tools, mcp_tools],
)

فایل را ذخیره کنید و به تب باز شده با رابط کاربری وب ADK برگردید.

اکنون، ما مجموعه‌ای از ابزارهای MCP گیت‌هاب را داریم که عامل ما می‌تواند آنها را فراخوانی کند. سرویس‌های QuantumRoast به XZ utils، یک ابزار فشرده‌سازی داده، متکی هستند. سیستم داخلی ثبت اشکالات ما در حال ردیابی یک CVE (آسیب‌پذیری امنیتی) از سال گذشته است که می‌توانیم آن را با استفاده از ابزارهای StackOverflow و Google Search به مخزن گیت‌هاب XZ Utils ردیابی کنیم. سپس می‌توانیم از یکی از ابزارهای MCP گیت‌هاب، search_issues ، برای تعیین زمان و نحوه‌ی وصله شدن آن CVE استفاده کنیم:

از نماینده موارد زیر را بپرسید:

  • Find the official XZ Utils GitHub repository
  • Search the repository for issues related to CVE-2024-3094

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

مثال گیت‌هاب ابزارهای MCP

اکنون عامل QuantumRoast ADK قادر به تعامل با ابزارهای سرور GitHub MCP است! 🤩

۱۱. تبریک

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

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

  • نحوه راه‌اندازی یک پروژه پایتون برای توسعه ADK.
  • چگونه یک عامل ADK پایه ایجاد کنیم.
  • نحوه پیاده‌سازی و استفاده از ابزارهای تابعی
  • نحوه ادغام ابزارهای داخلی مانند جستجوی گوگل.
  • چگونه می‌توان از ابزارهای شخص ثالث از چارچوب‌هایی مانند LangChain در ADK استفاده کرد.
  • نحوه استفاده از ابزارهای MCP برای تعامل با پایگاه‌های داده (Cloud SQL) و APIها.

فینال QuantumRoast

پاکسازی

شما می‌توانید پروژه ابری خود را حذف کنید تا از هزینه‌های اضافی جلوگیری شود.

اگرچه Cloud Run در صورت عدم استفاده از سرویس، هزینه‌ای دریافت نمی‌کند، اما ممکن است همچنان برای ذخیره تصویر کانتینر در Artifact Registry هزینه دریافت شود. حذف پروژه Cloud شما، پرداخت هزینه برای تمام منابع استفاده شده در آن پروژه را متوقف می‌کند.

اگر مایلید، پروژه را حذف کنید: 

gcloud projects delete $GOOGLE_CLOUD_PROJECT

همچنین ممکن است بخواهید منابع غیرضروری را از دیسک cloudshell خود حذف کنید. می‌توانید:

  1. پوشه پروژه codelab را حذف کنید: 
    rm -rf ~/quantum-roast
  2. هشدار! اقدام بعدی قابل بازگشت نیست! اگر می‌خواهید همه چیز را در Cloud Shell خود حذف کنید تا فضا آزاد شود، می‌توانید کل دایرکتوری خانگی خود را حذف کنید . مراقب باشید که هر چیزی که می‌خواهید نگه دارید در جای دیگری ذخیره شده باشد. 
    sudo rm -rf $HOME