将 Gemini Enterprise 智能体与 Google Workspace 集成

1. 准备工作

7zN3mxxU73oY8Gi.png

什么是 Gemini Enterprise？

Gemini Enterprise 是一个先进的智能体平台，它将 Google AI 的卓越能力带给每一位员工，融入每一个工作流。它让团队能够在一个安全的环境中发现、创建、共享和运行 AI 智能体。

  • 使用高级模型：用户可以立即使用 Google 最强大的多模态 AI（包括 Gemini）来应对复杂的业务挑战。
  • 利用专业智能体：该套件包含可用于研究、编码和记笔记的即用型 Google 智能体，可立即创造价值。
  • 赋能每位员工：通过无代码和专业代码选项，各部门的员工都可以构建和管理自己的自定义智能体，以实现工作流自动化。
  • 让智能体基于数据运行：智能体可安全地连接到公司内部数据和第三方应用，确保其回答符合语境。
  • 集中式治理：管理员可以直观呈现和审核所有智能体活动，确保组织符合严格的安全和合规性标准。
  • 通过生态系统进行扩展：该平台与广泛的合作伙伴应用和服务提供商网络集成，可在不同系统之间扩展自动化功能。

127f2ed7d484722c.png

什么是 Google Workspace？

Google Workspace 是一套基于云的生产力解决方案和协作解决方案，专为个人、学校和企业打造：

  • 沟通：专业电子邮件服务 (Gmail)、视频会议 (Meet) 和团队消息服务 (Chat)。
  • 内容创作：用于撰写文档 (Google 文档)、构建电子表格 (Google 表格) 和设计演示文稿 (Google 幻灯片) 的工具。
  • 整理：共享日历（日历）和数字记事（Keep）。
  • 存储空间：用于安全地保存和共享文件的集中式云空间（云端硬盘）。
  • 管理：用于管理用户和安全设置的管理控件（Workspace 管理控制台）。

哪些类型的自定义集成？

Google Workspace 和 Gemini Enterprise 形成强大的反馈环路，其中 Workspace 提供实时数据和协作上下文，而 Gemini Enterprise 提供自动化智能工作流所需的模型、智能体推理和编排。

  • 智能连接：借助 Google 管理的数据存储区、API 和 MCP 服务器（Google 管理的服务器和自定义服务器），代理可以安全无缝地访问 Workspace 数据并代表用户执行操作。
  • 自定义智能体：团队可以使用无代码设计器或专业代码框架，基于管理员管控的 Workspace 数据和操作构建专业智能体。
  • 原生集成：Workspace 加购项通过专用界面组件或后台进程，弥合了 AI 系统与 Chat 和 Gmail 等应用之间的差距。这样，客服人员就可以在用户需要时立即提供情境感知型帮助。

通过将 Google Workspace 的强大生产力生态系统与 Gemini Enterprise 的先进智能体功能相结合，组织可以借助自定义的、基于数据的 AI 智能体来转变运营方式，直接在团队日常使用的工具中自动执行复杂的工作流程。

前提条件

如果您想在自己的环境中完成所有步骤，则需要：

构建内容

在此 Codelab 中，我们将构建三个与 Google Workspace 紧密集成的 Gemini Enterprise AI 智能体解决方案。他们将展示可用于与数据、操作和界面互动的架构模式。

无代码自定义智能体

借助此智能体，用户可以使用自然语言搜索数据，并针对 Workspace 执行操作。它依赖于以下元素：

  • 模型：Gemini。
  • 数据和操作：Google Workspace（日历、Gmail、云端硬盘、NotebookLM）的 Gemini Enterprise 数据存储区、Google 搜索。
  • 智能体构建工具：Gemini Enterprise Agent Designer。
  • 代理主机：Gemini Enterprise。
  • 界面：Gemini Enterprise Web 应用。

90e42539e5959634.png60e62437ce29a818.png

专业代码自定义代理

