Tích hợp các trợ lý ảo Vertex AI với Google Workspace

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

Vertex AI là gì?

Vertex AI là nền tảng phát triển hợp nhất của Google Cloud để xây dựng, triển khai và mở rộng các ứng dụng và tác nhân AI cấp doanh nghiệp. Nền tảng này cung cấp cho các nhà phát triển và nhà khoa học dữ liệu những công cụ tinh vi cần thiết để thiết kế các quy trình công việc theo hướng tác nhân tuỳ chỉnh, được tích hợp sâu với cơ sở hạ tầng quy mô toàn cầu.

Truy cập vào Model Garden: Chọn trong số hơn 150 mô hình cơ sở, bao gồm toàn bộ họ mô hình Gemini, các mô hình của bên thứ ba và các mô hình nguồn mở chuyên biệt để tìm ra mô hình phù hợp cho các tác vụ cụ thể của tác nhân.
Thiết kế quy trình điều phối phức tạp: Vertex AI cung cấp khung để thiết kế các tác nhân tự động sử dụng khả năng suy luận để lập kế hoạch, thực hiện các tác vụ nhiều bước và gọi API bên ngoài.
Nền tảng kiến thức cấp doanh nghiệp: Kết nối các tác nhân với dữ liệu kinh doanh trực tiếp, bao gồm cả RAG (Tạo tăng cường khả năng truy xuất) hiệu suất cao để loại bỏ thông tin sai lệch và đảm bảo độ chính xác thực tế.
DevOps: Tích hợp liền mạch quá trình phát triển tác nhân vào các quy trình CI/CD hiện có bằng các SDK, API và công cụ đánh giá mạnh mẽ để đo lường hiệu suất và độ an toàn của tác nhân ở quy mô lớn.
Bảo mật cấp doanh nghiệp: Vertex AI đảm bảo rằng dữ liệu khách hàng được dùng để huấn luyện hoặc làm cơ sở vẫn ở chế độ riêng tư, được mã hoá và tuân thủ các yêu cầu về quyền lưu trú trên toàn cầu.
Cơ sở hạ tầng được tối ưu hoá: Dễ dàng mở rộng quy mô khối lượng công việc dựa trên tác nhân trên các cụm TPU và GPU đẳng cấp thế giới của Google, đảm bảo hiệu suất có độ trễ thấp ngay cả đối với những ứng dụng toàn cầu đòi hỏi khắt khe nhất.

Google Workspace là gì?

Google Workspace là một bộ giải pháp cộng tác và tăng năng suất trên đám mây, được thiết kế cho cá nhân, trường học và doanh nghiệp:

Giao tiếp: Dịch vụ email chuyên nghiệp (Gmail), hội nghị truyền hình (Meet) và nhắn tin cho nhóm (Chat).
Tạo nội dung: Các công cụ để viết tài liệu (Tài liệu), tạo bảng tính (Trang tính) và thiết kế bản trình bày (Trang trình bày).
Tổ chức: Lịch dùng chung (Lịch) và ghi chú kỹ thuật số (Keep).
Bộ nhớ: Không gian tập trung trên đám mây để lưu và chia sẻ tệp một cách an toàn (Drive).
Quản lý: Các chế độ kiểm soát của quản trị viên để quản lý người dùng và chế độ cài đặt bảo mật (Bảng điều khiển dành cho quản trị viên Workspace).

Những loại tích hợp tuỳ chỉnh nào?

Google Workspace và Vertex AI tạo ra một vòng phản hồi hiệu quả, trong đó Workspace cung cấp dữ liệu theo thời gian thực và bối cảnh cộng tác, còn Vertex AI cung cấp các mô hình, khả năng suy luận dựa trên tác nhân và khả năng điều phối cần thiết để tự động hoá các quy trình làm việc thông minh.

Khả năng kết nối thông minh: Các kho dữ liệu, API và máy chủ MCP (do Google quản lý và tuỳ chỉnh) cho phép các tác nhân truy cập vào dữ liệu trên Workspace một cách an toàn và liền mạch, đồng thời thực hiện hành động thay cho người dùng.
Tác nhân tuỳ chỉnh: Bằng cách sử dụng trình thiết kế không cần mã hoặc khung chuyên nghiệp, các nhóm có thể tạo tác nhân chuyên biệt dựa trên dữ liệu và hành động do quản trị viên quản lý trong Workspace.
Tích hợp tự nhiên: Tiện ích bổ sung Workspace giúp thu hẹp khoảng cách giữa các hệ thống AI và các ứng dụng như Chat và Gmail, cho dù thông qua các thành phần giao diện người dùng chuyên dụng hay các quy trình nền. Điều này cho phép các nhân viên hỗ trợ gặp gỡ người dùng đúng lúc và hỗ trợ ngay lập tức dựa trên ngữ cảnh.

Bằng cách kết hợp hệ sinh thái năng suất mạnh mẽ của Google Workspace với sức mạnh của tác nhân tiên tiến của Vertex AI, các tổ chức có thể chuyển đổi hoạt động của mình thông qua các tác nhân AI tuỳ chỉnh dựa trên dữ liệu, tự động hoá các quy trình làm việc phức tạp ngay trong những công cụ mà nhóm của họ vẫn đang sử dụng mỗi ngày.

Điều kiện tiên quyết

Nếu muốn tự mình thực hiện tất cả các bước trên môi trường của mình, bạn sẽ cần:

Kiến thức cơ bản về Google Cloud và Python.
Một dự án trên Google Cloud mà bạn là chủ sở hữu và có thông tin thanh toán. Để kiểm tra xem một dự án hiện có đã bật tính năng thanh toán hay chưa, hãy xem phần Xác minh trạng thái thanh toán của dự án. Để tạo dự án và thiết lập thông tin thanh toán, hãy xem phần Tạo dự án trên Google Cloud. Để thay đổi quyền sở hữu dự án, hãy xem phần Quản lý thành viên dự án hoặc thay đổi quyền sở hữu dự án.
Tài khoản Google Workspace Business hoặc Enterprise có quyền truy cập vào Google Chat và đã bật các tính năng thông minh.
Google Cloud CLI đã được cài đặt và khởi chạy cho dự án của bạn trên Google Cloud.
Đã cài đặt Python 3.11 trở lên, hãy xem hướng dẫn trên trang web chính thức của Python.

Sản phẩm bạn sẽ tạo ra

Trong lớp học lập trình này, chúng ta sẽ xây dựng 3 giải pháp bằng các tác nhân Vertex AI được tích hợp chặt chẽ với Google Workspace. Các mẫu này sẽ minh hoạ những mẫu kiến trúc có thể dùng để tương tác với dữ liệu, thao tác và giao diện người dùng.

Ứng dụng Vertex AI Search

Tác nhân này cho phép người dùng tìm kiếm dữ liệu và thực hiện các thao tác cho Workspace bằng ngôn ngữ tự nhiên. Thành phần này dựa vào các phần tử sau:

Mô hình: Gemini.
Dữ liệu và hành động: Kho dữ liệu Vertex AI cho Google Workspace (Lịch, Gmail, Drive).
Máy chủ lưu trữ tác nhân: Vertex AI Search.
Giao diện người dùng: Tiện ích web Vertex AI Search.

