Create a Custom Retriever in Salesforce Agentforce

A support team often keeps several PDFs in one Agentforce Data Library: a product guide, an internal policy document, and a troubleshooting handbook. That setup works well at first, until a prompt needs answers from only one document.

I ran into this exact requirement while setting up an Agentforce assistant for a Service Cloud team. The team wanted the assistant to answer policy questions only from its approved “Support Escalation Policy” PDF, not from every document in the library.

A custom retriever solves that problem by searching a selected Data Cloud search index and returning only the content you choose.

In this tutorial, I will show you how to create a custom retriever in Salesforce Agentforce, connect it to a search index, and use it inside an Agentforce Prompt Template.

What Is a Salesforce Custom Retriever?

A custom retriever is a Data Cloud resource that finds relevant content from a configured search index and sends that content into an AI prompt.

In simple terms, a custom retriever works like a focused search assistant:

1. You upload or bring content into Agentforce Data Library.
2. Salesforce breaks the document into smaller content sections, called chunks.
3. Salesforce creates a search index for those chunks.
4. Your custom retriever searches the index.
5. Your Prompt Template receives only the matching content before it generates an answer.

This design uses Retrieval-Augmented Generation (RAG). RAG means the AI first retrieves relevant company content and then uses that content to prepare its response.

It helps your Agentforce solution produce more grounded answers instead of relying only on general model knowledge.

For example, imagine that your Service Cloud team has uploaded these three PDFs to one data library:

• Product Setup Guide.pdf
• Support Escalation Policy.pdf
• Customer Refund Process.pdf

You may want a prompt template that answers escalation questions from only Support Escalation Policy.pdf. You should not let it mix refund rules or setup instructions into that response.

That is where a custom retriever becomes useful.

Pro Tip: In my experience, teams get better Agentforce results when they separate documents by business purpose. If a PDF covers a different audience, policy, or department, I create a dedicated retriever for it instead of relying on one broad retriever.

Before You Create a Custom Retriever in Salesforce

This tutorial uses a practical Service Cloud example. A support team handles around 500 cases every month and wants Agentforce to answer internal questions about escalation rules.

The team has already created an Agentforce Data Library and uploaded three PDF documents. We will create a custom retriever that uses only the search index for the Support Escalation Policy.pdf document.

You need the following before you start:

• Access to Data Cloud in your Salesforce org
• Access to Agentforce and Prompt Builder
• Permission to create or manage Search Indexes
• Permission to create Retrievers
• A ready Agentforce Data Library
• At least one uploaded PDF that Salesforce has successfully processed
• A user license, profile, or permission set that includes the required Data Cloud and Einstein permissions

If you have not created a library yet, start with this guide on how to create and configure an Agentforce Data Library. You can also learn how to assign a Data Library to an Agentforce agent when you want to use the same knowledge source in an agent topic.

A profile controls a user’s baseline permissions in Salesforce. A permission set adds extra permissions without changing the user’s profile. For this setup, use permission sets when possible because they make access easier to review and remove later.

How Salesforce Handles PDF Content

Before creating the retriever, it helps to understand what Salesforce does after you upload a PDF.

Salesforce does not send the complete PDF into a prompt every time someone asks a question. Instead, Agentforce and Data Cloud process the content in stages:

1. The system reads the document.
2. It divides the content into smaller pieces called chunks.
3. It converts the chunks into searchable representations.
4. It stores the searchable content in a search index.
5. A retriever searches the index based on the user’s question.
6. The prompt template receives the most relevant chunks.

A search index is a Data Cloud structure that makes your document content searchable. It allows semantic search, which means Salesforce can look for the meaning behind a question instead of matching only exact keywords.

For example, a support rep might ask:

“When should I send a customer issue to Level 2 support?”

Even if the PDF uses the phrase “Tier 2 escalation criteria,” the custom retriever can still locate the correct policy section because it searches for related meaning.

Create a Custom Retriever in Salesforce Agentforce

In the steps below, we will understand how to create the custom retriever in Salesforce and use it with a prompt template in Salesforce.

1. Create a Search Index in Data Cloud

To build a custom retriever, you first need a search index that points to the correct document data.

When you create a file-based Agentforce Data Library, Salesforce may create and reuse supporting search assets automatically.

However, you still need to inspect the available index and confirm that it contains the document content you plan to retrieve.

• Click the App Launcher.
• Search for and open Data Cloud.
• Open the Data Cloud app.

If you are new to the product, review this introduction to Salesforce Data Cloud before continuing. Data Cloud stores and prepares information for segmentation, analytics, and AI use cases such as Agentforce grounding.

• In Data Cloud, open the Search Indexes tab.
• Review the existing search indexes.
• Look for the index related to your Data Library or file-based content.
• Open the index record to confirm its status.

For a file-based data library, Salesforce often creates a search index that stores the PDF chunks. The exact name can vary by org, library setup, and release.

Do not rely only on the name. Open the index and verify the linked Data Model Object and fields.