借助此智能体，用户可以使用自定义工具和规则，以自然语言搜索数据并针对 Workspace 执行操作。它依赖于以下元素：

  • 模型：Gemini。
  • 数据和操作：Google Workspace（日历、Gmail、云端硬盘、NotebookLM）的 Gemini Enterprise 数据存储区、Google 搜索、Google 管理的 Agent Search 的 Model Context Protocol (MCP) 服务器、用于发送 Google Chat 消息（通过 Google Chat API）的自定义工具函数。
  • 智能体构建工具：智能体开发套件 (ADK)。
  • 代理主机：Agent Runtime。
  • 界面：Gemini Enterprise Web 应用。

1647ebff031c42e7.pnga8087d2351e77fb4.png

作为 Google Workspace 加购项的默认代理

借助此代理，用户可以在 Workspace 应用界面中以自然语言搜索 Workspace 数据。它依赖于以下元素：

  • 模型：Gemini。
  • 数据：Google Workspace（日历、Gmail、云端硬盘、NotebookLM）的 Gemini Enterprise 数据存储区、Google 搜索。
  • 代理主机：Gemini Enterprise。
  • 界面：适用于 Chat 和 Gmail 的 Google Workspace 加购项（可轻松扩展到 Google 日历、云端硬盘、文档、表格和幻灯片）。
  • Google Workspace 插件：Apps 脚本、Gemini Enterprise API、上下文（用户元数据、所选 Gmail 邮件）。

c8c63fb3f324fecf.pngd33b8cb50ee251b7.png

学习内容

  • Gemini Enterprise 与 Google Workspace 之间可实现数据和操作的集成点。
  • 用于构建托管在 Gemini Enterprise 中的自定义智能体的无代码和专业代码选项。
  • 用户可以通过哪些方式从 Gemini Enterprise Web 应用和 Google Workspace 应用访问智能体。

轻松访问此 Codelab

82JGvYaTp8dhuvv.png

2. 进行设置

查看概念

Gemini Enterprise 应用

Gemini Enterprise 应用可为最终用户提供搜索结果、操作和智能体。在 API 的上下文中，“应用”一词可以与“引擎”一词互换使用。应用必须连接到数据存储区，才能使用其中的数据来提供搜索结果、答案或操作。

Gemini Enterprise Web 应用

Gemini Enterprise Web 应用与 Gemini Enterprise 应用相关联。它是一个集中式 AI 主平台，员工可使用单个聊天界面搜索孤立的公司数据、运行专门的 AI 智能体来处理复杂的工作流，并生成具有企业级隐私保护的专业级内容。

初始化和访问资源

在本部分中，您可以使用自己偏好的网络浏览器访问和配置以下资源。

Gemini Enterprise 应用

在新标签页中打开 Google Cloud 控制台，然后按以下步骤操作：

  1. 选择您的项目。
  2. 在 Google Cloud 搜索字段中，搜索并选择 Gemini Enterprise，然后点击 + 创建应用。如果您没有 Gemini Enterprise 许可，系统会提示您激活 30 天免费试用许可。

  1. 将应用名称设置为 codelab。
  2. 系统会根据名称生成 ID，并显示在相应字段下方，请复制该 ID。
  3. 将多区域设置为 global (Global)。
  4. 点击创建。

8712ada39377205e.png

  1. 应用创建完毕后，系统会自动将您重定向到 Gemini Enterprise > 概览。
  2. 在获取完整访问权限下，点击设置身份。
  3. 在新界面中，选择使用 Google Identity，然后点击确认员工身份。

3209c156eff4ba43.png

  1. 系统会保存配置，并自动将您重定向到 Gemini Enterprise > 概览。
  2. 前往配置。
  3. 在功能管理标签页中，开启启用代理设计工具，然后点击保存。

f0cd9da419b41cb6.png

Gemini Enterprise Web 应用

在新的标签页中从 Cloud 控制台打开 Gemini Enterprise，然后按以下步骤操作：

  1. 点击名为 codelab 的应用。
  2. 复制显示的网址，因为我们将在后续步骤中使用该网址来前往 Gemini Enterprise Web 应用。

