Trang này được dịch bởi Cloud Translation API.

Quy trình làm việc dựa trên tác nhân trong Google Workspace: Xây dựng một tác nhân Google Tài liệu bằng ADK

1. Giới thiệu

Google Workspace là nơi diễn ra công việc. Từ việc soạn thảo báo cáo trong Tài liệu đến xử lý dữ liệu trong Trang tính và cộng tác trong Gmail và Meet.

Giờ đây, hãy tưởng tượng nếu Tài liệu, Trang tính và Gmail không chỉ là công cụ mà còn là cộng tác viên.

Với sự trợ giúp của Bộ công cụ phát triển tác nhân (ADK) của Google và Công cụ tác nhân của Vertex AI, điều đó không còn chỉ là ý tưởng nữa. Chúng tôi sẽ sử dụng các khung này để xây dựng một tác nhân thông minh, triển khai tác nhân ở quy mô lớn và tích hợp tác nhân một cách liền mạch vào các công cụ Google Workspace, mở ra một kỷ nguyên mới về năng suất dựa trên tác nhân.

Trong lớp học lập trình này, bạn sẽ sử dụng phương pháp từng bước như sau:

Phát triển Trợ lý kiểm tra thông tin bằng AI bằng Agent Development Kit.
Triển khai Agent trong Agent Engine, một môi trường được quản lý hoàn toàn để chạy Agent ở quy mô lớn.
Tích hợp Agent này vào Google Tài liệu để xác minh tính xác thực của văn bản trong tài liệu.

Sau đây là sơ đồ khái niệm giải thích cách hoạt động của giải pháp cuối cùng:

Đây là kết quả cuối cùng về cách hoạt động của Tác nhân xác minh thông tin trong Google Tài liệu, trong đó có một văn bản gốc chứa một số câu và tác nhân này sẽ xác minh thông tin cho từng câu trong tài liệu. Đầu ra được liên kết trong hộp có góc màu đỏ là đầu ra từ Agent.

Bạn sẽ thực hiện

Thiết kế, xây dựng và triển khai một Đặc vụ có thể xác minh tính xác thực trong Google Tài liệu.

Kiến thức bạn sẽ học được

Phát triển một Đặc vụ bằng Bộ phát triển đặc vụ (AK).
Kiểm thử Agent cục bộ và triển khai trên Agent Engine.
Tích hợp Agent vào một tài liệu trên Google Workspace (Google Tài liệu).

Bạn cần có

Trình duyệt web Chrome
Tài khoản Gmail
Một Dự án trên đám mây đã bật tính năng thanh toán

Lớp học lập trình này được thiết kế cho nhà phát triển ở mọi cấp độ (kể cả người mới bắt đầu), sử dụng Python và Apps Script trong mã mẫu. Tuy nhiên, bạn không bắt buộc phải có kiến thức về những ngôn ngữ lập trình này và chỉ cần có khả năng đọc mã cơ bản là đủ để hiểu các khái niệm được trình bày.

2. Trước khi bắt đầu

Tạo một dự án

Trong Google Cloud Console, trên trang chọn dự án, hãy chọn hoặc tạo một dự án trên Google Cloud.
Đảm bảo rằng bạn đã bật tính năng thanh toán cho dự án trên Cloud. Tìm hiểu cách kiểm tra xem tính năng thanh toán có được bật trên một dự án hay không .

Bạn sẽ sử dụng Cloud Shell, một môi trường dòng lệnh chạy trong Google Cloud và được tải sẵn bằng bq. Nhấp vào Kích hoạt Cloud Shell ở đầu bảng điều khiển Google Cloud.

Hình ảnh nút Kích hoạt Cloud Shell

Sau khi kết nối với Cloud Shell, bạn có thể kiểm tra để đảm bảo rằng bạn đã được xác thực và dự án được đặt thành mã dự án của bạn bằng lệnh sau:

gcloud auth list

Chạy lệnh sau trong Cloud Shell để xác nhận rằng lệnh gcloud biết về dự án của bạn.