A Data Model Object, or DMO, is a Data Cloud object that stores harmonized data. In this scenario, the DMO stores document-level information and chunk-level text that Salesforce can search.

Open the relevant search index and confirm that the most recent run completed successfully.

Look for a status such as:

• Completed
• Active
• Ready
• Successful

If the index shows a failure, fix that issue before you create a retriever. A retriever cannot return useful content if the index has not processed the PDF.

Also confirm that the document upload finished successfully in the Agentforce Data Library. If Salesforce cannot extract text from a PDF, the file may appear in the library but return no useful chunks during retrieval.

2. Create a Dedicated Index When Needed

If all three PDFs share one file-based library and one common index, you have two choices:

• Use a retriever filter that limits results to the target PDF.
• Create separate libraries or source structures when you need strict document separation.

For this example, we want to use only the Support Escalation Policy.pdf content. If your search index contains all three PDFs, configure a filter in the retriever by using a document name, source identifier, category, or metadata field.

The best filter field depends on your Data Cloud schema. Common options include:

• File name
• Document title
• Source record ID
• Category
• Knowledge area
• Product name
• Department
• Document type

If you plan this architecture from the beginning, add clear metadata values to every document. For example:

This approach gives you clean filters and makes the solution easier to maintain as your document library grows.

3. Create a Salesforce Custom Retriever

Now that your search index is ready, create a custom retriever that returns content from the escalation-policy PDF only.

• In Salesforce, open Agentforce Studio.
• Open AI Models or Einstein Studio, depending on your org’s navigation.
• Select the Retrievers tab.
• Click New Retriever.

Salesforce may show different names based on your release, but the key destination is the retriever setup area in Data Cloud AI Models.

3.1 Select Individual Retriever

Select Individual Retriever and click Next.

An individual retriever searches one selected index. This is the correct option when you want a focused prompt grounded by one policy document or one business content area.

You may also see an ensemble retriever option in some orgs. An ensemble retriever combines or ranks results from multiple retrievers. Do not use it for this scenario because the goal is strict focus on one PDF.

3.2 Select the Data Space, DMO, and Search Index

On the search configuration screen, select:

• Data Space: Choose the Data Cloud data space that contains the document data.
• Data Model Object: Choose the DMO connected to your PDF chunk data.
• Search Index: Choose the search index that processed the Agentforce Data Library content.

Click Next after confirming these values.

This selection tells the retriever where it should search. If you pick the wrong DMO or index, Salesforce may return empty results or content from an unrelated data source.

3.4 Filter Results to One PDF

This step is the most important part of the setup.

Enable Filter Documents to Return. Then configure a condition that limits retrieval to the Support Escalation Policy.pdf document.

Your actual field names will depend on your data library schema. Use the field that uniquely identifies the uploaded PDF.

A typical condition looks like this:

If your organization uses document metadata, use a business-friendly filter instead:

A metadata filter is usually more reliable than a file name filter. File names can change when someone uploads a replacement document. A stable metadata value such as Escalation Policy keeps your retriever working after future updates.

If you configure more than one filter, select the appropriate logic:

• All Conditions Are Met uses AND logic. Salesforce returns content only when every condition matches.
• Any Condition Is Met uses OR logic. Salesforce returns content when at least one condition matches.

For this tutorial, use All Conditions Are Met if you filter by both Department and Document Type.

Example:

This setup blocks other support documents from entering the prompt.

3.4 Choose Fields to Return

Next, select the fields that the custom retriever should return to Prompt Builder.

At minimum, return the field that contains the chunk text. It may have a name similar to:

• Chunk
• Chunk Text
• Content
• Text
• Content Body

You can also return supporting fields that help the prompt understand the source:

• Document Title
• File Name
• Source URL
• Section Title
• Category

For a simple policy-answering prompt, I recommend returning:

• Chunk Text
• Document Title
• Section Title, if available

The chunk text contains the actual content that Agentforce uses to answer the question. The title and section fields help you test whether the retriever selected the right source.

3.5 Configure Result Limits

Set the maximum number of results carefully.

For this support-policy example, start with three to five results. This gives the prompt enough policy context without sending too much unrelated text.

A practical starting point is:

More results do not always create a better answer. Sending too many chunks can make the prompt less focused and increase the chance that it combines separate policy sections incorrectly.

3.6 Name and Save the Retriever

Use a name that clearly shows the document and business purpose.

For example:

Support_Escalation_Policy_Retriever

Use a description such as:

Retrieves approved escalation policy content from the Support Escalation Policy PDF for Agentforce Prompt Templates.

Click Save.

After Salesforce creates the retriever, open it and copy its Retriever ID if your prompt template or test process requires it. Treat this ID like configuration data and document it in your implementation notes.

4. Use the Custom Retriever in Prompt Templates

Now you can add the custom retriever to an Agentforce Prompt Template.

A Prompt Template is a reusable instruction set that tells the AI what to generate. It can include Salesforce record fields, Flow outputs, related records, and retrieved knowledge.

For this example, we will create a prompt that answers support escalation questions using only the filtered policy PDF.