b46ee6176744565d.png

3. 无代码自定义代理

借助此智能体，用户可以使用自然语言搜索数据，并针对 Workspace 执行操作。它依赖于以下元素：

  • 模型：Gemini。
  • 数据和操作：Google Workspace（日历、Gmail、云端硬盘、NotebookLM）的 Gemini Enterprise 数据存储区、Google 搜索。
  • 智能体构建工具：Gemini Enterprise Agent Designer。
  • 代理主机：Gemini Enterprise。
  • 界面：Gemini Enterprise Web 应用。

查看概念

Gemini

Gemini 是 Google 推出的一款多模态 LLM。它能帮助人们释放潜力，从而加强想象力、增加好奇心并提高工作效率。

Gemini Enterprise 数据存储区

Gemini Enterprise 数据存储区是一种实体，其中包含从第一方数据源（例如 Google Workspace）或第三方应用（例如 Jira 或 Salesforce）提取的数据。包含第三方应用数据的数据存储区也称为数据连接器。

Gemini Enterprise Agent Designer

Gemini Enterprise Agent Designer 是一个交互式无代码/低代码平台，用于在 Gemini Enterprise 中创建、管理和启动单步和多步智能体。

查看解决方案架构

e77aafb772502aaf.png

启用 API

Gemini Enterprise Workspace 数据存储区需要启用以下 API：

  1. 在 Google Cloud 控制台中，启用日历、Gmail 和 People API：

573322606b715a69.png

  1. 依次点击菜单 ☰ > API 和服务 > 已启用的 API 和服务，然后确认列表中包含 Google 日历 API、Gmail API 和 People API。

Gemini Enterprise Workspace 日历和 Gmail 操作需要配置权限请求页面：

  1. 在 Google Cloud 控制台中，依次点击菜单 ☰ > Google Auth 平台 > 品牌推广。

  1. 点击开始使用。
  2. 在应用信息下，将应用名称设置为 Codelab。
  3. 在用户支持电子邮件中，选择一个支持电子邮件地址，以便用户在对自己的同意情况有疑问时与您联系。
  4. 点击下一步。
  5. 在受众群体下，选择内部。
  6. 点击下一步。
  7. 在联系信息下，输入一个电子邮件地址，以便您接收有关项目变更的通知。
  8. 点击下一步。
  9. 在完成部分，查看 Google API 服务用户数据政策，如果您同意该政策，请选择我同意 Google API 服务：用户数据政策。
  10. 依次点击继续和创建。

578c2b38219b2f7b.png

  1. 系统会保存配置，并自动将您重定向到 Google Auth Platform > 概览。
  2. 前往数据访问权限。
  3. 点击添加或移除范围。
  4. 复制以下授权范围，然后将其粘贴到手动添加授权范围字段中。
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.calendars
https://www.googleapis.com/auth/gmail.send
https://www.googleapis.com/auth/gmail.readonly
  1. 依次点击添加到表格、更新和保存。

874b1dda14e8f379.png

如需了解详情，请参阅完整的配置 OAuth 权限请求指南。

创建 OAuth 客户端凭据

为 Gemini Enterprise 创建新的 OAuth 客户端，以便对用户进行身份验证：

  1. 在 Google Cloud 控制台中，依次点击菜单 ☰ > Google Auth 平台 > 客户端。

  1. 点击 + 创建客户端。
  2. 在应用类型部分，选择 Web 应用。
  3. 将名称设置为 codelab。
  4. 跳过已获授权的 JavaScript 来源。
  5. 在已获授权的重定向 URI 部分中，点击添加 URI，然后输入 https://vertexaisearch.cloud.google.com/oauth-redirect。
  6. 点击创建。
  7. 系统会显示一个对话框，其中包含您新创建的 OAuth 客户端 ID 和密钥。请将此信息保存在安全的地方。

a46e5ebfb851aea5.png

创建数据存储区

您需要创建数据存储区，才能将 Gemini Enterprise 关联到您的 Workspace 数据。

