Google Gemini Enterprise — A2A MCP 封装器

概述

本仓库展示了 Neo4j 图数据库与 Google Gemini Enterprise 之间基于 Agent-to-Agent (A2A) 协议的生产级集成。此架构采用了去耦合的微服务方案。

  1. MCP 工具服务：独立部署在 Google Cloud Run 上的官方 Neo4j 模型上下文协议 (MCP) 服务器。

  2. ADK 代理服务：一个封装在 A2A 协议中的定制化 Google 代理开发工具 (ADK) 应用程序，同样托管在 Cloud Run 上。它具有自定义的 Starlette/FastAPI ASGI 中间件层，可直接根据 Google 的身份服务器安全验证终端用户的 OAuth 2.0 访问令牌；此外还配有一个专用的 Neo4j 令牌跟踪数据库，用于监控和限制每个用户的每日 LLM 使用量（可选功能）。

核心功能

  1. 去耦合架构：将 Neo4j MCP 二进制文件与 Python 推理代理分离，使两个 Cloud Run 服务能够独立扩展。

  2. 原生图查询：通过 HTTP 使用远程 Neo4j MCP 服务器，自主探索图模式并执行 Cypher 查询。

  3. 自定义 Python 工具：使用专门的硬编码业务逻辑（例如 get_investments）扩展 MCP 功能。

  4. 安全令牌验证：纯 ASGI 中间件实时拦截并验证 Gemini Enterprise OAuth 2.0 访问令牌，提取用户的电子邮件地址。

  5. 精细化令牌管理（可选）：使用 ADK 回调来计算每个请求的精确计费令牌，并在辅助 Neo4j 数据库中跟踪每个用户的每日使用限额。

架构流程

  1. 发现：Gemini Enterprise 发送 /.well-known/agent.json 请求。该服务返回详细说明代理技能并确认需要身份验证的 AgentCard（清单）。

  2. 身份验证：Gemini 提示用户通过 Google OAuth 2.0 登录。

  3. 执行：Gemini 发送包含用户提示词和 Authorization: Bearer <TOKEN> 请求头的 POST / 请求。

  4. 验证：自定义 Python 中间件拦截该请求，通过 Google 的 tokeninfo 端点验证令牌，提取用户邮箱，并检查其在跟踪数据库中的每日令牌限额。

  5. 推理：Google ADK LlmAgent 确定是使用 Neo4j MCP 模式工具还是自定义投资工具来制定响应。

  6. 跟踪：响应生成后，ADK 回调会捕获确切的令牌使用量并更新跟踪数据库中的用户记录。

先决条件

在部署之前，请确保具备以下条件：

  • 已启用结算功能的 Google Cloud 项目。

  • 已安装并完成身份验证的 Google Cloud CLI (gcloud)。

  • 具有凭据的 Neo4j 数据库（AuraDB 或自托管）。

  • 已启用的 Google Cloud API：

    • Cloud Run API (run.googleapis.com)

    • Secret Manager API (secretmanager.googleapis.com)

第 1 步：部署独立的 Neo4j MCP 服务器

将官方 Neo4j MCP 镜像部署为 Cloud Run 后端服务。我们将主数据库凭据注入此处，以便它能安全地连接到您的图数据库。详细指南请见此处。

gcloud run deploy <INSTANCE_NAME> \
- service-account=mcp-server-sa@<PROJECT_ID>.iam.gserviceaccount.com \
- no-allow-unauthenticated \
- region=<LOCATION> \
- image=docker.io/mcp/neo4j:latest \
- port=80 \
- set-env-vars="NEO4J_MCP_TRANSPORT=http,NEO4J_MCP_HTTP_PORT=80,NEO4J_MCP_HTTP_HOST=0.0.0.0" \
- set-secrets="NEO4J_URI=<URI_SECRET_NAME>:latest,NEO4J_DATABASE=<DATABASE_SECRET_NAME>:latest" \
- min-instances=0 \
- max-instances=1

第 2 步：安全配置 (Secret Manager)

我们使用 Google Cloud Secret Manager 存储凭据。与跟踪相关的凭据是可选的。如果您希望跟踪令牌使用情况，请将环境变量 TRACK_TOKEN_USAGE 设置为 True。

    echo -n "your-tracking-db-uri" | gcloud secrets create TRACKING_NEO4J_URI --data-file=-
    echo -n "tracking-db-username" | gcloud secrets create TRACKING_NEO4J_USER --data-file=-
    echo -n "tracking-db-password" | gcloud secrets create TRACKING_NEO4J_PASS --data-file=-
    echo -n "daily token limit value" | gcloud secrets create DAILY_TOKEN_LIMIT --data-file=-
    echo -n "your-google-api-key" | gcloud secrets create GOOGLE_API_KEY --data-file=-
    echo -n "https://your-mcp-cloud-run-url/mcp" | gcloud secrets create MCP_URL --data-file=-
    echo -n "https://your-expected-adk-cloud-run-url" | gcloud secrets create SERVICE_URL --data-file=-
    echo -n "neo4j db username" | gcloud secrets create NEO4J_USERNAME --data-file=-
    echo -n "neo4j db password" | gcloud secrets create NEO4J_PASSWORD --data-file=-

设置 3：授予 Cloud Run 读取密钥的权限

# Grants the Secret Accessor role to the default Compute Engine service account
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUM=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

gcloud projects add-iam-policy-binding $PROJECT_ID
  --member="serviceAccount:${PROJECT_NUM}-compute@developer.gserviceaccount.com"
  --role="roles/secretmanager.secretAccessor"

第 4 步：部署 ADK AgentDeployment

将容器部署到 Cloud Run。我们必须使用 --allow-unauthenticated，以便服务能够被公开访问，同时完全依赖我们的 Python 中间件来进行授权。

gcloud run deploy neo4j-a2a-service
  --source .
  --region us-central1
  --allow-unauthenticated
  --set-secrets="NEO4J_URI=NEO4J_URI:latest,NEO4J_USERNAME=NEO4J_USERNAME:latest,NEO4J_PASSWORD=NEO4J_PASSWORD:latest,NEO4J_DATABASE=NEO4J_DATABASE:latest,GOOGLE_API_KEY=GOOGLE_API_KEY:latest,SERVICE_URL=SERVICE_URL:latest"

第 3 步：Gemini Enterprise 配置

在 Gemini Enterprise 门户中注册已部署的代理。

  1. 导航到 Gemini Enterprise 中的添加代理配置页面。

  2. 提供代理卡（Agent Card），可从（例如：https://neo4j-a2a-service-xxxx-uc.a.run.app/.well-known/agent.card）检索。

  3. 将身份验证类型设置为 OAuth 2.0。

  4. 使用您的 GCP 凭据（API 和服务 → 凭据 → OAuth 2.0 客户端 ID）填写 OAuth 详细信息。

  5. 确保将以下重定向 URI 添加到您的 Google Cloud OAuth 客户端 ID 配置中：

Gemini Enterprise 用户界面。

  1. 在 Gemini Enterprise 聊天机器人 UI 中提出与您的数据库相关的问题（例如：“@Neo4j-Secured 系统中有多少个用户？”）。

  2. Gemini 将提示您登录并通过 OAuth 授权访问您的电子邮件地址。

  3. 一旦经过身份验证，ADK 代理将处理请求、调用远程 MCP/自定义工具，并将答案流式传输回 UI。

  4. （可选）如果用户超过了 Neo4j 跟踪数据库中设置的每日令牌限额，代理将优雅地返回一条“达到限额”的消息。

参考文档

Neo4j • Neo4j & MCP

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.