首页 / 文章 / 实用指南：在 GCP 上利用 Neo4j 构建能做出更优决策的 AI 智能体

neo4j gcp gemini ai-agent graphrag agents

实用指南：在 GCP 上利用 Neo4j 构建能做出更优决策的 AI 智能体

《实用笔记：利用Neo4j在GCP上构建能做出更好决策的AI智能体》的操作指南：为采用该架构的团队提供合同模板、检查清单以及可直接插入的代码片段。

3107 词

本指南将逐步构建从原材料到可运行系统的完整流程，主题为：使用 Neo4j 在 GCP 上构建能够做出更优决策的 AI 智能体。重点在于可操作的步骤、明确的检查点，以及可直接放入代码仓库的代码，无需猜测其用途。在概览阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测其中的隐藏状态。配置信息应与应用程序代码分开存放。环境文件、密钥存储和功能标志应集中管理，以便操作人员无需查看整个图结构即可进行审计。

实现可导航、可解释的 AI 的图结构知识层

在处理“图结构知识层”阶段时，首先需记录下合约的详细内容：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。在成本较高的操作之后设置检查点。当操作员重新尝试某个节点时，恢复流程不应再次调用相同的大型语言模型。

构建更精准的检索系统：从向量到GraphRAG

在处理“构建更精确的检索”阶段时，首先需明确相关约定：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合预期。相比冗长的脚本，应优先选择小型且可测试的单元。当某个步骤出现故障时，故障原因应能指向单一责任模块，而非复杂的流程链。在调整提示词之前，先使用固定的问题集来评估召回率。仅仅更换提示词很难改善较差的检索效果。

MATCH (contract:Contract)
SEARCH contract IN (
  VECTOR INDEX contracts FOR $embedding
  WHERE contract.status = 'active'
  AND contract.jurisdiction = $jurisdiction
  LIMIT 5
)
MATCH (contract)-[:SIGNED_BY]->(party:Party),
MATCH (contract)-[:SOURCED_FROM]->(doc:Document)
MATCH clauses = (contract)-[:RELATED_TO*1..2]-(:Clause)
RETURN contract, party, doc, collect(clauses)

Aura Agents：值得信赖的低代码GraphRAG解决方案

在处理 Aura Agents Trusted Low-Code 阶段时，首先需明确合同条款：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。将此阶段视为输入与验证后输出之间的契约。为相关组件命名，定义成功检测标准，并杜绝无声的半完成状态。在调整提示词之前，先使用固定的问题集测试召回率。仅仅更换提示词很难解决检索效果不佳的问题。在处理 Aura Agents Trusted Low-Code 阶段时，首先需明确合同条款：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。

语义层：帮助智能体选择合适的数据与资源

将语义层视为可度量的界面，能最有效地辅助智能体开展工作。在扩大范围之前，先记录一份最佳操作案例、一个故障实例以及回滚说明。同时记录正常流程与恢复流程。重试机制、人工干预环节以及死信处理都是产品本身的组成部分，而非后续需要补充的内容。保持图结构的状态简洁且类型明确。嵌套的数据块会掩盖某个节点编写了哪个字段的信息，还会在流程中断后导致无法继续执行。

图内存：构建有状态且可解释的智能体

将图内存构建的“有状态阶段”视为可测量的对象来处理，效果最佳。在扩大范围之前，先记录一份理想的运行日志、一个故障案例以及回滚说明。优先选择小型且可测试的单元，而非庞大的脚本。当某个步骤出现故障时，故障应能指向单一的责任主体，而非复杂的流程链。保持图状态的扁平化与类型化。嵌套的数据结构会掩盖哪个节点修改了哪个字段的信息，还会在进程中断后导致无法继续执行。

使用 neo4j-agent-memory 实现图内存

将分阶段实现的图内存视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想状态下的完整数据、一个故障案例以及回滚说明。应将这一阶段视为输入与已验证输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的半完成状态。要保持图状态的简洁性与类型化。嵌套的数据结构会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致无法继续处理。将分阶段实现的图内存视为可度量的对象时，其效果最佳。在扩大范围之前，需记录一份理想状态下的完整数据、一个故障案例以及回滚说明。应将配置信息置于应用程序代码之外。环境文件、密钥存储和功能开关应集中存放于一个位置，以便操作人员无需查看整个图结构即可进行审计。

