דף זה תורגם על ידי Cloud Translation API.

תהליכי עבודה מבוססי-סוכנים בתוך Google Workspace: יצירת סוכן Google Docs באמצעות ADK

1. מבוא

‫Google Workspace הוא המקום שבו העבודה מתבצעת. מכתיבת טיוטות של דוחות ב-Docs ועד ניתוח נתונים ב-Sheets ועבודה משותפת ב-Gmail וב-Meet.

עכשיו דמיינו שאם Docs,‏ Sheets ו-Gmail לא היו רק כלים, אלא שותפים לעבודה.

בעזרת Agent Development Kit ‏ (ADK) של Google ו-Agent Engine של Vertex AI, זה כבר לא רק רעיון. אנחנו נשתמש במסגרות האלה כדי ליצור סוכן חכם, לפרוס את הסוכן בהיקף נרחב ולשלב אותו בצורה חלקה בכלי Google Workspace שלנו, וכך נפתח עידן חדש של פרודוקטיביות מבוססת-סוכנים.

ב-codelab הזה תלמדו איך:

מפתחים את סוכן בדיקת העובדות באמצעות AI באמצעות ערכת פיתוח סוכנים.
פריסת הסוכן ב-Agent Engine, סביבה מנוהלת במלואה להרצת סוכנים בקנה מידה רחב.
משלבים את הסוכן הזה ב-Google Docs כדי לבצע בדיקת עובדות לטקסט במסמך.

תרשים קונספט שמסביר איך הפתרון הסופי פועל:

זוהי פלט סופי שמראה איך סוכן בדיקת העובדות פועל בתוך מסמך Google Docs. הטקסט המקורי מכיל כמה הצהרות, והסוכן מבצע בדיקת עובדות לכל אחת מההצהרות במסמך. הפלט שמוקף בתיבה עם הפינה האדומה הוא הפלט של הסוכן.

מה עושים

תכנון, בנייה ופריסה של סוכן שיבצע בדיקת עובדות במסמך Google Docs.

מה תלמדו

פיתוח סוכן באמצעות ערכת פיתוח סוכנים (AK).
בודקים את הסוכן באופן מקומי ומפרסים אותו ב-Agent Engine.
משלבים את הסוכן במסמך Google Workspace (Google Docs).

מה צריך

דפדפן האינטרנט Chrome
חשבון Gmail
פרויקט ב-Cloud עם חיוב מופעל

ב-codelab הזה, שמיועד למפתחים בכל הרמות (כולל מתחילים), נעשה שימוש ב-Python וב-Apps Script בקוד לדוגמה. עם זאת, לא נדרש ידע בשפות התכנות האלה, ויכולת בסיסית של קריאת קוד תספיק כדי להבין את המושגים שמוצגים.

‫2. לפני שמתחילים

יצירת פרויקט

ב-Google Cloud Console, בדף לבחירת הפרויקט, בוחרים או יוצרים פרויקט ב-Google Cloud.
הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

תשתמשו ב-Cloud Shell, סביבת שורת פקודה שפועלת ב-Google Cloud ומגיעה עם bq שנטען מראש. לוחצים על 'הפעלת Cloud Shell' בחלק העליון של מסוף Google Cloud.

תמונה של לחצן Activate Cloud Shell

אחרי שמתחברים ל-Cloud Shell, בודקים שכבר בוצע אימות ושהפרויקט מוגדר למזהה הפרויקט באמצעות הפקודה הבאה:

gcloud auth list

מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שפקודת gcloud מכירה את הפרויקט.

gcloud config list project

אם הפרויקט לא מוגדר, משתמשים בפקודה הבאה כדי להגדיר אותו:

gcloud config set project <YOUR_PROJECT_ID>

מפעילים את ממשקי ה-API הנדרשים באמצעות הפקודה שמוצגת למטה. זה יימשך כמה דקות, אז כדאי לחכות בסבלנות.

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

אם הפקודה תפעל בהצלחה, תוצג הודעה שדומה לזו שמופיעה בהמשך:

Operation "operations/..." finished successfully.

אם פספסתם API כלשהו, תמיד תוכלו להפעיל אותו במהלך ההטמעה.

אפשר לעיין במאמרי העזרה בנושא פקודות gcloud ושימוש בהן.

3. יצירת סוכן ADK

בואו ניצור את סוכן ADK‏ (Document Fact Checker Agent), בודק מבוסס-AI שבודק עובדות בטקסט, בהשראת פונקציית בדיקת העובדות המותאמת אישית של Google‏ דוגמה. בניגוד לגישה החד-שלבית של הדוגמה, הסוכן שלנו משתמש בנימוק רב-שלבי כדי לחלץ טענות, לאמת אותן באמצעות 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 כדי ליצור scaffolding לסוכן שלנו באמצעות הפקודה 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
)

