Google Gemini Enterprise — A2A 直接服务

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

此应用程序作为一个独立的微服务运行，利用原生的 Google Workspace 身份验证提供安全的多租户数据库访问，无需进行自定义密码管理。

架构概述

Neo4j Gemini A2A Architecture

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

此服务充当 Google 基础设施与您的 Neo4j 数据库之间的安全智能桥梁。

它完全以无服务器 (Serverless) 方式运行在 Google Cloud Run 上。用户首先访问托管的 /setup 页面，安全输入其目标 Neo4j 凭据，这些凭据将与用户的 Google Workspace 电子邮件地址进行映射。

当用户在 Gemini 中与 Agent 聊天时，Gemini 会提示他们“使用 Google 登录”。应用程序的自定义 ASGI 中间件会拦截该请求，验证 Google OAuth 令牌，提取用户的电子邮件，检索其数据库凭据，并使用 Google ADK 安全地针对图数据库执行自然语言查询。

:sparkles: 核心功能

无缝 Google 身份验证： 将身份管理完全卸载给 Google Workspace。用户通过标准的 OAuth 2.0 进行身份验证，这意味着无需维护自定义密码或自定义 JWT 基础设施。基于电子邮件的多租户： 根据已验证用户的电子邮件地址，动态将自然语言查询路由到不同的目标 Neo4j 数据库。智能图推理（计算下推）： 利用 ADK 的 BuiltInPlanner 强制 Agent 在执行查询前读取数据库模式并构建高效的单次往返 Cypher 查询，从而消除昂贵的 LLM “幻觉循环”。成本控制与限流： 使用 ADK 回调拦截每次交互的精确 LLM 令牌使用量，并从存储在内部跟踪数据库中的用户每日分配额度中扣除。断路器： 实现严格的 RunConfig 防护机制 (max_llm_calls)，以防止语法错误导致的无限重试，确保快速失败并保持低延迟。

:arrows_counterclockwise: 生命周期分解

配置： 用户访问 /setup 门户，输入其 Workspace 电子邮件，并提供目标 Neo4j URI 和凭据。应用程序将此映射安全地保存在内部跟踪数据库中。注册： 管理员通过自动生成的 Agent 卡片 (/.well-known/agent.json) 将 Agent 添加到 Gemini Enterprise UI，并提供标准的 Google Cloud OAuth 凭据。授权： 当用户与 Agent 交互时，Gemini 会启动原生的 Google OAuth 流程。Gemini 接收 Google 访问令牌并将其转发给应用程序。验证： Starlette OAuthValidationMiddleware 拦截请求，ping Google userinfo 端点以验证令牌，并将用户的电子邮件提取到会话上下文中。执行： AgentExecutor 从跟踪数据库中检索用户特定的数据库凭据，制定计划，安全地连接到其图数据库，并将查询结果流式传输回 Gemini UI。

:rocket: 部署与托管

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

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

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

gcloud run deploy neo4j-a2a-agent \
  --source . \
  --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"

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

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

1. 启用 GCP API

Cloud Run API： 用于托管 Starlette 应用程序。 Vertex AI API： 允许 ADK Agent 调用 Gemini。 Secret Manager API： 用于安全地存储和检索敏感配置数据。

2. Google Cloud OAuth 设置

您必须在 GCP 控制台中创建 OAuth 2.0 客户端 ID（Web 应用程序）。确保添加以下授权的重定向 URI，以便 Gemini 完成登录流程： • https://vertexaisearch.cloud.google.com/oauth-redirect • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

3. 环境变量

`SERVICE_URL`：流量路由到的 Cloud Run 应用的实际公共基础 URL。 `TRACKING_NEO4J_URI`：用于计费、令牌跟踪和存储租户路由凭据的内部 Neo4j 实例的 URI。 `TRACKING_NEO4J_USER`：跟踪数据库用户名。 `TRACKING_NEO4J_PASS`：跟踪数据库密码。 `GEMINI_MODEL`：LLM 模型字符串（例如 gemini-2.5-pro）。 `TRACK_TOKEN_USAGE`：布尔字符串 (True/False)，用于切换令牌计费/限制逻辑。

: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/
    │   ├── marketplace.py   # Setup URL handling
    │   └── middleware.py    # validating Google Access Tokens
    ├── 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.