Salesforce Agentforce + Neo4j 集成

概述

Salesforce Agentforce 是 Salesforce 的企业级 AI 代理平台，由 Atlas Reasoning Engine (ARE) 驱动——这是一种 ReAct 风格的编排循环，能够进行规划、工具选择、观察结果并迭代以回答用户查询。

核心功能

  • Atlas Reasoning Engine (规划 → 行动 → 观察 → 决策循环)

  • 主题（语义路由层）+ 操作（工具执行层）

  • 原生 MCP 客户端（试点阶段：2025 年 7 月，Beta 功能：2025 年 10 月）

  • 外部服务操作 (External Service Actions) — 将任何 OpenAPI 3.0 规范导入为代理工具

  • Apex 操作 — 为复杂集成提供完整的类 Java 服务端代码

  • BYOM（自带模型）— 通过您的账户连接 Claude、GPT-4、Gemini

  • Einstein 信任层 — PII（个人身份信息）脱敏，与 LLM 提供商之间零数据留存

  • 代理 API — 从外部 Python/Java/REST 客户端调用代理

官方资源

扩展点

本节概述了使用 Neo4j 扩展 Salesforce Agentforce 功能的主要方法。下方的架构图作为基础蓝图，展示了从用户到数据库的标准请求流程，您可以利用三种集成路径中的任何一种进行自定义。

架构

┌─────────────────────────────────────────────────────────────────────────┐
│                         Salesforce Agentforce                           │
│                                                                         │
│ 1. User: "Provide me insights about the company Microsoft"              │
│ 2. Agent captures "Microsoft" and triggers Prompt Template action       │
│                                │                                        │
│                       ┌────────▼────────┐                               │
│                       │ Prompt Template │                               │
│                       └────────┬────────┘                               │
│                                │ 3. Describes intent & response format  │
│                                │ 4. Invokes Flow                        │
│                       ┌────────▼────────┐                               │
│                       │ Salesforce Flow │                               │
│                       └────────┬────────┘                               │
│                                │ 5. Calls Apex class                    │
│                       ┌────────▼────────┐                               │
│                       │   Salesforce    │                               │
│                       │    Bindings     │                               │
│                       └────────┬────────┘                               │
└────────────────────────────────┼────────────────────────────────────────┘
                                 │ HTTPS (Named Credential)
                                 ▼
                     ┌──────────────────────┐
                     │. Neo4j MCP Server    │
                     │. Neo4j HTTP QueryAPI │
                     │. Remote API bridge   │
                     └───────────┬──────────┘
                                 │
                                 ▼
                      ┌────────────────────┐
                      │   Neo4j Database   │
                      └────────────────────┘

设计考量

  1. 代理应保持指令简洁，并将额外工作委托给其他元素（如提示词模板 Prompt Templates）

  2. 为什么要使用提示词模板？

    • 基础与格式化：提示词模板有效地为 LLM 提供了基础信息。代理无需随意决定如何呈现来自 Neo4j 的原始数据，模板会明确定义最终响应的意图、结构（例如：项目符号、摘要）、角色和语气。

    • 减少幻觉：通过严格约束对检索数据的解释方式，最小化模型产生幻觉或遗漏关键数据点的风险。

    • 声明式控制：管理员无需触碰任何代码，即可动态迭代 LLM 的提示词和输出格式。

  3. 为什么要使用 Salesforce Flow 来包装 Apex？

    • 编排与解耦：Flow 作为声明式编排层，将业务逻辑（对 Neo4j 的 Apex 调用）与代理的提示词呈现逻辑分离开来。

    • 数据富集：在将数据返回给提示词模板之前，Flow 可以无缝地将 Neo4j 图数据库的响应与本地 Salesforce CRM 数据（例如：获取客户记录、过往商机）结合起来，为 LLM 提供统一的上下文。

    • 灵活性与复用性：如果需要更改错误处理、路由或其他逻辑，Salesforce 管理员无需开发者修改和部署新的 Apex 代码即可更新 Flow。

三种集成路径 — “Salesforce 绑定”的实现方式

  • 原生 MCP 客户端

  • 外部服务操作 (External Service Actions)

  • Apex 操作

路径 A：原生 MCP 客户端

⚠️ 本章节内容正在编写中

Agentforce 现在包含原生 MCP（模型上下文协议）客户端。注册任何 MCP 服务器（包括 Neo4j 的）后，它无需编写任何自定义代码即可作为代理工具使用。

⚠️ Salesforce 对自定义 MCP 服务器的支持目前处于 Beta 阶段，尚未公开发布（试点阶段：2025 年 7 月，Beta 阶段：2025 年 10 月，正式发布：2026 年 4 月）。