הנקודות העיקריות בקוד המקור שלמעלה הן:

אנחנו מגדירים את נציג ה-AI על ידי מתן שם, ואז מציינים את המודל, התיאור וסט הוראות מפורט ומפורט מאוד.
ערכת ההוראות היא החלק הכי חשוב שמגדיר בדיוק איך הסוכן צריך לחשוב ולפעול. המבנה הזה משקף את אופן העבודה של בודקי עובדות מקצועיים – והופך את ה-AI לצינור אוטומטי לביקורת.
אחרי שהסוכן יצהיר על עצמו, נעבור לשלב הבא וניתן לו גישה למידע מהעולם האמיתי דרך 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 כמו Docs או Sheets.

לסיכום, יצרנו סוכן חזק לביקורת AI באמצעות Agent Development Kit ‏ (ADK) של Google. הסוכן שלנו יכול לקרוא טקסט, לזהות טענות עובדתיות, לחפש מקורות מהימנים (באמצעות הכלי google_search) ולהחזיר פסק דין ברור.

בנינו ובדקנו הכול באופן מקומי דרך ממשק האינטרנט של ADK, וראינו איך הסוכן ניתח הצהרה כמו:

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

הנציג אימת תביעה אחת כtrue וסימן את השנייה כfalse. זו הוכחה קטנה אבל מתאימה לכך שההגדרה המקומית שלנו פועלת בצורה מושלמת.

עכשיו הגיע הזמן לבצע את הצעד הגדול הבא – מעבר מפתרון מקומי לענן. בשלב הבא נבצע את הפעולה הזו.

4. פריסת הסוכן ב-Vertex AI Agent Engine

סוכן אמיתי הוא לא רק משהו שאפשר לבדוק במחשב הנייד, אלא גם משהו שאפשר להפעיל בהיקף גדול, לשלב עם מערכות אחרות ולפרוס לצורך ייצור באפליקציות.

למה כדאי לפרוס?

ריכזנו כמה סיבות טובות לפריסת הסוכנים בענן.

יכולת הרחבה: טיפול בבקשות בהיקף גדול ללא מגבלות זמן ריצה מקומיות.
מהימנות: ניטור מובנה ושינוי קנה מידה אוטומטי, עם תיקונים כמו עדכון התצורה של כלי ה-ADK מ-18 באוקטובר 2025.
מוכן לשילוב: חשיפת נקודת קצה של API לביצוע שיחות חלקות ב-Workspace.

למה כדאי להשתמש ב-Vertex AI Agent Engine?

אפשר לחשוב על Vertex AI Agent Engine כבית של סוכני ה-ADK שפרסתם – סביבה מנוהלת שנבנתה כדי לספק אמינות, יכולת הרחבה ואינטגרציה.

הוא מאפשר לסוכן:

מצב וזיכרון מתמידים
ביצוע משולב של כלי (למשל, חיפוש Google, מודלים של Vertex AI)
אבטחת נקודות קצה של API לקריאות חיצוניות
רישום ביומן וניראות (observability) באמצעות 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 Agent Engine באמצעות הפקודה 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.
יוצג לכם קישור ליומנים, שדרכו תוכלו לראות את Logs Explorer של הפרויקט שלכם ב-Cloud. אפשר ללחוץ עליו כדי לראות את ההתקדמות המפורטת, כולל שלבי ההגדרה, התקנת התלות ואתחול המודל. אם משהו משתבש (למשל חסר רכיב תלוי או שיש בעיה בהרשאה), הודעת השגיאה תופיע כאן.
הודעת השלמה – אחרי שהפריסה תסתיים, תופיע הודעת אישור במסוף עם מזהה מנוע ההסקה. דוגמה לכך מוצגת בהמשך:

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

שלב 3 : אימות הסוכן ב-Cloud Console (Agent Engine)

אחרי שהפריסה תושלם, עוברים לקטע Vertex AI → Agent Engine במסוף Google Cloud. הסוכן שפרסתם אמור להופיע במסוף כמו שמוצג בהמשך:

🎉 זהו! הסוכן שלכם פעיל עכשיו ב-Vertex AI ומוכן לשילוב ב-Google Workspace או לבדיקה ישירה.

שלב 4 : בדיקת סוכן הפריסה

מעולה! הסוכן שלך פעיל עכשיו ב-Vertex AI Agent Engine. השלב הבא הוא לבדוק שהפריסה בוצעה בצורה נכונה ושהמערכת מגיבה לבקשות.

יש כמה דרכים לעשות את זה, בהתאם לדרך העבודה המועדפת עליכם:

דרך מסוף Google Cloud: ממשק חזותי להצגה, לניהול ולבדיקה של הסוכנים שנפרסו ישירות.
שימוש ב-REST API‏ (cURL): מתאים למפתחים שרוצים לשלוח בקשות באופן ידני ולבדוק את התגובות.
עם Vertex AI SDK ל-Python: אפשרות תכנותית יותר לשילוב בדיקות בתהליך הפיתוח.

כל אחת מהגישות האלה מספקת תובנות לגבי התנהגות הנציג אחרי הפריסה, כלומר אם הוא מעבד שאילתות, מטפל בסשנים או מחזיר תשובות. כדי לקרוא שלבים מפורטים, דוגמאות והגדרות מתקדמות לכל שיטה, אפשר לעיין במסמכים הרשמיים כאן.

הבודק מבוסס-AI שלכם הוא עכשיו סוכן מבוסס-ענן, שמוטמע ב-Vertex AI Agent Engine ומוכן לבדוק עובדות בקנה מידה גדול באמצעות google_search. הוא הופך לחבר צוות דיגיטלי אמין שמבוסס על API, ומפיק JSON כמו:

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

בקטע הבא נבדוק את זה ישירות, ונשלב את הסוכן בתוך מסמך Google כדי לאמת את העובדות שמצוינות במסמך.

5. שילוב של סוכן לבדיקת עובדות ב-Google Docs

בקטע הזה נסביר איך לחבר את כל החלקים – איך להביא את הסוכן שפרסתם לתוך Google Docs. בעזרת כמה שורות של Apps Script, תוכלו להפוך מסמך Google Docs רגיל לכלי עריכה מבוסס-AI שיכול לנתח תוכן ולבדוק עובדות באופן אוטומטי באמצעות הסוכן שהטמעתם.

שלב 1: הגדרת הסביבה של Google Docs

מתחילים בפתיחת מסמך Google חדש או קיים (docs.new).

מסמך Google Docs שבו אנחנו משתמשים במדריך הזה מכיל את התוכן הבא (אפשר להשתמש בו או בתוכן שלכם שאתם מתכננים לבדוק את העובדות שבו):

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: הגדרת פרויקט וקבצים של Apps Script

כדי להגדיר את זה, צריך שני קבצים בפרויקט Apps Script:

‫AIVertex.gs – מטפל בכל התקשורת עם Vertex AI ועם סוכן ה-ADK.
‫Code.gs – שולט בממשק, בתפריטים ובפעולות במסמך של Google Docs.

בתפריט, עוברים אל Extensions -> Apps Script כדי לפתוח את העורך. נשתמש במרחב הזה כדי להתחבר לסוכן ADK שנפרס. תמצאו קובץ Code.gs שכבר נוצר, ותצטרכו להחליף את התוכן שלו בקוד Code.gs שמופיע בקטע הבא.

בואו נסביר כל אחת מהן.

AIVertex.gs

יוצרים קובץ חדש באמצעות סימן הפלוס (+) שליד הקטע Files (קבצים) בצד ימין, בוחרים בו כ-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;
}

הקובץ הזה מקשר בין ממשק המשתמש של Docs לבין הלוגיקה של ADK שצוינה למעלה. היא מאפשרת להפעיל את הביקורת ישירות מתפריט מותאם אישית ב-Docs. באופן כללי, הסקריפט:

התוסף מוסיף תפריט מותאם אישית ב-Google Docs בשם AI Audit Tools (כלי ביקורת מבוססי-AI).
הוא אוסף את הטקסט מהמסמך ושולח אותו לסוכן ADK לצורך ניתוח.
התוצאות של הביקורת שנוצרו על ידי AI מוצגות בחזרה במסמך.

שלב 3 : יצירת חשבון שירות

כשמשלבים פונקציונליות של סוכן שמבצע שיחות במסמך Google Docs, אנחנו צריכים לספק זהות למסמך Google Docs, כך שתהיה לו ההרשאה הנכונה להפעיל את הסוכן שנפרס ב-Agent Engine. לשם כך, נשתמש בחשבון שירות שיוקצה לו התפקיד הנכון: 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 לחשבון השירות. הפרויקט שלכם ב-Apps Script ישתמש בזה כדי לבצע אימות. כדי לקבל את המפתח:

במסוף Google Cloud, עוברים אל IAM & Admin > Service Accounts.
לוחצים על חשבון השירות הספציפי שיצרתם.
עוברים לכרטיסייה Keys.
לוחצים על Add Key (הוספת מפתח) → Create New Key (יצירת מפתח חדש).
בוחרים באפשרות JSON ולוחצים על Create (יצירה).
קובץ JSON יורד אוטומטית, וחשוב לשמור אותו במקום בטוח. בקטע הבא תדביקו את התוכן שלו במאפייני הסקריפט.

שלב 4 : מוסיפים מאפייני סקריפט

