Google Gemini Enterprise — GE Marketplace

此存储库包含一个可用于生产环境的 AI Agent，它将组织特定的 Neo4j 图数据库连接到 Google Gemini Enterprise。利用 Agent-to-Agent (A2A) 协议和 Google 的 Agent 开发套件 (ADK)，用户可以使用自然语言安全地查询其企业图数据。

该应用程序专为 Google Cloud Marketplace 设计，作为“代理即服务”(Agent-as-a-Service, AaaS) 提供，具备完整的多租户隔离、自动计费生命周期管理和动态客户端注册 (DCR) 功能。

架构概述

Neo4j Gemini AaaS Architecture

:bulb: 工作原理 (TL;DR)

本服务充当 Google 基础设施与客户 Neo4j 数据库之间安全、智能的桥梁。它完全以无服务器 (Serverless) 方式在 Google Cloud Run 上运行。当客户购买该 Agent 后，Google 会发送后台 Pub/Sub 事件进行注册。随后，客户访问托管的设置页面，安全地提供其 Neo4j 凭据。最后，当客户与 Gemini 对话时，本服务会拦截自然语言查询，验证其特定的 OAuth 令牌，利用 ADK 将提示词转换为 Cypher 语句，针对其隔离的 Neo4j 实例执行查询，并将流式结果返回至 Gemini UI。

:sparkles: 核心功能

真正的多租户：根据客户通过加密验证的 Marketplace 身份，动态将自然语言查询路由至相应的目标 Neo4j 数据库。无障碍入门：为 IT 管理员提供自定义 HTML 设置门户，无需复杂的 GCP 采购 ID 即可安全输入数据库凭据。动态客户端注册 (DCR)：当 Gemini 连接到 Agent 时，自动配置自定义 OAuth 2.0 凭据，将连接严格限制为经批准的 Marketplace 权益。自定义 OAuth 2.0 提供程序：充当授权服务器，具有自定义同意 UI，可防止浏览器竞争条件并安全签发 JWT。限流与计费：使用 ADK 回调拦截每次交互的精确 LLM token 使用量，并从存储在内部跟踪数据库中的客户每日限额中扣除。

:satellite: Marketplace 与 Pub/Sub 集成

为实现计费和租户配置自动化，本应用程序会监听标准的 Google Cloud Marketplace Pub/Sub 主题。推送订阅会将这些事件直接路由至 /pubsub 端点。

事件类型 系统操作

`ENTITLEMENT_CREATION_REQUESTED`

提取账户 ID 和权益 ID，在内部跟踪数据库中创建 PENDING（待处理）用户记录。

`ENTITLEMENT_ACTIVE`

确认客户已完成 /setup 配置，且计费已正式启动。

`ENTITLEMENT_PLAN_CHANGED`

根据客户新选择的层级调整其每日 LLM token 限额。

`ENTITLEMENT_CANCELLED`

立即撤销 OAuth 访问权限，删除目标数据库凭据，并停止计费。

:arrows_counterclockwise: 生命周期详解

购买：客户购买 Agent。Pub/Sub 事件触发其内部跟踪配置文件的创建。配置：客户被重定向至 /setup 门户，输入目标 Neo4j URI 和凭据。应用程序安全保存这些信息，并 ping GCP 采购 API 以开始计费。注册：客户将 Agent 添加至其 Gemini UI。Gemini 调用 /dcr 获取动态生成的 OAuth 凭据。授权：当用户与 Agent 对话时，Gemini 针对 /auth/authorize 发起 OAuth 流程。应用程序通过 /auth/token 签发已签名的 JWT 令牌，并将该会话映射到客户的订单 ID。执行：Starlette 中间件提取订单 ID。Neo4jADKExecutor 获取租户特定的数据库凭据，安全连接至其图数据库并执行查询。

:rocket: 部署与托管

本应用程序已容器化，旨在部署于 Google Cloud Run。敏感凭据必须存储在 Google Secret Manager 中，并在运行时挂载到容器内。