Tác nhân tuỳ chỉnh

Trợ lý này cho phép người dùng tìm kiếm dữ liệu và thực hiện các thao tác cho Workspace bằng ngôn ngữ tự nhiên thông qua các công cụ và quy tắc tuỳ chỉnh. Thành phần này dựa vào các phần tử sau:

Mô hình: Gemini.
Dữ liệu và hành động: Kho dữ liệu Vertex AI cho Google Workspace (Lịch, Gmail, Drive), máy chủ Giao thức bối cảnh mô hình tìm kiếm (MCP) Vertex AI do Google quản lý, hàm công cụ tuỳ chỉnh để gửi tin nhắn Google Chat (thông qua Google Chat API).
Công cụ tạo tác nhân: Bộ công cụ phát triển tác nhân (ADK).
Máy chủ lưu trữ tác nhân: Vertex AI Agent Engine.
Giao diện người dùng: ADK Web.

Agent dưới dạng tiện ích bổ sung của Google Workspace

Trợ lý này cho phép người dùng tìm kiếm dữ liệu cho Workspace bằng ngôn ngữ tự nhiên trong bối cảnh giao diện người dùng của ứng dụng Workspace. Thành phần này dựa vào các phần tử sau:

Mô hình: Gemini.
Dữ liệu và hành động: Kho dữ liệu Vertex AI cho Google Workspace (Lịch, Gmail, Drive), máy chủ Giao thức bối cảnh mô hình tìm kiếm (MCP) Vertex AI do Google quản lý, hàm công cụ tuỳ chỉnh để gửi tin nhắn Google Chat (thông qua Google Chat API).
Công cụ tạo tác nhân: Bộ công cụ phát triển tác nhân (ADK).
Máy chủ lưu trữ tác nhân: Vertex AI Agent Engine.
Giao diện người dùng: Tiện ích bổ sung Google Workspace cho Chat và Gmail (dễ dàng mở rộng sang Lịch, Drive, Tài liệu, Trang tính và Trang trình bày).
Tiện ích bổ sung Google Workspace: Apps Script, API Công cụ tác nhân Vertex AI, theo ngữ cảnh (thư Gmail đã chọn).

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

Các điểm tích hợp giữa Vertex AI Search và Google Workspace cho phép sử dụng dữ liệu và thực hiện các hành động.
Các lựa chọn để xây dựng tác nhân tuỳ chỉnh được lưu trữ trong Vertex AI.
Những cách mà người dùng có thể truy cập vào các tác nhân như Tiện ích web Vertex AI Search và các ứng dụng Google Workspace.

2. Thiết lập

Trước khi xây dựng các giải pháp, chúng ta phải khởi động chế độ cài đặt Vertex AI Applications của dự án, bật các API bắt buộc và tạo các kho dữ liệu Vertex AI Workspace.

Xem lại các khái niệm

Ứng dụng Vertex AI

Ứng dụng Vertex AI là một giải pháp toàn diện, được quản lý trên Google Cloud, tích hợp các mô hình học máy (chẳng hạn như tác nhân AI tạo sinh hoặc công cụ tìm kiếm) với dữ liệu doanh nghiệp và các công cụ chuyên dụng để thực hiện các tác vụ phức tạp như tìm kiếm ngữ nghĩa, tạo nội dung hoặc tương tác tự động với khách hàng.

Kho dữ liệu Vertex AI

Kho dữ liệu Vertex AI là một thực thể chứa dữ liệu được nhập từ một nguồn dữ liệu của bên thứ nhất, chẳng hạn như Google Workspace hoặc các ứng dụng bên thứ ba, chẳng hạn như Jira hoặc Shopify. Kho dữ liệu chứa dữ liệu từ các ứng dụng bên thứ ba còn được gọi là trình kết nối dữ liệu.

Khởi chạy chế độ cài đặt Ứng dụng Vertex AI

Khởi chạy chế độ cài đặt Ứng dụng Vertex AI để bật tính năng tạo tác nhân.

Mở Google Cloud Console trong một thẻ mới, sau đó làm theo các bước sau:

Chọn dự án của bạn.
Trong trường tìm kiếm của Google Cloud, hãy chuyển đến Ứng dụng AI

Nhấp vào Tiếp tục và kích hoạt API sau khi xem xét và đồng ý với các điều khoản.
Chuyển đến phần Cài đặt.
Trong thẻ Xác thực, hãy chỉnh sửa global.

Chọn Google Identity, rồi nhấp vào Lưu.

Bật API

Các kho dữ liệu Vertex AI Workspace yêu cầu bạn bật các API sau:

Trong Bảng điều khiển Google Cloud, hãy bật Calendar API, Gmail API và People API:

Nhấp vào Trình đơn ☰ > API và dịch vụ > API và dịch vụ đã bật, sau đó xác nhận rằng API Lịch Google, Gmail API và People API có trong danh sách.

Tạo kho dữ liệu

Tạo kho dữ liệu Google Drive:

Trong Google Cloud Console, hãy chuyển đến AI Applications (Các ứng dụng AI), sau đó chuyển đến Data Stores (Kho dữ liệu).

Nhấp vào + Tạo kho dữ liệu.
Trong phần Nguồn, bên dưới Google Drive, hãy nhấp vào Chọn.

Trong mục Dữ liệu, hãy chọn Tất cả rồi nhấp vào Tiếp tục.

Trong mục Cấu hình, hãy đặt Tên trình kết nối dữ liệu thành drive, rồi nhấp vào Tiếp tục sau khi xem xét và đồng ý với các khoản phí có thể áp dụng.

Trong mục Định giá, hãy chọn mô hình định giá mà bạn muốn rồi nhấp vào Tạo. Bạn nên sử dụng mức giá chung trong bối cảnh của lớp học lập trình này.
Bạn sẽ tự động được chuyển hướng đến Kho dữ liệu, nơi bạn có thể xem kho dữ liệu mới thêm.

Tạo kho dữ liệu Lịch Google:

Nhấp vào + Tạo kho dữ liệu.
Trong phần Nguồn, hãy tìm Lịch Google rồi nhấp vào Chọn.
Trong phần Hành động, hãy nhấp vào Bỏ qua.
Trong mục Cấu hình, hãy đặt Tên trình kết nối dữ liệu thành calendar.
Nhấp vào Tạo.
Bạn sẽ tự động được chuyển hướng đến Kho dữ liệu, nơi bạn có thể xem kho dữ liệu mới thêm.

Tạo kho dữ liệu Google Gmail:

Nhấp vào + Kho dữ liệu mới.
Trong phần Nguồn, hãy tìm Google Gmail rồi nhấp vào Chọn.
Trong phần Hành động, hãy nhấp vào Bỏ qua.
Trong mục Cấu hình, hãy đặt Tên trình kết nối dữ liệu thành gmail.
Nhấp vào Tạo.
Bạn sẽ tự động được chuyển hướng đến Kho dữ liệu, nơi bạn có thể xem kho dữ liệu mới thêm.

3. Ứng dụng Vertex AI Search

Tác nhân này cho phép người dùng tìm kiếm dữ liệu và thực hiện các thao tác cho Workspace bằng ngôn ngữ tự nhiên. Thành phần này dựa vào các phần tử sau:

