Relationship Research Agent (RRA)

An AI-powered Salesforce application that automatically discovers and visualizes business relationships by analyzing CRM data and web sources.

Overview

Relationship Research Agent (RRA) enhances your Salesforce CRM by automatically discovering and mapping business relationships between people and organizations. Using AI-powered analysis, RRA:

• Discovers hidden connections between accounts, contacts, leads, and opportunities
• Visualizes relationship networks with interactive D3.js-based graphs
• Enriches CRM data by combining internal records with web research
• Provides context with citations and sources for every relationship discovered

Features

• 🔍 Automated Relationship Discovery - Analyzes CRM data and web sources to find connections
• 📊 Interactive Graph Visualization - D3.js-powered relationship network display
• 🤖 AI-Powered Entity Matching - Uses Einstein Prompt Builder for intelligent entity resolution
• ⚡ Async Processing - Background job processing for large data sets
• 📱 Lightning Experience Ready - Custom components for Account, Contact, Lead, and Opportunity pages

Prerequisites

Before installing RRA, ensure your Salesforce org has:

• Salesforce Edition: Enterprise, Unlimited, or Developer Edition
• API Version: 62.0 or higher
• Agentforce: Enabled
• Einstein Prompt Builder: GenAI Prompt Template support
• Agentforce Data Library: Web Retriever configured
• Platform Cache: Org cache allocated
• Lightning Experience: Enabled
• My Domain: Deployed

Installation

1. Clone the Repository

   git clone https://github.com/SalesforceLabs/RelationshipResearchAgent.git
   cd RelationshipResearchAgent

2. (Optional) Install Dev Dependencies

   Only needed if you plan to run tests, linters, or formatters.

   nvm use  # optional: if using nvm
   npm install

3. Authenticate to Salesforce

   sf org login web --set-default

   Or authenticate to a specific instance:

   sf org login web --instance-url https://your-domain.my.salesforce.com --alias rra-org

4. Configure Salesforce Org Prerequisites

   a. Enable Agentforce

   • Navigate to Setup > Agentforce
   • Enable Agentforce for your org

   b. Create Web Retriever (Agentforce Data Library)

   • Navigate to Setup > Agentforce Data Library
   • Click New
   • Configure:
     • Data Type: Web
     • Turn on Web Search: Enabled
     • Web Source: Search the Web
   • Save

   c. Disable Data Masking

   • Navigate to Setup > Einstein Trust Layer
   • Select Large Language Model Data Masking
   • Turn Off

   Note: Data masking will hinder entity name recognition and relationship extraction.

5. Deploy All Metadata to Salesforce

   sf project deploy start --test-level NoTestRun

   Or deploy using the manifest:

   sf project deploy start --manifest manifest/package.xml

6. Activate Custom Record Pages

   • Navigate to Setup > Lightning App Builder
   • Open each custom record page:
     • RRA_Account_Record_Page
     • RRA_Contact_Record_Page
     • RRA_Lead_Record_Page
     • RRA_Opportunity_Record_Page
   • Click Activation
   • Set as org default or assign to specific apps/profiles
   • Save

   Alternatively, you can add the RRA component to your own custom record pages.

7. Verify Prompt Templates

   Navigate to Setup > Prompt Builder and verify all templates are active:

   • RRA_CommonNameVariants
   • RRA_EntityMatcher
   • RRA_EntitiesFromCRM
   • RRA_ConsolidateInsights
   • RRA_AppendRelationships
   • RRA_DeepWebResearch_Discovery
   • RRA_DeepWebResearch_Refinement
   • RRA_ConsolidateCrossSourceInsights

   Known Issue: Templates may deploy as inactive. Manually activate if needed, and ensure output mode is set to JSON.

Usage

Discovering Relationships

1. Navigate to an Account, Contact, Lead, or Opportunity record
2. The RRA component appears on the Lightning page
3. Click Start Research
4. Processing occurs in the background (async)
5. View the interactive relationship graph when complete

Understanding the Visualization

• Nodes: Represent people and organizations
• Edges: Show relationships with predicates (e.g., "founded", "CEO of")
• Colors: Indicate entity types

Interacting with the Graph

Click on entities to:

• Create Record: Create a new CRM record (Account, Contact, or Lead) from an unmatched entity
• Link Record: Associate an entity with an existing CRM record
• View Record: Navigate to the linked CRM record
• View Citations: See source URLs and references for discovered relationships

Monitoring Job Status

RRA processes relationships asynchronously in the background. To monitor job progress:

1. Navigate to Setup > Environments > Jobs > Apex Jobs
2. Look for jobs with class name RRAClientAsync
3. Check the Status column (Queued, Processing, Completed, Failed)
4. Refresh the record page to see updated results when the job completes

Architecture

Core Components

Apex Classes:

• RRAClient / RRAClientAsync - Main API entry points
• CrmRelationshipInsightsProcessor - Orchestrates relationship discovery
• DeepWebResearchEngine - Web research via Agentforce
• EntityMatcher - AI-powered entity resolution
• EntityMatcherDataCloud - Data Cloud subroutines for entity resolution
• CrmDatabaseSelectors - Database queries for CRM data
• RelationshipInsightsPersister - Persists discovered relationships

Lightning Web Components:

• rraComponent - Main component for Lightning pages
• rraGraph - D3.js-based graph visualization
• rraConfirmMatchModal - Entity matching UI
• rraCreateRecordModal - Record creation dialog

Custom Objects:

• RRARelationships__c - Stores relationship data as JSON
• RRALogs__c - Stores critical log and telemetry data

GenAI Prompt Templates:

• 7 specialized prompts for entity extraction, matching, consolidation, and web research

Data Cloud components

Data Cloud components are optional and requires manual building of pipelines per the reference documentation. See DataCloud Readme

With Data Cloud components enabled, Entity Resolution can be executed against data coming from external datasources (such as leads or SSOT), and can be customized to work with custom text fields, not just default name fields.

RRA will fail gracefully if DataCloud components are not available, e.g. will perform CRM matching instead.

Configure Logging and Telemetry

Currently, logging and telemetry data are handled through NebulaLogger. See Logging readme RRA functionality does not require NebulaLogger and will continue working without it. Additionally, critical telemetry data is also collected in RRALogs__c custom table.

Customizing Research

RRA uses AI prompt templates to extract and prioritize business relationships. You can customize which relationship types are prioritized based on your use case (sales, investment research, partnerships, academic research, etc.).

For example, a sales team might prioritize employment relationships over board positions, while investment researchers might prioritize ownership and funding relationships.

See Prompt Customization Guide for detailed instructions on modifying relationship priorities directly in Salesforce PromptBuilder.

Development

Running Tests

Run all Apex tests:

sf apex run test --synchronous --code-coverage --result-format human

Run specific test class:

sf apex run test --synchronous --tests EntityMatcherTest

View Debug Logs

Get the most recent log:

sf apex log get --number 1

Filter to USER_DEBUG only:

sf apex log get --number 1 | grep 'USER_DEBUG'

Remove ANSI color codes with ansi2txt:

sf apex log get --number 1 | ansi2txt > test.log

Code Quality

Format code with Prettier:

npm run prettier

Verify formatting:

npm run prettier:verify

Run linter:

npm run lint

Deploying Specific Components

Deploy a single Apex class:

sf project deploy start --metadata ApexClass:EntityMatcher

Deploy multiple components:

sf project deploy start --metadata ApexClass:EntityMatcher --metadata ApexClass:EntityMatcherTest

Updating SLDS Icons

The graph component uses Salesforce Lightning Design System icons via SVG sprite files.

To update icons:

# Install SLDS
npm install @salesforce-ux/design-system --save-dev

# Copy sprite files to static resources
cp node_modules/@salesforce-ux/design-system/assets/icons/standard-sprite/svg/symbols.svg force-app/main/default/staticresources/symbols.svg
cp node_modules/@salesforce-ux/design-system/assets/icons/utility-sprite/svg/symbols.svg force-app/main/default/staticresources/symbolsutil.svg

Known Issues

Prompt Builder Templates

• Templates may deploy as inactive even when exported as active
• Output mode may reset from JSON
• Workaround: Manually activate templates and set output mode to JSON in Prompt Builder
  • Go to Setup -> Prompt Builder
  • For every template whose name starts with RRA:
    • Open the template
    • In Template Settings, Response set Format selector to JSON.
    • Save and activate.
  • Note that the versions of the prompts will not be 1, this is normal. The template files may contain many previous versions. Salesforce will activate the latest one.

Advanced permissions required

Currently, all users of RRA must have permissions to execute Prompt Templates, and are assumed to have the same, advanced level of permissions. Non-admin and non-privileged users will be supported in subsequent versions of RRA.

Debugging

Show debug controls on webpage

• Add ?c__rraDebug=1 to the url of the web page. Refresh the page if necessary.

Investigate research failures

If you click Start Research on UI component and get an error:

• Go to Setup -> Apex Jobs; use timestamps to locate the job started by RRAClientAsync.
• If status details read something like No generations returned from the prompt template., this means a template has not been activated.
• To investigate further, get Apex logs: sf apex log get --number 1 | grep 'USER_DEBUG'
• With Nebula, you can also look for errors in Nebula logs.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Security

To report security vulnerabilities, see SECURITY.md.

License

Copyright (c) 2025 Salesforce, Inc.

Licensed under the Apache License, Version 2.0. See LICENSE.txt for details.

Support

• GitHub Issues: Report bugs and request features
• GitHub Discussions: Ask questions and share ideas

---

Built with ❤️ by Salesforce