gcloud config list project

Nếu bạn chưa đặt dự án, hãy dùng lệnh sau để đặt:

gcloud config set project <YOUR_PROJECT_ID>

Bật các API bắt buộc thông qua lệnh bên dưới. Quá trình này có thể mất vài phút, vì vậy, vui lòng kiên nhẫn chờ đợi.

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

Khi thực thi lệnh thành công, bạn sẽ thấy một thông báo tương tự như thông báo dưới đây:

Operation "operations/..." finished successfully.

Nếu bỏ lỡ API nào, bạn luôn có thể bật API đó trong quá trình triển khai.

Tham khảo tài liệu để biết các lệnh và cách sử dụng gcloud.

3. Tạo ADK Agent

Hãy tạo tác nhân ADK (Document Fact Checker Agent), một Kiểm toán viên dựa trên AI có chức năng kiểm chứng văn bản, lấy cảm hứng từ hàm tuỳ chỉnh Kiểm chứng của Google sample. Không giống như phương pháp một bước của mẫu, tác nhân của chúng tôi sử dụng quy trình suy luận nhiều bước để trích xuất các tuyên bố, xác minh các tuyên bố đó bằng google_search và xuất JSON có cấu trúc.

Bước 1 : Cài đặt Bộ công cụ phát triển tác nhân

Mở một thẻ dòng lệnh mới trong Cloud Shell và tạo một thư mục có tên là my-agents như sau. Chuyển đến thư mục my-agents.

mkdir workspace-agents
cd workspace-agents

Bây giờ, hãy tạo một môi trường Python ảo bằng cách sử dụng venv như sau:

python -m venv .venv

Kích hoạt môi trường ảo như sau:

source .venv/bin/activate

Cài đặt ADK như sau:

pip install google-adk

Giờ đây, bạn có thể gọi tiện ích adk như sau.

adk

Thao tác này sẽ cho bạn thấy danh sách các lệnh.

$ 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.

Bước 2 : Phát triển Document Fact Checker Agent bằng ADK

Bây giờ, chúng ta sẽ dùng adk để tạo giàn giáo cho tác nhân thông qua lệnh adk create với tên ứng dụng là **(docfactcheckeragent)**như dưới đây.

adk create docfactcheckeragent

Làm theo các bước và chọn những mục sau:

Mô hình Gemini để chọn mô hình cho tác nhân gốc.
Chọn Vertex AI cho phần phụ trợ.
Mã dự án và khu vực mặc định của bạn trên Google sẽ xuất hiện. Chọn chính chế độ mặc định.

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

Quan sát thư mục nơi mẫu mặc định và các tệp bắt buộc cho Agent đã được tạo.

Đầu tiên là tệp .env. Nội dung của tệp này được trình bày bên dưới:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_GOOGLE_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_GOOGLE_PROJECT_REGION

Các giá trị này cho biết chúng ta sẽ sử dụng Gemini thông qua Vertex AI cùng với các giá trị tương ứng cho mã dự án trên Google Cloud và vị trí.

Sau đó, chúng ta có tệp __init__.py đánh dấu thư mục là một mô-đun và có một câu lệnh duy nhất nhập tác nhân từ tệp agent.py.

from . import agent

Cuối cùng là tệp agent.py. Bạn sẽ cần thay thế nội dung trong tệp agent.py này bằng mã bên dưới:

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
)

Các điểm chính của mã nguồn trên là:

Chúng ta xác định tác nhân AI bằng cách đặt tên cho tác nhân đó, sau đó là mô hình, nội dung mô tả và một bộ hướng dẫn rất chi tiết.
Tập lệnh là phần quan trọng nhất để xác định chính xác cách mà tác nhân nên suy nghĩ và hoạt động. Cấu trúc này phản ánh cách các chuyên gia kiểm chứng chuyên nghiệp làm việc – biến AI thành một quy trình kiểm toán tự động.
Sau khi hoàn tất việc khai báo tác nhân này, chúng ta sẽ chuyển sang cấp cho tác nhân quyền truy cập vào thông tin ngoài đời thực thông qua Google Search tool. Thay vì dựa vào dữ liệu được huấn luyện trước, tác nhân có thể thực hiện các lượt tìm kiếm trực tiếp, đánh giá kết quả và cung cấp thông tin trích dẫn mới nhất.

