SfSkills Domains Docs GitHub

Home / agentforce / rag-patterns-in-salesforce

rag-patterns-in-salesforce

Grounding Agentforce agents with retrieved knowledge using Data Cloud vector search: RAG pipeline design, vector search index configuration, chunking and embedding strategy, and how retrieved context flows through the Einstein Trust Layer into prompts. NOT for the Query API, Data Cloud access tokens, or Easy vs Advanced index mechanics — use agentforce/data-cloud-vector-search-dev. NOT for structured DMO retrievers, sharing enforcement at retrieval time and citations — use agentforce/data-cloud-grounding-for-agentforce.

Open the skill folder on GitHub

RAG Patterns in Salesforce

This skill activates when an Agentforce agent or a Prompt Builder template needs to retrieve and incorporate content from a knowledge source at inference time using Data Cloud search. It covers the full RAG pipeline: ingesting source content into Data Cloud, configuring search indexes (vector or hybrid), choosing chunking and embedding settings, connecting a retriever to a prompt template or an Einstein Data Library, and how the Einstein Trust Layer treats retrieved content.

Correction (2026-10-03): earlier versions of this skill described a "Grounding record" on a subagent with top_k and a {!topic.product} filter, and a {!grounding.chunks} merge field. None of these appear in the Generative AI guide or the Data Cloud guide. The documented model is: a search index creates a default retriever, custom retrievers are built in Einstein Studio, and a retriever is added to a prompt template from the Resource picker; for agents, an Einstein Data Library creates the index, retriever, prompt template, and Answer Questions with Knowledge action.

Before Starting

Gather this context before working on anything in this domain:

Questions to Ask Before Configuring

Each question traces to a gotcha in references/gotchas.md.

QuestionWhy it mattersWhat a good answer addsWhat proper configuration adds over just doing it
"What is the content: Knowledge HTML, PDFs, transcripts, or DMO text?"Passage extraction uses HTML structure, PDF chunking depends on encoding, and tables can't be chunked (Gotcha 1)A chunking strategy per sourceChunks follow the document's real sections
"Which languages is the content in?"Max tokens default to 512, and non-Latin text can exceed it, so text drops out of the embedding (Gotcha 2)A max-token setting and embedding model per languageJapanese or Chinese content is fully embedded
"Which fields will narrow results (product, region, category)?"Retriever filters only use fields defined as filter fields on the index, up to 10 conditions (Gotcha 3)Filter fields designed into the indexProduct-scoped answers without a second index
"How many search indexes already exist in this Data Cloud instance?"The limit is 10 search indexes per instance (Gotcha 4)An index budget across teamsThe next team is not blocked by a forgotten test index
"How will the configuration reach production?"Change sets and Metadata API deployments don't include the retriever or search index (Gotcha 5)Data kit or rebuild steps for the target orgTemplates deploy into an org where their retriever exists
"Does any content need customer-managed key encryption?"Search indexes don't support encryption with customer-managed keys (Gotcha 6)A decision on which content may be indexedCompliance is checked before indexing, not after

Core Concepts

1. Search Index (Vector or Hybrid)

A search index "stores chunked and vectorized data that can be searched and retrieved from other applications." It lives in a data space and is associated with a DMO. Creating one makes a chunk DMO and an index DMO. Use vector search for semantic matches and hybrid search when queries include exact terms such as product codes.

SettingWhat the guides say
Chunking strategySemantic-based passage extraction (HTML headings, lists, and bold subheadings are passage boundaries), window-based passage extraction, conversation-based (audio and video transcripts), prepend fields (for example, Title on each Knowledge chunk)
Max tokens"In Data Cloud, the max token limit is set to 512 by default." Use a lower limit for non-Latin languages
Embedding modelE5-Large V2, Multilingual E5-Large, Whisper-Large-V3. Easy Setup defaults: passage extraction, E5-Large V2, hybrid search. UNVERIFIED (2026-10-03): the earlier claim that custom embedding models can be registered through Model Builder
Chunk overlapUNVERIFIED (2026-10-03): the earlier "10 to 20% overlap" guidance was not found in the Data Cloud guide, which documents no overlap setting
Pre-filter fieldsUp to 10 fields; text values up to 1,024 characters

2. Retrievers

