أدوات إنشاء وكيل: من البداية إلى المساعد باستخدام "حزمة تطوير التطبيقات"

1. مقدمة

في هذا التمرين المعملي، ستنشئ وكيلاً باستخدام حزمة تطوير الوكلاء (ADK). ستتعرّف على كيفية إنشاء وكيل مساعد لتحديد أخطاء البرامج باستخدام "حزمة تطوير التطبيقات" وأنواع مختلفة من الأدوات. ستبدأ باستخدام وكيل أساسي وتضيف تدريجيًا أدوات لتحسين إمكاناته، بما في ذلك أدوات الوظائف والأدوات المضمّنة والأدوات الخارجية وأدوات Model Context Protocol (MCP).

أدوات إنشاء وكيل

أهداف الدورة التعليمية

  • كيفية إعداد مشروع Python لتطوير "حزمة تطوير التطبيقات"
  • كيفية إنشاء وكيل ADK أساسي
  • كيفية تنفيذ أدوات الوظائف واستخدامها
  • كيفية دمج "الأدوات المضمّنة"، مثل "بحث Google"
  • كيفية الاستفادة من الأدوات التابعة لجهات خارجية من أُطر عمل مثل LangChain ضمن "حزمة تطوير التطبيقات"
  • كيفية استخدام أدوات MCP للتفاعل مع قواعد البيانات (Cloud SQL) وواجهات برمجة التطبيقات

2. نظرة عامة

تخيّل أنّك مدير مشروعات في QuantumRoast، وهي شركة عالمية لتصنيع آلات القهوة.

Quantum Roast

تساعد زملاءك في الفريق على التنقّل بين مجموعة كبيرة من خرائط الطريق الهندسية، وتغيير الاستراتيجيات المفاجئ (سنركّز على شاي الماتشا الآن!)، وتذاكر الدعم الواردة من العملاء، بدءًا من أنظمة الفواتير التي تتضمّن أخطاءً إلى آلة القهوة التي تصدر ضوضاء حادة على مدار الساعة طوال أيام الأسبوع.

في يوم عادي، يكون لديك حوالي خمسين علامة تبويب مفتوحة في المتصفّح: نظام التذاكر الداخلية والبريد الإلكتروني والدردشة وGitHub و"بحث Google" وStackOverflow وغير ذلك. أنت تحب وظيفتك وزملاءك، ولكن في بعض الأيام، تشعر بالإرهاق.

مدير المشاريع المُرهَق

ماذا لو كان بإمكاننا إنشاء مساعد لمساعدتك في إنشاء طلبات دعم البرامج وتحديد أولوياتها وتصحيح الأخطاء؟ يُتيح وكيل الذكاء الاصطناعي إمكانية إجراء ذلك.

وكيل الذكاء الاصطناعي

Agent Development Kit (ADK)

‫Agent Development Kit (ADK) هو إطار عمل مرن ونمطي لتطوير وكلاء الذكاء الاصطناعي وتفعيلهم. على الرغم من أنّ ADK محسّن للعمل مع Gemini ومنظومة Google المتكاملة، إلا أنّه لا يعتمد على نموذج معيّن ولا على طريقة نشر معيّنة، وقد تم تصميمه ليكون متوافقًا مع أُطر العمل الأخرى. تم تصميم ADK لجعل عملية تطوير الوكلاء تبدو أقرب إلى تطوير البرامج، ولتسهيل إنشاء البُنى الأساسية للوكلاء ونشرها وتنظيمها، بدءًا من المهام البسيطة وصولاً إلى مهام سير العمل المعقّدة.

‫ADK هو إطار العمل الذي سنستخدمه لإنشاء مساعد أخطاء برامج QuantumRoast.

مخطّط الوكيل

أساسيات الأدوات

تستخدم وكلاء الذكاء الاصطناعي النماذج، وليس مجرد منطق مبرمَج، للتوصل إلى حلّ للمشكلة. لكنّ قدرات وكلاء الذكاء الاصطناعي لا تقتصر على التحليل المستند إلى النماذج اللغوية الكبيرة، بل تتعدّاها إلى جمع البيانات الخارجية ثم اتخاذ إجراء نيابةً عن المستخدم. بدلاً من إخبارك بكيفية حلّ مشكلة ما، يمكن أن يساعدك وكيل الذكاء الاصطناعي في حلّها فعليًا. كيف يمكننا تنفيذ ذلك؟ باستخدام الأدوات