from neo4j_agent_memory import MemoryClient, MemorySettings
from neo4j_agent_memory.integrations.google_adk import Neo4jMemoryService

async with MemoryClient(settings) as client:
    # Create memory service
    memory_service = Neo4jMemoryService(
        memory_client=client, user_id="user-123",
        include_entities=True, include_preferences=True,
    )

    # Store a conversation session
    session = {
        "id": "session-1",
        "messages": [
            {"role": "user", "content": "I always want to use Gemini Flash for speed and cost reasons."},
            {"role": "assistant", "content": "Noted!"},
        ]
    }
    await memory_service.add_session_to_memory(session)

    # Search across all memory types
    results = await memory_service.search_memories(
        query="user preferences", limit=10,
    )

    for entry in results:
        print(f"[{entry.memory_type}] {entry.content}")

作为托管服务的图内存

若将图内存作为处理阶段，在修改代码之前需明确输入参数、该步骤的负责人以及终止条件。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的功能。对于涉及资金支出或修改生产数据的操作路径，必须设置人工审批环节。编译时的逻辑连接并不等同于业务功能的完整性。

上下文图：提升智能体的决策能力

在“上下文图优化智能体”阶段，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任点，而非复杂的流程链。对于涉及资金支出或修改生产数据的操作，需经过人工审批。编译时的连接方式并不等同于业务功能的完整性。

// Full chain behind a single bq.customer_lookup call
MATCH (tc:ToolCall {name: 'bq.customer_lookup', id: $call_id})
      <-[:CALLED]-(r:ReasoningStep)<-[:TRIGGERED]-(t:Turn),
      (r)-[:LED_TO]->(d:Decision)-[:CITES]->(e:Evidence)
      -[:RESOLVES_TO]->(c:Customer)
RETURN t.question, c.name, c.jurisdiction,
       d.outcome, d.decided_at, d.reviewed_by

// Reversed decisions in the last quarter that went through this tool
MATCH (d:Decision:Reversed)<-[:LED_TO]-(:ReasoningStep)
      -[:CALLED]->(:ToolCall {name: 'bq.customer_lookup'}),
      (d)-[:CITES]->(e:Evidence)
WHERE d.reversed_at > datetime() - duration('P90D')
RETURN e.source_type, count(DISTINCT d) AS reversal_count
ORDER BY reversal_count DESC

将Neo4j与谷歌的智能体基础设施集成

在将 Neo4j 与 Google 集成的阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功检测标准，并杜绝无声的半完成状态。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接配置并不等同于业务上的完整性。在将 Neo4j 与 Google 集成的阶段，修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于操作人员可审计的位置，无需阅读代码即可查看。

整个图结构。

官方 Neo4j MCP 服务器

在处理官方 Neo4j MCP 服务器阶段时，首先需记录下契约内容：所需的输入参数、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及死信处理都是产品功能的一部分，而非后续需要补充的内容。需为每次调用记录工具名称、参数哈希值、延迟时间以及最终结果。没有这些记录，调试代理将陷入无止境的循环，耗费大量时间。

Google ADK

在处理 Google ADK 阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。建议使用小型、可测试的单元，而非冗长的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的 LLM 接口。

Gemini Enterprise

在处理 Gemini Enterprise 阶段时，首先需写下合同条款：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。将此阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功检测标准，并杜绝无声的半完成状态。每次调用时都要记录请求 ID、模型 ID 以及延迟时间。没有这些记录，间歇性的服务提供商错误就会被视为应用程序的故障。在处理 Gemini Enterprise 阶段时，首先需写下合同条款：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。

立即开始构建，或在 Google Cloud Next ‘26 上现场观看

“立即开始构建”或相关阶段若被视为可度量的对象，效果会更好。在扩大范围之前，需记录一份最佳操作案例、一个故障案例以及回滚说明。同时记录正常流程与恢复流程。重试机制、人工审核环节以及死信处理都是产品的一部分，而非后续需要补充的功能。保持图表状态简洁且类型明确。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，且在中断后会导致无法继续处理。

运营检查清单

“运营检查清单”阶段若被视为可度量的对象，效果会更好。在扩大范围之前，需记录一份最佳操作案例、一个故障案例以及回滚说明。

在功能结果旁记录处理时间以及令牌或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外账单。

保持图结构扁平且具有类型约束。嵌套的数据块会隐藏是哪个节点修改了哪个字段，还会在中断后导致无法继续执行。