"When a search index is created in Data Cloud, a default retriever is created automatically. You can't customize a default retriever." Custom retrievers are built in Einstein Studio: pick the data space, DMO, and index; add up to 10 filter conditions (only on the index's filter fields); choose output fields and the maximum number of results. Each save creates a new version, and "Only one version of a retriever can be active."

In a prompt template, add the retriever from the Resource field and tune it in the Configuration panel: Search Text (limited to 255 characters, globals, and prompt inputs; it can't use related lists, Flow, or Apex), Output Fields, and Number of Results. Retrieved data appears in the preview resolution as JSON.

Terminology. Agent topics were renamed subagents in April 2026, with no change to functionality. This skill leads with subagent in prose, and keeps topic in metadata names, merge fields such as {!topic.…}, and search keywords, because those did not change.

3. Einstein Data Library (Agents)

A data library "automates several configuration steps across Data Cloud and Prompt Builder," creating data streams, a search index, and a retriever. The Answer Questions with Knowledge action answers from the library. A library uses Knowledge or file uploads, not both, and neither the data space nor the source can be changed later. Each feature uses one data library at a time. For Knowledge, choose identifying and content fields, optionally restrict to public articles or data categories, and turn on Show sources for citations.

4. Einstein Trust Layer and Retrieved Content

Grounding uses only data the running user can access. For prompt templates, pattern-based masking scans all prompt text, including retrieved chunks; field-based masking covers only record merge fields and related lists. For agents, masking is disabled. Audit data records the hydrated prompt, masked prompt, and retrieved data. UNVERIFIED (2026-10-03): the earlier claim that the Trust Layer can restrict which indexes an agent may query through org-level grounding policies.

Common Patterns

Pattern 1: Knowledge Grounding for a Service Agent With a Data Library

When to use: A service agent must answer from Salesforce Knowledge with citations.

How it works:

  1. In Einstein Data Library setup, create a library in the right data space (it can't be changed later).
  2. Choose Knowledge, select identifying fields (title, summary) and content fields (resolution steps), and filter by data categories if the base is large.
  3. Turn on Show sources and set the Knowledge domain URL for citations.
  4. Save; data streams, the search index, and the retriever are created. Assign the library to the agent in Agent Builder (Knowledge tab).
  5. Test in the agent preview with real questions and check that sources point at the right articles.

Why not the alternative: Without retrieval the agent relies on training data, which does not reflect org-specific content.

Pattern 2: Filtered Retrieval by Product Line

When to use: One index holds documents for several products, and answers must stay within one.

How it works:

  1. Add Product_Line__c as a filter field when creating the search index (advanced setup).
  2. In Einstein Studio, create a custom retriever with a condition Product_Line__c equals CRM (up to 10 conditions; All Conditions Are Met or Any Condition Is Met), output fields, and number of results. Activate it.
  3. Use one retriever per product, or a dynamic retriever where a standard template supports one. UNVERIFIED (2026-10-03): passing a runtime value from the conversation into a retriever filter was not found in a fetched source.

Why not the alternative: Semantic similarity alone mixes products that share vocabulary.

Pattern 3: Prompt Template With a Retriever Resource

When to use: A template must combine CRM fields and retrieved passages.

How it works:

  1. In Prompt Builder, insert record merge fields for the context, then select Resource > Einstein Search > the DMO > the retriever.
  2. In the Configuration panel, build the Search Text from prompt inputs (for example account name: Input.Account.Name), pick output fields such as Chunk, and set the number of results.
  3. Put instructions after the context block and tell the model to answer only from the retrieved passages.
  4. Preview and read the retriever's JSON output in the resolution.

Why not the alternative: Unbounded results crowd out the record context the template also needs.

Decision Guidance

SituationRecommended ApproachReason
Agent answers from Knowledge or uploaded filesEinstein Data LibraryCreates index, retriever, template, and action with defaults
Source is HTML Knowledge with clear headingsSemantic-based passage extraction, keep the HTMLHeadings and lists become passage boundaries
Queries include product codes or exact termsHybrid search indexCombines vector similarity with keyword precision
Multi-product content in one indexFilter fields on the index plus custom retrieversFilters apply only to fields the index defines
Non-Latin contentMax tokens below 512, Multilingual E5-LargePunctuation-based token estimates can exceed the embedding limit
Deploying to another orgData kit for the search index configuration, then create the retriever before deploying templatesChange sets and Metadata API don't carry retrievers or indexes
  1. Answer the Questions table: content types and languages, filter fields, index budget, deployment path, and encryption constraints.
  2. Choose the path: an Einstein Data Library for agents, or a search index (Easy or Advanced setup) plus a custom retriever for prompt templates.
  3. Configure chunking (strategy, max tokens, prepend fields), the embedding model, and filter fields; record the choices in the decision record.
  4. Build and activate the retriever, add it to the prompt template or library, and preview with representative questions; read the retrieved JSON.
  5. Run python3 scripts/check_rag_patterns_in_salesforce.py --manifest-dir <project> to catch retriever search-text limits, number-of-results budgets, and leftover merge fields from older guidance.
  6. Plan deployment: data kit for the index configuration, retriever recreated in the target org before templates deploy (references/metadata-examples.md), and a test as each persona.

Review Checklist

Run through these before marking RAG grounding work complete:

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

  1. Stripping HTML removes the structure the chunker uses: Correction (2026-10-03): earlier versions said to strip HTML from Knowledge bodies before indexing. Semantic-based passage extraction "uses the semantic meaning inherent in HTML tags to chunk a document into passages," and passage extraction "work[s] best for HTML files."
  2. Metadata Filters Are Pre-Filters, Not Post-Filters: Filter fields are selected for pre-filtering on the index (up to 10). A filter that matches nothing leaves no candidates. UNVERIFIED (2026-10-03): the earlier advice to prefer LIKE over exact match; check the supported operators in the Search Index Reference.
  3. Masking does not clean retrieved chunks for agents: Data masking is disabled for agents. For prompt templates, pattern-based masking scans retrieved text for its listed data types only.
  4. Index refresh follows the data stream: UNVERIFIED (2026-10-03): the earlier statement that new data streams default to scheduled batch refresh and that continuous mode must be configured was not found in a fetched source. Test how soon a newly published article becomes retrievable.
  5. Number of results counts against the prompt: Each retrieved chunk is added to the prompt. With max tokens at 512, ten results can add roughly 5,000 tokens before any other context.

Output Artifacts

ArtifactDescription
Search index configurationChunking strategy, max tokens, embedding model, search type, filter fields; deployable via data kit
RetrieverDefault or custom retriever with filters, output fields, number of results, and active version
Decision recordChunking, max tokens, embedding model, filters, number of results, and residency rationale
Prompt template or data libraryThe consumer of the retriever, with preview evidence
Agent preview test resultsMinimum 5 representative queries with retrieved passages or sources

Dependencies

Package files