الأداة هي إمكانية تساعد وكيل الذكاء الاصطناعي في التفاعل مع العالم. يمكن أن تكون الأداة أي شيء تقريبًا: وظيفة مضمّنة أو قاعدة بيانات مستضافة أو واجهة برمجة تطبيقات تابعة لجهة خارجية أو حتى وكيل آخر. تتضمّن أُطر عمل وكلاء الذكاء الاصطناعي، مثل مجموعة أدوات تطوير الوكلاء (ADK)، ميزة دعم مدمجة للأدوات، ما يتيح استخدام مجموعة متنوعة من أنواع الأدوات التي سنتناولها بعد قليل.

ولكن كيف يعرف الوكيل متى يجب استدعاء أداة معيّنة وكيفية استدعائها؟ يلعب نموذج الوكيل هنا بعض الأدوار الرئيسية.

طريقة عمل الأدوات

الخطوة الأولى هي اختيار الأداة. نقدّم للوكيل قائمة بالأدوات وبعض التعليمات حول كيفية استخدامها. عندما يطلب المستخدم من الوكيل تنفيذ إجراء معيّن، يساعد نموذج الوكيل في تحديد الأدوات التي يجب استخدامها وسبب استخدامها، وذلك لمساعدة المستخدم.

الخطوة الرئيسية الثانية هي استدعاء الدوال. إنّ تسمية "استدعاء الدوال" هي تسمية خاطئة بعض الشيء لأنّ النموذج لا يستدعي الأداة فعليًا، بل يستعد لاستدعائها من خلال تنسيق نص الطلب الذي يستخدمه الإطار بعد ذلك لاستدعاء الأداة.

أخيرًا، يساعد النموذج في تفسير الردّ من تلك الأداة، مثل قائمة بالأخطاء المفتوحة من قاعدة البيانات، ويقرّر ما إذا كان سيتّخذ إجراءً إضافيًا أو سيردّ على المستخدم بهذه المعلومات.

للاطّلاع على كل ذلك عمليًا، حان الوقت لإنشاء وكيل مساعد أخطاء QuantumRoast باستخدام ADK Python.

QuantumRoast Bug Assistant

3- قبل البدء

إعداد مشروع Google Cloud

  1. إذا لم يكن لديك حساب على Google، عليك إنشاء حساب على Google.
    • استخدام حساب شخصي بدلاً من حساب عمل أو حساب تديره مؤسسة تعليمية قد تتضمّن حسابات العمل والحسابات التي تديرها المؤسسة التعليمية قيودًا تمنعك من تفعيل واجهات برمجة التطبيقات اللازمة لهذا الدرس التطبيقي.
  2. سجِّل الدخول إلى Google Cloud Console.
  3. فعِّل الفوترة في Cloud Console.
    • يجب أن تكلّف إكمال هذا المختبر أقل من دولار أمريكي واحد من موارد السحابة الإلكترونية.
    • يمكنك اتّباع الخطوات في نهاية هذا المختبر لحذف الموارد وتجنُّب تحمّل المزيد من الرسوم.
    • يمكن للمستخدمين الجدد الاستفادة من الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
  4. أنشئ مشروعًا جديدًا أو اختَر إعادة استخدام مشروع حالي.

فتح Cloud Shell Editor

  1. انتقِل إلى محرّر Cloud Shell
  2. إذا لم تظهر المحطة الطرفية في أسفل الشاشة، افتحها باتّباع الخطوات التالية:
    • انقر على قائمة الهامبرغر رمز قائمة الخطوط الثلاثة
    • انقر على Terminal.
    • انقر على نافذة طرفية جديدةفتح نافذة طرفية جديدة في "محرِّر 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 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)

تفعيل واجهات برمجة التطبيقات

في الوحدة الطرفية، شغِّل الأمر التالي لتفعيل واجهات Google Cloud APIs اللازمة:

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 for PostgreSQL