Mô hình: Gemini.
Dữ liệu và hành động: Kho dữ liệu Vertex AI cho Google Workspace (Lịch, Gmail, Drive).
Máy chủ lưu trữ tác nhân: Vertex AI Search.
Giao diện người dùng: Tiện ích web Vertex AI Search.

Xem lại các khái niệm

Ứng dụng Vertex AI Search

Ứng dụng Vertex AI Search cung cấp kết quả tìm kiếm, hành động và tác nhân cho người dùng cuối. Thuật ngữ ứng dụng có thể được dùng thay thế cho thuật ngữ công cụ trong bối cảnh API. Ứng dụng phải được kết nối với một kho dữ liệu để sử dụng dữ liệu từ kho đó nhằm phân phát kết quả tìm kiếm, câu trả lời hoặc hành động.

Tiện ích tìm kiếm trên web của Vertex AI là một thành phần giao diện người dùng có thể tuỳ chỉnh và được tạo sẵn, cho phép nhà phát triển nhúng thanh tìm kiếm và giao diện kết quả dựa trên AI trực tiếp vào một trang web mà không cần viết nhiều mã.

Bản xem trước của Vertex AI Search

Vertex AI Search Preview là một môi trường kiểm thử tích hợp trong Bảng điều khiển Google Cloud, cho phép nhà phát triển xác thực các cấu hình tìm kiếm và câu trả lời tạo sinh trước khi triển khai liền mạch các chế độ cài đặt đó cho một tiện ích tìm kiếm trên web Vertex AI sẵn sàng cho sản xuất.

Xem xét kiến trúc giải pháp

Tạo ứng dụng

Tạo một ứng dụng tìm kiếm mới để liên kết các kho dữ liệu của bạn.

Mở AI Applications > Apps (Ứng dụng AI > Ứng dụng) trên Cloud Console, sau đó làm theo các bước sau:

Nhấp vào biểu tượng + Tạo ứng dụng.
Trong phần Loại, trong mục Tìm kiếm tuỳ chỉnh (chung), hãy nhấp vào Tạo.

Trong phần Cấu hình, hãy đánh dấu vào Các tính năng của phiên bản dành cho doanh nghiệp và Câu trả lời tạo sinh sau khi xem xét và đồng ý với mức giá.
Đặt Tên ứng dụng thành codelab.
Một mã nhận dạng sẽ được tạo dựa trên tên và xuất hiện bên dưới trường, hãy sao chép mã nhận dạng đó.
Đặt Tên công ty thành Codelab.
Đặt Nhiều khu vực thành global (Global).
Nhấp vào Tiếp tục.

Trong mục Dữ liệu, hãy chọn các kho lưu trữ dữ liệu drive, gmail và calendar, rồi nhấp vào Tiếp tục.

Trong mục Định giá, hãy chọn mô hình định giá mà bạn muốn rồi nhấp vào Tạo. Bạn nên sử dụng mức giá chung trong bối cảnh của lớp học lập trình này.
Ứng dụng sẽ được tạo và bạn sẽ tự động được chuyển hướng đến Ứng dụng AI > Ứng dụng > codelab > Tổng quan về ứng dụng.
Chuyển đến mục Kho dữ liệu được kết nối.
Sau vài phút, tất cả trạng thái của cửa hàng dữ liệu được kết nối sẽ là Đang hoạt động.

Định cấu hình giao diện và hành vi của tiện ích tìm kiếm.

Chuyển đến phần Cấu hình.
Trong thẻ Giao diện người dùng, hãy đặt Loại tìm kiếm thành Tìm kiếm có câu hỏi tiếp theo, rồi nhấp vào Lưu và xuất bản.

Dùng thử ứng dụng

Kiểm thử ứng dụng tìm kiếm ngay trong bảng điều khiển Google Cloud.

Chuyển đến Xem trước, Tiện ích trên web sẽ xuất hiện.
Trong cuộc trò chuyện, hãy nhập Do I have any meetings today? rồi nhấn enter.
Trong cuộc trò chuyện, hãy nhập Did I receive an email on March 1st 2026? rồi nhấn enter.
Trong cuộc trò chuyện, hãy nhập Give me the title of the latest Drive file I created rồi nhấn enter.

4. Nhân viên hỗ trợ tuỳ chỉnh

Mô hình: Gemini.
Dữ liệu và hành động: Kho dữ liệu Vertex AI cho Google Workspace (Lịch, Gmail, Drive), máy chủ Giao thức bối cảnh mô hình tìm kiếm (MCP) Vertex AI do Google quản lý, hàm công cụ tuỳ chỉnh để gửi tin nhắn Google Chat (thông qua Google Chat API).
Công cụ tạo tác nhân: Bộ công cụ phát triển tác nhân (ADK).
Máy chủ lưu trữ tác nhân: Vertex AI Agent Engine.
Giao diện người dùng: ADK Web.

Xem lại các khái niệm

Agent Development Kit (ADK)

Bộ công cụ phát triển tác nhân (ADK) là một bộ công cụ và khung chuyên biệt được thiết kế để đơn giản hoá việc tạo các tác nhân AI tự trị bằng cách cung cấp các mô-đun dựng sẵn để suy luận, quản lý bộ nhớ và tích hợp công cụ.

Giao thức ngữ cảnh mô hình (MCP)

Giao thức ngữ cảnh mô hình (MCP) là một tiêu chuẩn mở được thiết kế để cho phép tích hợp liền mạch và an toàn giữa các ứng dụng AI và nhiều nguồn dữ liệu hoặc công cụ thông qua một giao diện "cắm và chạy" phổ biến.

Công cụ hàm

Công cụ hàm là một quy trình thực thi được xác định trước mà mô hình AI có thể kích hoạt để thực hiện các hành động cụ thể hoặc truy xuất dữ liệu theo thời gian thực từ các hệ thống bên ngoài, mở rộng khả năng của mô hình này ngoài việc chỉ tạo văn bản đơn giản.

ADK Web

ADK web là giao diện người dùng dành cho nhà phát triển được tích hợp sẵn cùng với ADK SDK để giúp việc phát triển và gỡ lỗi trở nên dễ dàng hơn.

Xem xét cấu trúc giải pháp

Xem mã nguồn

agent.py

Đoạn mã sau đây xác thực bằng Vertex AI, khởi chạy các công cụ Vertex AI Search MCP và Chat API, đồng thời xác định hành vi của tác nhân.

Xác thực: Thao tác này truy xuất ACCESS_TOKEN từ các biến môi trường để xác thực MCP và các lệnh gọi API.
Thiết lập công cụ: Công cụ này khởi động vertexai_mcp, một bộ công cụ kết nối với máy chủ Giao thức ngữ cảnh mô hình (MCP) của Vertex AI Search và công cụ send_direct_message. Nhờ đó, tác nhân có thể tìm kiếm trong các kho dữ liệu được kết nối của bạn và gửi tin nhắn trên Google Chat.
Định nghĩa về tác nhân: Định nghĩa root_agent bằng mô hình gemini-2.5-flash. Các chỉ dẫn này yêu cầu nhân viên hỗ trợ ưu tiên sử dụng công cụ tìm kiếm để truy xuất thông tin và công cụ send_direct_message để thực hiện các hành động, từ đó giúp nhân viên hỗ trợ nắm được thông tin trong dữ liệu doanh nghiệp của bạn.

