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

1. مقدمه

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

Tools Make an Agent

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

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

2. بررسی اجمالی

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

کباب کوانتومی

شما به هم تیمی‌های خود کمک می‌کنید تا دریایی از نقشه‌های راه مهندسی، محورهای استراتژی ناگهانی (ما در حال انجام ماچا هستیم!) و بلیط‌های دریافتی از مشتریان - همه چیز، از سیستم‌های فاکتور حشره‌دار گرفته تا دستگاه قهوه‌ساز که صدایی با صدای بلند 24/7 ایجاد می‌کند، هدایت کنند.

در یک روز عادی، حدود پنجاه برگه مرورگر باز دارید: سیستم بلیط داخلی، ایمیل، چت، GitHub، جستجوی Google، StackOverflow و موارد دیگر. شما شغل و هم تیمی هایتان را دوست دارید – اما بعضی روزها غرق می شوید.

مدیر پروژه غرق

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

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

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

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

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

نمودار عامل

ابزار 101

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

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

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

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

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

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

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

برای مشاهده همه اینها در عمل، زمان ساخت عامل دستیار اشکال QuantumRoast با استفاده از ADK Python فرا رسیده است.

دستیار QuantumRoast Bug

3. قبل از شروع

راه اندازی پروژه Google Cloud

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

ویرایشگر پوسته ابری را باز کنید

  1. به Cloud Shell Editor بروید
  2. اگر ترمینال در پایین صفحه ظاهر نشد، آن را باز کنید:
    • روی منوی همبرگر کلیک کنید نماد منوی همبرگر
    • روی ترمینال کلیک کنید
    • روی New Terminal کلیک کنید ترمینال جدید را در Cloud Shell Editor باز کنید
  3. در ترمینال، پروژه خود را با این دستور تنظیم کنید (به جای YOUR_PROJECT_ID ):
    • قالب: 
      gcloud config set project YOUR_PROJECT_ID
    • مثال: 
      gcloud config set project lab-project-id-example
    • اگر نمی توانید ID پروژه خود را به خاطر بسپارید:
      • شما می توانید تمام شناسه های پروژه خود را با موارد زیر فهرست کنید: 
        gcloud projects list | awk '/PROJECT_ID/{print $2}'
      شناسه پروژه را در ترمینال Cloud Shell Editor تنظیم کنید
  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

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

پس از ایجاد، می توانید نمونه خود را در Cloud Console در اینجا مشاهده کنید.

یک پایگاه داده Cloud 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 (Cloud SQL)، Cloud SQL Studio را برای نمونه software-assistant باز کنید.

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

Cloud SQL Studio

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

ویرایشگر Cloud SQL Studio

سپس، کد 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 زیر را برای پیاده سازی یک تریگر قرار دهید.

دکمه 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 ردیف را مشاهده کنید که شبیه موارد زیر است:

Cloud SQL DB را تأیید کنید

حالا شما آماده هستید تا به قسمت سرگرم کننده یعنی کد بروید!

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

قبل از اینکه بتوانیم در ساخت عامل خود شیرجه بزنیم، باید مطمئن شویم که راه اندازی پروژه پایتون مناسبی داریم. ما همه این کارها را در 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 با متغیرهای محیطی مورد نیاز برای ADK برای فراخوانی صحیح مدل‌های Gemini است. ما از طریق Vertex API به 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 ID پروژه شما است: 

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

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

5. پایگاه ADK Agent

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

باز کردن agent.py در Cloud Shell Editor: 

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 را باز کنید.

پیش نمایش وب پوسته ابری

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

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

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

از نماینده بپرسید What day is it today? .

مثال وب ADK

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

زمان اجرای اولین نوع ابزار ADK، یک ابزار تابعی است .

6. ابزار تابع

اولین و ساده ترین نوع ابزار 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 استفاده می شود. 

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 Editor: 

cloudshell edit software_bug_assistant/agent.py

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

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 Web Function Tool

نماینده می تواند با تماس با get_current_date Function Tool تاریخ را با موفقیت بگوید! 🎉