لدى QuantumRoast قاعدة بيانات لطلبات الدعم المتعلقة بالأخطاء تتضمّن جميع طلبات الدعم الداخلية. لنبدأ بإعدادها من خلال إنشاء مثيل Cloud SQL for 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 Console (Cloud SQL)، افتح Cloud SQL Studio للمثيل software-assistant.

سجِّل الدخول إلى قاعدة بياناتtickets-db باستخدام المستخدم postgres وadmin ككلمة مرور.

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

أنت الآن جاهز للانتقال إلى الجزء الممتع، وهو كتابة الرمز البرمجي.

4. إعداد مشروع Python

قبل أن ننتقل إلى إنشاء الوكيل، علينا التأكّد من إعداد مشروع Python بشكل سليم. سننفّذ كل ذلك في Cloud Shell.

أولاً، أنشئ مجلدًا باسم quantum-roast وانتقِل إلى cd:

mkdir quantum-roast && cd quantum-roast

بعد أن أنشأنا مجلدًا لمشروعنا، حان الوقت لتهيئة مشروعنا وإنشاء الملفات المقابلة التي سنحتاج إليها.

سنستخدم uv (أداة إدارة الحِزم والمشاريع السريعة جدًا في Python) التي تأتي مثبّتة مسبقًا في 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 بشكل صحيح. سنصل إلى Gemini من خلال Vertex API.

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.

5- Base ADK Agent

لنبدأ بإعداد وكيل أساسي في "حزمة تطوير التطبيقات" (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). سيؤدي ذلك إلى إنشاء بيئة افتراضية تلقائيًا مع تثبيت "حزمة تطوير التطبيقات" (ADK) باستخدام uv run.

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 Web

ستلاحظ من الردّ أنّ الوكيل لا يمكنه الإجابة عن هذا السؤال الأساسي. تذكَّر أنّ النماذج اللغوية الكبيرة هي أنظمة معزولة تم تدريبها على بيانات سابقة. ليس لديها معلومات في الوقت الفعلي عن الأحداث الأخيرة أو حتى التاريخ الحالي... إلا إذا زوّدتها بأدوات.

حان الوقت لتنفيذ النوع الأول من أدوات "مجموعة أدوات تطوير التطبيقات"، وهو أداة دالة.

6. أداة الدالة

أول أنواع أدوات ADK وأبسطها هي أداة الدالة. وهي تعني حرفيًا ما يبدو عليه الاسم، أي دالة Python يستدعيها الوكيل.

أداة الدالة

أدوات الدوال فعّالة جدًا لأنّها تتيح لك كتابة رمز مخصّص يمكن للوكيل استدعاؤه كأداة، مثل إجراء عملية حسابية أو استدعاء واجهة برمجة تطبيقات أو طلب البحث في قاعدة بيانات. يمكن أن تكون هذه الدوال بسيطة أو معقّدة، فالأمر يعود إليك تمامًا.

في 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 التي سيتم استخدامها كأداة دالة.

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 التالي.

7. أداة مدمَجة

هناك نوع آخر من أدوات ADK وهو أداة مدمَجة. هذه هي الأدوات التي تعمل مع ميزات النموذج الرئيسي من Google، مثل تنفيذ التعليمات البرمجية داخل النموذج نفسه. يمكننا ربط الأداة المضمّنة بحث 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 وتمريره إلى الوكيل الرئيسي في 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],
)

احفظ الملف وارجع إلى النافذة المفتوحة التي يتم فيها تشغيل واجهة مستخدم الويب الخاصة بـ "حزمة تطوير Android".

في QuantumRoast، نريد التأكّد من حماية موقعنا الإلكتروني وبرامجنا من الثغرات والمخاطر الأمنية الشائعة (CVE)، وهي ثغرات أمنية عامة في مجال الأمن السيبراني. يمكننا استخدام أداة "بحث Google" الجديدة الخاصة بالوكيل للبحث على الويب عن أحدث الثغرات الأمنية الشائعة (CVE) التي تم رصدها.

نفِّذ طلب البحث التالي: Do a web search for 5 of the most recent CVEs?.