4.1 Open Prompt Builder

1. From Setup, search for Prompt Builder.
2. Open Prompt Builder.
3. Click New Prompt Template.
4. Choose the template type that matches your use case.

For a reusable question-answering experience, choose the prompt type your org uses for knowledge-based answers. If you are building a record-driven response, select Field Generation or another relevant template type.

You can also review how to create prompt templates in Salesforce Agentforce before configuring your first one.

4.2 Name the Prompt Template

Use a clear naming standard. For example:

Answer_Support_Escalation_Policy

Add a useful description:

Answers support escalation questions using the approved Support Escalation Policy custom retriever.

A consistent naming convention matters when your org grows from a few prompts to dozens of prompts, actions, and agents.

4.3 Add Prompt Instructions

In the prompt workspace, write direct instructions that force the model to rely on the retrieved policy content.

Use a prompt like this:

You are a support operations assistant.

Answer the user's question using only the retrieved Support Escalation Policy content.

If the retrieved content does not contain the answer, say:
"I could not find this information in the Support Escalation Policy."

Do not invent escalation timelines, approval levels, or customer commitments.

Give the answer in clear bullet points when the policy includes multiple steps.

These instructions reduce hallucinations. A hallucination happens when an AI model gives information that sounds confident but does not come from the approved data or the user’s input.

4.4 Insert the Custom Retriever Resource

In the Prompt Builder workspace:

• Click Insert Resource.
• Choose the search or Einstein Search resource category.
• Select your Data Cloud DMO.
• Select Support_Escalation_Policy_Retriever.
• Set the Search Text to the user’s question or query variable.
• Select the retriever output field, such as Chunk Text.
• Insert the resource into the prompt.

Your resulting prompt can follow this pattern:

User question:
{!$Input:Question}

Approved escalation policy content:
{!$EinsteinSearch:Support_Escalation_Policy_Retriever.results}

Instructions:
Answer only from the approved escalation policy content.
If the answer is missing, state that the policy does not provide the information.

The resource token format may differ slightly in your org. Salesforce creates the correct merge syntax when you insert the retriever through Prompt Builder, so avoid typing the resource manually.

4.5 Test the Prompt in Preview

Use the Preview panel to test the prompt before you activate it.

Try questions that should return an answer:

• “When should a support case move to Level 2?”
• “Who approves a Severity 1 escalation?”
• “What response time applies to a critical customer issue?”

Then test questions that the PDF should not answer:

• “What is the refund approval process?”
• “How do I configure the product integration?”
• “What discount should a sales rep offer?”

The prompt should answer the escalation questions and clearly say that the policy does not contain answers for refund or product setup questions.

This testing proves that the retriever filter works. If it answers a refund question with refund-policy details, your filter or search index selection is too broad.

You can also learn how to assign a prompt template to an Agentforce agent after you finish testing.

4.6 Save and Activate the Template

After successful testing:

1. Save the prompt template.
2. Create a new version if your org requires versioning.
3. Activate the approved version.
4. Assign the template to the appropriate Agentforce action, topic, or process.

If you plan to trigger the prompt through automation, see how to invoke flows from a Prompt Template and how to call an Agentforce Prompt Template from Salesforce Flow.

Things to Keep in Mind

• Use stable document metadata: Filter by a metadata value such as Document Type or Department instead of only the PDF file name. Stable metadata prevents broken retrievers when someone replaces or renames a file.
• Return only useful fields: Always include the chunk text, then add source fields only when they help testing or citations. Returning unnecessary fields can make prompts harder to maintain.
• Keep result counts small: Start with three to five results. Too many chunks can dilute the prompt and create less precise answers.
• Test no-answer questions: Ask questions that the target PDF does not cover. Your prompt must state that the content is unavailable instead of inventing an answer.
• Review access and governance: Give Data Cloud, Agentforce, and Prompt Builder access through controlled permission sets. Limit who can upload, replace, or manage policy documents.
• Use clear retriever names: Name retrievers by business purpose and content source, such as Support_Escalation_Policy_Retriever. Avoid generic names like Retriever1 because they become difficult to manage later.

Frequently Asked Questions

Conclusion

A custom retriever gives your Agentforce Prompt Template a focused, approved knowledge source by connecting a Data Cloud search index to one specific PDF or document category.

Start with a single policy document, apply a reliable metadata filter, test both valid and invalid questions, and expand only after you confirm that the prompt stays grounded.

You May Also Like

• Set up Data Cloud in Salesforce Agentforce
• Understand prompts and Prompt Builder in Salesforce Agentforce
• Learn Agentforce best practices for agents
• Configure Agentforce for customer service
• Understand the Einstein Trust Layer in Salesforce Agentforce

Shubham

Shubham is a Certified Salesforce Developer with technical skills for Building applications using custom objects, approval processes, validation rules, Salesforce flows, and UI customization. He is proficient in writing Apex classes, triggers, controllers, Apex Batches, and bulk load APIs. I am also familiar with Visualforce Pages and Lightning Web Components. Read more about me.