تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

1. مقدمة

‫Google Workspace هو المكان الذي يتم فيه إنجاز العمل. بدءًا من إعداد مسودات التقارير في "مستندات Google" إلى تحليل البيانات في "جداول بيانات Google" والتعاون في Gmail وMeet

تخيّل الآن أنّ "مستندات Google" و"جداول بيانات Google" وGmail ليست مجرد أدوات، بل هي متعاونون.

بفضل "حزمة تطوير الوكيل" (ADK) من Google و"محرك الوكيل" في Vertex AI، لم يعُد ذلك مجرد فكرة، بل سنستخدم هذه الأُطر لإنشاء وكيل ذكي ونشره على نطاق واسع ودمجه بسلاسة في أدوات Google Workspace، ما يتيح عصرًا جديدًا من الإنتاجية المستندة إلى الوكلاء.

في هذا الدرس البرمجي، ستتّبع نهجًا خطوة بخطوة على النحو التالي:

تطوير "وكيل التحقّق من الحقائق" المستند إلى الذكاء الاصطناعي باستخدام "حزمة تطوير الوكلاء"
يمكنك نشر Agent في Agent Engine، وهي بيئة مُدارة بالكامل لتشغيل الوكلاء على نطاق واسع.
يمكنك دمج هذا الوكيل في "مستندات Google" للتحقّق من صحة النص في المستند.

في ما يلي مخطط مفاهيمي يوضّح طريقة عمل الحل النهائي:

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

المهام التي ستنفذها

تصميم وكيل وإنشاؤه ونشره لإجراء عمليات التحقّق من صحة الأخبار داخل "مستند Google"

ما ستتعلمه

تطوير وكيل باستخدام "حزمة تطوير الوكلاء" (AK)
اختبِر الوكيل محليًا ونشِّره على Agent Engine.
دمج "الوكيل" في مستند Google Workspace (مستند Google)

المتطلبات

متصفّح الويب Chrome
حساب Gmail
مشروع على السحابة الإلكترونية تم تفعيل الفوترة فيه

يستخدم هذا الدرس العملي، المصمّم للمطوّرين من جميع المستويات (بما في ذلك المبتدئين)، لغة Python وApps Script في الرمز النموذجي. ومع ذلك، لا يُشترط معرفة لغات البرمجة هذه، وستكون القدرة الأساسية على قراءة الرموز البرمجية كافية لفهم المفاهيم المقدَّمة.

2. قبل البدء

إنشاء مشروع

في Google Cloud Console، ضمن صفحة اختيار المشروع، اختَر أو أنشِئ مشروعًا على Google Cloud.
تأكَّد من تفعيل الفوترة لمشروعك على Cloud. تعرَّف على كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع .

ستستخدم Cloud Shell، وهي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بأداة bq. انقر على "تفعيل Cloud Shell" في أعلى "وحدة تحكّم Google Cloud".

صورة زر تفعيل Cloud Shell

بعد الاتصال بـ Cloud Shell، تحقَّق من أنّك قد تمّت مصادقتك وأنّه تم ضبط المشروع على معرّف مشروعك باستخدام الأمر التالي:

gcloud auth list

نفِّذ الأمر التالي في Cloud Shell للتأكّد من أنّ أمر gcloud يعرف مشروعك.

gcloud config list project

إذا لم يتم ضبط مشروعك، استخدِم الأمر التالي لضبطه:

gcloud config set project <YOUR_PROJECT_ID>

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

gcloud services enable cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       aiplatform.googleapis.com \
                       discoveryengine.googleapis.com

عند تنفيذ الأمر بنجاح، من المفترض أن تظهر لك رسالة مشابهة للرسالة الموضّحة أدناه:

Operation "operations/..." finished successfully.

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

راجِع المستندات لمعرفة أوامر gcloud وطريقة استخدامها.

3- إنشاء وكيل ADK

لننشئ الآن وكيل ADK (Document Fact Checker Agent)، وهو مدقّق مستند إلى الذكاء الاصطناعي يتحقّق من صحة النص، مستوحى من وظيفة Google المخصّصة للتحقّق من صحة الأخبار sample. على عكس النهج المكوّن من خطوة واحدة في العيّنة، يستخدم الوكيل أسلوب التفكير المتعدّد الخطوات لاستخراج الادعاءات والتحقّق منها باستخدام google_search وإخراج JSON منظَّم.

