Agentforce Data Library: grounding an agent on your knowledge and PDFs without hand-building RAG

You want the obvious thing: an Agentforce agent that answers from your knowledge — the support articles, the product PDFs, the policy docs — instead of from whatever the model absorbed in training. So you go looking for how, and the advice splits into two camps that seem to describe different products. One camp says “just add a Data Library, it’s a few clicks.” The other walks you through ingesting unstructured data into a data lake object, configuring a search index with a chunking strategy, building a retriever, and wiring it into a prompt template. Which one is real?

Both. They’re the same machinery seen from two ends. A Data Library is Agentforce’s one-click front door to retrieval-augmented generation, and the thing it quietly builds behind that single screen is exactly the search index and retriever the second camp assembles by hand. Understanding that — that a Data Library is a Data 360 RAG pipeline with the knobs hidden and set to defaults — is what tells you when the fast path is genuinely enough and when you’ve outgrown it and need to open the hood. This post is what a Data Library actually provisions, how it grounds an answer, where the credits and the failure modes hide, and the exact line where you graduate to a hand-built pipeline.

What a Data Library actually is (and what it builds for you)

An Agentforce Data Library is a Setup feature — you’ll find it by searching “Agentforce Data Library” in Setup, or you can create one inline in Agentforce Builder while configuring an agent’s data sources. You point it at a source, and Salesforce’s own documentation is refreshingly blunt about what happens next: creating a Data Library “automatically sets up all the components needed for a working RAG-powered solution,” using default settings, and you can optionally “use the created components as a basis for further configuration.”

Those components are not trivial, and they are not new. Under the Data Library, Salesforce provisions a data stream, the data lake and data model objects with their mapping, a vector data store, a Data 360 search index, a retriever, a prompt template, and the agent action — the entire retrieval stack. The content you point it at is ingested, chunked, embedded as vectors, stored in Data 360’s vector store, and retrieved by semantic search at runtime.

A Data Library is not an alternative to Data Cloud. It is Data Cloud — the same search index and retriever you’d build by hand, generated for you with the tuning decisions already made. The convenience is real; the machinery underneath is identical.

That last point catches teams off guard, because a Data Library is often sold as the “you don’t need Data Cloud” option. You do — Data 360 has to be provisioned in the org, and a Data Library consumes Data 360 credits. What you don’t need is to configure Data 360 by hand. The distinction matters for both cost and mental model, and it’s the same “what’s free vs. what bills” question we mapped in does Agentforce need Data Cloud: the free Data 360 provisioning that ships with Enterprise Edition and up is enough to start a Data Library, but production knowledge bases keep metering against it.

The four things a Data Library can ground on

When you create a Data Library, you choose a data source, and there are four types. Knowing which is which prevents the most common early mistake — building a file library when you meant to index Knowledge, or vice versa.

• Salesforce Knowledge — indexes your Knowledge articles (records and fields), and you can scope it with Data Category filters so the agent only retrieves from the right slice of the knowledge base.
• Uploaded files — a file-based library for PDFs and documents you upload directly, for content that doesn’t live in Knowledge. The documented per-file limits sit around 4 MB for text/HTML and 100 MB for PDFs; confirm the current caps and accepted file types in the live docs before you plan a bulk load, because they’re the kind of number that moves between releases.
• Web Search — added in the Summer ‘25 wave, this grounds the agent on public web results, pulling title, URL, snippet, and publish date. Note this is search-engine results, not the same thing as crawling and indexing your own website — that’s a hand-built flow, covered below.
• Custom Retriever — you point the library at a retriever you built yourself over a Data 360 search index. This is the escape hatch that makes the fast path and the hand-built path compose rather than compete.

How an answer actually gets grounded

The runtime wiring is worth getting exact, because the terms get conflated. In Agentforce Builder, the relevant topic is General FAQ, and the action under it is Answer Questions with Knowledge. That action is backed by the Data Library’s auto-created retriever. When a user asks something, the action runs a semantic search against the indexed chunks, retrieves the most relevant passages, and grounds the model’s answer on them — retrieval-augmented generation, end to end. The action respects permissions and sharing settings, so a user can’t retrieve a chunk from an article they couldn’t otherwise see.

The mechanics are the same three-step pipeline we broke down in Intelligent Context — extraction, chunking, retrieval — the difference being that a Data Library makes those decisions for you rather than exposing them. The chunks come from Data 360’s default chunking; the vectors come from an out-of-the-box embedding model; the retriever returns a default set of results. You didn’t choose any of it, which is the whole point of the fast path and, later, the whole reason you might leave it.

The setup, start to finish

For a file-based library grounding an agent on a folder of PDFs, the sequence is short:

1. Confirm Data 360 is provisioned and you have the admin and Data Cloud permissions. The free Enterprise-and-up provisioning is enough to begin.
2. In Setup → Agentforce Data Library → New, name the library and choose the File Upload source.
3. Upload the files, respecting the documented size limits, and save.
4. Salesforce auto-provisions the stack — data stream, DLO/DMO and mapping, chunking, search index, and retriever — with default settings.
5. Wait for the library to reach a ready state. It moves through an indexing lifecycle (broadly: not started → indexing → ready), and this is the step people skip. Attach a library that’s still indexing and the agent retrieves nothing — a “why is my agent ignoring the docs” bug that’s really just an unfinished index.
6. Attach the library to the agent in Agentforce Builder, so the Answer Questions with Knowledge action under General FAQ uses its retriever.
7. When content changes, the index refreshes on a cadence; for Knowledge-sourced libraries the sync runs periodically rather than instantly, so freshly published articles take a little while to become retrievable.