يجب أن يتصل الوكيل بـ search_agent للبحث على الويب.

مثال على أداة ADK Web المضمّنة

لقد نجحنا الآن في منح وكيلك إذن بالبحث على الويب من خلال الأداة المضمّنة في ADK والمخصّصة لـ "بحث Google". 🎉

ننتقل الآن إلى نوع أداة ADK التالي.

8. الأداة الخارجية

تم تصميم ADK لتكون قابلة للتوسيع بشكل كبير، ما يتيح لك دمج الأدوات بسلاسة من أُطر عمل أخرى لبرامج الذكاء الاصطناعي التابعة لجهات خارجية، مثل CrewAI وLangChain. وتُعدّ إمكانية التشغيل التفاعلي هذه أمرًا بالغ الأهمية لأنّها تتيح تسريع وقت التطوير وإعادة استخدام الأدوات الحالية.

الأداة الخارجية

لربط وكيل تصحيح الأخطاء الخاص بنا ببيانات الأسئلة والأجوبة الفعّالة في StackOverflow، يمكننا الاستفادة من مكتبة أدوات LangChain الشاملة، وتحديدًا أداة StackExchange API Wrapper. تتوافق "حزمة تطوير تطبيقات Android" مع أدوات تابعة لجهات خارجية مثل LangChain، لذا لا تتطلّب إضافة هذه الأداة إلى وكيل "حزمة تطوير تطبيقات Android" سوى بضعة أسطر من الرمز البرمجي.

أولاً، يجب إضافة تبعيات جديدة لكلّ من LangChain وStackOverflow (langchain-community وstackapi) إلى مشروعنا:

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

افتح ملف tools.py لإضافة دعم لأداة LangChain StackExchange.

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.

جرِّب أن تسأل الوكيل عن بعض الثغرات الأمنية السابقة "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?".

مثال على أداة خارجية على الويب في حزمة تطوير التطبيقات

استخدم وكيلنا الآن أداة LangChain بنجاح في "مجموعة أدوات تطوير التطبيقات" (ADK) لإرسال طلب بحث إلى StackOverflow. 🥳

حان الوقت للتعرّف على نوع أداة ADK التالي... أدوات MCP!

9- أداة MCP (قاعدة البيانات)

يشير الاختصار MCP إلى بروتوكول Model Context. وهو بروتوكول مفتوح طرحته شركة Anthropic في عام 2024. توفّر MCP طبقة تجريد بين وكيل الذكاء الاصطناعي و "الخلفيات" (واجهات برمجة التطبيقات وقواعد البيانات) للأدوات.

طريقة عمل MCP

تتضمّن "منصة المحتوى المميّز" بعض المواصفات الفريدة. على عكس بروتوكول HTTP العادي، يوفّر بروتوكول MCP اتصالاً ثنائي الاتجاه بين العميل والخادم. تتضمّن هذه الأداة طريقة خاصة لتحديد الأدوات ورسائل الخطأ الخاصة بكل أداة. يمكن لمزوّد الأداة بعد ذلك إنشاء خوادم MCP استنادًا إلى واجهات برمجة التطبيقات الخاصة به، ما يتيح توفير أداة واحدة أو أكثر من الأدوات المُنشأة مسبقًا للمطوّرين والمستخدمين. بعد ذلك، يمكن لأُطر عمل الوكلاء تهيئة عملاء MCP داخل تطبيق وكيل، وذلك لاكتشاف هذه الأدوات واستدعائها.

في QuantumRoast، لدينا قاعدة بيانات Cloud SQL for PostgreSQL لتسجيل أخطاء البرامج الداخلية. نريد إنشاء أدوات ADK ليتمكّن وكيلنا من تنفيذ طلبات بحث معيّنة في قاعدة البيانات.

قاعدة بيانات أداة MCP

أسهل طريقة للقيام بذلك هي استخدام MCP Toolbox for Databases، وهو خادم MCP مفتوح المصدر لقواعد البيانات. تتوافق Toolbox مع أكثر من 15 قاعدة بيانات، إحداها هي Cloud SQL.