الخطوة 1 : تثبيت "حزمة تطوير الوكيل"

افتح علامة تبويب جديدة في Cloud Shell وأنشئ مجلدًا باسم my-agents على النحو التالي. انتقِل أيضًا إلى المجلد my-agents.

mkdir workspace-agents
cd workspace-agents

لننشئ الآن بيئة Python افتراضية باستخدام venv على النحو التالي:

python -m venv .venv

فعِّل البيئة الافتراضية باتّباع الخطوات التالية:

source .venv/bin/activate

ثبِّت "حزمة تطوير التطبيقات" (ADK) على النحو التالي:

pip install google-adk

ستتمكّن الآن من استدعاء الأداة المساعدة adk على النحو التالي.

adk

ستظهر لك قائمة بالأوامر.

$ adk
Usage: adk [OPTIONS] COMMAND [ARGS]...

  Agent Development Kit CLI tools.

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  api_server   Starts a FastAPI server for agents.
  conformance  Conformance testing tools for ADK.
  create       Creates a new app in the current folder with prepopulated agent template.
  deploy       Deploys agent to hosted environments.
  eval         Evaluates an agent given the eval sets.
  eval_set     Manage Eval Sets.
  run          Runs an interactive CLI for a certain agent.
  web          Starts a FastAPI server with Web UI for agents.

الخطوة 2 : تطوير "وكيل التحقّق من صحة المستندات" باستخدام "حزمة تطوير التطبيقات"

سنستخدم الآن adk لإنشاء بنية أساسية للوكيل من خلال الأمر adk create مع اسم التطبيق **(docfactcheckeragent)**كما هو موضّح أدناه.

adk create docfactcheckeragent

اتّبِع الخطوات واختَر ما يلي:

نموذج Gemini لاختيار نموذج للوكيل الأساسي
اختَر Vertex AI للواجهة الخلفية.
سيتم عرض رقم تعريف مشروع Google التلقائي ومنطقتك. اختَر القيمة التلقائية نفسها.

Choose a model for the root agent:
1. gemini-2.5-flash
2. Other models (fill later)

Choose model (1, 2): 1
1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

You need an existing Google Cloud account and project, check out this link for details:
https://google.github.io/adk-docs/get-started/quickstart/#gemini---google-cloud-vertex-ai

Enter Google Cloud project ID [YOUR_PROJECT_ID]: 
Enter Google Cloud region [us-central1]: 

Agent created in <YOUR_HOME_FOLDER>/workspace-agents/docfactcheckeragent:
- .env
- __init__.py
- agent.py

لاحظ المجلد الذي تم فيه إنشاء نموذج تلقائي والملفات المطلوبة للوكيل.

أولاً، يجب إنشاء ملف .env. يمكنك الاطّلاع على محتوى هذه الرسالة أدناه:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

تشير القيم إلى أنّنا سنستخدم Gemini من خلال Vertex AI مع القيم ذات الصلة لرقم تعريف المشروع على Google Cloud والموقع الجغرافي.

بعد ذلك، لدينا الملف __init__.py الذي يحدّد المجلد كوحدة نمطية ويتضمّن عبارة واحدة تستورد الوكيل من الملف agent.py.

from . import agent

أخيرًا، هناك ملف agent.py. عليك استبدال المحتوى في ملف agent.py هذا بالرمز البرمجي الموضّح أدناه:

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