在新的标签页中从 Cloud 控制台打开 Gemini Enterprise，然后按以下步骤操作：

  1. 点击名为 codelab 的应用。
  2. 在导航菜单中，点击关联的数据存储区。
  3. 点击 + 新建数据存储区。
  4. 在来源中，搜索 Google 日历，然后点击选择。
  5. 在操作部分，输入之前步骤中保存的客户端 ID 和客户端密钥，然后点击确认身份验证，并按照相应步骤对 OAuth 客户端进行身份验证和授权。
  6. 启用“创建日历活动”和“更新日历活动”操作。
  7. 点击继续。

a1d76e70edec0cf.png

  1. 在配置部分中，将数据连接器名称设置为 calendar。
  2. 点击创建。
  3. 系统会自动将您重定向到关联的数据存储区，您可以在其中看到新添加的数据存储区。

创建 Google Gmail 数据存储区：

  1. 点击 + 新建数据存储区。
  2. 在来源中，搜索 Google Gmail，然后点击选择。
  3. 在操作部分，输入之前步骤中保存的客户端 ID 和客户端密钥，然后点击验证身份验证。
  4. 启用发送电子邮件操作。
  5. 点击继续。
  6. 在配置部分中，将数据连接器名称设置为 gmail。
  7. 点击创建。
  8. 系统会自动将您重定向到关联的数据存储区，您可以在其中看到新添加的数据存储区。

创建 Google 云端硬盘数据存储区：

  1. 点击 + 新建数据存储区。
  2. 在来源中，搜索 Google 云端硬盘，然后点击选择。
  3. 在数据部分中，选择全部，然后点击继续。
  4. 在配置部分中，将数据连接器名称设置为 drive。
  5. 点击创建。
  6. 系统会自动将您重定向到关联的数据存储区，您可以在其中看到新添加的数据存储区。

创建 NotebookLM 数据存储区：

  1. 点击 + 新建数据存储区。
  2. 在来源中，搜索 NotebookLM，然后点击选择。
  3. 在配置部分中，将数据连接器名称设置为 notebooklm。
  4. 点击创建。
  5. 系统会自动将您重定向到关联的数据存储区，您可以在其中看到新添加的数据存储区。

几分钟后，所有已连接的数据存储区（NotebookLM 除外）的状态都将变为有效。如果您看到任何错误，可以点击相应数据源来查看错误详情。

ceba9eb2480a2696.png

测试数据存储区

运行一些测试查询，验证数据存储区是否正在正确提取数据。

打开我们之前复制的 Gemini Enterprise Web 应用网址：

  1. 依次点击菜单 ☰ > 新对话。
  2. 在新聊天消息字段的页脚中，点击连接器图标，然后启用所有连接器。
  3. 您现在可以尝试使用与连接器相关的提示。例如，在聊天中，输入 Do I have any meetings today?，然后按 enter。
  4. 接下来，尝试输入 How many emails did I receive today? 并按 enter。
  5. 最后，输入 Give me the title of the last Drive file I created，然后按 enter。

90e42539e5959634.png

创建自定义代理

在 Gemini Enterprise Web 应用中，使用 Agent Designer 创建新智能体：

  1. 依次点击“菜单”图标 ☰ >“+ 新建代理”。
  2. 在聊天中，输入 An agent that always sends pirate-themed emails but use normal English otherwise，然后按 enter。

2803c1dedd20433e.png

  1. Agent Designer 会根据提示起草代理，并在编辑器中打开该代理。
  2. 点击创建

试用自定义代理

测试新代理，看看它如何回答问题和执行操作。

  1. 在 Gemini Enterprise Web 应用中，与新创建的代理对话：
  2. 依次点击菜单 ☰ > 代理。
  3. 在您的代理下选择相应代理。
  4. 在新聊天消息字段的页脚中，点击连接器图标，然后点击启用操作（针对邮件），并按照说明授权代理
  5. 在聊天中，输入 Send an email to someone@example.com saying I'll see them at Cloud Next, generate some subject and body yourself，然后按 enter。您可以将示例电子邮件地址替换为您的电子邮件地址。
  6. 点击“✔️”即可发送电子邮件。