...
MODEL = "gemini-2.5-flash"

# Access token for authentication
ACCESS_TOKEN = os.environ.get("ACCESS_TOKEN")
if not ACCESS_TOKEN:
    raise ValueError("ACCESS_TOKEN environment variable must be set")

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def send_direct_message(email: str, message: str) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=ACCESS_TOKEN)
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT,
        headers={"Authorization": f"Bearer {ACCESS_TOKEN}"}
    ),
    tool_filter=['search']
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

Tải mã nguồn xuống

Tải mã mẫu xuống môi trường cục bộ để bắt đầu.

Tải kho lưu trữ này trên GitHub xuống.

Trong cửa sổ dòng lệnh, hãy mở thư mục solutions/enterprise-ai-agent-local.

Cho phép API

Giải pháp này yêu cầu bạn bật thêm các API sau:

Trong Google Cloud Console, hãy bật Vertex AI, Cloud Resource Manager và Google Chat API:

Nhấp vào Trình đơn ☰ > API và Dịch vụ > API và Dịch vụ đã bật, sau đó xác nhận rằng Vertex AI API, Cloud Resource Manager API và Google Chat API có trong danh sách.

Giải pháp này yêu cầu bạn thiết lập màn hình xin phép:

Trong Bảng điều khiển Google Cloud, hãy nhấp vào Trình đơn ☰ > Nền tảng xác thực của Google > Thương hiệu.

Nhấp vào Bắt đầu.
Trong phần Thông tin về ứng dụng, hãy đặt Tên ứng dụng thành Codelab .
Trong phần Email hỗ trợ người dùng, hãy chọn một địa chỉ email hỗ trợ mà người dùng có thể liên hệ với bạn nếu họ có thắc mắc về sự đồng ý của mình.
Nhấp vào Tiếp theo.
Trong phần Đối tượng, hãy chọn Nội bộ.
Nhấp vào Tiếp theo.
Trong phần Thông tin liên hệ, hãy nhập Địa chỉ email để bạn có thể nhận thông báo về mọi thay đổi đối với dự án của mình.
Nhấp vào Tiếp theo.
Trong phần Hoàn tất, hãy xem kỹ Chính sách dữ liệu người dùng của dịch vụ API của Google. Nếu bạn đồng ý, hãy chọn Tôi đồng ý với Chính sách dữ liệu người dùng của dịch vụ API của Google.
Nhấp vào Tiếp tục rồi nhấp vào Tạo.

Cấu hình sẽ được lưu và bạn sẽ tự động được chuyển hướng đến trang Google Auth Platform > Overview (Nền tảng xác thực của Google > Tổng quan).

Để tìm hiểu thêm, hãy xem hướng dẫn đầy đủ về cách Định cấu hình màn hình xin phép bằng OAuth.

Tạo thông tin đăng nhập của ứng dụng OAuth

Tạo ứng dụng OAuth mới cho ứng dụng dành cho máy tính để xác thực người dùng trong môi trường cục bộ:

Trong Bảng điều khiển Google Cloud, hãy nhấp vào Trình đơn ☰ > Nền tảng xác thực của Google > Ứng dụng.

Nhấp vào + Tạo ứng dụng.
Đối với Loại ứng dụng, hãy chọn Ứng dụng dành cho máy tính.
Đặt Tên thành codelab.
Nhấp vào Tạo. Thông tin xác thực mới tạo sẽ xuất hiện.
Nhấp vào Tải JSON xuống rồi lưu tệp dưới dạng client_secret.json trong thư mục solutions/enterprise-ai-agent-local.

Bật MCP của Vertex AI Search

Trong một thiết bị đầu cuối, hãy thực thi:

gcloud beta services mcp enable discoveryengine.googleapis.com \
     --project=$(gcloud config get-value project)

Định cấu hình ứng dụng Chat

Định cấu hình ứng dụng Google Chat bằng các thông tin cơ bản.

Trong Google Cloud Console, hãy tìm Google Chat API trong trường tìm kiếm của Google Cloud, nhấp vào Google Chat API, nhấp vào Quản lý rồi nhấp vào Cấu hình.

Đặt Tên ứng dụng và Nội dung mô tả thành Vertex AI.
Đặt URL của hình đại diện thành https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png.
Huỷ chọn Bật các tính năng tương tác rồi nhấp vào Tắt trong hộp thoại phương thức xuất hiện.
Chọn Ghi lỗi vào Nhật ký.
Nhấp vào Lưu.

Chạy Tác nhân trong ADK Web

Khởi chạy tác nhân cục bộ bằng giao diện web ADK.

Trong một cửa sổ dòng lệnh, hãy mở thư mục solutions/enterprise-ai-agent-local rồi thực thi:

# 1. Authenticate with all the required scopes
gcloud auth application-default login \
  --client-id-file=client_secret.json \
   --scopes=https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/chat.spaces,https://www.googleapis.com/auth/chat.messages

# 2. Configure environment
export ACCESS_TOKEN=$(gcloud auth application-default print-access-token)
export GOOGLE_GENAI_USE_VERTEXAI=1
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value project)
export GOOGLE_CLOUD_LOCATION=us-central1

# 3. Create and activate a new virtual environment
python3 -m venv .venv
source .venv/bin/activate

# 4. Install poetry and project dependencies
pip install poetry
poetry install

# 5. Start ADK Web
adk web

Dùng thử tác nhân

Xác minh quy trình bằng cách trò chuyện với nhân viên hỗ trợ tuỳ chỉnh.

Trong trình duyệt Internet, hãy mở trang web ADK.
Trong cuộc trò chuyện, hãy nhập Please find my meetings for today, I need their titles and links rồi nhấn enter.
Trợ lý sẽ trả lời bằng danh sách các sự kiện trên Lịch (tuỳ thuộc vào tài khoản của người dùng).
Trong cuộc trò chuyện, hãy nhập Please send a Chat message to someone@example.com with the following text: Hello! rồi nhấn enter.
Trợ lý sẽ trả lời bằng một thông báo xác nhận.

5. Agent dưới dạng tiện ích bổ sung của Google Workspace

Mô hình: Gemini.
Dữ liệu và hành động: Kho dữ liệu Vertex AI cho Google Workspace (Lịch, Gmail, Drive), máy chủ Giao thức bối cảnh mô hình tìm kiếm (MCP) Vertex AI do Google quản lý, hàm công cụ tuỳ chỉnh để gửi tin nhắn Google Chat (thông qua Google Chat API).
Công cụ tạo tác nhân: Bộ công cụ phát triển tác nhân (ADK).
Máy chủ lưu trữ tác nhân: Vertex AI Agent Engine.
Giao diện người dùng: Tiện ích bổ sung Google Workspace cho Chat và Gmail (dễ dàng mở rộng sang Lịch, Drive, Tài liệu, Trang tính và Trang trình bày).
Tiện ích bổ sung Google Workspace: Apps Script, API Công cụ tác nhân Vertex AI, theo ngữ cảnh (thư Gmail đã chọn).

Xem lại các khái niệm

Tiện ích bổ sung của Google Workspace