root_agent = Agent(
    name='ai_auditor',
    model='gemini-2.5-flash',
    description="Fact-checks statements from a document and provides citations.",
    instruction="""
You are an AI Auditor specialized in factual verification and evidence-based reasoning.
Your goal is to analyze text from a Google Doc, identify verifiable factual claims, and produce a concise, source-backed audit report.

### 🔍 TASK FLOW

1. **Extract Claims**
   - Analyze the input text and identify factual claims that can be objectively verified.
   - A factual claim is any statement that can be proven true or false with external evidence.
   - Skip opinions, vague generalizations, or speculative language.
   - List each claim as a string in a JSON array.

2. **Verify Claims**
   - For each extracted claim:
     - Use the `google_search` tool to find relevant, credible results.
     - Evaluate at least the top 3 relevant URLs to determine the claim's accuracy.
     - Cross-check multiple sources when possible to ensure confidence.

3. **Classify Findings**
   - For each claim, determine one of the following verdicts:
     - ✅ **True:** Supported by multiple reputable sources.
     - ⚠️ **Misleading / Partially True:** Contains partially correct or context-dependent information.
     - ❌ **False:** Contradicted by credible evidence.
     - ❓ **Unverifiable:** Insufficient information to confirm or deny.
   - Provide a **confidence score (0–100)** reflecting the strength of evidence.

4. **Record Evidence**
   - For each claim, include:
     - The **verdict**
     - **Reasoning summary** (1–2 sentences)
     - **List of citation URLs** used for verification

5. **Summarize Results**
   - Compile a final report including:
     - Total number of claims analyzed
     - Distribution of verdicts (True / False / Misleading / Unverifiable)
     - Brief overall conclusion (e.g., "Most claims are accurate but some lack supporting evidence.")

### 🧾 OUTPUT FORMAT

Return your final response in structured JSON format as follows:

{
  "claims": [
    {
      "claim": "...",
      "verdict": "True | False | Misleading | Unverifiable",
      "confidence": 0-100,
      "reasoning": "...",
      "sources": ["https://...", "https://..."]
    }
  ],
  "summary": {
    "total_claims": X,
    "verdict_breakdown": {
      "True": X,
      "False": X,
      "Misleading": X,
      "Unverifiable": X
    },
    "overall_summary": "..."
  }
}

### 🧠 ADDITIONAL INSTRUCTIONS
- Always prefer authoritative domains (.gov, .edu, .org, or major media).
- Avoid low-quality or user-generated content as primary sources.
- Be concise, accurate, and transparent about uncertainty.
    """,
    tools=[google_search],  # Only use the search tool
)

في ما يلي النقاط الرئيسية لرمز المصدر أعلاه:

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

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

الخطوة 3 : اختبار الوكيل محليًا

من نافذة الوحدة الطرفية الحالية، أدخِل الأمر التالي. تأكَّد من أنّك في المجلد الرئيسي (workspace-agents) الذي يحتوي على المجلد docfactcheckeragent.

adk web

في ما يلي نموذج للتنفيذ:

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

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

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

انقر على الرابط الأخير، وسيؤدي ذلك إلى فتح وحدة تحكّم على الويب لاختبار "الوكيل". تُعدّ تفاعلاتنا الأولى أساسية، إذ إنّها تساعدنا في فهم ما يمكن أن يفعله الوكيل. ويختبر ذلك قدرة الوكيل على تلخيص description وinstruction text.

يقدم الوكيل ملخصًا موجزًا لقدراته، مستندًا إلى وصفه ومجموعة التعليمات.

بعد ذلك، نزوّده بعبارتَين (The sky is blue due to Rayleigh scattering. The Earth is flat.)، ويدقّق بنجاح في المحتوى ويعرض استجابة JSON منظَّمة بشكل جيد.

الخيارات المتقدّمة:

تستردّ أداة google_search الصفحات ذات الصلة من الويب.
يحلّل نموذج Gemini 2.5 Flash هذه المقتطفات ويصنّفها حسب مدى صحتها.
تتولّى حزمة تطوير التطبيقات (ADK) تنظيم عملية الاستدلال وتضمن اتّباع منطق خطوة بخطوة.

تساعد مرحلة الاختبار المحلية هذه في التحقّق من صحة سير عمل الوكيل قبل نشره على Vertex AI Agent Engine، حيث يمكن ربطه بأدوات Google Workspace، مثل "مستندات Google" أو "جداول بيانات Google".

باختصار، أنشأنا "وكيل تدقيق" قويًا يعمل بالذكاء الاصطناعي باستخدام "حزمة تطوير الوكلاء" (ADK) من Google. تمكّن الوكيل من قراءة النص وتحديد الادعاءات الواقعية والبحث في مصادر موثوقة (باستخدام أداة google_search) وتقديم حكم واضح.

لقد أنشأنا واختبرنا كل شيء محليًا من خلال واجهة الويب الخاصة بـ ADK، ورأينا كيف حلّل الوكيل عبارة مثل:

The sky is blue due to Rayleigh scattering. The Earth is flat.

أكّد الوكيل أنّ إحدى المطالبتَين هي true، وأشار إلى أنّ الأخرى هي false، وهذا دليل بسيط ولكنّه مناسب على أنّ الإعداد المحلي يعمل بشكلٍ مثالي.

حان الوقت الآن لاتّخاذ الخطوة الكبيرة التالية، وهي الانتقال من التخزين المحلي إلى التخزين على السحابة الإلكترونية. لننفّذ ذلك في الخطوة التالية.

4. تفعيل الوكيل في "محرك وكلاء Vertex AI"

لا يقتصر استخدام الوكيل الحقيقي على الاختبار على الكمبيوتر المحمول، بل يمكنك تشغيله على نطاق واسع ودمجه مع أنظمة أخرى ونشره في مرحلة الإنتاج على مستوى تطبيقاتك.

لماذا يجب نشر التطبيق؟

في ما يلي بعض الأسباب الوجيهة لنشر "البرامج الآلية" في السحابة الإلكترونية.

قابلية التوسّع: يمكنك معالجة الطلبات الكثيرة بدون حدود وقت التشغيل المحلية.
الموثوقية: تتضمّن عمليات رصد وتوسيع نطاق تلقائية، بالإضافة إلى إصلاحات، مثل تحديث إعدادات أداة ADK في 18 أكتوبر 2025.
جاهز للتكامل: يمكنك عرض نقطة نهاية لواجهة برمجة التطبيقات لإجراء مكالمات Workspace بسلاسة.

لماذا Vertex AI Agent Engine؟

يمكنك اعتبار "محرك وكلاء Vertex AI" المكان المناسب لوكلاء ADK الذين تم تفعيلهم، فهو بيئة مُدارة مصمّمة لتوفير الموثوقية وقابلية التوسّع والتكامل.

يمنح هذا الإذن الوكيل ما يلي:

الحالة والذاكرة الثابتتان
استخدام الأدوات المدمجة (مثل ‫(Google Search، ونماذج Vertex AI)
تأمين نقاط نهاية واجهة برمجة التطبيقات للطلبات الخارجية
التسجيل وإمكانية تتبُّع البيانات من خلال Cloud Logging
إتاحة التنسيق بين وكلاء متعدّدين

باختصار، يمكنك الكتابة مرة واحدة باستخدام ADK، ثم توسيع نطاقها باستخدام Agent Engine.

الخطوة 1 : الإعداد للنشر

علينا إجراء بعض الخطوات قبل نشر وكيل Vertex AI Agent Engine. تتطلّب عملية النشر إنشاء حزمة Google Cloud Storage لعناصر الوكيل، كما يجب توفير ملف requirements.txt، لكي تكون جميع التبعيات المطلوبة لتشغيل رمز الوكيل متاحة لبيئة وقت التشغيل في Agent Engine.

في نافذة Cloud Shell، أدخِل الأمر التالي لإنشاء حزمة (تذكَّر استبدال YOUR_BUCKET_NAME وYOUR_PROJECT_ID وYOUR_PROJECT_REGION بالقيم الفعلية الخاصة بمشروعك):

gcloud storage buckets create gs://YOUR_BUCKET_NAME \
                              --project=YOUR_PROJECT_ID \
                              --location=YOUR_PROJECT_REGION

بعد ذلك، أنشئ ملف requirements.txt التالي في المجلد الجذر (workspace-agents)، ويتم عرض محتواه أدناه:

google-cloud-aiplatform
google-adk
requests

الخطوة 2 : نشر الوكيل

الخطوة التالية هي نشر الوكيل في "محرك وكيل Vertex AI" باستخدام الأمر adk deploy.

adk deploy agent_engine \
    --project=YOUR_PROJECT_ID \
    --region=YOUR_PROJECT_REGION \
    --display_name "Doc Fact Checker" \
    --staging_bucket gs://YOUR_BUCKET_NAME \
    --requirements_file requirements.txt \
    docfactcheckeragent/

من المفترض أن يؤدي ذلك إلى بدء عملية نشر الوكيل في Agent Engine. تستغرق هذه العملية وقتًا طويلاً، ومن المتوقّع أن تستغرق حوالي 5 دقائق. في ما يلي نظرة عامة على ما يحدث:

بدء إنشاء الوكيل: تعمل حزمة ADK CLI على تجميع الرمز البرمجي وتحميله إلى حزمة Cloud Storage، كما أنّها تُفعّل Vertex AI لإنشاء مثيل جديد من Agent Engine.
يتم تزويدك برابط "السجلات"، حيث يمكنك عرض "مستكشف سجلات Cloud" لمشروعك. انقر عليه لعرض تفاصيل التقدّم، بما في ذلك خطوات الإعداد وتثبيت التبعيات وتهيئة النموذج. إذا حدث خطأ (مثل عدم توفّر تبعية أو مشكلة في الأذونات)، ستظهر لك رسالة الخطأ هنا.
رسالة الاكتمال - بعد اكتمال عملية النشر، ستظهر لك رسالة تأكيد في نافذة الأوامر تتضمّن معرّف Reasoning Engine. في ما يلي عينة منها:

AgentEngine created. Resource name: projects/SOME_ID/locations/REGION/reasoningEngines/SOME_ID

الخطوة 3 : تأكيد صحة بيانات الوكيل في Cloud Console (محرك الوكيل)

بعد اكتمال عملية النشر، انتقِل إلى قسم Vertex AI → Agent Engine في وحدة تحكّم Google Cloud. من المفترض أن يظهر لك الوكيل الذي تم نشره في وحدة التحكّم كما هو موضّح أدناه:

🎉 انتهى الأمر. أصبح الوكيل متاحًا الآن على Vertex AI وجاهزًا للدمج في Google Workspace أو اختباره مباشرةً.

الخطوة 4 : اختبار وكيل النشر

تهانينا، أصبح الوكيل متاحًا الآن على "محرك وكيل Vertex AI". الخطوة التالية هي اختبار ما إذا كان قد تم نشره بشكل صحيح ويستجيب للطلبات.

هناك بعض الطرق المختلفة لتنفيذ ذلك، حسب طريقة العمل المفضّلة لديك:

من خلال Google Cloud Console: واجهة مرئية تتيح لك عرض العملاء الذين تم نشرهم وإدارتهم واختبارهم مباشرةً.
استخدام واجهة REST API (cURL): هذه الطريقة مثالية للمطوّرين الذين يريدون إرسال الطلبات وفحص الردود يدويًا.
باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Vertex AI للغة Python: خيار أكثر قابلية للبرمجة لدمج الاختبار في سير عمل التطوير

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

أصبح "مدقّق الذكاء الاصطناعي" الآن وكيلاً مستندًا إلى السحابة الإلكترونية، وتم نشره في Vertex AI Agent Engine، وهو جاهز للتحقّق من الحقائق على نطاق واسع باستخدام google_search. لقد تحوّل إلى زميل رقمي موثوق يعتمد على واجهة برمجة التطبيقات، ويقدّم مخرجات بتنسيق JSON مثل:

{ "claims": [{"claim": "The sky is blue...", "verdict": "True", "confidence": 95}] }

سنجرّب ذلك مباشرةً في القسم التالي، حيث سنُدرج الوكيل داخل مستند Google ونتأكّد من صحة الحقائق الواردة في المستند.

5- دمج Fact Checker Agent في "مستندات Google"

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

الخطوة 1: إعداد بيئة "مستندات Google"

ابدأ بفتح مستند Google جديد أو حالي (docs.new).

يحتوي مستند Google الذي نستخدمه في هذا البرنامج التعليمي على المحتوى التالي (يمكنك استخدام هذا المحتوى أو المحتوى الخاص بك الذي تخطط للتحقق من صحته):

Climate change is mainly caused by solar activity cycles, not human activities. The Earth's temperature has not increased significantly in the last 100 years. Wind energy now produces more electricity than coal in every country in Europe. In 2015, nearly all world nations signed the Paris Agreement to limit global warming.

الخطوة 2: إعداد مشروع وملفات "نصوص برمجية للتطبيقات"

ستحتاج إلى ملفَين في مشروع "برمجة تطبيقات Google" لإجراء عملية الإعداد هذه:

‫AIVertex.gs: يتعامل مع جميع عمليات التواصل مع Vertex AI ووكيل ADK.
Code.gs: يتحكّم في واجهة "مستندات Google" والقوائم وإجراءات المستندات.

من القائمة، انتقِل إلى Extensions -> Apps Script لفتح أداة التعديل. سنستخدم هذه المساحة للاتصال بـ "وكيل حزمة تطوير التطبيقات على Android" الذي تم نشره. ستجد ملف Code.gs تم إنشاؤه مسبقًا، وعليك استبدال محتواه برمز Code.gs المقدَّم في القسم التالي.

دعونا نتحدّث عن كل مرحلة.

AIVertex.gs

أنشئ ملفًا جديدًا من خلال علامة الجمع بجانب قسم "الملفات" على يمين الشاشة، واختَر Script وانسخ المحتوى التالي فيه.

const LOCATION = PropertiesService.getScriptProperties().getProperty('LOCATION');
const GEMINI_MODEL_ID = PropertiesService.getScriptProperties().getProperty('GEMINI_MODEL_ID');
const REASONING_ENGINE_ID = PropertiesService.getScriptProperties().getProperty('REASONING_ENGINE_ID');
const SERVICE_ACCOUNT_KEY = PropertiesService.getScriptProperties().getProperty('SERVICE_ACCOUNT_KEY');

const credentials = credentialsForVertexAI();

/**
 * @param {string} statement The statement to fact-check.
 */
function requestLlmAuditorAdkAiAgent(statement) {
  return UrlFetchApp.fetch(
    `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
      contentType: 'application/json',
      muteHttpExceptions: true,
      payload: JSON.stringify({
        "class_method": "async_stream_query",
        "input": {
          "user_id": "google_sheets_custom_function_fact_check",
          "message": statement,
        }
      })
    }
  ).getContentText();
}

/**
 * @param {string} prompt The Gemini prompt to use.
 */
function requestOutputFormatting(prompt) {
  const response = UrlFetchApp.fetch(
    `https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${credentials.projectId}/locations/${LOCATION}/publishers/google/models/${GEMINI_MODEL_ID}:generateContent`,
    {
      method: 'post',
      headers: { 'Authorization': `Bearer ${credentials.accessToken}` },
      contentType: 'application/json',
      muteHttpExceptions: true,
      payload: JSON.stringify({
        "contents": [{
          "role": "user",
          "parts": [{ "text": prompt }]
        }],
        "generationConfig": { "temperature": 0.1, "maxOutputTokens": 2048 },
        "safetySettings": [
          {
            "category": "HARM_CATEGORY_HARASSMENT",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_HATE_SPEECH",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
            "threshold": "BLOCK_NONE"
          },
          {
            "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
            "threshold": "BLOCK_NONE"
          }
        ]
      })
    }
  );
  return JSON.parse(response).candidates[0].content.parts[0].text
}

/**
 * Gets credentials required to call Vertex API using a Service Account.
 * Requires use of Service Account Key stored with project.
 * 
 * @return {!Object} Containing the Google Cloud project ID and the access token.
 */
function credentialsForVertexAI() {
  const credentials = SERVICE_ACCOUNT_KEY;
  if (!credentials) {
    throw new Error("service_account_key script property must be set.");
  }

  const parsedCredentials = JSON.parse(credentials);

  const service = OAuth2.createService("Vertex")
    .setTokenUrl('https://oauth2.googleapis.com/token')
    .setPrivateKey(parsedCredentials['private_key'])
    .setIssuer(parsedCredentials['client_email'])
    .setPropertyStore(PropertiesService.getScriptProperties())
    .setScope("https://www.googleapis.com/auth/cloud-platform");
  return {
    projectId: parsedCredentials['project_id'],
    accessToken: service.getAccessToken(),
  }
}

تذكَّر حفظ الملف.

يؤدّي هذا الملف الإجراءات التالية:

تتم المصادقة بشكل آمن على Vertex AI باستخدام مفتاح حساب خدمة. يتم استدعاء "وكيل ADK" الذي تم نشره لتحليل نص المستند أو التحقّق من صحة المعلومات الواردة فيه.
يستخدم Gemini لتنسيق الردود الذكية، ما يجعل النتائج سهلة القراءة.

Code.gs

/**
 * Adds a custom menu in Google Docs to run the AI Audit directly.
 */
function onOpen() {
  DocumentApp.getUi()
    .createMenu('AI Audit Tools')
    .addItem('Run AI Audit', 'runAuditAndInsert')
    .addToUi();
}

/**
 * Returns the entire text content of the document.
 */
function getDocumentText() {
  const doc = DocumentApp.getActiveDocument();
  const body = doc.getBody();
  let text = body.getText();
  return text.trim();
}

/**
 * Runs the AI Audit and inserts the result as text at the end of the document.
 */
function runAuditAndInsert() {
  const docText = getDocumentText();
  const result = runAudit(docText);

  if (result) {
    const doc = DocumentApp.getActiveDocument();
    const body = doc.getBody();
    // Append the audit result as a new paragraph at the end of the document
    body.appendParagraph('AI Audit Result: ' + result);
  }
}

/**
 * Runs the AI Audit using ADK Agent and Gemini formatting.
 */
function runAudit(docText) {
  console.log('[INFO] Starting AI audit process...');
  if (!docText) {
    console.log('[WARN] No text in document.');
    return '⚠️ The document is empty. Please add some text to audit.';
  }

  // Check for excessive document length to avoid token limits
  if (docText.length > 10000) {
    console.log('[WARN] Document too long.');
    return '⚠️ Document exceeds 10,000 characters. Please shorten the text.';
  }

  console.log('[STEP] Sending text to ADK Agent...');
  const rawAudit = requestLlmAuditorAdkAiAgent(docText);

  // Check if rawAudit is an error message
  if (rawAudit.startsWith('ERROR:')) {
    console.error('[ERROR] ADK Agent returned error:', rawAudit);
    return rawAudit;
  }

  console.log('[STEP] Formatting AI response...');
  let formatted;
  try {
    formatted = requestOutputFormatting(
      `Here is a fact-checking result: ${rawAudit}.
       Summarize it. Keep the main verdict and reasoning. Remove markdown and make it concise.`
    );
  } catch (error) {
    console.error('[ERROR] Formatting failed:', error.toString());
    return `ERROR: Failed to format audit result - ${error.toString()}`;
  }

  console.log('[SUCCESS] Audit completed successfully.');
  console.log('[RESULT] Final Output:', formatted);
  return formatted;
}

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

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

الخطوة 3 : إنشاء حساب خدمة

عند دمج وظيفة "الاتصال بالوكيل" في مستند Google، علينا تقديم هوية إلى مستند Google، بحيث يكون لديه الدور الصحيح لاستدعاء "الوكيل" الذي تم نشره في "محرك الوكيل". لهذا الغرض، سنستخدم حساب خدمة سيحصل على الدور الصحيح: roles/aiplatform.user.

في Cloud Shell، شغِّل النص البرمجي التالي خطوة بخطوة:

export PROJECT_ID="YOUR_PROJECT_ID"
export SA_NAME="docfactcheckeragentsa"

gcloud iam service-accounts create $SA_NAME \
  --project=$PROJECT_ID \
  --display-name="Doc Fact Checker Agent Service Account"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
--member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountTokenCreator"

سيؤدي ذلك إلى إنشاء حساب الخدمة بالأذونات الصحيحة.

سننشئ مفتاح JSON لحساب الخدمة. سيستخدم مشروع "برمجة تطبيقات Google" هذا المعرّف للمصادقة. في ما يلي خطوات الحصول على المفتاح:

في Google Cloud Console، انتقِل إلى إدارة الهوية وإمكانية الوصول > حسابات الخدمة.
انقر على حساب الخدمة المحدّد الذي أنشأته للتو.
انتقِل إلى علامة التبويب "المفاتيح".
انقر على "إضافة مفتاح" (Add Key) → "إنشاء مفتاح جديد" (Create New Key).
اختَر JSON، ثم انقر على "إنشاء".
سيتم تنزيل ملف JSON تلقائيًا، ويجب الحفاظ على أمانه. ستلصق محتواه في خصائص النص البرمجي في القسم التالي.

الخطوة 4 : إضافة خصائص البرنامج النصي

ارجع إلى محرّر Apps Script في "مستند Google".

لربط النص البرمجي بالموارد التي تم نشرها، انتقِل إلى Project Settings → Script Properties → Add Script Property.

أضِف ما يلي إلى "خصائص النص البرمجي":

LOCATION: منطقة نشر Vertex AI مثلاً: us-central1
‫GEMINI_MODEL_ID: نموذج Gemini الذي سيتم استخدامه. استخدِم القيمة: gemini-2.5-flash
‫REASONING_ENGINE_ID: رقم تعريف وكيل ADK الذي تم نشره. يمكن الحصول على ذلك من خيار "محرك الوكيل" (Agent Engine) في وحدة التحكّم من الوكيل المحدّد الذي نشرته. سيظهر لك اسم مورد للوكيل الذي تم نشره. معرّف الوكيل هو آخر قيمة رقمية في اسم المورد (أي RESOURCE_ID). على سبيل المثال، projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
SERVICE_ACCOUNT_KEY: انسخ المحتوى الكامل لمفتاح JSON الذي نزّلته لحساب الخدمة الذي أنشأناه في الخطوة السابقة.

انقر على حفظ مواقع النص البرمجي.

الخطوة 5 : إضافة مكتبة OAuth2

يحتاج مشروع "برمجة التطبيقات" إلى مكتبة OAuth2 لمصادقة طلبات البيانات من واجهة برمجة التطبيقات.

لإضافة هذه الميزة، اتّبِع الخطوات التالية:

الانتقال إلى Services → Libraries
انقر على Add a Library.
أدخِل رقم تعريف النص البرمجي: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

الخطوة 6 : اختبار "وكيل Fact Checker Doc" في "مستندات Google"

نحن في الخطوة الأخيرة لاختبار الوكيل داخل "مستندات Google". لإجراء ذلك، اتّبِع الخطوات التالية:

في محرِّر "برمجة تطبيقات Google"، شغِّل الدالة onOpen() مرة واحدة. سيؤدي ذلك إلى إضافة قائمة جديدة باسم "أدوات التدقيق المستندة إلى الذكاء الاصطناعي" في "مستندات Google".
ارجع إلى مستندك. سيظهر لك عنصر قائمة إضافي في القائمة الرئيسية بعنوان AI Audit Tools. انقر على ذلك، ثم على Run AI Audit.

في ما يلي نموذج لعملية التنفيذ:

6. تنظيف

لتجنُّب تحصيل رسوم مستمرة من حسابك على Google Cloud، من المهم حذف الموارد التي أنشأناها خلال ورشة العمل هذه.

إذا لم تعُد بحاجة إلى نشر "الوكيل" في Agent Engine، يمكنك حذفه باتّباع الخطوات الموضّحة أدناه:

انتقِل إلى صفحة Vertex AI Agent Engine في Google Cloud Console.
ابحث عن الوكيل الذي تريد حذفه من قائمة الوكلاء الذين تم نشرهم.
انقر على قائمة الخيارات الإضافية (رمز النقاط الثلاث) بجانب اسم الوكيل.
اختَر حذف من القائمة المنسدلة.
أكِّد عملية الحذف من خلال النقر على حذف الوكيل في مربّع حوار التأكيد.

كإجراء جيد، احذف حساب الخدمة أيضًا.

gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

7. تهانينا

لقد نشرت الآن "وكيل الذكاء الاصطناعي" وربطته بـ "مستندات Google"، وشاهدت طريقة عمله، أي تحليله للمحتوى واستنتاجه وتلخيصه في المكان الذي يتم فيه تخزين المحتوى. ما أنشأناه هنا ليس مجرد عرض توضيحي مستقل. وهي الأساس للتعاون الذكي المستند إلى وكيل داخل Google Workspace.

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

يمتد التصميم نفسه بشكل طبيعي ليشمل "جداول بيانات Google" و"العروض التقديمية من Google" وDrive وGmail. تخيَّل وكلاء:

تدقيق البيانات المالية والإبلاغ عن أي تناقضات في "جداول بيانات Google"
إنشاء عروض تقديمية وملخّصات تلقائيًا في "العروض التقديمية من Google"
تصنيف المستندات وتنظيمها بذكاء في Drive
أو حتى صياغة الرسائل الإلكترونية والتحقّق من صحة المعلومات الواردة فيها مباشرةً في Gmail

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