路径 B：外部服务操作 (External Service Actions)

部署一个自定义 REST 适配器，并将该适配器的 OpenAPI 规范导入到 Salesforce 外部服务中。零 Apex 代码 — 完全声明式。REST 适配器充当 Salesforce 和 Neo4j 查询 API 之间的桥梁，允许您通过 HTTP 请求针对 Neo4j 服务器执行 Cypher 语句。

我们提供了一个基于 nodejs 和 itty-router 的示例桥接服务器，它公开了一个供 Salesforce 发现的相关 openapi.json 模式端点。该服务器可以轻松部署到 Cloudflare Workers 等平台。

一旦桥接建立，所需的 Salesforce 配置包括将服务导入 Salesforce 外部服务（设置 → 集成 → 外部服务 → 新建）。新创建的操作随后即可在 Salesforce Flow 等工具中引用。

路径 C：Apex 操作

编写带有 @InvocableMethod 注解的 Apex 类。这些类将成为具有访问 Salesforce 平台功能（CRM 记录、流等）全部权限的代理操作。

@InvocableMethod(
    label='Get Neo4j Organization Insights'
    description='Queries Neo4j for strategic insights about an organization, including competitors, suppliers, and geographic presence.')
    public static List<Response> getInsights(List<Request> requests) {
    }

完整、可部署且经过测试的 Apex 代码位于 examples/track-c/apex 文件夹中。部署 Apex 类后，代码即可作为 Salesforce Flow 中的操作进行引用。

高级 UI 与图可视化 (LWC)

除了将 Neo4j 数据输入到 LLM 中，您还可以使用 Lightning Web Components (LWC) 在 Salesforce UI 中直接可视化图数据。通过复用相同的 Apex 类（在 @InvocableMethod 之外同时使用 @AuraEnabled 注解），您可以获取图数据并使用 JavaScript 可视化库（如 D3.js、vis.js 或 Cytoscape）进行渲染。

应用场景

  1. 丰富的 Agentforce 响应：在 Agentforce 聊天窗口中返回交互式 LWC，而不是纯文本摘要。

  2. 独立记录页面：将 Neo4j 知识图谱小部件直接嵌入标准的 Salesforce 客户或联系人记录页面，以显示局部连接。

一旦相应的 Apex 方法被标记为 @AuraEnabled(cacheable=true)，从 LWC 解析该方法即可如下运作

// Imperatively fetch fresh data from Neo4j through your Apex service
const rawData = await getInsights([{ recordId: this.recordId }]);
this.processNeo4jData(rawData);

Neo4j 图小部件的入门实现可以在 examples/lwc/neo4jGraphWidget 目录中找到（即将推出）。

代码示例

查看 examples/ 目录

文件 描述

examples/agent.yaml

定义代理的 YAML 脚本

examples/track-c/apex/

包含测试的 Apex 文件

examples/track-b/neo4j-bridge/index.ts

Neo4j 桥接服务器示例

Salesforce 配置

以下步骤提供了所有路径连接外部服务所需的基础设置。

1. 外部凭据 (External Credentials) — 设置 → 安全 → 外部凭据 → 新建

为 Neo4j 身份验证创建自定义外部凭据

Label: `demo_companies_neo4jlabs_auth` (or descriptive name)
Name: `demo_companies_neo4jlabs_auth`
Principal: Named Principal
Authentication Protocol: Basic Authentication

Create a Principal with parameters:
  - Parameter Name: "username" → Value: "companies"
  - Parameter Name: "password" → Value: "companies"

注意事项

  • 外部凭据允许命名凭据 (Named Credentials) 安全地管理身份验证，无需硬编码凭据

  • 应启用“生成授权头”选项，或通过自定义头进行处理

  • 对于使用传统设置的 HTTP 传输，请确保正确配置了自定义头

2. 命名凭据 (Named Credentials) — 设置 → 安全 → 命名凭据 → 新建

创建引用该外部凭据的命名凭据

Name: demo_companies_neo4jlabs_url (must match ENDPOINT constant in your Apex code)
URL: https://demo.neo4jlabs.com:7473
External Credential: demo_companies_neo4jlabs_auth (from Step 1)
Allow Merge Fields in HTTP Body: ☑ (enables dynamic Cypher parameters)
Allowed Namespaces for Callouts: Ensure your namespace (or 'None') is allowed

关键考量

  • 命名凭据名称必须与 Apex 代码中的 callout: 前缀匹配（例如：callout:demo_companies_neo4jlabs_url）

  • 这实现了集中式身份验证 — 在此处更新凭据而无需修改 Apex 代码

  • 授权头由命名凭据自动管理

3. 远程站点设置 (Remote Site Settings) — 设置 → 安全 → 远程站点设置