Tiện ích bổ sung Google Workspace là một ứng dụng tuỳ chỉnh giúp mở rộng một hoặc nhiều ứng dụng Google Workspace (Gmail, Chat, Lịch, Tài liệu, Drive, Meet, Trang tính và Trang trình bày).

Apps Script

Apps Script là một nền tảng JavaScript dựa trên đám mây do Google Drive cung cấp, cho phép bạn tích hợp và tự động hoá các tác vụ trên các sản phẩm của Google.

Khung thẻ Google Workspace

Khung thẻ trong Google Workspace cho phép nhà phát triển tạo giao diện người dùng phong phú và có tính tương tác. Thư viện này cho phép tạo các thẻ có tổ chức và bắt mắt, có thể bao gồm văn bản, hình ảnh, nút và các tiện ích khác. Các thẻ này giúp nâng cao trải nghiệm người dùng bằng cách cung cấp thông tin có cấu trúc và cho phép thực hiện các thao tác nhanh ngay trong các ứng dụng Workspace.

Xem xét kiến trúc giải pháp

Xem mã nguồn

Tác nhân

agent.py

Đoạn mã sau đây xác thực bằng Vertex AI, khởi chạy các công cụ Vertex AI Search MCP và Chat API, đồng thời xác định hành vi của tác nhân.

Xác thực: Nó sử dụng hàm trợ giúp _get_access_token_from_context để truy xuất mã thông báo xác thực (CLIENT_AUTH_NAME) mà ứng dụng chèn. Mã thông báo này rất quan trọng để gọi một cách an toàn các dịch vụ hạ nguồn như Vertex AI Search MCP và các công cụ của Google Chat.
Thiết lập công cụ: Công cụ này khởi động vertexai_mcp, một bộ công cụ kết nối với máy chủ Giao thức ngữ cảnh mô hình (MCP) của Vertex AI Search và công cụ send_direct_message. Nhờ đó, tác nhân có thể tìm kiếm trong các kho dữ liệu được kết nối của bạn và gửi tin nhắn trên Google Chat.
Định nghĩa về tác nhân: Định nghĩa root_agent bằng mô hình gemini-2.5-flash. Các chỉ dẫn này yêu cầu nhân viên hỗ trợ ưu tiên sử dụng công cụ tìm kiếm để truy xuất thông tin và công cụ send_direct_message để thực hiện các hành động, từ đó giúp nhân viên hỗ trợ nắm được thông tin trong dữ liệu doanh nghiệp của bạn.

...
MODEL = "gemini-2.5-flash"

# Client injects a bearer token into the ToolContext state.
# The key pattern is "CLIENT_AUTH_NAME_<random_digits>".
# We dynamically parse this token to authenticate our MCP and API calls.
CLIENT_AUTH_NAME = "enterprise-ai"

VERTEXAI_SEARCH_TIMEOUT = 15.0

def get_project_id():
    """Fetches the consumer project ID from the environment natively."""
    _, project = google.auth.default()
    if project:
        return project
    raise Exception(f"Failed to resolve GCP Project ID from environment.")

def find_serving_config_path():
    """Dynamically finds the default serving config in the engine."""
    project_id = get_project_id()
    engines = discoveryengine_v1.EngineServiceClient().list_engines(
        parent=f"projects/{project_id}/locations/global/collections/default_collection"
    )
    for engine in engines:
        # engine.name natively contains the numeric Project Number
        return f"{engine.name}/servingConfigs/default_serving_config"
    raise Exception(f"No Discovery Engines found in project {project_id}")

def _get_access_token_from_context(tool_context: ToolContext) -> str:
    """Helper method to dynamically parse the intercepted bearer token from the context state."""
    escaped_name = re.escape(CLIENT_AUTH_NAME)
    pattern = re.compile(fr"^{escaped_name}_\d+$")
    # Handle ADK varying state object types (Raw Dict vs ADK State)
    state_dict = tool_context.state.to_dict() if hasattr(tool_context.state, 'to_dict') else tool_context.state
    matching_keys = [k for k in state_dict.keys() if pattern.match(k)]
    if matching_keys:
        return state_dict.get(matching_keys[0])
    raise Exception(f"No bearer token found in ToolContext state matching pattern {pattern.pattern}")

def auth_header_provider(tool_context: ToolContext) -> dict[str, str]:
    token = _get_access_token_from_context(tool_context)
    return {"Authorization": f"Bearer {token}"}

def send_direct_message(email: str, message: str, tool_context: ToolContext) -> dict:
    """Sends a Google Chat Direct Message (DM) to a specific user by email address."""
    chat_client = chat_v1.ChatServiceClient(
        credentials=Credentials(token=_get_access_token_from_context(tool_context))
    )

    # 1. Setup the DM space or find existing one
    person = chat_v1.User(
        name=f"users/{email}",
        type_=chat_v1.User.Type.HUMAN
    )
    membership = chat_v1.Membership(member=person)
    space_req = chat_v1.Space(space_type=chat_v1.Space.SpaceType.DIRECT_MESSAGE)
    setup_request = chat_v1.SetUpSpaceRequest(
        space=space_req,
        memberships=[membership]
    )
    space_response = chat_client.set_up_space(request=setup_request)
    space_name = space_response.name
    
    # 2. Send the message
    msg = chat_v1.Message(text=message)
    message_request = chat_v1.CreateMessageRequest(
        parent=space_name,
        message=msg
    )
    message_response = chat_client.create_message(request=message_request)
    
    return {"status": "success", "message_id": message_response.name, "space": space_name}

vertexai_mcp = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://discoveryengine.googleapis.com/mcp",
        timeout=VERTEXAI_SEARCH_TIMEOUT,
        sse_read_timeout=VERTEXAI_SEARCH_TIMEOUT
    ),
    tool_filter=['search'],
    # The auth_header_provider dynamically injects the bearer token from the ToolContext
    # into the MCP call for authentication.
    header_provider=auth_header_provider
)

# Answer nicely the following user queries:
#  - Please find my meetings for today, I need their titles and links
#  - What is the latest Drive file I created?
#  - What is the latest Gmail message I received?
#  - Please send the following message to someone@example.com: Hello, this is a test message.

root_agent = LlmAgent(
    model=MODEL,
    name='enterprise_ai',
    instruction=f"""
        You are a helpful assistant that always uses the Vertex AI MCP search tool to answer the user's message, unless the user asks you to send a message to someone.
        If the user asks you to send a message to someone, use the send_direct_message tool to send the message.
        You MUST unconditionally use the Vertex AI MCP search tool to find answer, even if you believe you already know the answer or believe the Vertex AI MCP search tool does not contain the data.
        The Vertex AI MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the Vertex AI MCP search tool with servingConfig and query parameters, do not use any other parameters.
        Always use the servingConfig {find_serving_config_path()} while using the Vertex AI MCP search tool.
    """,
    tools=[vertexai_mcp, FunctionTool(send_direct_message)]
)

Khách hàng

appsscript.json

Cấu hình sau đây xác định các điều kiện kích hoạt và quyền của tiện ích bổ sung.