Đó là điều khiến hệ thống này có tính chủ động – mô hình không chỉ tạo ra câu trả lời mà còn hành động (sử dụng các công cụ) để xác minh thông tin.

Bước 3 : Kiểm thử Agent cục bộ

Từ cửa sổ dòng lệnh hiện có, hãy đưa ra lệnh sau. Đảm bảo rằng bạn đang ở trong thư mục mẹ (workspace-agents) chứa thư mục docfactcheckeragent.

adk web

Dưới đây là một ví dụ về quá trình thực thi:

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)

Nhấp vào đường liên kết cuối cùng. Thao tác này sẽ mở ra một bảng điều khiển web để kiểm thử Agent. Tương tác đầu tiên của chúng ta là điều cơ bản: hiểu rõ những gì mà trợ lý có thể thực sự làm. Điều này kiểm tra khả năng tóm tắt description và instruction text của trợ lý.

Trợ lý đưa ra bản tóm tắt ngắn gọn về các khả năng của mình, dựa trên nội dung mô tả và bộ hướng dẫn.

Sau đó, chúng tôi cung cấp cho nó 2 câu lệnh (The sky is blue due to Rayleigh scattering. The Earth is flat.) và nó đã kiểm tra thành công nội dung, đồng thời trả về một phản hồi JSON có cấu trúc rõ ràng.

Tìm hiểu sâu:

Công cụ google_search tìm nạp các trang có liên quan trên web.
Mô hình Gemini 2.5 Flash sẽ phân tích những đoạn trích đó và phân loại mức độ chân thực.
ADK xử lý việc điều phối lý luận và đảm bảo tuân thủ logic từng bước.

Giai đoạn kiểm thử cục bộ này giúp xác thực quy trình làm việc của tác nhân trước khi bạn triển khai tác nhân đó trên Vertex AI Agent Engine, nơi tác nhân có thể kết nối với các công cụ của Google Workspace như Tài liệu hoặc Trang tính.

Tóm lại, chúng tôi đã xây dựng một AI Auditor Agent mạnh mẽ bằng cách sử dụng Agent Development Kit (ADK) của Google. Trợ lý của chúng tôi có thể đọc văn bản, xác định tuyên bố thực tế, tìm kiếm các nguồn đáng tin cậy (bằng công cụ google_search) và đưa ra kết quả rõ ràng.

Chúng tôi đã xây dựng và thử nghiệm mọi thứ tại chỗ thông qua giao diện web ADK và nhận thấy cách tác nhân phân tích một câu lệnh như:

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

Nhân viên hỗ trợ đã xác minh một yêu cầu bồi thường là true và gắn cờ yêu cầu còn lại là false. Đây là một bằng chứng nhỏ nhưng phù hợp cho thấy chế độ thiết lập cục bộ của chúng tôi hoạt động hoàn hảo.

Giờ là lúc thực hiện bước quan trọng tiếp theo – chuyển từ dữ liệu cục bộ sang đám mây. Hãy thực hiện việc đó trong bước tiếp theo.

4. Triển khai Agent vào Vertex AI Agent Engine

Một tác nhân thực không chỉ là thứ bạn kiểm thử trên máy tính xách tay, mà còn là thứ bạn có thể chạy ở quy mô lớn, tích hợp với các hệ thống khác và triển khai cho hoạt động sản xuất trên các ứng dụng của mình.

Lý do nên triển khai

Sau đây là một số lý do chính đáng để triển khai các Agent của bạn vào đám mây.

