All articles

Agentforce

Why your Agentforce agent returns the wrong Knowledge article, or none

The article exists. You can find it in two seconds. The agent swears it has nothing, or cites the one article you didn't want. It worked in Prompt Builder, which is exactly why you can't see the bug. The retriever runs as the agent user, and that single fact explains most Knowledge grounding failures. Here is the order to check them in.

The article is right there. You searched Knowledge, found it in two seconds, read the exact paragraph that answers the customer. Then the agent tells the customer it doesn’t have that information, or worse, cites a different article that’s close enough to sound authoritative and wrong enough to matter.

And it worked in Prompt Builder. You tested the retriever, it returned the right passage, you shipped it. The agent in production does something else.

That gap has one cause more often than any other, and it is not the model and not the retriever tuning. The retriever runs as the agent user, and the agent user does not have the access you have. Before you touch chunk sizes, fusion rankers, or the prompt, check what the agent user is allowed to see, because that is where the article went.

The retriever runs as the agent user, not as you

Grounding on Salesforce Knowledge is retrieval, and retrieval respects sharing. A retriever performs semantic search and then filters the results by what the running user is permitted to read. In an agent conversation, the running user is the agent user, a specific user with its own profile, permission sets, and data category visibility.

Salesforce is explicit about the consequence. If the agent user lacks the required Knowledge object permissions or data category access, those articles are automatically removed during retrieval. Not flagged. Not logged as an error the customer or the agent sees. Removed, silently, before the model ever sees them.

The agent then answers from whatever survived the filter, which is how you get a confident citation of the wrong article: the right one was filtered out, and the second-best remained.

So the first move when an agent won’t surface an article is not to inspect the retriever. Log in as the agent user, or check its permissions directly, and confirm it can read that Knowledge article and the data categories it sits under. Nine times out of ten the fix is a permission set, not a tuning pass.

Why Prompt Builder hides exactly this bug

The reason this bug ships is that the tool you test in lies to you about access, through no fault of its own.

Salesforce notes that testing in Prompt Builder, Flows, or other system-level tools may run with elevated or administrative privileges, so the retriever returns articles the agent user would never be allowed to see. Your test passes because you, or the system context, can read everything. The agent fails because it can’t. Same retriever, same query, different identity, opposite result.

That trap is what makes Knowledge grounding feel non-deterministic, when it isn’t. Retrieval is deterministic against two different permission sets, and you have only been looking at one of them.

Any grounding test that matters has to run as the agent user. If your testing process verifies retrieval in Prompt Builder and stops there, it verifies the wrong thing, and this belongs in your agent testing checklist as a step with its own line.

There is a governance mirror of this worth holding in your head. The same mechanism that hides an article from an under-permissioned agent will expose one to an over-permissioned agent. Scoping what a grounded agent can retrieve is the same control read from the other direction, and getting the agent user’s access exactly right, no more and no less, solves both the leak and the blank.

Indexing is a pipeline, and a fresh article is not in it yet

The second common cause is timing. Knowledge grounding is not a live read of the Knowledge object; it is retrieval over a search index built from it, and getting an article into that index takes a pipeline.

A Data Library auto-provisions the search index and retriever for you, which is why it is the fastest way to ground an agent on Knowledge. The convenience hides the latency.

If the library is attached and queried before indexing finishes, the agent grounds on an index that is empty or partial, and it looks like a permissions problem when it is a clock problem. Give the initial index time to build before you judge the results.

The same lag hits edits. An updated or newly published article is not useful to the agent until the change moves through the whole chain: ingestion, mapping, chunking, indexing, and only then retrieval.

So “I fixed the article and the agent still quotes the old answer” is usually not a cache to clear but a pipeline mid-flight. Confirm the article has re-indexed before you treat a stale answer as a bug. Debugging an agent in production starts with knowing which stage you’re looking at.

When access is fine and it still picks the wrong article

Suppose the agent user can read everything and the index is current, and the agent still surfaces a weaker article over the right one. Now, and only now, it is a retrieval-quality problem, and the fixes are different.

Inspect the passages, not the prose. The temptation is to read the agent’s final answer and conclude the retriever failed. Read the retrieved chunks instead: did the authoritative passage rank near the top, did it get returned at all, did a pile of loosely related chunks crowd it out? Measuring retriever quality means looking at what came back before the model wrote anything, because the model can only reason over what it was handed.

Check the fields feeding semantic search. Salesforce advises defining the right identifying fields, ones that carry a concise description or the gist of the article, because those feed the semantic match. Point the search at a field full of boilerplate or an opaque ID and ranking suffers. If recall is the problem, the search index type and the fusion ranker are the levers, and the choice between keyword, vector, and hybrid indexes decides how forgiving the match is to wording.

Mind the vocabulary gap. Customers rarely use your internal terms. If your articles say “provisioning error” and customers say “it won’t turn on”, semantic search bridges some of that but not all. One effective move is to instruct the agent to normalize the customer’s phrasing to your known terms before it fetches grounding, so the query that hits the index speaks the index’s language.

The order to check, written down

When an agent returns the wrong Knowledge article or none, resist the urge to start tuning. Work it in this order, because it runs cheapest-first and the top of the list is where the answer usually is.

  1. Confirm the agent user can read the article and its data categories. Check as the agent user, not as yourself.
  2. Confirm the index has finished building, and that any edited article has re-indexed through the full pipeline.
  3. Re-run the retrieval as the agent user and read the returned chunks, not the final answer.
  4. If the right chunk isn’t ranking, look at the identifying fields, the index type, and the fusion ranker.
  5. If the query and the article speak different vocabularies, normalize the customer’s terms before grounding.

Most tickets close at step one or two. The teams that burn a week on this are the ones who start at step four, because retrieval tuning is the interesting problem and permissions are the boring one. The boring one is where the article went. A grounded agent is only as good as the data its identity is allowed to reach, and the data underneath it is allowed to be found, so start there every time.

Understanding the basics

Why does my Agentforce agent say it has no information when the Knowledge article clearly exists?

Most often because the agent user lacks the Knowledge object permissions or data category access for that article, and the retriever removes articles the running user can’t read before the model sees them. Check the agent user’s access first. The article exists for you; the question is whether it exists for the identity the agent runs as.

Why does retrieval work in Prompt Builder but fail for the live agent?

Prompt Builder and other system-level tools can run with elevated privileges, so they return articles the agent user would never be allowed to see. The agent runs as the agent user and gets the filtered result. Always test grounding as the agent user, not in a tool that runs as an admin.

I updated a Knowledge article and the agent still gives the old answer. Why?

Grounding reads a search index, not the live article, and an edit has to move through ingestion, mapping, chunking, and indexing before retrieval can see it. The old answer usually means the re-index hasn’t completed, not that there’s a cache to clear. Confirm the article has re-indexed before treating it as a bug.

The agent returns an article, just the wrong one. How do I fix ranking?

That’s a retrieval-quality problem once access and indexing are ruled out. Inspect the chunks the retriever returned to see whether the right passage ranked at all, then adjust the identifying fields that feed semantic search, the search index type, and the fusion ranker. Normalizing the customer’s wording to your internal terms before grounding also helps the match.


A grounded agent that can’t find the right answer is usually a permissions and pipeline problem wearing a tuning problem’s clothes. If your agent is surfacing the wrong Knowledge articles and you want it diagnosed in the right order, talk to us.

Keep reading

All articles