Xác định tiện ích bổ sung: Thông tin này cho Workspace biết rằng dự án này là một tiện ích bổ sung cho cả Chat và Gmail.
Trình kích hoạt theo bối cảnh: Đối với Gmail, trình kích hoạt này thiết lập một contextualTrigger sẽ kích hoạt onAddonEvent bất cứ khi nào người dùng mở một thư email. Việc này cho phép tiện ích bổ sung "xem" nội dung email.
Quyền: Phần này liệt kê oauthScopes cần thiết để chạy tiện ích bổ sung, chẳng hạn như quyền đọc email hiện tại, thực thi tập lệnh và kết nối với các dịch vụ bên ngoài (như API Vertex AI).

...
"addOns": {
    "common": {
      "name": "Vertex AI",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/quickstart-app-avatar.png"
    },
    "chat": {},
    "gmail": {
      "contextualTriggers": [
        {
          "unconditional": {},
          "onTriggerFunction": "onAddonEvent"
        }
      ]
    }
  },
  "oauthScopes": [
   "https://www.googleapis.com/auth/script.external_request",
   "https://www.googleapis.com/auth/cloud-platform",
   "https://www.googleapis.com/auth/gmail.addons.execute",
   "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
 ]
...

Chat.gs

Đoạn mã sau đây xử lý các tin nhắn đến trong Google Chat.

Nhận tin nhắn: Hàm onMessage là điểm truy cập cho các lượt tương tác với tin nhắn.
Quản lý bối cảnh: Thao tác này lưu space.name (mã nhận dạng của không gian trò chuyện) vào các thuộc tính của người dùng. Điều này đảm bảo rằng khi sẵn sàng trả lời, tác nhân sẽ biết chính xác cuộc trò chuyện nào cần đăng tin nhắn.
Uỷ quyền cho Agent: Thao tác này gọi requestAgent, truyền thông báo của người dùng đến logic cốt lõi xử lý hoạt động giao tiếp API.

...
// Service that handles Google Chat operations.

// Handle incoming Google Chat message events, actions will be taken via Google Chat API calls
function onMessage(event) {
  if (isInDebugMode()) {
    console.log(`MESSAGE event received (Chat): ${JSON.stringify(event)}`);
  }
  // Extract data from the event.
  const chatEvent = event.chat;
  setChatConfig(chatEvent.messagePayload.space.name);

  // Request AI agent to answer the message
  requestAgent(chatEvent.messagePayload.message);
  // Respond with an empty response to the Google Chat platform to acknowledge execution
  return null; 
}

// --- Utility functions ---

// The Chat direct message (DM) space associated with the user
const SPACE_NAME_PROPERTY = "DM_SPACE_NAME"

// Sets the Chat DM space name for subsequent operations.
function setChatConfig(spaceName) {
  const userProperties = PropertiesService.getUserProperties();
  userProperties.setProperty(SPACE_NAME_PROPERTY, spaceName);
  console.log(`Space is set to ${spaceName}`);
}

// Retrieved the Chat DM space name to sent messages to.
function getConfiguredChat() {
  const userProperties = PropertiesService.getUserProperties();
  return userProperties.getProperty(SPACE_NAME_PROPERTY);
}