Khả năng mở rộng: Xử lý các yêu cầu có số lượng lớn mà không bị giới hạn thời gian chạy cục bộ.
Độ tin cậy: Tính năng giám sát và tự động mở rộng quy mô tích hợp, cùng các bản sửa lỗi như bản cập nhật cấu hình công cụ ADK ngày 18 tháng 10 năm 2025.
Sẵn sàng tích hợp: Cung cấp một điểm cuối API để thực hiện các cuộc gọi liền mạch trên Workspace.

Tại sao nên dùng Vertex AI Agent Engine?

Hãy coi Vertex AI Agent Engine là nơi lưu trữ các tác nhân ADK mà bạn đã triển khai – một môi trường được quản lý, được xây dựng để đảm bảo độ tin cậy, khả năng mở rộng và tích hợp.

Tính năng này cung cấp cho nhân viên hỗ trợ:

Trạng thái và bộ nhớ liên tục
Thực thi công cụ tích hợp (ví dụ: Google Tìm kiếm, Các mô hình Vertex AI)
Bảo mật các điểm cuối API cho các lệnh gọi bên ngoài
Ghi nhật ký và khả năng ghi nhận thông tin thông qua Cloud Logging
Hỗ trợ gốc cho hoạt động điều phối nhiều tác nhân

Nói tóm lại, bạn chỉ cần viết một lần bằng ADK, sau đó mở rộng quy mô bằng Agent Engine.

Bước 1 : Thiết lập để triển khai

Chúng ta cần làm một số việc trước khi triển khai nhân viên hỗ trợ Vertex AI Agent Engine. Quy trình triển khai yêu cầu bạn tạo một bộ chứa Google Cloud Storage cho các cấu phần phần mềm của tác nhân và chúng ta cũng cần cung cấp một tệp requirements.txt để tất cả các phần phụ thuộc cần thiết để chạy mã Tác nhân đều có sẵn cho môi trường thời gian chạy của Công cụ tác nhân.

Trong thiết bị đầu cuối Cloud Shell, hãy đưa ra lệnh sau để tạo một nhóm (Nhớ thay thế YOUR_BUCKET_NAME, YOUR_PROJECT_ID và YOUR_PROJECT_REGION bằng các giá trị thực tế dành riêng cho dự án của bạn):

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

Tiếp theo, hãy tạo tệp requirements.txt sau đây trong thư mục gốc (workspace-agents), nội dung của tệp này được trình bày bên dưới:

google-cloud-aiplatform
google-adk
requests

Bước 2 : Triển khai Agent

Bước tiếp theo là triển khai tác nhân của bạn vào Vertex AI Agent Engine bằng lệnh 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/

Thao tác này sẽ bắt đầu một quy trình triển khai nhân viên hỗ trợ của chúng tôi vào Agent Engine. Quá trình này tốn nhiều thời gian và dự kiến mất khoảng 5 phút. Nhìn chung, đây là những gì sẽ xảy ra:

Bắt đầu tạo tác nhân – ADK CLI đóng gói mã của bạn, tải mã đó lên vùng lưu trữ Cloud Storage và kích hoạt Vertex AI để tạo một phiên bản Agent Engine mới.
Bạn sẽ thấy một đường liên kết đến Nhật ký, nơi bạn có thể xem trình khám phá Nhật ký trên đám mây cho dự án của mình. Nhấp vào nút này để xem tiến trình chi tiết, bao gồm các bước thiết lập, quá trình cài đặt phần phụ thuộc và quá trình khởi tạo mô hình. Nếu có vấn đề xảy ra (chẳng hạn như thiếu phần phụ thuộc hoặc có vấn đề về quyền), bạn sẽ thấy thông báo lỗi tại đây.
Thông báo hoàn tất – Sau khi quá trình triển khai hoàn tất, bạn sẽ thấy một thông báo xác nhận trong thiết bị đầu cuối kèm theo mã Reasoning Engine. Sau đây là một ví dụ:

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

Bước 3 : Xác minh Agent trong Cloud Console (Agent Engine)

