۱. مقدمه
فضای کاری گوگل جایی است که کار در آن اتفاق می‌افتد. از تهیه گزارش در اسناد گرفته تا پردازش داده‌ها در Sheets و همکاری در Gmail و Meet.
حالا تصور کنید که داکز، شیتس و جیمیل شما فقط ابزار نباشند، بلکه همکار هم باشند.
با کمک کیت توسعه عامل (ADK) گوگل و موتور عامل Vertex AI، این دیگر فقط یک ایده نیست، بلکه ما از این چارچوب‌ها برای ساخت یک عامل هوشمند، استقرار عامل در مقیاس بزرگ و ادغام یکپارچه آن در ابزارهای Google Workspace خود استفاده خواهیم کرد و دوره جدیدی از بهره‌وری عامل‌محور را ممکن خواهیم ساخت.
در این آزمایشگاه کد، شما از یک رویکرد گام به گام به شرح زیر استفاده خواهید کرد:
- با استفاده از کیت توسعه عامل، عامل بررسی حقایق هوش مصنوعی را توسعه دهید.
- عامل را در Agent Engine مستقر کنید، یک محیط کاملاً مدیریت‌شده برای اجرای عامل‌ها در مقیاس بزرگ.
- این عامل را در Google Doc ادغام کنید تا بررسی صحت متن موجود در سند انجام شود.
یک نمودار مفهومی که نحوه عملکرد راه‌حل نهایی را توضیح می‌دهد، در زیر نشان داده شده است:
در اینجا خروجی نهایی نحوه عملکرد عامل بررسی واقعیت در داخل یک سند گوگل (Google Doc) آمده است، که در آن یک متن اصلی حاوی برخی عبارات وجود داشته و این عامل برای هر یک از عبارات موجود در سند، بررسی واقعیت انجام می‌دهد. خروجی که در کادر با گوشه قرمز قرار دارد، خروجی عامل است.
کاری که انجام خواهید داد
- طراحی، ساخت و استقرار عاملی که بررسی صحت اطلاعات را در داخل یک سند گوگل انجام می‌دهد.
آنچه یاد خواهید گرفت
- با استفاده از کیت توسعه عامل (AK) یک عامل توسعه دهید.
- Agent را به صورت محلی آزمایش کنید و آن را روی Agent Engine مستقر کنید.
- عامل را در یک سند Google Workspace (Google Doc) ادغام کنید.
آنچه نیاز دارید
- مرورگر وب کروم
- یک حساب جیمیل
- یک پروژه ابری با قابلیت پرداخت صورتحساب
این آزمایشگاه کد که برای توسعه‌دهندگان در تمام سطوح (از جمله مبتدیان) طراحی شده است، از پایتون و Apps Script در کد نمونه خود استفاده می‌کند. با این حال، دانش این زبان‌های برنامه‌نویسی پیش‌نیاز نیست و توانایی خواندن کد اولیه برای درک مفاهیم ارائه شده کافی خواهد بود.
۲. قبل از شروع
ایجاد یک پروژه
- در کنسول گوگل کلود ، در صفحه انتخاب پروژه، یک پروژه گوگل کلود را انتخاب یا ایجاد کنید.
- مطمئن شوید که صورتحساب برای پروژه ابری شما فعال است. یاد بگیرید که چگونه بررسی کنید که آیا صورتحساب در یک پروژه فعال است یا خیر .
- شما از Cloud Shell ، یک محیط خط فرمان که در Google Cloud اجرا می‌شود و bq از قبل روی آن بارگذاری شده است، استفاده خواهید کرد. روی Activate Cloud Shell در بالای کنسول Google Cloud کلیک کنید.
- پس از اتصال به 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 به مستندات مراجعه کنید.
۳. ساخت عامل ADK
بیایید یک عامل ADK ( Document Fact Checker Agent ) ایجاد کنیم، یک حسابرس مبتنی بر هوش مصنوعی که متن را بررسی صحت می‌کند و از نمونه تابع سفارشی بررسی صحت گوگل الهام گرفته شده است. برخلاف رویکرد تک مرحله‌ای نمونه، عامل ما از استدلال چند مرحله‌ای برای استخراج ادعاها، تأیید آنها با google_search و خروجی ساختاریافته JSON استفاده می‌کند.
مرحله ۱: نصب کیت توسعه عامل
یک تب ترمینال جدید در Cloud Shell باز کنید و پوشه‌ای به نام my-agents به صورت زیر ایجاد کنید. به پوشه my-agents نیز بروید.
mkdir workspace-agents
cd workspace-agents
حالا، بیایید یک محیط مجازی پایتون با استفاده از 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 برای ایجاد یک چارچوب برای عامل خود از طریق دستور adk create با نام برنامه ** (docfactcheckeragent) ** مطابق شکل زیر استفاده کنیم.
adk create docfactcheckeragent
مراحل زیر را دنبال کنید و موارد زیر را انتخاب کنید:
- مدل جمینی برای انتخاب مدل برای عامل ریشه.
- برای بک‌اند، Vertex AI را انتخاب کنید.
- شناسه و منطقه پیش‌فرض پروژه گوگل شما نمایش داده خواهد شد. گزینه پیش‌فرض را انتخاب کنید.
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
پوشه‌ای را که در آن یک الگوی پیش‌فرض و فایل‌های مورد نیاز برای Agent ایجاد شده‌اند، مشاهده کنید.
اولین مورد، فایل .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حرکت می‌کنیم. به جای تکیه بر داده‌های از پیش آموزش‌دیده، عامل می‌تواند جستجوهای زنده انجام دهد، نتایج را ارزیابی کند و استنادهای به‌روز ارائه دهد.
این همان چیزی است که این سیستم را عامل‌گرا می‌کند - این مدل فقط پاسخ‌ها را تولید نمی‌کند، بلکه برای تأیید اطلاعات (با استفاده از ابزارها) اقدام می‌کند.
مرحله ۳: تست عامل به صورت محلی
از پنجره ترمینال موجود دستور زیر را اجرا کنید. مطمئن شوید که در پوشه والد (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)
روی آخرین لینک کلیک کنید تا یک کنسول وب برای آزمایش عامل (Agent) باز شود. اولین تعامل ما اساسی است: درک اینکه عامل واقعاً چه کاری می‌تواند انجام دهد. این، توانایی عامل را در خلاصه کردن 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 متصل شود.
به طور خلاصه، ما یک عامل حسابرس هوش مصنوعی قدرتمند با استفاده از کیت توسعه عامل (ADK) گوگل ساختیم. عامل ما می‌تواند متن را بخواند، ادعاهای واقعی را شناسایی کند، منابع معتبر را جستجو کند (با استفاده از ابزار google_search) و حکم روشنی ارائه دهد.
ما همه چیز را به صورت محلی از طریق رابط وب ADK ساختیم و آزمایش کردیم و دیدیم که چگونه عامل، جمله‌ای مانند زیر را تجزیه و تحلیل می‌کند:
The sky is blue due to Rayleigh scattering. The Earth is flat.
عامل یکی از ادعاها را به عنوان true و دیگری را به عنوان false علامت‌گذاری کرد، که مدرکی کوچک اما مناسب است مبنی بر اینکه تنظیمات محلی ما کاملاً کار می‌کند.
حالا وقت برداشتن قدم بزرگ بعدی است - انتقال از فضای محلی به فضای ابری. بیایید این کار را در ادامه انجام دهیم.
۴. استقرار عامل در موتور عامل هوش مصنوعی ورتکس
یک عامل واقعی فقط چیزی نیست که روی لپ‌تاپ خود آزمایش کنید، بلکه چیزی است که می‌توانید در مقیاس بزرگ اجرا کنید، با سایر سیستم‌ها ادغام کنید و برای تولید در برنامه‌های خود مستقر کنید.
چرا استقرار (Deploy)؟
در اینجا چند دلیل خوب برای استقرار نمایندگان خود در فضای ابری آورده شده است.
- مقیاس‌پذیری: رسیدگی به درخواست‌های با حجم بالا بدون محدودیت زمان اجرای محلی.
- قابلیت اطمینان: نظارت داخلی و مقیاس‌بندی خودکار، با اصلاحاتی مانند به‌روزرسانی پیکربندی ابزار ADK در ۱۸ اکتبر ۲۰۲۵.
- آماده برای ادغام: یک نقطه پایانی API را برای فراخوانی‌های یکپارچه فضای کاری ارائه دهید.
چرا موتور عامل هوش مصنوعی ورتکس؟
موتور عامل هوش مصنوعی ورتکس (Vertex AI Agent Engine) را به عنوان خانه‌ای برای عامل‌های ADK مستقر خود در نظر بگیرید - یک محیط مدیریت‌شده که برای قابلیت اطمینان، مقیاس‌پذیری و یکپارچه‌سازی ساخته شده است.
به نماینده شما این موارد را می‌دهد:
- حالت پایدار و حافظه
- اجرای یکپارچه ابزار (مثلاً جستجوی گوگل، مدل‌های هوش مصنوعی ورتکس)
- نقاط پایانی API را برای تماس‌های خارجی ایمن کنید
- ثبت وقایع و قابلیت مشاهده از طریق ثبت وقایع ابری
- پشتیبانی بومی از هماهنگی چندعاملی
به طور خلاصه - شما یک بار با ADK می‌نویسید و سپس آن را با استفاده از Agent Engine مقیاس‌بندی می‌کنید.
مرحله ۱: آماده‌سازی برای استقرار
قبل از اینکه Agent Vertex AI Agent Engine را مستقر کنیم، باید چند کار انجام دهیم. فرآیند استقرار نیاز به ایجاد یک مخزن ذخیره‌سازی ابری گوگل برای مصنوعات Agent دارد و همچنین باید یک فایل requirements.txt ارائه دهیم تا تمام وابستگی‌های مورد نیاز برای اجرای کد Agent در محیط زمان اجرای Agent Engine در دسترس باشد.
در ترمینال Cloud Shell خود، دستور زیر را برای ایجاد یک سطل (bucket) وارد کنید (به یاد داشته باشید که 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: عامل را مستقر کنید
مرحله بعدی این است که عامل خود را با استفاده از دستور adk deploy در موتور عامل هوش مصنوعی Vertex مستقر کنید.
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 دقیقه طول بکشد. در سطح بالا، این اتفاقی است که می‌افتد:
- ایجاد Agent آغاز می‌شود - ADK CLI کد شما را بسته‌بندی می‌کند، آن را در فضای ذخیره‌سازی ابری شما آپلود می‌کند و Vertex AI را برای ایجاد یک نمونه جدید از Agent Engine فعال می‌کند.
- یک لینک Logs به شما ارائه می‌شود که می‌توانید در آن کاوشگر Cloud Logs پروژه خود را مشاهده کنید. برای مشاهده جزئیات پیشرفت، از جمله مراحل راه‌اندازی، نصب وابستگی‌ها و مقداردهی اولیه مدل، روی آن کلیک کنید. اگر مشکلی پیش بیاید (مانند از دست دادن وابستگی یا مشکل مجوز)، پیام خطا را در اینجا خواهید یافت.
- پیام تکمیل - پس از اتمام استقرار، یک پیام تأیید در ترمینال با شناسه موتور Reasoning خود مشاهده خواهید کرد. نمونه‌ای از آن در زیر نشان داده شده است:
AgentEngine created. Resource name: projects/SOME_ID/locations/REGION/reasoningEngines/SOME_ID
مرحله 3: تأیید عامل در کنسول ابری (موتور عامل)
پس از اتمام استقرار، به بخش Vertex AI → Agent Engine در کنسول Google Cloud خود بروید. باید عامل مستقر شده خود را مطابق شکل زیر در کنسول مشاهده کنید:
🎉 همین! اکنون عامل شما در Vertex AI فعال است و آماده ادغام با Google Workspace یا آزمایش مستقیم آن می‌باشد.
مرحله 4: تست عامل استقرار
تبریک - عامل شما اکنون در Vertex AI Agent Engine فعال است! مرحله بعدی آزمایش این است که آیا به درستی مستقر شده و به درخواست‌ها پاسخ می‌دهد یا خیر.
بسته به اینکه ترجیح می‌دهید چگونه کار کنید، چند روش مختلف برای انجام این کار وجود دارد:
- از طریق کنسول گوگل کلود: یک رابط کاربری بصری برای مشاهده، مدیریت و آزمایش مستقیم عامل‌های مستقر شده شما.
- استفاده از REST API (cURL): ایده‌آل برای توسعه‌دهندگانی که می‌خواهند درخواست‌ها را به صورت دستی ارسال کرده و پاسخ‌ها را بررسی کنند.
- با Vertex AI SDK برای پایتون: گزینه‌ای برنامه‌نویسی‌شده‌تر برای ادغام تست در گردش کار توسعه شما.
هر رویکرد به شما بینشی در مورد نحوه رفتار عامل شما پس از استقرار می‌دهد، یعنی اینکه آیا در حال پردازش پرس‌وجوها، مدیریت جلسات یا بازگرداندن پاسخ‌ها است. برای بررسی مراحل دقیق، مثال‌ها و پیکربندی‌های پیشرفته برای هر روش، مستندات رسمی را اینجا بررسی کنید.
حسابرس هوش مصنوعی شما اکنون یک عامل مبتنی بر ابر است که در موتور عامل هوش مصنوعی Vertex مستقر شده و آماده بررسی واقعیت در مقیاس با google_search است. این به یک هم تیمی دیجیتال قابل اعتماد و مبتنی بر API تبدیل شده است و JSON مانند موارد زیر را تولید می‌کند:
{ "claims": [{"claim": "The sky is blue...", "verdict": "True", "confidence": 95}] }
ما این را مستقیماً در بخش بعدی آزمایش خواهیم کرد، جایی که عامل را درون یک سند گوگل ادغام کرده و حقایق ذکر شده در سند را اعتبارسنجی خواهیم کرد.
۵. عامل بررسی واقعیت را در Google Docs ادغام کنید
در این بخش، همه چیز را به هم متصل خواهیم کرد - عامل مستقر شما را در داخل Google Docs قرار می‌دهیم. با چند خط اسکریپت Apps، یک Google Doc استاندارد را به یک ویرایشگر با کمک هوش مصنوعی تبدیل خواهید کرد که می‌تواند محتوا را به طور خودکار با استفاده از عامل مستقر شما تجزیه و تحلیل و بررسی کند.
مرحله ۱: محیط گوگل داکس خود را تنظیم کنید
با باز کردن یک سند گوگل جدید یا موجود ( docs.new ) شروع کنید.
گوگل داکی که ما برای این آموزش استفاده می‌کنیم شامل مطالب زیر است (می‌توانید از آن یا محتوای خودتان که قصد بررسی صحت آن را دارید استفاده کنید):
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 خود نیاز دارید:
-
AIVertex.gs- تمام ارتباطات با Vertex AI و ADK Agent را مدیریت می‌کند. -
Code.gs- رابط کاربری، منوها و اقدامات سند Google Docs را کنترل می‌کند.
از منو، به Extensions -> Apps Script بروید تا ویرایشگر باز شود. ما از این فضا برای اتصال به ADK Agent مستقر شده استفاده خواهیم کرد. یک فایل 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 برای قالب‌بندی هوشمند پاسخ استفاده می‌کند و نتایج را برای انسان قابل خواندن می‌سازد.
کد.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 اضافه می‌کند.
- متن سند شما را دریافت کرده و برای تجزیه و تحلیل به ADK Agent شما ارسال می‌کند.
- نتایج حسابرسی تولید شده توسط هوش مصنوعی را دوباره در سند نمایش می‌دهد.
مرحله ۳: ایجاد حساب کاربری سرویس
وقتی قابلیت فراخوانی عامل (Agent) را در یک سند گوگل (Google Doc) ادغام می‌کنید، باید یک هویت (identity) به سند گوگل (Google Doc) ارائه دهیم، به طوری که نقش صحیحی برای فراخوانی عامل (Agent) مستقر در موتور عامل (Agent Engine) داشته باشد. برای این منظور، از یک حساب کاربری سرویس (Service Account) استفاده خواهیم کرد که نقش صحیحی خواهد داشت: 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 شما برای احراز هویت از آن استفاده خواهد کرد. مراحل دریافت کلید عبارتند از:
- در کنسول گوگل کلود، به بخش IAM & Admin > Service Accounts بروید.
- روی حساب سرویس خاصی که تازه ایجاد کرده‌اید کلیک کنید.
- به برگه کلیدها بروید.
- روی افزودن کلید → ایجاد کلید جدید کلیک کنید.
- JSON را انتخاب کنید، سپس روی ایجاد کلیک کنید.
- یک فایل JSON به صورت خودکار دانلود می‌شود، شما باید آن را ایمن نگه دارید. محتوای آن را در بخش بعدی در ویژگی‌های اسکریپت خود قرار خواهید داد.
مرحله ۴: افزودن ویژگی‌های اسکریپت
به ویرایشگر Apps Script در Google Doc برگردید.
برای اتصال اسکریپت خود به منابع مستقر شده، به Project Settings → Script Properties → Add Script Property بروید.
موارد زیر را به ویژگی‌های اسکریپت خود اضافه کنید:
-
LOCATION: منطقه استقرار هوش مصنوعی Vertex شما. مثلاً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 که برای حساب سرویسی که در مرحله قبل ایجاد کردیم دانلود کرده‌اید را کپی کنید.
روی ذخیره ویژگی‌های اسکریپت کلیک کنید.
مرحله ۵: کتابخانه OAuth2 را اضافه کنید
پروژه Apps Script ما برای احراز هویت فراخوانی‌های API به کتابخانه OAuth2 نیاز دارد.
برای اضافه کردن آن:
- به
Services → Librariesبروید - روی
Add a Libraryکلیک کنید - شناسه اسکریپت را وارد کنید:
1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
مرحله ۶: بررسی‌کننده‌ی صحت اسناد (Fact Checker Doc Agent) را در گوگل داکس (Google Docs) آزمایش کنید
ما در مرحله آخر برای آزمایش عامل درون Google Docs هستیم. برای این کار موارد زیر را انجام دهید:
- در ویرایشگر Apps Script، تابع
onOpen()را یک بار اجرا کنید. این کار یک منوی جدید AI Audit Tools در Google Docs اضافه می‌کند. - به سند خود برگردید. در منوی اصلی، یک گزینه منوی اضافی با عنوان
AI Audit Toolsمشاهده خواهید کرد. روی آن کلیک کنید و سپسRun AI Audit.
در اینجا یک نمونه اجرا شده است:
۶. پاکسازی
برای جلوگیری از هزینه‌های مداوم برای حساب Google Cloud خود، مهم است که منابعی را که در طول این کارگاه ایجاد کرده‌ایم، حذف کنید.
اگر دیگر نیازی به استقرار Agent در Agent Engine ندارید، می‌توانید آن را از طریق مراحل زیر حذف کنید:
- به صفحه Vertex AI Agent Engine در کنسول Google Cloud بروید.
- عامل مورد نظر برای حذف را از لیست عوامل مستقر پیدا کنید.
- روی منوی سه نقطه (اقدامات بیشتر) کنار نام نماینده کلیک کنید.
- از منوی کشویی، حذف را انتخاب کنید.
- با کلیک روی حذف عامل در کادر تأیید، حذف را تأیید کنید.
به عنوان یک اقدام خوب، حساب سرویس را نیز حذف کنید.
gcloud iam service-accounts delete ${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
۷. تبریک
اکنون عامل هوش مصنوعی خود را مستقر کرده‌اید، آن را به Google Docs متصل کرده‌اید و آن را در عمل دیده‌اید - تجزیه و تحلیل، استدلال و خلاصه‌سازی درست در جایی که محتوای شما قرار دارد. آنچه ما در اینجا ساخته‌ایم فقط یک نسخه آزمایشی مستقل نیست. این پایه و اساس همکاری هوشمند و مبتنی بر عامل در Google Workspace است.
با ترکیب قابلیت‌های استدلال ADK با مدل‌های مولد Gemini، ما عملاً Google Docs را به یک دستیار زنده و متفکر تبدیل کرده‌ایم - دستیاری که می‌تواند متن شما را بخواند، بررسی کند و با توجه به متن، آن را اصلاح کند.
همین طرح به طور طبیعی در سراسر Sheets، Slides، Drive و Gmail گسترش می‌یابد. تصور کنید که عامل‌ها:
- داده‌های مالی را حسابرسی کنید و ناسازگاری‌ها را در Sheets علامت‌گذاری کنید
- تولید خودکار ارائه‌های متنی و خلاصه‌ها در اسلایدها
- اسناد را هوشمندانه در Drive برچسب گذاری و سازماندهی کنید
- یا حتی ایمیل‌ها را مستقیماً در جیمیل پیش‌نویس و بررسی کنید.
این نمایش، زمینه را برای ساخت گردش‌های کاری عامل‌محور فراهم می‌کند که به طور یکپارچه در ابزارهای روزانه Workspace شما ادغام می‌شوند و اسناد ایستا را به همکاران پویای هوش مصنوعی تبدیل می‌کنند.