חוזרים אל עורך Apps Script ב-Google Docs.

כדי לקשר את הסקריפט למשאבים שפרסתם, עוברים אל 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

פרויקט Apps Script שלנו צריך את ספריית OAuth2 כדי לאמת קריאות ל-API.

כדי להוסיף אותו:

מעבר אל Services → Libraries
לוחצים על Add a Library.
מזינים את מזהה הסקריפט: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

שלב 6 : בדיקת סוכן המסמכים של בודק העובדות ב-Google Docs

הגענו לשלב האחרון בבדיקת הסוכן ב-Google Docs. כדי לעשות את זה:

בעורך Apps Script, מריצים את הפונקציה onOpen() פעם אחת. תפריט חדש של כלי ביקורת מבוססי-AI יתווסף ל-Google Docs.
חוזרים למסמך. בתפריט הראשי יופיע פריט תפריט נוסף בשם AI Audit Tools. לוחצים על הפריט ואז על Run AI Audit.

דוגמה להרצה:

6. הסרת המשאבים

כדי להימנע מחיובים שוטפים בחשבון Google Cloud, חשוב למחוק את המשאבים שיצרנו במהלך הסדנה הזו.

אם אין יותר צורך בפריסת הסוכן ב-Agent Engine, אפשר למחוק אותו באמצעות השלבים שבהמשך:

עוברים לדף Vertex AI Agent Engine במסוף Google Cloud.
ברשימת הסוכנים שנפרסו, מאתרים את הסוכן שרוצים למחוק.
לוחצים על סמל האפשרויות הנוספות (3 נקודות) ליד השם של הנציג.
בתפריט הנפתח, בוחרים באפשרות מחיקה.
בתיבת הדו-שיח לאישור, לוחצים על מחיקת הסוכן כדי לאשר את המחיקה.

מומלץ גם למחוק את חשבון השירות.

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

7. מזל טוב

השלמתם את הפריסה של סוכן ה-AI, קישרתם אותו ל-Google Docs וראיתם אותו בפעולה – מנתח, מסיק מסקנות ומסכם בדיוק במקום שבו התוכן נמצא. מה שבנינו כאן הוא לא רק הדגמה עצמאית. הוא הבסיס לשיתוף פעולה חכם שמבוסס על סוכנים בתוך Google Workspace.

שילוב היכולות של ADK עם המודלים הגנרטיביים של Gemini הפך את Google Docs למעשה לעוזר חי וחושב – כזה שיכול לקרוא, לבדוק ולשפר את הטקסט שלכם בהקשר.

אותו תרשים זרימה מתרחב באופן טבעי ל-Sheets, ל-Slides, ל-Drive ול-Gmail. תארו לעצמכם סוכנים ש:

ביקורת על נתונים פיננסיים וסימון אי-התאמות ב-Sheets
יצירה אוטומטית של מצגות שיווקיות וסיכומים ב-Slides
תיוג וארגון חכם של מסמכים ב-Drive
או אפילו לנסח אימיילים ולבדוק את העובדות שלהם ישירות ב-Gmail

ההדגמה הזו מציגה את הבסיס ליצירת תהליכי עבודה מבוססי-סוכנים שמשתלבים בצורה חלקה בכלים היומיומיים שלכם ב-Workspace, והופכים מסמכים סטטיים לשותפים דינמיים מבוססי-AI.

תהליכי עבודה מבוססי-סוכנים בתוך Google Workspace: יצירת סוכן Google Docs באמצעות ADK

1. מבוא

מה עושים

מה תלמדו

מה צריך

‫2. לפני שמתחילים

יצירת פרויקט

3. יצירת סוכן ADK

שלב 1 : התקנת ערכת פיתוח של סוכנים

שלב 2 : פיתוח סוכן לבדיקת עובדות במסמך באמצעות ADK

שלב 3 : בדיקת הסוכן באופן מקומי

4. פריסת הסוכן ב-Vertex AI Agent Engine

למה כדאי לפרוס?

למה כדאי להשתמש ב-Vertex AI Agent Engine?

שלב 1 : הגדרת הפריסה

שלב 3 : אימות הסוכן ב-Cloud Console (Agent Engine)

שלב 4 : בדיקת סוכן הפריסה

5. שילוב של סוכן לבדיקת עובדות ב-Google Docs

שלב 1: הגדרת הסביבה של Google Docs

שלב 2: הגדרת פרויקט וקבצים של Apps Script

שלב 3 : יצירת חשבון שירות

שלב 4 : מוסיפים מאפייני סקריפט

שלב 5 : הוספת ספריית OAuth2

שלב 6 : בדיקת סוכן המסמכים של בודק העובדות ב-Google Docs

6. הסרת המשאבים

7. מזל טוב

מאמרי עזרה