زمان بررسی نوع ابزار بعدی ADK است.

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

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

ابزار داخلی

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

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)

در اینجا، ما در واقع ابزار جستجوی Google را با دستورالعمل‌های سیستم خود در عامل خود می‌پیچانیم، و به طور مؤثر از یک عامل به عنوان ابزار استفاده می‌کنیم.

اکنون می‌توانیم search_tool وارد و به root agent در 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) که آسیب‌پذیری‌های امنیت سایبری عمومی هستند محافظت می‌شوند. ما می‌توانیم از ابزار جستجوی Google جدید نماینده خود برای جستجوی وب برای CVEهای اخیراً کشف شده استفاده کنیم.

پرس و جوی زیر را اجرا کنید: Do a web search for 5 of the most recent CVEs? .

نماینده ما باید با search_agent تماس بگیرد تا در وب جستجو کند.

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

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

به نوع ابزار بعدی ADK بروید.

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

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 وارد و به root agent در 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 Web UI به برگه باز خود بازگردید.

سعی کنید از نماینده چیزی در مورد 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!

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

MCP مخفف عبارت Model Context Protocol است. این یک پروتکل باز است که توسط Anthropic در سال 2024 معرفی شده است . MCP یک لایه انتزاعی بین عامل هوش مصنوعی و "پشتیبان" ابزار (API ها، پایگاه های داده) فراهم می کند.

MCP چگونه کار می کند

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

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

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

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

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

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

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

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

جعبه ابزار MCP را برای سرور پایگاه داده در اجرای ابری اجرا کنید

ابتدا جعبه ابزار 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 برای پایگاه‌های داده در 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" \
    --allow-unauthenticated

صبر کنید تا استقرار به پایان برسد...

با جستجو در گزارش‌های Cloud Run، بررسی کنید که جعبه ابزار در حال اجرا است: 

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!"

URL اجرای Cloud را برای سرویس جعبه ابزار به عنوان یک متغیر محیطی ذخیره کنید تا عامل 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 Agent

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

uv add toolbox-core==0.5.0

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

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 وارد و به root agent در agent.py ارسال کنیم: 

cloudshell edit software_bug_assistant/agent.py

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

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 Web UI به برگه باز خود بازگردید.

اکنون می توانید در مورد بلیط های ذخیره شده در پایگاه داده بلیط های داخلی 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 برای ابزارهای پایگاه داده جستجو کرده است!🚀

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

در مورد اتصال عامل ADK ما به ابزارهای MCP که مانند جعبه ابزار MCP برای پایگاه داده SDK خود را ندارند، چطور؟

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

ابزار MCP (API)

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

ابزار MCP GitHub

رمز دسترسی شخصی GitHub (PAT)

برای احراز هویت با سرور GitHub MCP، به یک رمز دسترسی شخصی GitHub نیاز دارید.

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

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

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

export GITHUB_PAT=YOUR_GITHUB_PAT

به روز رسانی QuantumRoast Agent

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

فایل tools.py را باز کنید تا پشتیبانی از ابزارهای GitHub را اضافه کنید. 

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

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

اکنون می‌توانیم mcp_tools وارد و به root agent در 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 Web UI به برگه باز خود بازگردید.

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

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

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

باید ببینید که ابزارهای GitHub توسط نماینده فراخوانی می شوند.

MCP Tools GitHub مثال

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

11. تبریک می گویم

تبریک می گویم! شما با موفقیت عامل دستیار اشکال QuantumRoast را با استفاده از Agent Development Kit (ADK) ساخته‌اید و انواع ابزارهای مختلف را برای افزایش قابلیت‌های آن یکپارچه کرده‌اید. شما با یک عامل اولیه شروع کردید و به تدریج Function Tools، Built-in Tools، Third-Party Tools و MCP Tools را اضافه کردید.

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

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

کوانتوم روست فینال

پاکسازی

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

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

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

gcloud projects delete $GOOGLE_CLOUD_PROJECT

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

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