What you will be able to do
- Recognise when an agent's failure comes from knowledge it never had, and pick RAG as the fix
- Match a retrieval symptom to the right technique: semantic, keyword or hybrid search, query rewriting, filter extraction, or re-ranking
- Tell apart failures fixed by managed agent sessions (within one interaction) and those fixed by managed agent memory (across conversations)
1.The agent never had the knowledge: add retrieval
The simplest design, an LLM with a prompt, answers from what it learned in training. That works for generic questions, but such a model is often disconnected from your real business data. You can embed some data in the system prompt. When the knowledge is proprietary, changes often or is domain-specific, though, the more direct fix is retrieval-augmented generation. RAG also lets the model cite its sources, and its retrieval step can enforce access control based on the user's credentials.
So when an agent states things that were never true for your business, or were true once but have since changed, it is usually missing knowledge, not reasoning badly. A deterministic RAG chain runs the same three steps for every request, in a fixed order the developer defines. The model doesn't decide the order, which makes the chain predictable and easy to audit.
Checkpoint 1 of 6· Put it in order
Put the steps of a deterministic RAG chain in order
- 1.Generate a response by sending the augmented prompt to an LLM
- 2.Retrieve top-k results from a vector index relevant to the user request
- 3.Augment a prompt by combining the user request with the retrieved context
Retrieval has to come first so the prompt can be augmented with the results, and generation runs on that augmented prompt.
“Augment a prompt by combining the user request with the retrieved context.”Source: docs.databricks.com
2.The agent retrieved, but retrieved the wrong thing
Adding retrieval brings a new failure. When the harness pulls the wrong material from search or memory, the model can still answer confidently. Databricks splits RAG problems into retrieval quality (did the right information come back?) and generation quality (did the model use it well?). These overlap: generation can't recover from context that is missing key information or full of superfluous material.
The fix depends on the pattern of wrong results. The examples in the table come from the Databricks RAG quality guide.
| Symptom | Technique |
|---|---|
| Users' words differ from the documents' words ("turn my phone on" vs a section called "toggling the power") | Semantic search |
| Queries hinge on specific technical terms ("what does model HD7-8D do?") | Keyword search (e.g. BM25) |
| Queries mix concepts and exact terms ("how do I turn on my HD7-8D?") | Hybrid search |
| Ambiguous query or multi-turn chat that doesn't match document terminology | Query rewriting |
| Query names a time period, product or place ("reports from 2023") | Filter extraction plus metadata filtering |
| Relevant chunks come back but are poorly ordered | Re-ranking |
Some of these fixes need changes in more than one place. Retrieval quality depends on both the offline data pipeline (parsing, chunking, metadata, embedding model) and the online chain (query transformation, number of chunks, re-ranking). Filter extraction is a clear example: it only works if the pipeline has extracted the metadata fields and the retriever accepts and applies the filters.
The same reasoning applies to structured data. If a Genie Agent picks the wrong table because tables overlap, remove the unnecessary ones. If it filters on "California" when the column stores "CA", turn on example values and value dictionaries so it can see the real values.
Checkpoint 2 of 6· Check yourself
Support users ask questions such as "what does model HD7-8D do?". The retriever returns manual pages that are conceptually similar but about other models. Which retrieval approach fits this query pattern best?
Product codes are exactly the kind of non-descriptive term that keyword matching handles well and embeddings can blur. Semantic search is what produced the near-miss results in the first place.
“Scenarios requiring precise keyword matches, ideal for specific term-focused queries such as product names.”Source: docs.databricks.com
Checkpoint 3 of 6· Exam question
An agent has been running for over an hour on a data-cleaning task, and its context now contains dozens of prior tool calls and their outputs. When given a new sub-task that requires a different approach, the agent instead re-issues the same sequence of tool calls it used earlier in the session, seemingly anchored to the pattern already present in its context rather than reasoning about the new sub-task. Which failure mode is this?
Correct answer: A — Context distraction
- A. Correct. As accumulated history grows, the model over-weights the pattern of past actions already in context instead of reasoning fresh about the new sub-task — this is context distraction, where a large context pulls the agent's behavior toward repeating what it has already done.
- B. Incorrect. Context poisoning requires a specific wrong fact or hallucination to be present and repeatedly relied on; here there is no incorrect fact, just an over-reliance on prior action history.
- C. Incorrect. Context confusion is caused by irrelevant content (e.g., unrelated tool schemas or documents) being used inappropriately, not by an outsized volume of relevant prior actions.
- D. Incorrect. Context clash requires two contradictory pieces of information in context; here there is no contradiction, only repetition of an established pattern.
3.The agent forgot: sessions or memory?
Forgetting comes in two kinds, and Databricks has a separate managed store for each, both backed by Lakebase. A managed agent session holds the state of the interaction in progress, usually the ordered transcript of messages, tool calls and results. The agent reads it at the start of each turn and appends to it as the interaction continues. This lets an interaction survive a restart and rebuild its full context on a follow-up. Managed agent memory holds durable facts, preferences and decisions about a subject, which the agent recalls in later, unrelated conversations.
The two stores connect: as a session builds up, the agent or application extracts the durable facts and writes them to memory. The stores are independent, so clearing a session doesn't remove anything from memory. To let an agent decide when to save and recall, wrap the store's operations as tools and explain in the system prompt when to use them.
def make_memory_tools(memory_store, actor_id: str):
@function_tool
def search_memory(query: str) -> str:
"""Search long-term memory for relevant facts about the user."""
results = memory_store.search(actor_id=actor_id, query=query, limit=10)
return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."Checkpoint 4 of 6· Fill the gap
Which memory store operation completes the save tool?
@function_tool
def save_memory(path: str, content: str, description: str = "") -> str:
"""Save a durable, long-term memory about the user."""
memory_store. ? (actor_id=actor_id, path=path, content=content, description=description)The example wraps the store's search and add operations as tools. Saving uses add, and recall uses search.
Source: docs.databricks.comCheckpoint 5 of 6· Check yourself
An agent's serving process restarts in the middle of a multi-step interaction. When the user follows up, the agent has lost the transcript, including its earlier tool calls. What addresses this most directly?
The lost state belongs to a single interaction, and sessions exist to persist and resume exactly that. Memory is for durable facts that matter across conversations.
“Persist and resume an agent's session state so an interaction survives restarts”Source: docs.databricks.com
Checkpoint 6 of 6· Exam question
A retrieval step returns three chunks: one relevant passage about a product's warranty policy and two unrelated chunks about a different product line that happened to match on shared keywords. The agent's final answer paraphrases details from one of the unrelated chunks instead of the relevant warranty passage. Which failure mode best explains this behavior?
Correct answer: A — Context confusion
- A. Correct. Irrelevant content (the unrelated product chunks) was present in the context and ended up being used to generate the response instead of the relevant passage — this is context confusion, where superfluous content degrades output quality.
- B. Incorrect. Context poisoning requires a hallucinated or erroneous fact to be introduced and then repeatedly relied on; here the unrelated chunks are real content, just irrelevant to the question.
- C. Incorrect. Context distraction is about over-weighting a large volume of prior actions/history, not about a small number of irrelevant retrieved documents being misused.
- D. Incorrect. Context clash requires two contradictory statements both present in context; the unrelated chunks do not contradict the warranty passage, they are simply off-topic.
Exam traps
Each one states something that sounds right. Open it to see what is actually true.
1.Retrieval problems belong to the data pipeline, so re-chunking or re-embedding is always the fix.Why is that wrong?
Retrieval quality also depends on the RAG chain: query rewriting, how many chunks are retrieved, and re-ranking. Some fixes, such as filter extraction, need changes to both.
Covered in The agent retrieved, but retrieved the wrong thing
2.Long-term memory is the right place for an agent's in-conversation history, and deleting a session also wipes what was learned.Why is that wrong?
Short-term history within an interaction belongs in managed agent sessions. The two stores are independent, so deleting a session doesn't delete memory.
Covered in The agent forgot: sessions or memory?
3.When memory is exposed as a tool, the model can pass in whichever actor_id fits the request.Why is that wrong?
The application sets actor_id from the verified end-user identity. The model must never choose whose memory it reads or writes.
Covered in The agent forgot: sessions or memory?
Practise it for real
Save a user preference to a managed memory store and recall it with a natural-language search, as an agent would at the start of a new conversation.
1.Make sure you have a memory store named support-agent-memory (creating a store provisions its Lakebase storage automatically), and set DATABRICKS_HOST and DATABRICKS_TOKEN.
Why: Both calls below address the store by its display name.
You should see: A workspace-scoped store you can write entries to.
2.POST to /api/2.0/agents/memory-stores/support-agent-memory/entries with actor_id "user-123", path "/preferences/communication.md", content "Prefers email over phone." and description "Communication preferences".
Why: actor_id says whose memory it is, path organises it, and description improves retrieval.
You should see: A new entry, uniquely identified by actor_id, session_id and path.
3.POST to /api/2.0/agents/memory-stores/support-agent-memory/entries:search with actor_id "user-123" and query "communication preferences".
Why: This is the recall step that fixes 'the agent forgot between conversations'.
You should see: The email-preference entry, returned among the most relevant entries for that actor.
Stuck? Get a nudge
Search is scoped to an actor. If nothing comes back, check that the actor_id matches the one you saved with.
Sources
Every claim above is drawn from one of these pages, quoted as it was written on the date shown.
- 1.
“This approach is especially valuable for answering questions about proprietary, frequently changing, or domain-specific information.”
↩︎ The agent never had the knowledge: add retrieval“Up-to-date information: A RAG application can supply the LLM with information from an updated knowledge base.”
↩︎ Prediction - 2.
“This design is good for simple or generic queries but is often disconnected from your real-world business data.”
↩︎ The agent never had the knowledge: add retrieval“The LLM does not make decisions about which tools to call or in what order.”
↩︎ The agent never had the knowledge: add retrieval“Augment a prompt by combining the user request with the retrieved context.”
↩︎ Checkpoint - 3.https://www.databricks.com/blog/ai-harnessSecondary source
“When the harness pulls in the wrong information from memory or search systems, the model may confidently generate incorrect answers.”
↩︎ The agent retrieved, but retrieved the wrong thing - 4.
“It's difficult to generate high-quality RAG output if the context provided to the LLM is missing important information or contains superfluous information.”
↩︎ The agent retrieved, but retrieved the wrong thing“Retrieval quality can be influenced by both the data pipeline”
↩︎ Exam trap 1 - 5.
“Filter extraction must be done in conjunction with changes to both metadata extraction data pipeline and retriever chain components.”
↩︎ The agent retrieved, but retrieved the wrong thing“Scenarios requiring precise keyword matches, ideal for specific term-focused queries such as product names.”
↩︎ Checkpoint - 6.
“verify that relevant columns have Example values and Value dictionaries enabled.”
↩︎ The agent retrieved, but retrieved the wrong thing“If possible, remove unnecessary or overlapping tables or columns.”
↩︎ The agent retrieved, but retrieved the wrong thing - 7.
“sessions give the agent continuity within a conversation, and memory gives it continuity across conversations.”
↩︎ The agent forgot: sessions or memory?“deleting a session, or an entire session store, does not delete memory retained in a memory store.”
↩︎ Exam trap 2“Remember a user's preferences, facts, and decisions across separate conversations”
↩︎ Prediction“Persist and resume an agent's session state so an interaction survives restarts”
↩︎ Checkpoint - 8.
“For short-term conversation history within a single interaction, use managed agent sessions.”
↩︎ The agent forgot: sessions or memory?“Set the actor_id in trusted application code from the verified end-user identity.”
↩︎ The agent forgot: sessions or memory?“Never let the model choose whose memory to read or write.”
↩︎ Exam trap 3