// Finds the Chat DM space name between the Chat app and the given user.
function findChatAppDm(userName) {
  return Chat.Spaces.findDirectMessage(
    { 'name': userName },
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

// Creates a Chat message in the configured space.
function createMessage(message) {
  const spaceName = getConfiguredChat();
  console.log(`Creating message in space ${spaceName}...`);
  return Chat.Spaces.Messages.create(
    message,
    spaceName,
    {},
    {'Authorization': `Bearer ${getAddonCredentials().getAccessToken()}`}
  ).name;
}

Đoạn mã sau đây tạo thanh bên Gmail và nắm bắt ngữ cảnh email.

Tạo giao diện người dùng: createSidebarCard tạo giao diện trực quan bằng Workspace Card Service. Thao tác này sẽ tạo một bố cục đơn giản có vùng nhập văn bản và nút "Gửi tin nhắn".
Nắm bắt bối cảnh email: Trong handleSendMessage, mã này kiểm tra xem người dùng hiện có đang xem email hay không (event.gmail.messageId). Nếu có, mã này sẽ tìm nạp một cách an toàn tiêu đề và nội dung của email rồi thêm vào câu lệnh của người dùng.
Hiển thị kết quả: Sau khi tác nhân phản hồi, mã sẽ cập nhật thẻ trên thanh bên để hiển thị câu trả lời.

...
// Service that handles Gmail operations.

// Triggered when the user opens the Gmail Add-on or selects an email.
function onAddonEvent(event) {
  // If this was triggered by a button click, handle it
  if (event.parameters && event.parameters.action === 'send') {
    return handleSendMessage(event);
  }

  // Otherwise, just render the default initial sidebar
  return createSidebarCard();
}

// Creates the standard Gmail sidebar card consisting of a text input and send button.
// Optionally includes an answer section if a response was generated.
function createSidebarCard(optionalAnswerSection) {
  const card = CardService.newCardBuilder();
  const actionSection = CardService.newCardSection();

  // Create text input for the user's message
  const messageInput = CardService.newTextInput()
    .setFieldName("message")
    .setTitle("Message")
    .setMultiline(true);

  // Create action for sending the message
  const sendAction = CardService.newAction()
    .setFunctionName('onAddonEvent')
    .setParameters({ 'action': 'send' });

  const sendButton = CardService.newTextButton()
    .setText("Send message")
    .setTextButtonStyle(CardService.TextButtonStyle.FILLED)
    .setOnClickAction(sendAction);

  actionSection.addWidget(messageInput);
  actionSection.addWidget(CardService.newButtonSet().addButton(sendButton));

  card.addSection(actionSection);

  // Attach the response at the bottom if we have one
  if (optionalAnswerSection) {
    card.addSection(optionalAnswerSection);
  }

  return card.build();
}

// Handles clicks from the Send message button.
function handleSendMessage(event) {
  const commonEventObject = event.commonEventObject || {};
  const formInputs = commonEventObject.formInputs || {};
  const messageInput = formInputs.message;

  let userMessage = "";
  if (messageInput && messageInput.stringInputs && messageInput.stringInputs.value.length > 0) {
    userMessage = messageInput.stringInputs.value[0];
  }

  if (!userMessage || userMessage.trim().length === 0) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Please enter a message."))
      .build();
  }

  let finalQueryText = `USER MESSAGE TO ANSWER: ${userMessage}`;

  // If we have an email selected in Gmail, append its content as context
  if (event.gmail && event.gmail.messageId) {
    try {
      GmailApp.setCurrentMessageAccessToken(event.gmail.accessToken);
      const message = GmailApp.getMessageById(event.gmail.messageId);

      const subject = message.getSubject();
      const bodyText = message.getPlainBody() || message.getBody();

      finalQueryText += `\n\nEMAIL THE USER HAS OPENED ON SCREEN:\nSubject: ${subject}\nBody:\n---\n${bodyText}\n---`;
    } catch (e) {
      console.error("Could not fetch Gmail context: " + e);
      // Invalidate the token explicitly so the next prompt requests the missing scopes
      ScriptApp.invalidateAuth();

      CardService.newAuthorizationException()
        .setResourceDisplayName("Enterprise AI")
        .setAuthorizationUrl(ScriptApp.getAuthorizationUrl())
        .throwException();
    }
  }

  try {
    const response = queryAgent({ text: finalQueryText });

    // We leverage the 'showdown' library to parse the LLM's Markdown output into HTML
    // We also substitute markdown listings with arrows and adjust newlines for clearer rendering in the sidebar
    let displayedText = substituteListingsFromMarkdown(response.text);
    displayedText = new showdown.Converter().makeHtml(displayedText).replace(/\n/g, '\n\n');

    const textParagraph = CardService.newTextParagraph();
    textParagraph.setText(displayedText);

    const answerSection = CardService.newCardSection()
      .addWidget(textParagraph);

    const updatedCard = createSidebarCard(answerSection);

    return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();

  } catch (err) {
    return CardService.newActionResponseBuilder()
      .setNotification(CardService.newNotification().setText("Error fetching response: " + err.message))
      .build();
  }
}
...

AgentHandler.gs

Đoạn mã sau đây điều phối lệnh gọi API đến Vertex AI.

Điều phối lệnh gọi API: queryAgent là cầu nối giữa tiện ích bổ sung của bạn và Vertex AI Agent Engine. Thao tác này tạo một yêu cầu bao gồm cụm từ tìm kiếm của người dùng và mã thông báo uỷ quyền trong trạng thái.
Truyền trực tuyến Phản hồi: Vì phản hồi của tác nhân có thể mất một chút thời gian, nên nó sử dụng API streamQuery với Sự kiện do máy chủ gửi (SSE). Đoạn mã này thu thập câu trả lời theo từng phần và tái tạo câu trả lời đầy đủ.

...
// Service that handles Vertex AI Agent operations.

// Submits a query to the AI agent and returns the response string synchronously
function queryAgent(input) {
 let systemPrompt = "SYSTEM PROMPT START Do not respond with tables but use bullet points instead." +
   " Do not ask the user follow-up questions or converse with them as history is not kept in this interface." +
   " SYSTEM PROMPT END\n\n";

 const requestPayload = {
   "class_method": "async_stream_query",
   "input": {
     "user_id": "vertex_ai_add_on",
     "message": { "role": "user", "parts": [{ "text": systemPrompt + input.text }] },
     "state_delta": {
       "enterprise-ai_999": `${ScriptApp.getOAuthToken()}`
     }
   }
 };

 const responseContentText = UrlFetchApp.fetch(
   `https://${getLocation()}-aiplatform.googleapis.com/v1/${getReasoningEngine()}:streamQuery?alt=sse`,
   {
     method: 'post',
     headers: { 'Authorization': `Bearer ${ScriptApp.getOAuthToken()}` },
     contentType: 'application/json',
     payload: JSON.stringify(requestPayload),
     muteHttpExceptions: true
   }
 ).getContentText();
  if (isInDebugMode()) {
   console.log(`Response: ${responseContentText}`);
 }

 const events = responseContentText.split('\n').map(s => s.replace(/^data:\s*/, '')).filter(s => s.trim().length > 0);
 console.log(`Received ${events.length} agent events.`);

 let author = "default";
 let answerText = "";
 for (const eventJson of events) {
   if (isInDebugMode()) {
     console.log("Event: " + eventJson);
   }
   const event = JSON.parse(eventJson);

   // Retrieve the agent responsible for generating the content
   author = event.author;
  
   // Ignore events that are not useful for the end-user
   if (!event.content) {
     console.log(`${author}: internal event`);
     continue;
   }

   // Handle text answers
   const parts = event.content.parts || [];
   const textPart = parts.find(p => p.text);
   if (textPart) {
     answerText += textPart.text;
   }
 }
 return { author: author, text: answerText };
}
...

Triển khai Agent trong Vertex AI Agent Engine

Trong một cửa sổ dòng lệnh, hãy mở thư mục solutions/enterprise-ai-agent từ các nguồn đã tải xuống ở các bước trước rồi thực thi:

# 1. Create and activate a new virtual environment
deactivate
python3 -m venv .venv
source .venv/bin/activate

# 2. Install poetry and project dependencies
pip install poetry
poetry install

# 3. Deploy the agent
adk deploy agent_engine \
  --project=$(gcloud config get-value project) \
  --region=us-central1 \
  --display_name="Enterprise AI" \
  enterprise_ai

Khi bạn thấy dòng Deploying to agent engine... (Đang triển khai cho công cụ tác nhân...) trong nhật ký, hãy mở một cửa sổ dòng lệnh mới và thực thi lệnh sau để thêm các quyền cần thiết vào Vertex AI Reasoning Engine Service Agent (Tác nhân dịch vụ Công cụ suy luận Vertex AI):

# 1. Get the current Project ID
PROJECT_ID=$(gcloud config get-value project)

# 2. Extract the Project Number for that ID
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# 3. Construct the Service Account name
SERVICE_ACCOUNT="service-${PROJECT_NUMBER}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"

# 4. Apply the IAM policy binding
gcloud projects add-iam-policy-binding $PROJECT_ID \
     --member="serviceAccount:$SERVICE_ACCOUNT" \
     --role="roles/discoveryengine.viewer"

Đợi lệnh adk deploy hoàn tất, sau đó sao chép tên tài nguyên của tác nhân mới triển khai từ đầu ra lệnh có màu xanh lục.

Khởi tạo tài khoản dịch vụ

Tạo một tài khoản dịch vụ chuyên dụng để uỷ quyền cho các hoạt động phía máy chủ của tiện ích bổ sung.

Trong Bảng điều khiển Google Cloud, hãy làm theo các bước sau:

Nhấp vào Trình đơn ☰ > IAM và Quản trị > Tài khoản dịch vụ > + Tạo tài khoản dịch vụ.

Đặt Tên tài khoản dịch vụ thành vertexai-add-on.

Nhấp vào Xong. Bạn sẽ được chuyển hướng đến trang Tài khoản dịch vụ và có thể thấy tài khoản dịch vụ mà bạn đã tạo.

Chọn tài khoản dịch vụ mới tạo rồi chọn thẻ Khoá.
Nhấp vào Thêm khoá rồi nhấp vào Tạo khoá mới.
Chọn JSON rồi nhấp vào Tạo.

Hộp thoại sẽ đóng và cặp khoá công khai/riêng tư mà bạn vừa tạo sẽ tự động tải xuống môi trường cục bộ dưới dạng tệp JSON.

Tạo và định cấu hình dự án Apps Script

Tạo một dự án Apps Script mới để lưu trữ mã của tiện ích bổ sung và định cấu hình các thuộc tính kết nối của dự án đó.

Nhấp vào nút sau để mở dự án Apps Script Tiện ích bổ sung AI cho doanh nghiệp:

Nhấp vào Tổng quan > Tạo bản sao.
Trong dự án Apps Script, hãy nhấp vào Cài đặt dự án > Chỉnh sửa thuộc tính tập lệnh > Thêm thuộc tính tập lệnh để thêm thuộc tính tập lệnh.
Đặt REASONING_ENGINE_RESOURCE_NAME thành tên tài nguyên của tác nhân Vertex AI mà bạn đã sao chép ở các bước trước. Tham số này có định dạng như sau:

projects/<PROJECT_NUMBER>/locations/us-central1/reasoningEngines/<AGENT_ID>

Đặt APP_SERVICE_ACCOUNT_KEY thành khoá JSON trong tệp tài khoản dịch vụ đã tải xuống ở các bước trước.
Nhấp vào Lưu thuộc tính của tập lệnh

Triển khai cho Gmail và Chat

Triển khai tiện ích bổ sung để kiểm thử tiện ích đó ngay trong Gmail và Google Chat.

Trong dự án Apps Script, hãy làm theo các bước sau:

Nhấp vào Triển khai > Triển khai thử nghiệm, rồi nhấp vào Cài đặt. Tính năng này hiện đã có trong Gmail.
Nhấp vào Sao chép trong phần Mã triển khai tiêu đề.

Trong Bảng điều khiển Google Cloud, hãy làm theo các bước sau:

Tìm Google Chat API trong trường tìm kiếm của Google Cloud, nhấp vào Google Chat API, nhấp vào Quản lý rồi nhấp vào Cấu hình.

Chọn Bật các tính năng tương tác.
Huỷ chọn Tham gia không gian và cuộc trò chuyện nhóm.
Trong phần Cài đặt kết nối, hãy chọn Apps Script.
Đặt Mã hoạt động triển khai thành Mã hoạt động triển khai đầu trang đã sao chép ở các bước trước.
Trong phần Chế độ hiển thị, hãy chọn Cho phép một số người và nhóm cụ thể trong miền Workspace của bạn sử dụng ứng dụng Chat này rồi nhập địa chỉ email của bạn.
Nhấp vào Lưu.

Dùng thử Tiện ích bổ sung

Tương tác với tiện ích bổ sung đang hoạt động để xác minh rằng tiện ích đó có thể tìm nạp dữ liệu và trả lời các câu hỏi trong ngữ cảnh.

Mở Google Chat trong thẻ mới, sau đó làm theo các bước sau:

Mở một không gian nhắn tin trực tiếp với ứng dụng Chat Vertex AI.

Nhấp vào Định cấu hình rồi thực hiện quy trình xác thực.
Nhập What are my meetings for today? rồi nhấn enter. Ứng dụng trò chuyện Vertex AI sẽ trả lời bằng kết quả.

Mở Gmail trong một thẻ mới, sau đó làm theo các bước sau:

Gửi email cho chính bạn với Tiêu đề được đặt thành We need to talk và Nội dung được đặt thành Are you available today between 8 and 9 AM?
Mở email mới nhận được.
Mở thanh bên của tiện ích bổ sung Vertex AI.
Đặt Message (Thông báo) thành Do I have any meeting conflicts?
Nhấp vào Gửi tin nhắn.
Câu trả lời sẽ xuất hiện sau nút này.

6. Dọn dẹp

Xoá dự án trên Google Cloud

Để tránh phát sinh phí cho Tài khoản Google Cloud của bạn đối với các tài nguyên được sử dụng trong lớp học lập trình này, bạn nên xoá dự án trên Google Cloud.

Trong Bảng điều khiển Google Cloud, hãy làm theo các bước sau:

Nhấp vào Trình đơn ☰ > IAM và Quản trị > Cài đặt.

Nhấp vào Tắt.
Nhập mã dự án.
Nhấp vào Vẫn tắt.

7. Xin chúc mừng

Xin chúc mừng! Bạn đã xây dựng các giải pháp khai thác sức mạnh của việc kết hợp Vertex AI và Google Workspace cho nhân viên!

Tiếp theo là gì?

Trong lớp học lập trình này, chúng tôi chỉ giới thiệu những trường hợp sử dụng điển hình nhất, nhưng có rất nhiều lĩnh vực mở rộng mà bạn có thể muốn cân nhắc trong các giải pháp của mình, chẳng hạn như:

Sử dụng các công cụ dành cho nhà phát triển dựa trên AI, chẳng hạn như Gemini CLI và Antigravity.
Tích hợp với các khung và công cụ tác nhân khác, chẳng hạn như MCP tuỳ chỉnh, lệnh gọi hàm tuỳ chỉnh và giao diện người dùng tạo sinh.
Tích hợp với các mô hình AI khác, bao gồm cả mô hình tuỳ chỉnh, được lưu trữ trong các nền tảng chuyên dụng như Vertex AI.
Tích hợp với các tác nhân khác, được lưu trữ trong các nền tảng chuyên dụng như Dialogflow hoặc do bên thứ ba cung cấp thông qua Cloud Marketplace.
Xuất bản các tác nhân trên Cloud Marketplace để hỗ trợ các nhóm, tổ chức hoặc người dùng công khai.

Tìm hiểu thêm

Có rất nhiều tài nguyên dành cho nhà phát triển, chẳng hạn như video trên YouTube, trang web tài liệu, mã mẫu và hướng dẫn:

Tích hợp các trợ lý ảo Vertex AI với Google Workspace

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

Vertex AI là gì?

Google Workspace là gì?

Những loại tích hợp tuỳ chỉnh nào?

Điều kiện tiên quyết

Sản phẩm bạn sẽ tạo ra

Ứng dụng Vertex AI Search

Tác nhân tuỳ chỉnh

Agent dưới dạng tiện ích bổ sung của Google Workspace

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

2. Thiết lập

Xem lại các khái niệm

Ứng dụng Vertex AI

Kho dữ liệu Vertex AI

Khởi chạy chế độ cài đặt Ứng dụng Vertex AI

Bật API

Tạo kho dữ liệu

3. Ứng dụng Vertex AI Search

Xem lại các khái niệm

Ứng dụng Vertex AI Search

Tiện ích web Vertex AI Search

Bản xem trước của Vertex AI Search

Xem xét kiến trúc giải pháp

Tạo ứng dụng

Định cấu hình tiện ích web

Dùng thử ứng dụng

4. Nhân viên hỗ trợ tuỳ chỉnh

Xem lại các khái niệm

Agent Development Kit (ADK)

Giao thức ngữ cảnh mô hình (MCP)

Công cụ hàm

ADK Web

Xem xét cấu trúc giải pháp

Xem mã nguồn

agent.py

Tải mã nguồn xuống

Cho phép API

Định cấu hình màn hình đồng ý OAuth

Tạo thông tin đăng nhập của ứng dụng OAuth

Bật MCP của Vertex AI Search

Định cấu hình ứng dụng Chat

Chạy Tác nhân trong ADK Web

Dùng thử tác nhân

5. Agent dưới dạng tiện ích bổ sung của Google Workspace

Xem lại các khái niệm

Tiện ích bổ sung của Google Workspace

Apps Script

Khung thẻ Google Workspace

Xem xét kiến trúc giải pháp

Xem mã nguồn

Tác nhân

agent.py

Khách hàng

appsscript.json

Chat.gs

Sidebar.gs

AgentHandler.gs

Triển khai Agent trong Vertex AI Agent Engine

Khởi tạo tài khoản dịch vụ

Tạo và định cấu hình dự án Apps Script

Triển khai cho Gmail và Chat

Dùng thử Tiện ích bổ sung

6. Dọn dẹp

Xoá dự án trên Google Cloud

7. Xin chúc mừng

Tiếp theo là gì?

Tìm hiểu thêm