尽管命名凭据已针对特定 URL 绕过了远程站点设置

Remote Site Name: Neo4j Demo Companies
Remote Site URL: https://demo.neo4jlabs.com:7473
☑ Disable Protocol Security (if using non-HTTPS in dev environments only)

何时添加

  • 如果不将命名凭据用于其他集成

  • 如果其他 Salesforce 功能需要直接访问该端点

  • 确保此服务器的组织范围连通性

4. 权限 — 设置 → 用户/简档/权限集

授予用户访问 Neo4j 集成的权限

Permission Set: Create or select existing
Enable Permissions:
  → External Credential Principal Access:
    [Select] demo_companies_neo4jlabs_auth
  → Execute Named Credential:
    [Select] demo_companies_neo4jlabs_url
  → (If using Apex) Execute Apex Classes:
    [Select] Neo4jService, Neo4jAction

监控与故障排除

Setup → AgentForce → Agents → [Your Agent] → Debug Logs
# View ARE reasoning traces and action execution logs

Setup → Security → Named Credentials → [Your NC] → Test Connection
# Verify authentication is working

Setup → Integrations → External Services → [Your ES] → Test Operations
# Test individual API calls

问题与限制

截至 2026 年 3 月，AuraDB（Neo4j 的云服务）与 Salesforce 之间存在网络限制。直接从 Salesforce（通过 Apex 代码）发起的 HTTP 调用会被阻止，并导致 400 Bad Request 响应。一种中间变通方案是在它们之间放置一个代理（例如，使用 Cloudflare Workers）。这允许 Apex 的 HttpRequest 成功执行。

export default {
    async fetch(request, env) {
        // my Aura instance
        const neo4jUrl = "https://xxxxxxx.databases.neo4j.io/db/xxxxx/query/v2";

        // Clone the request but strip all Salesforce headers
        const newRequest = new Request(neo4jUrl, {
            method: request.method,
            body: await request.arrayBuffer(),
            headers: {
                "Content-Type": "application/json",
                "Accept": "application/json",

                // Pass through your Authorization header from SF
                "Authorization": request.headers.get("Authorization"),
                "User-Agent": "curl/7.68.0" // Mimic curl
            }
        });

     return fetch(newRequest);
    }
};

获取公司见解 — 实现

场景

行业研究代理 (Industry Research Agent) 查询 Neo4j 公司新闻知识图谱（25 万个实体），以提供：

  1. 公司概况（行业、地点、领导层）

  2. 语义新闻搜索（基于文章向量嵌入的相似度搜索）

  3. 组织关系映射

  4. 竞争对手、供应商和子公司

数据集

公司新闻知识图谱（演示访问）

NEO4J_URI      = "neo4j+s://demo.neo4jlabs.com:7687"
NEO4J_USERNAME = "companies"
NEO4J_PASSWORD = "companies"
NEO4J_DATABASE = "companies"

数据模型

(:Organization)-[:HAS_CEO]->(:Person)
(:Organization)-[:HAS_COMPETITOR|HAS_SUPPLIER|HAS_SUBSIDIARY]->(:Person)
(:Article)-[:MENTIONS]->(:Organization)

Cypher 查询

MATCH (org:Organization {name: "Neo4j"})
OPTIONAL MATCH (org)-[:HAS_CEO]->(ceo:Person)

// 1. Get Network (Competitors, Suppliers, Subsidiaries) with their CEOs as complete nodes
WITH org, ceo,
     [(org)-[:HAS_COMPETITOR]-(comp) | {organization: comp, ceo: [(comp)-[:HAS_CEO]->(c) | c][0]}] AS competitors,
     [(org)-[:HAS_SUPPLIER]->(supp) | {organization: supp, ceo: [(supp)-[:HAS_CEO]->(c) | c][0]}] AS suppliers,
     [(org)-[:HAS_SUBSIDIARY]->(sub) | {organization: sub, ceo: [(sub)-[:HAS_CEO]->(c) | c][0]}] AS subsidiaries

// 2. Fetch exactly 10 articles mentioning any entity in the network
CALL (org, competitors, suppliers, subsidiaries) {
    WITH [c IN competitors | c.organization] +
         [s IN suppliers | s.organization] +
         [sub IN subsidiaries | sub.organization] +
         [org] AS targets
    UNWIND targets AS target
    WITH DISTINCT target WHERE target IS NOT NULL
    MATCH (article:Article)-[:MENTIONS]->(target)
    RETURN DISTINCT article
    LIMIT 10
}

// 3. Return everything as complete nodes
RETURN
    org,
    ceo,
    competitors,
    suppliers,
    subsidiaries,
    collect(article) AS related_articles

资源

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