60e62437ce29a818.pngd4fb65d14fdf27da.png

4. Pro-code 自定义代理

借助此智能体，用户可以使用自定义工具和规则，以自然语言搜索数据并针对 Workspace 执行操作。它依赖于以下元素：

  • 模型：Gemini。
  • 数据和操作：Google Workspace（日历、Gmail、云端硬盘、NotebookLM）的 Gemini Enterprise 数据存储区、Google 搜索、Google 管理的 Agent Search 的 Model Context Protocol (MCP) 服务器、用于发送 Google Chat 消息（通过 Google Chat API）的自定义工具函数。
  • 智能体构建工具：智能体开发套件 (ADK)。
  • 代理主机：Agent Runtime。
  • 界面：Gemini Enterprise Web 应用。

它将使用自带功能集成到 Gemini Enterprise 中，因此我们需要完成部署、注册和配置步骤。

查看概念

Gemini Enterprise Agent Platform

Gemini Enterprise Agent Platform（以前称为 Vertex AI）是一个开放而全面的平台，可帮助企业快速构建、扩缩、治理和优化依托企业数据的企业级智能体。

4670fcf7a826af4d.png

智能体开发套件 (ADK)

智能体开发套件 (ADK) 是一套专门的工具和框架，旨在通过提供用于推理、内存管理和工具集成的预构建模块，简化自主 AI 智能体的创建过程。

模型上下文协议 (MCP)

Model Context Protocol (MCP) 是一种开放标准，旨在通过通用的“即插即用”接口，在 AI 应用与各种数据源或工具之间实现无缝、安全的集成。

函数工具

函数工具是一种预定义的可执行例程，AI 模型可以触发该例程来执行特定操作或从外部系统检索实时数据，从而将其功能扩展到简单的文本生成之外。

查看解决方案架构

43df337e0f3d64e8.png

查看源代码

agent.py

以下代码会向 Gemini Enterprise 进行身份验证，初始化 Agent Search MCP 和 Chat API 工具，并定义智能体的行为。

  1. 身份验证：它使用辅助函数 _get_access_token_from_context 来检索 Gemini Enterprise 注入的身份验证令牌 (CLIENT_AUTH_NAME)。此令牌对于安全地调用下游服务（例如 Agent Search MCP 和 Google Chat 工具）至关重要。
  2. 工具设置：它会初始化 vertexai_mcp（一种连接到 Agent Search Model Context Protocol (MCP) 服务器的工具集）和 send_direct_message 工具。这样，代理便能够搜索您关联的数据存储区并发送 Google Chat 消息。
  3. 智能体定义：使用 gemini-2.5-flash 模型定义 root_agent。这些指令会告知智能体优先使用搜索工具来检索信息，并使用 send_direct_message 工具来执行操作，从而有效地使智能体以企业数据为依据。
...
MODEL = "gemini-2.5-flash"

# Gemini Enterprise authentication 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}

agentsearch_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 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 MCP search tool to find answer, even if you believe you already know the answer or believe the MCP search tool does not contain the data.
        The MCP search tool accesses the user's data through datastores including Google Drive, Google Calendar, and Gmail.
        Only use the 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 MCP search tool.
    """,
    tools=[agentsearch_mcp, FunctionTool(send_direct_message)]
)

启用 API

该解决方案需要启用其他 API：

  1. 在 Google Cloud 控制台中，启用 Agent Platform、Cloud Resource Manager 和 Google Chat API：

4f02a36b050bab00.png

  1. 依次点击菜单 ☰ > API 和服务 > 已启用的 API 和服务，然后确认列表中包含 Vertex AI API、Cloud Resource Manager API 和 Google Chat API。

此解决方案需要额外的数据访问权限：

  1. 在 Google Cloud 控制台中，依次点击菜单 ☰ > Google Auth 平台 >