Sau khi quá trình triển khai hoàn tất, hãy chuyển đến mục Vertex AI → Agent Engine trong bảng điều khiển Google Cloud. Bạn sẽ thấy tác nhân đã triển khai của mình được liệt kê trong bảng điều khiển như minh hoạ dưới đây:

🎉 Vậy là xong! Giờ đây, tác nhân của bạn đã hoạt động trên Vertex AI và sẵn sàng được tích hợp vào Google Workspace hoặc được kiểm thử trực tiếp.

Bước 4 : Kiểm thử Agent triển khai

Xin chúc mừng! Giờ đây, tác nhân của bạn đã hoạt động trên Vertex AI Agent Engine! Bước tiếp theo là kiểm tra để đảm bảo rằng tính năng này được triển khai đúng cách và phản hồi các yêu cầu.

Bạn có thể thực hiện việc này theo một số cách, tuỳ thuộc vào cách bạn muốn làm việc:

Thông qua Google Cloud Console: Một giao diện trực quan để xem, quản lý và kiểm thử trực tiếp các đặc vụ đã triển khai.
Sử dụng REST API (cURL): Lý tưởng cho những nhà phát triển muốn gửi yêu cầu theo cách thủ công và kiểm tra phản hồi.
Với Vertex AI SDK cho Python: Một lựa chọn có lập trình hơn để tích hợp hoạt động kiểm thử vào quy trình phát triển của bạn.

Mỗi phương pháp sẽ cung cấp cho bạn thông tin chi tiết về cách hoạt động của tác nhân sau khi được triển khai, tức là liệu tác nhân có đang xử lý các truy vấn, xử lý các phiên hay trả về các phản hồi hay không. Để khám phá các bước chi tiết, ví dụ và cấu hình nâng cao cho từng phương thức, hãy xem tài liệu chính thức tại đây.

Giờ đây, Trình kiểm toán AI của bạn là một tác nhân dựa trên đám mây, được triển khai cho Vertex AI Agent Engine, sẵn sàng kiểm chứng thông tin trên quy mô lớn bằng google_search. Nó được chuyển đổi thành một đồng đội kỹ thuật số đáng tin cậy, dựa trên API, tạo ra JSON như:

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

Chúng ta sẽ trực tiếp thử nghiệm điều này trong phần tiếp theo, nơi chúng ta sẽ tích hợp tác nhân vào một tài liệu trên Google và xác thực các thông tin được nêu trong tài liệu.

5. Tích hợp Fact Checker Agent vào Google Tài liệu

Trong phần này, chúng ta sẽ kết nối mọi thứ lại với nhau – đưa tác nhân đã triển khai vào Google Tài liệu. Chỉ với vài dòng Apps Script, bạn sẽ biến một Google Tài liệu tiêu chuẩn thành một trình chỉnh sửa có sự hỗ trợ của AI, có thể phân tích và kiểm tra tính xác thực của nội dung một cách tự động bằng cách sử dụng tác nhân mà bạn đã triển khai.

Bước 1: Thiết lập môi trường Google Tài liệu

Bắt đầu bằng cách mở một tệp Google Tài liệu mới hoặc hiện có (docs.new).

Tài liệu trên Google mà chúng ta đang dùng cho hướng dẫn này có nội dung như sau (bạn có thể dùng tài liệu đó hoặc nội dung của riêng bạn mà bạn dự định xác minh tính xác thực):

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.

Bước 2: Thiết lập dự án và tệp Apps Script

Bạn sẽ cần 2 tệp trong dự án Apps Script cho chế độ thiết lập này:

AIVertex.gs – xử lý mọi hoạt động giao tiếp với Vertex AI và ADK Agent.
Code.gs – kiểm soát giao diện, trình đơn và các thao tác trên tài liệu của Google Tài liệu.

Trên trình đơn, hãy chuyển đến biểu tượng Extensions -> Apps Script để mở trình chỉnh sửa. Chúng tôi sẽ sử dụng không gian này để kết nối với ADK Agent đã triển khai. Bạn sẽ thấy một tệp Code.gs đã được tạo và bạn sẽ cần thay thế nội dung của tệp đó bằng mã Code.gs được cung cấp trong phần tiếp theo.