توفّر مجموعة الأدوات ما يلي:

  • تطوير مبسط: يمكنك دمج الأدوات في برنامجك الآلي باستخدام أقل من 10 أسطر من الرموز البرمجية، وإعادة استخدام الأدوات بين برامج آلية أو أُطر متعددة، ونشر إصدارات جديدة من الأدوات بسهولة أكبر.
  • أداء أفضل: أفضل الممارسات، مثل تجميع الاتصالات والمصادقة وغير ذلك
  • أمان محسّن: مصادقة مدمجة للوصول إلى بياناتك بشكل أكثر أمانًا
  • إمكانية المراقبة الشاملة: مقاييس وتتبُّع جاهزان للاستخدام مع دعم مدمج لـ OpenTelemetry

تتضمّن حزمة ADK دعمًا لأدوات MCP Toolbox لقواعد البيانات، ما يسهّل عملية الدمج.

MCP Toolbox for Databases

نشر MCP Toolbox for Databases Server على Cloud Run

أولاً، سننشر MCP Toolbox for Databases Server على 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.

سنخزّن ملف tools.yaml في Secret Manager لأنّه يحتوي على بيانات اعتماد حساسة في 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

يُرجى الانتظار إلى أن تنتهي عملية النشر...

تأكَّد من أنّ Toolbox قيد التشغيل من خلال طلب بيانات سجلّات 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 لخدمة Toolbox على Cloud Run كمتغيّر بيئة لكي يعرف وكيل 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

ثانيًا، يجب إضافة العنصر التابع لحزمة تطوير البرامج (SDK) الخاصة بأداة MCP Toolbox لقواعد البيانات (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 وتمريره إلى الوكيل الرئيسي في 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 لقواعد البيانات!🚀

10. اختياري: أداة MCP (واجهة برمجة التطبيقات)

ماذا عن ربط وكيل ADK بأدوات MCP التي لا تتضمّن حزمة SDK خاصة بها، مثل MCP Toolbox for Database؟

يتوافق ADK مع أدوات إدارة الموافقة العامة من خلال فئة MCPToolset. فئة MCPToolset هي الآلية الأساسية في حزمة تطوير التطبيقات (ADK) لدمج الأدوات من خادم MCP.

أداة MCP (واجهة برمجة التطبيقات)

يمكن استخدام MCPToolset للاتصال بخوادم MCP محلية أو بعيدة، ونريد في QuantumRoast ربط وكيلنا بخادم MCP البعيد في GitHub لتسهيل استدعاء واجهات برمجة التطبيقات في GitHub. سيسمح ذلك لموظف الدعم باستخراج معلومات حول المشاكل من مستودعات البرامج المتاحة للجميع أو حتى من قواعد بيانات الرموز الخاصة بنا. يعرض خادم GitHub MCP أجزاء مختلفة من وظائف GitHub، بدءًا من المشاكل وطلبات السحب، وصولاً إلى الإشعارات وأمان الرموز البرمجية.

أداة MCP على GitHub

رمز الدخول الشخصي (PAT) في GitHub

للمصادقة باستخدام خادم GitHub MCP، تحتاج إلى رمز وصول شخصي على GitHub.

للحصول على بطاقة، اتّبِع الخطوات التالية:

  1. انتقِل إلى إعدادات المطوّرين في GitHub.
  2. انقر على "رموز الدخول الشخصية" -> "الرموز المميزة (القديمة)".
  3. انقر على "إنشاء رمز مميّز جديد" -> "إنشاء رمز مميّز جديد (الإصدار الكلاسيكي)".
  4. أدخِل اسمًا وصفيًا للرمز المميّز.
  5. حدِّد تاريخ انتهاء صلاحية الرمز المميّز.
  6. ملاحظة مهمة: لأسباب أمنية، امنح الرمز المميز النطاقات الأكثر محدودية اللازمة. للحصول على إذن بالقراءة فقط للمستودعات، تكون نطاقات repo:status وpublic_repo وread:user كافية في أغلب الأحيان. تجنَّب منح أذونات كاملة للمستودع أو المشرف إلا إذا كان ذلك ضروريًا للغاية.
  7. انقر على Generate token.
  8. انسخ الرمز المميز الذي تم إنشاؤه.

في نافذة Cloud Shell الطرفية، شغِّل الأمر التالي لضبط رمز PAT الخاص بك على GitHub ليتمكّن الوكيل من استخدامه. استبدِل YOUR_GITHUB_PAT برمز PAT الذي تم إنشاؤه.

export GITHUB_PAT=YOUR_GITHUB_PAT

تعديل وكيل QuantumRoast

بالنسبة إلى مساعد تصحيح الأخطاء، سنعرض بعض أدوات GitHub للقراءة فقط، وذلك للسماح لموظفي QuantumRoast بالعثور على مشاكل متعلقة بالتبعيات المفتوحة المصدر، ومعرفة ما إذا كان ذلك سيساعد في تحديد السبب الجذري للأخطاء التي يرونها في نظام التذاكر الداخلي. سنستخدم MCPToolset في "حزمة تطوير التطبيقات على Android" مع 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",
    ],
)