创建所需密钥：在 Secret Manager 中存储敏感变量（如 INTERNAL_SECRET_KEY 和 TRACKING_NEO4J_PASS）。gcloud secrets create TRACKING_NEO4J_PASS --data-file=path/to/password.txt

部署至 Cloud Run（将密钥映射为环境变量）

gcloud run deploy neo4j-adk-agent \
  --image gcr.io/YOUR_PROJECT_ID/neo4j-adk-agent \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars="SERVICE_URL=https://...,TRACKING_NEO4J_URI=neo4j+s://...,GEMINI_MODEL=gemini-2.5-pro" \
  --set-secrets="TRACKING_NEO4J_PASS=TRACKING_NEO4J_PASS:latest,INTERNAL_SECRET_KEY=INTERNAL_SECRET_KEY:latest"

配置 Pub/Sub 推送订阅：在 GCP 控制台中，为您的 Marketplace 主题创建推送订阅，并将端点 URL 指向 https://YOUR_CLOUD_RUN_URL/pubsub。

:gear: 先决条件与环境设置

确保您的 Google Cloud 项目中已配置以下内容

1. 启用 GCP API

Cloud Run API：用于托管 Starlette 应用程序。Vertex AI API：允许 ADK Agent 调用 Gemini。Secret Manager API：安全存储和检索敏感配置数据。Cloud Commerce Partner Procurement API：用于批准 Marketplace 购买并管理权益。

2. IAM 权限（针对 Cloud Run 服务账户）

Vertex AI User、Commerce Partner Editor（或用于访问采购 API 的等效权限）、Pub/Sub Subscriber、Secret Manager Secret Accessor

3. 环境变量

`SERVICE_URL`: 您的 Cloud Run 应用的公共基础 URL，流量由此路由。`PROVIDER_URL`: 在 GCP Agent Card 中配置的逻辑受众标识符（例如 https://neo4j.com.cn），仅用于 DCR 期间的 JWT 验证。`MARKETPLACE_PROVIDER_ID`: 您的 Google Cloud 合作伙伴 ID（用于批准计费）。`INTERNAL_SECRET_KEY`: 用于签署自定义 OAuth JWT 访问令牌的安全随机字符串。`TRACKING_NEO4J_URI`: 用于计费、token 跟踪和存储租户路由凭据的内部 Neo4j 实例 URI。`TRACKING_NEO4J_USER`: 跟踪数据库用户名。`TRACKING_NEO4J_PASS`: 跟踪数据库密码。`GEMINI_MODEL`: LLM 模型字符串（例如 gemini-2.5-pro）。`TRACK_TOKEN_USAGE`: 布尔字符串（True/False），用于开启或关闭 token 计费/限制逻辑。

:open_file_folder: 项目结构

├── main.py                  # Uvicorn entry point, Starlette app assembly, and Root 301 Redirect
├── requirements.txt         # Python dependencies
├── Dockerfile               # Production-ready container definition
├── architecture.png         # System architecture diagram
└── app/
    ├── api/
    │   ├── auth_routes.py   # DCR and Custom OAuth 2.0 endpoints
    │   ├── marketplace.py   # Pub/Sub listeners, API approvals, and HTML form handlers
    │   └── middleware.py    # JWT validation interceptor
    ├── core/
    │   ├── config.py        # Environment variables, Agent Card definition, and Base64 Icons
    │   └── context.py       # ContextVars for multi-tenant state management
    ├── services/
    │   ├── agent_executor.py # Core ADK execution, dynamic DB routing, and Guardrails
    │   ├── custom_tools.py  # Custom Neo4j Python functions
    │   └── token_manager.py # Graph-backed OAuth, Billing, and User State engine
    └── templates/           # Jinja2 HTML templates
        ├── authorize.html   # Custom OAuth consent screen
        ├── setup.html       # Customer DB configuration form
        └── success.html     # Setup completion confirmation

参考文档

ADK 代理 • 代理开发工具 (Agent Development Kit)

A2A 协议 • A2A Protocol

Gemini Enterprise & Agents • Gemini for Google Workspace / Enterprise

© . This site is unofficial and not affiliated with Neo4j, Inc.