Hãy cùng tìm hiểu từng loại.

AIVertex.gs

Tạo một tệp mới thông qua dấu + bên cạnh phần Tệp ở bên trái, chọn tệp đó làm Script rồi sao chép nội dung sau vào tệp đó.

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(),
  }
}

Hãy nhớ lưu tệp.

Tệp này thực hiện những việc sau:

Xác thực một cách an toàn với Vertex AI bằng khoá Tài khoản dịch vụ. Thao tác này sẽ gọi ADK Agent đã triển khai để phân tích hoặc kiểm tra tính xác thực của văn bản trong tài liệu.
Sử dụng Gemini để định dạng câu trả lời một cách thông minh , giúp kết quả dễ đọc.

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;
}

Tệp này kết nối giao diện người dùng của Tài liệu với logic ADK ở trên. Tiện ích này cho phép bạn kích hoạt quy trình kiểm tra ngay từ trình đơn tuỳ chỉnh của Tài liệu. Nhìn chung, phương thức này thực hiện những việc sau:

Thêm một trình đơn tuỳ chỉnh có tên là Công cụ kiểm tra bằng AI vào Google Tài liệu.
Lấy văn bản trong tài liệu của bạn và gửi đến ADK Agent để phân tích.
Hiển thị kết quả kiểm tra do AI tạo trong tài liệu.

Bước 3 : Tạo tài khoản dịch vụ

Khi bạn tích hợp chức năng Gọi qua tổng đài vào Google Tài liệu, chúng tôi cần cung cấp một danh tính cho Google Tài liệu để tài liệu đó có vai trò phù hợp nhằm gọi Tổng đài được triển khai trong Agent Engine. Để làm việc này, chúng ta sẽ sử dụng một Tài khoản dịch vụ có vai trò phù hợp: roles/aiplatform.user.

Trong Cloud Shell, hãy chạy từng bước trong tập lệnh sau:

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"

Thao tác này sẽ tạo tài khoản dịch vụ có các quyền phù hợp.

Chúng tôi sẽ tạo một khoá JSON cho tài khoản dịch vụ. Đây là thông tin mà dự án Apps Script của bạn sẽ dùng để xác thực. Các bước để lấy khoá như sau:

Trong bảng điều khiển Google Cloud, hãy chuyển đến phần IAM & Admin > Service Accounts (IAM và Quản trị > Tài khoản dịch vụ).
Nhấp vào tài khoản dịch vụ cụ thể mà bạn vừa tạo.
Chuyển đến thẻ Khoá.
Nhấp vào Thêm khoá → Tạo khoá mới.
Chọn JSON, rồi nhấp vào Tạo.
Một tệp JSON sẽ tự động tải xuống, bạn nên giữ tệp đó an toàn. Bạn sẽ dán nội dung của tệp này vào các thuộc tính tập lệnh trong phần tiếp theo.

Bước 4 : Thêm thuộc tính tập lệnh

Quay lại trình chỉnh sửa Apps Script trong Google Tài liệu.

Để kết nối tập lệnh với các tài nguyên đã triển khai, hãy chuyển đến Project Settings → Script Properties → Add Script Property.

Thêm nội dung sau vào Thuộc tính tập lệnh:

LOCATION: Khu vực triển khai Vertex AI. Ví dụ: us-central1
GEMINI_MODEL_ID: Mô hình Gemini sẽ sử dụng. Sử dụng giá trị: gemini-2.5-flash
REASONING_ENGINE_ID: Mã nhận dạng ADK Agent đã triển khai. Bạn có thể lấy thông tin này từ lựa chọn Agent Engine (Công cụ đại lý) trong bảng điều khiển của Đại lý cụ thể mà bạn đã triển khai. Bạn sẽ thấy tên tài nguyên cho Agent đã triển khai. Mã nhận dạng của nhân viên hỗ trợ là giá trị dạng số cuối cùng trong tên tài nguyên (tức là RESOURCE_ID). Ví dụ: projects/SOME_ID/locations/REGION/reasoningEngines/RESOURCE_ID
SERVICE_ACCOUNT_KEY: Sao chép toàn bộ nội dung cho khoá JSON mà bạn đã tải xuống cho Tài khoản dịch vụ mà chúng ta đã tạo ở bước trước.