لاحظ كيف نحتاج أيضًا إلى تقديم رمز الوصول الشخصي (PAT) من GitHub إلى تعريف MCPToolset، تمامًا كما لو كنت ستوفّر رمز مصادقة عند إعداد برنامج عادي للوصول إلى واجهة برمجة التطبيقات في الرمز البرمجي. يقتصر نطاق رمز 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 على GitHub يمكن أن يستدعيها الوكيل. تعتمد خدمات QuantumRoast على XZ utils، وهي أداة لضغط البيانات. يتتبّع نظام تذاكر الأخطاء الداخلية CVE (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 على GitHub

أصبح بإمكان وكيل QuantumRoast ADK التفاعل مع أدوات خادم MCP في GitHub. 🤩

11. تهانينا

تهانينا! لقد أنشأت بنجاح وكيل QuantumRoast لمساعدتك في إصلاح الأخطاء باستخدام مجموعة أدوات تطوير الوكلاء (ADK) ودمجت أنواعًا مختلفة من الأدوات لتعزيز إمكاناته. بدأت باستخدام وكيل أساسي وأضفت تدريجيًا أدوات الوظائف والأدوات المضمّنة والأدوات الخارجية وأدوات MCP.

المواضيع التي تناولناها

  • كيفية إعداد مشروع Python لتطوير "حزمة تطوير التطبيقات"
  • كيفية إنشاء وكيل ADK أساسي
  • كيفية تنفيذ أدوات الوظائف واستخدامها
  • كيفية دمج "الأدوات المضمّنة"، مثل "بحث Google"
  • كيفية الاستفادة من الأدوات التابعة لجهات خارجية من أُطر عمل مثل LangChain ضمن "حزمة تطوير التطبيقات"
  • كيفية استخدام أدوات MCP للتفاعل مع قواعد البيانات (Cloud SQL) وواجهات برمجة التطبيقات

QuantumRoast Final

تنظيف

يمكنك حذف مشروعك على Google Cloud لتجنُّب تكبُّد رسوم إضافية.

على الرغم من أنّ Cloud Run لا يفرض رسومًا عندما لا تكون الخدمة قيد الاستخدام، قد يتم تحصيل رسوم منك مقابل تخزين صورة الحاوية في Artifact Registry. يؤدي حذف مشروعك على السحابة الإلكترونية إلى إيقاف الفوترة لجميع الموارد المستخدَمة في هذا المشروع.

إذا أردت، يمكنك حذف المشروع باتّباع الخطوات التالية:

gcloud projects delete $GOOGLE_CLOUD_PROJECT

يمكنك أيضًا حذف الموارد غير الضرورية من قرص cloudshell. يمكنك إجراء ما يلي:

  1. احذف دليل مشروع الدرس البرمجي: 
    rm -rf ~/quantum-roast
  2. تحذير! لا يمكن التراجع عن هذا الإجراء. إذا أردت حذف كل المحتوى على Cloud Shell لإخلاء بعض المساحة، يمكنك حذف دليلالمنزل بأكمله. يُرجى التأكّد من حفظ كل ما تريد الاحتفاظ به في مكان آخر. 
    sudo rm -rf $HOME