That’s genuinely most of it. The reason RAG has a reputation for being hard is everything a Data Library is hiding from you — and for a competent knowledge-deflection agent, hiding it is the right call.

Where Data Libraries stop — and when to graduate

Here’s the honest boundary, because a fast path oversold is how teams end up fighting a black box three weeks before launch. A Data Library gives you defaults you cannot tune from the library screen: you don’t choose the chunking strategy or chunk and overlap size, you don’t pick the embedding model, you don’t configure hybrid search (blending vector and keyword retrieval), and you don’t set the retriever’s top-k or which fields it filters and returns. For a clean corpus of well-structured articles, those defaults are fine. For a messy one — scanned contracts, 90-page handbooks where the answer spans three sections, tables that extraction mangles — the default chunking is often exactly what puts the wrong passage in front of the model, fluently.

When that happens, you graduate to the hand-built path: ingest the content into an Unstructured Data Model Object, create a search index configuration where you explicitly set the chunking strategy, max-token size, and field selection, and build a retriever where you control filters, returned fields, top-k, and hybrid search. That’s the same pipeline our Intelligent Context walkthrough tunes on a small sample before publishing to millions of records, and grounding an agent on your own crawled website is a member of this family too — a manual search-index-and-retriever build, not the Web Search source type.

The good news is it’s an upgrade, not a rewrite. Build the custom retriever over your own search index, then feed it back into a Data Library through the Custom Retriever source type. You keep the Data Library’s clean wiring into the agent and swap only the retrieval brain underneath. So the decision rule is simple:

• Start with a Data Library. Get RAG working, see whether the default chunks answer real questions.
• Graduate to a hand-built search index + custom retriever when you can point at specific questions the defaults answer wrong, and you need control over chunking, hybrid search, or filtering to fix them.
• Compose the two by pointing a Data Library at your custom retriever, so the agent’s wiring never changes.

Don’t hand-build first. The number of hours teams spend tuning a chunking strategy for a corpus the defaults would have handled fine is not small.

The failure modes to expect

Four show up again and again, and none of them are subtle once you know to look:

• The index isn’t ready. The single most common “it doesn’t work” is a library attached before indexing finished. Wait for the ready state; if a library never leaves “not started,” the practical fix is usually to delete and recreate it.
• It works in the Playground but not in the running agent. Same data space, same objects, and retrieval returns results when you test the retriever directly but nothing at agent runtime. This is almost always the agent’s running-user (bot) context and permissions — the retriever runs as the agent user, and that user needs access to the data. It’s the same running-user identity trap that catches custom actions.
• The wrong chunk grounds the answer, invisibly. A Data Library gives you little visibility into which passage grounded a response, so a confidently wrong answer looks identical to a right one. This is where session tracing and observability earn their keep — retrieval quality is not something you can eyeball from the chat window.
• “Data Cloud is free” turns into a bill. Every ingested chunk and every retrieval meters Data 360 credits. The free provisioning covers a pilot; a production knowledge base grounding thousands of conversations a day is a standing line item. Forecast it the way you’d forecast any Data 360 consumption, and watch the Digital Wallet once it’s live.

What to actually do

If you’re grounding an agent on knowledge and you don’t yet have a specific, reproducible retrieval complaint, build a Data Library and move on — it’s the fastest path to a working, permission-respecting RAG agent, and the machinery underneath is the real thing, not a toy. Pick the source type deliberately (Knowledge with Data Category scoping for articles, File Upload for loose PDFs), wait for the index to reach ready before you attach it, and test with questions a real customer would ask, not the one whose answer sits in a single clean paragraph. Confirm the agent’s running user can actually see the data, or you’ll debug a permissions problem as a retrieval problem.

Then watch two things: the answers, and the meter. When you can name questions the defaults get wrong, graduate the retrieval to a hand-built search index and custom retriever and plug it back in — don’t start there. And price the whole thing as Data 360 consumption from day one, because the convenience of the fast path never made the credits free. Get that sequence right and you get the thing you actually wanted at the top: an agent that answers from your content, quickly, without a month of RAG plumbing you didn’t need to build.

Understanding the basics

Does the Agentforce Data Library require Data Cloud (Data 360)?

Yes. A Data Library is a convenience layer over Data 360, not a replacement for it — under the hood it provisions a Data 360 search index, a vector store, and a retriever, and it consumes Data 360 credits. What it saves you is the manual configuration of Data 360, not the platform itself. The free Data 360 provisioning that comes with Enterprise Edition and above is enough to start a Data Library, but a production knowledge base keeps metering credits against it.

What can an Agentforce Data Library ground an agent on?

Four source types: Salesforce Knowledge articles (with Data Category filtering), uploaded files like PDFs, Web Search over public web results (added in Summer ‘25), and a Custom Retriever you built yourself over a Data 360 search index. The Custom Retriever option is what lets you start on the automatic path and later swap in a hand-tuned retrieval pipeline without rewiring the agent.

When should I build a custom retriever instead of using a Data Library?

Use a Data Library until you can point at specific questions its default retrieval answers wrong. A Data Library doesn’t let you tune the chunking strategy, embedding model, hybrid search, or the retriever’s top-k and filters — so when a messy corpus retrieves the wrong passage, you graduate to a hand-built search index configuration and retriever over an Unstructured Data Model Object, where you control all of that. Then point the Data Library at that custom retriever so the agent’s wiring stays the same. Start automatic; graduate only when a real retrieval failure justifies it.

---

Standing up a knowledge agent and not sure whether a wrong answer is your grounding, your chunking, or the agent user’s permissions? Talk to us — getting agents grounded on the right content, at a cost you can defend, is exactly the work we do.