Nhấp vào Lưu thuộc tính của tập lệnh.

Bước 5 : Thêm thư viện OAuth2

Dự án Apps Script của chúng tôi cần thư viện OAuth2 để xác thực các lệnh gọi API.

Cách thêm:

Chuyển đến Services → Libraries
Nhấp vào Add a Library
Nhập Mã tập lệnh: 1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF

Bước 6 : Kiểm thử Fact Checker Doc Agent trong Google Tài liệu

Chúng ta đang ở bước cuối cùng để kiểm thử tác nhân trong Google Tài liệu. Để thực hiện việc này, hãy làm như sau:

Trong trình chỉnh sửa Apps Script, hãy chạy hàm onOpen() một lần. Thao tác này sẽ thêm một trình đơn mới là Công cụ kiểm tra bằng AI trong Google Tài liệu.
Quay lại tài liệu của bạn. Bạn sẽ thấy một mục trình đơn khác trong trình đơn chính có tên là AI Audit Tools. Nhấp vào biểu tượng đó rồi nhấp vào Run AI Audit.

Dưới đây là một lần chạy mẫu:

6. Dọn dẹp

Để tránh bị tính phí liên tục cho tài khoản Google Cloud của bạn, bạn cần xoá các tài nguyên mà chúng ta đã tạo trong hội thảo này.

Nếu không cần triển khai Agent trong Agent Engine nữa, bạn có thể xoá Agent theo các bước dưới đây:

Chuyển đến trang Vertex AI Agent Engine trong Google Cloud Console.
Tìm tác nhân mà bạn muốn xoá trong danh sách các tác nhân đã triển khai.
Nhấp vào trình đơn có biểu tượng ba dấu chấm (thao tác khác) bên cạnh tên của nhân viên hỗ trợ.
Chọn Xoá trong trình đơn thả xuống.
Xác nhận thao tác xoá bằng cách nhấp vào Xoá tác nhân trong hộp thoại xác nhận.

Bạn cũng nên xoá tài khoản dịch vụ.

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

7. Xin chúc mừng

Giờ đây, bạn đã triển khai AI Agent, kết nối AI Agent với Google Tài liệu và thấy AI Agent hoạt động – phân tích, suy luận và tóm tắt ngay tại nơi lưu trữ nội dung của bạn. Những gì chúng ta đã xây dựng ở đây không chỉ là một bản minh hoạ độc lập. Đây là nền tảng cho hoạt động cộng tác thông minh, dựa trên tác nhân trong Google Workspace.

Bằng cách kết hợp khả năng suy luận của ADK với các mô hình tạo sinh của Gemini, chúng tôi đã biến Google Tài liệu thành một trợ lý sống động và thông minh, có thể đọc, kiểm tra và tinh chỉnh văn bản của bạn theo ngữ cảnh.

Bản thiết kế tương tự cũng được mở rộng một cách tự nhiên trên Trang tính, Trang trình bày, Drive và Gmail. Hãy tưởng tượng những tác nhân có thể:

Kiểm tra dữ liệu tài chính và gắn cờ những điểm không nhất quán trong Trang tính
Tự động tạo bản đề xuất và bản tóm tắt trong Trang trình bày
Gắn nhãn và sắp xếp tài liệu một cách thông minh trong Drive
Hoặc thậm chí soạn thảo và kiểm tra tính xác thực của email ngay trong Gmail

Bản minh hoạ này đặt nền tảng cho việc xây dựng quy trình làm việc dựa trên tác nhân, tích hợp liền mạch vào các công cụ Workspace hằng ngày của bạn, biến tài liệu tĩnh thành cộng tác viên AI linh hoạt.