只要预算允许，就在持续集成过程中使用测试用例而非真实的付费 API 来对关键路径进行压力测试。

将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个图结构即可进行审计。

保持图结构扁平且具有类型约束。嵌套的数据块会隐藏是哪个节点修改了哪个字段，还会在中断后导致无法继续执行。

在升级技术栈之前，先冻结现有版本，为关键路径生成标准化的执行记录，并确认回滚步骤。共享环境需要设置速率限制、租户验证机制，以及明确的密钥轮换负责人。与其追求花哨的一次性演示，不如注重扎实的可靠性。

关于49b808f05f56的批量处理说明：不要将提供者密钥放入代码仓库，为每个会话设置令牌使用上限，并将转录内容存储在评估用示例文件旁边，以便后续更换模型时仍能保持可比性。

强化措施的第0阶段若被视为可量化的评估标准，则效果最佳。在扩大范围之前，先记录一份理想的转录样本、一个失败案例以及回滚说明。将此阶段视为输入与经过验证的输出之间的契约，为相关文件命名，明确成功标准，杜绝无声的半完成状态。

强化措施细节0/779：针对此说明需测量处理耗时、错误类型以及令牌使用量，然后依据固定的评估标准而非主观判断来决定是否保留该变更。

在强化措施的第一阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。

强化措施细节 1/779：针对此措施需统计耗时、错误类型以及令牌使用情况，然后依据固定的评估标准而非主观判断来决定是否保留该变更。

在处理强化措施的第2阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。相比冗长的脚本，更应采用小型且可测试的单元。当某个步骤失败时，故障应能指向单一的责任模块，而非复杂的流程链。

强化措施细节2/779：需测量该步骤的运行时间、错误类型以及代币消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。

将强化措施的第3阶段视为可量化的目标面处理效果最佳。在扩大范围之前，先记录一份理想的运行示例、一个失败案例以及回滚说明。在功能结果旁同时记录时间消耗及代币或查询成本。提前明确成本情况，可避免在从演示环境过渡到共享环境时出现意外支出。

强化措施细节 3/779：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。

在强化措施的第4阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新执行该步骤，而无需猜测隐藏状态。需同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品的一部分，而非后续需要补充的内容。

强化措施细节 4/779：为该记录测量运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个别案例来决定是否保留该变更。

在处理强化措施的第5阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许部分完成的情况。

强化措施细节5/779：需测量该步骤的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。

将强化措施的第6阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份标准操作示例、一个失败案例以及回滚说明。应将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放于一处，以便操作人员无需查看全部代码结构即可进行审计。

强化措施细节 6/779：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。

对于强化措施的第7阶段，在修改代码之前需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比复杂的脚本，更应采用小型且可测试的单元。当某一步骤失败时，故障原因应能指向具体的责任方，而非整个混乱的流程。

强化措施细节 7/779：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。

在处理强化建议的第8阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合初始要求。

在功能结果旁记录执行时间以及令牌或查询成本。提前了解这些成本信息，可避免在系统从演示环境过渡到共享环境时出现意外费用。

强化建议的第8项/共779项：需测量该建议对应的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非主观判断来决定是否保留该修改。

将强化建议的第9阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一个理想运行案例、一个失败案例以及回滚说明。

应同时记录正常流程和故障恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。

强化措施细节9/779：记录该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。

在强化措施的第10阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入参数与验证后输出结果之间的契约，为相关成果命名、定义成功检测标准，并拒绝默许部分完成的情况。

强化措施细节10/779：记录该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。

在处理强化措施的第11阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合要求。应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放于一个位置，这样操作人员无需查看整个系统结构即可进行审计。

强化措施细节11/779：需测量该措施的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该修改。

将强化措施的第12阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份标准操作流程、一个失败案例以及回滚说明。相比复杂的脚本，更应采用小型且可测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个具体责任模块，而非整个混乱的流程链。

强化措施细节 12/779：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。

对于强化措施的第0阶段，在修改代码之前需明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。同时需将正常流程与异常恢复流程一并记录下来。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续需要补充的内容。

强化措施细节 0/798：测量该任务的执行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。

在处理强化措施的第一阶段时，首先写下相关契约：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合约定。将这一阶段视为输入与验证后输出之间的契约。为相关产物命名，明确成功判定标准，杜绝默许部分完成的情况。

强化措施细节 1/798：需记录该步骤的耗时、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该修改。

全部文章发送简报