All chapters
  1. Start hereAn agent is a model call in a loop
  2. Chapter 1One call: what a model is from the outside
  3. Chapter 2The loop: where a call becomes an agent
  4. Chapter 3The abstraction ladder: six rungs over one call
  5. Chapter 4The eight jobs of a harness
  6. Chapter 5Context: deciding what the model sees
  7. Chapter 6Tools: what the model may ask for, and where it runs
  8. Chapter 7MCP: one way to plug tools into any harness
  9. Chapter 8RAG: retrieval is context assembly
  10. Chapter 9Control flow and state: stopping, pausing and resuming
  11. Chapter 10Guardrails: identity, approval and the output contract
  12. Chapter 11Reliability and cost: retries, budgets and the failures that will happen
  13. Chapter 12Observability and evals: knowing what the agent did, and whether it was right
  14. Chapter 13Many agents: more loops, and what each one costs
  15. Adopt · 1SDKs: the same loop in Python, TypeScript and Java
  16. Adopt · 2Coding harnesses: a finished harness for software work
  17. Adopt · 3Frameworks and graph runtimes: the loop as a library
  18. Adopt · 4Managed platforms: someone else runs the loop
  19. Adopt · 5Build your own: a whole harness in one file
  20. DecideBuild or adopt: who runs each job?
  21. ReferenceGlossary
  22. AboutAbout this site
Chapter 8

RAG: retrieval is context assembly

A model cannot know your documents. Retrieval puts the right ones into the context at the right moment. Chunks, vectors, hybrid search, re-ranking, and the two ways a harness can use them.

Stage 5 of the full build is underwriting. Code has run the 29 rules on a house and priced it. One point is flagged, and the rules alone cannot settle it. An experienced underwriter would settle it from memory: we have seen houses like this one, this is how we decided them, and this is why.

The model that must now recommend has no such memory. The insurer's past decisions are rows in the insurer's database. They are private records, and the model has never seen them. Ask it anyway, and it will write a fluent paragraph about houses in general. Nothing in that paragraph comes from what this insurer decided.

A larger model does not fix this, and neither does a better prompt, because the facts are missing from the request. Someone has to find the few past decisions that matter for this house and put them into the context: everything sent to the model in one call.

A model cannot know your documents. Retrieval is code that finds the few records this request needs and puts them into the context. Inside a harness it is not a separate system. It is job 1 when code does it, and job 2 when the model asks for it through a tool.

The usual name is RAG, retrieval-augmented generation: retrieve first, then generate. This chapter starts with the smallest retrieval that works, shows where it stops, and builds up the usual pipeline one failure at a time.

1. The simplest retrieval that works: three documents and a keyword#

The miniature has to solve a small version of the same problem. The model needs the insurer's underwriting rules for the email in front of it, and those rules are not public knowledge. So before the first model call, code picks the rule documents that apply and writes them into the request.

The code below is the whole of it: RULE_DOCS and retrieve_rules from examples/quote-email/harness.py. It shows the three things any retrieval does. It selects: a document is a hit when one of its keywords appears in the lower-cased email. It checks who may read: may_read must find the caller's role in the document's roles. And it labels: each hit becomes one line that starts with its id. A successful run proves that matching documents reach the context for a role that may read them. It does not prove the match is a good one. The comment on the first line says so: this is a stand-in.

RULE_DOCS = [  # a stand-in for a document store; real systems retrieve with search
    {"id": "eligibility-basics", "roles": {"underwriter", "intake_bot", "broker_portal"}, "keywords": ["quote"],
     "text": "A quote needs a verified address, the year built and the square footage."},
    {"id": "fl-coastal", "roles": {"underwriter", "intake_bot"}, "keywords": [" fl"],
     "text": "Florida: homes built before 1950 go to human review. Flood zone AE rates in the high band."},
    {"id": "pricing-internal", "roles": {"underwriter"}, "keywords": ["quote"],
     "text": "Internal: the high band carries a 35% wind surcharge. Never share the surcharge with brokers."},
]


def retrieve_rules(caller: Caller, email: str) -> str:
    """Job 1 (with job 5): fetch rule documents that match the email AND that this role may read."""
    hits = [doc for doc in RULE_DOCS if may_read(caller, doc) and any(k in email.lower() for k in doc["keywords"])]
    return "\n".join(f"[{doc['id']}] {doc['text']}" for doc in hits)

The result does not go to the model as a message. assemble_context, the function that builds every request, places it as the third block of the system prompt, after the instructions for the caller's role and before the history. The command below prints the request body without calling anything. Here it runs as the intake service, and the output is trimmed to that third block.

cd examples/quote-email
/opt/homebrew/bin/python3 harness.py --dry-run --role intake_bot
{
  "type": "text",
  "text": "Underwriting rules:\n[eligibility-basics] A quote needs a verified address, the year built and the square footage.\n[fl-coastal] Florida: homes built before 1950 go to human review. Flood zone AE rates in the high band.",
  "cache_control": {
    "type": "ephemeral"
  }
}

Three details in this small output return throughout the chapter.

Two documents came back, not three. pricing-internal matches the word "quote", but the intake service is not in its roles, so the document never entered the request.

Each line carries its id. The model can say which rule it used, and code can check that the id is one it was given.

The block has a cache marker, because the retrieved rules stay the same for every step of one run. Context explains why that works and why the block sits where it does.

That is retrieval at the bottom: a search, a permission check, and a place in the context. Everything later in this chapter improves the first of those three and keeps the other two.

2. Where a keyword match stops#

The table shows retrieve_rules called directly with four emails, as the underwriter role. These are real results from the miniature.

The email saysDocuments returnedWhat happened
"Please quote homeowners for 18 Gulf Shore Blvd, Naples FL, built 1998, 2,400 sq ft."eligibility-basics, fl-coastal, pricing-internalCorrect
"Please quote homeowners for 18 Gulf Shore Blvd, Naples, Florida, built 1998."all threeCorrect, by luck: "florida" happens to begin with " fl"
"Can you price home insurance for 18 Gulf Shore Blvd, Naples FL, built 1998?"fl-coastal onlyA miss. The email never says "quote", so two rules that apply are left out
"Please quote a house with a red flag on the roof in Austin TX"all threeA false match. " flag" contains " fl", so a Texas house gets the Florida rule

The third and fourth rows fail in opposite directions, and they have one cause. The function compares letters. The broker and the rule author mean the same thing by "price" and "quote", and the function cannot know that. "Flag" and "FL" mean different things, and it cannot know that either.

Neither failure raises an error. In the third row the model receives a shorter block of rules, the run ends normally, and the answer was reached without a rule that applied. That is what makes retrieval hard to operate: from the outside, a bad search looks exactly like a good one.

3. The full build asks two questions that keywords cannot answer#

The full build of the quote system needs retrieval in two places, and neither is a lookup by word.

The first comes up early. When the valuation of a house is missing or its confidence is low, it helps to know what similar insured homes are worth. The second is the one from the opening: how did underwriters decide this point on similar risks?

"Similar" is the hard word in both. The system has to find records that are close to this house in the ways that matter, and return a handful.

So the full build keeps two retrieval stores. Both are tables in PostgreSQL, the same database that holds the business rows, with an extension called pgvector that the next section explains. The numbers are from this example.

StoreThe questionOne document isRowsWho asks
customer_profilesWhat are similar insured homes worth?One policy in force1,140, seededCode, at the classify stage, and only when the valuation is missing or its confidence is below 0.7
precedentsHow did underwriters decide this point on similar risks?One decided point of one quote41 seeded, plus one per new decisionThe model, at the underwriting stage, through a tool named search_precedents

The last column is the subject of section 5. First the pipeline itself: how a record gets into a store, and how one quote reads from it.

Diagram: Retrieval in the full build · a write path and a read path

Two lanes. The top lane runs when data changes: a record becomes a text, a vector and a stored row. The bottom lane runs for one quote: filter, order by distance, re-rank, then into the context. Click any box.

  1. Write path · nightly, or after a decision
    1. Record to template text: One policy or one decided point becomes one short text made of bands. Nothing is split, because a record is already the right size.
    2. Embed in the service: A small embedding model turns the text into 384 numbers. It runs inside the service, so no data leaves it.
    3. Store the row and its vector: The vector is a column next to the business columns, with a version number that marks which template and model produced it.
  2. Read path · for one quote
    1. Filter first: The hard business rule: same state, same ZIP prefix, size within 25%. A similar house in another state is not a comparable house.
    2. Order by vector distance: Inside the filter, rows are ordered by how close their vector is to the request's vector. The request was embedded once, at intake.
    3. Re-rank the candidates: Code scores each candidate again on matching bands, similarity and recency, and keeps both sides of the decision.
    4. Into the context: The results reach the model with their ids: placed by code before the call, or returned as a tool result when the model asked.

The top lane runs when data changes; the bottom lane runs for one quote. The next section takes the boxes one at a time, each introduced by the failure it removes.

4. From a keyword to a pipeline, one failure at a time#

A document is too long to send whole#

The three rule documents in the miniature are one sentence each. A real underwriting manual is hundreds of pages. Sending all of it on every call is the crowding problem from Context at its worst: the model pays for every page on every step, and the two paragraphs that matter are buried.

The fix is to store the manual in pieces and retrieve only the pieces that match. One piece is called a chunk, and splitting is called chunking. A common default is a fixed size with an overlap, so that a sentence cut at a boundary appears whole in the next piece. OpenAI's vector stores, for example, document a default of 800 tokens per chunk with 400 of overlap.

The cost is at the boundaries. The model reads a chunk without its neighbours. If a rule says "except in the cases listed below" and the list falls in the next chunk, the model receives a rule without its exceptions. Small chunks match precisely and lose their surroundings; large chunks keep them and fill the context.

The full build does not chunk. One record is one document, because a policy or a decision is already the right size. That works only for record-shaped data; a 40-page policy wording would need chunking. So the first design decision in any retrieval system is not about technology. It is: what is one document?

The words differ and the meaning is close#

This is the failure from section 2, and it needs a way to compare meaning.

An embedding model is a model that reads a text and returns a fixed-length list of numbers, called a vector. It is trained so that texts with similar meaning get vectors that point in similar directions. "Price home insurance" and "quote homeowners" land close together. "Red flag" and "Florida" do not. The vector for one text is its embedding.

Search then becomes geometry. Turn every document into a vector once and store it. Turn the request into a vector the same way. Return the documents whose vectors are nearest. A database that stores vectors and answers "which are nearest to this one" is a vector store. This is vector search, also called semantic search.

The full build makes four decisions here, and each has a reason.

What text is embedded. A fixed template of bands, for example sqft_band=2500-4000; year_built_band=1990-2010; zip3=954. No raw numbers and no personal data. A general text embedding does not reliably place nearby numbers near each other, and a band gives a house built in 1976 and one built in 1979 the same meaning for retrieval.

Which embedding model. A small open model, all-MiniLM-L6-v2, which returns 384 numbers and runs inside the service. The texts are about 40 tokens long. There is no network call and no price per call, and no data leaves the service.

Where the vectors live. In PostgreSQL with pgvector, an extension that adds a vector column type and distance operators. The business filter and the vector search are then one query, in one transaction, with one backup.

When the request is embedded. Once, at intake. The vector is stored, and later stages reuse it.

Each decision has a cost. A larger hosted embedding model handles long natural text better. A dedicated vector database scales further, and is one more system to keep in sync. And the embedding model is a commitment: vectors from two different models cannot be compared, so changing the model, or the template, means embedding every stored record again.

Exact search, approximate indexes, and distanceWhat the pgvector README says, and what the full build found at its size

The embedding model and the index are two separate choices. The model turns text into a vector. The index finds the nearest vectors quickly, and it does not depend on which model made them.

ChoiceWhat it doesWhat the pgvector README says, read 2026-11-16
Exact scanCompares the query with every row that passes the filter"By default, pgvector performs exact nearest neighbor search, which provides perfect recall."
IVFFlat indexGroups vectors into lists and searches only the nearest lists"It has faster build times and uses less memory than HNSW, but has lower query performance"
HNSW indexA layered graph; the search walks from a node to a nearer node"better query performance than IVFFlat (in terms of speed-recall tradeoff), but has slower build times and uses more memory"

Recall is the share of true nearest neighbours that a search finds. An approximate index, in the README's words, "trades some recall for speed". The setting hnsw.ef_search moves that trade; its default is 40.

The full build uses cosine distance, the <=> operator. It compares the direction of two vectors, not their length. Similarity is 1 minus the distance.

At the full build's size the index does not matter. With 1,140 rows and a selective filter, PostgreSQL used the ordinary index on state and ZIP prefix, then sorted about 190 rows by exact distance. The precedents table has no vector index at all, for the same reason. These figures are from the build's own notes and were not re-measured here. An index is an optimisation. Exact search is the baseline you measure it against.

The table, the index and the query, trimmed from the full build's schema. It is shown as documented shape and was not run here.

CREATE TABLE customer_profiles (
    -- ... policy columns: state, zip3, dwelling_type, sqft, year_built, insured_value ...
    profile_text      text NOT NULL,        -- 'sqft_band=2500-4000; year_built_band=1990-2010; zip3=954; ...'
    embedding         vector(384) NOT NULL,
    embedding_version int NOT NULL          -- goes up when the template or the model changes
);

CREATE INDEX customer_profiles_embedding_hnsw ON customer_profiles
    USING hnsw (embedding vector_cosine_ops) WITH (m = 16, ef_construction = 64);
CREATE INDEX customer_profiles_filter ON customer_profiles (state, zip3, dwelling_type);

BEGIN;
SET LOCAL hnsw.ef_search = 80;                    -- wider search at query time: better recall, slower
SET LOCAL hnsw.iterative_scan = relaxed_order;    -- keep scanning until enough rows pass the filter
SELECT id, insured_value, 1 - (embedding <=> :q) AS similarity
FROM customer_profiles
WHERE state = :state AND zip3 = :zip3 AND sqft BETWEEN :low AND :high
ORDER BY embedding <=> :q
LIMIT 8;
COMMIT;

The meaning is close and the exact token matters#

Vector search has the opposite weakness to keyword search. It is good at "about the same thing" and poor at "exactly this string". A flood zone code such as AE, a policy form number or a rule id is a short token with little meaning of its own. Its vector sits near the vectors of many other short codes, so the one document that contains the exact code may not come back first.

The fix is to run both searches and merge the two result lists. That is hybrid search: a keyword search for exact tokens, a vector search for meaning, and a rule for combining their rankings. The pgvector README points the same way: "Use together with Postgres full-text search for hybrid search", with Reciprocal Rank Fusion named as one way to combine the results.

The cost is a second index to keep, and a merge rule whose weights someone must choose and test.

The full build, as described, does not run a keyword search. Its exact matching is a filter on structured columns, two sections below. That fits when the exact values are fields in a row. Hybrid search earns its place when they are words inside text.

The nearest text is not the most useful#

Vector distance finds similar text. The underwriter needs something narrower: similar risk, decided recently, and seen from both sides. A search that returns the six nearest precedents might return six approvals. The model would then read six reasons to approve and none to decline.

So retrieval is done in two stages. The first is cheap and wide. The second looks only at the candidates and orders them with a better, slower rule. That second stage is re-ranking.

In the full build, stage one takes 50 candidates by vector distance. Stage two scores each one again: 0.6 × matching bands, plus 0.3 × similarity, plus 0.1 × recency. A candidate that matches fewer than 4 of the 8 bands is dropped. The result is the top 3 that approved and the top 3 that declined.

That re-ranker is plain code with business rules in it. The other common kind is a re-ranking model, which reads the query and one candidate together and returns a relevance score. It is too slow to run over a whole store, which is why it runs second.

The cost is tuning. The weights 0.6, 0.3 and 0.1 are configuration, and nothing says they are right until they are tested against cases with known answers.

A similar house in the wrong state, and a document for the wrong reader#

Two different problems have the same fix, and the fix has a trap.

The first is a business rule. A house in another state can have a very similar vector, and it is not a comparable house. No amount of similarity should bring it back. The full build therefore filters first, on state, ZIP prefix and size within 25%, and only then orders by vector distance. The filter carries the hard rule. The vector carries the soft similarity.

The trap is in how a filter meets an approximate index, as the pgvector README describes: "With approximate indexes, filtering is applied after the index is scanned. If a condition matches 10% of rows, with HNSW and the default hnsw.ef_search of 40, only 4 rows will match on average." You asked for 8 rows and received 4, with no error. From version 0.8.0, pgvector offers iterative index scans, which keep scanning until enough rows pass. The full build also widens the filter step by step when fewer than 3 rows match, and reports each step.

The second problem is access. Go back to the miniature and the document pricing-internal. Its own text says "Never share the surcharge with brokers." That sentence is a request to the model. The control is somewhere else: may_read keeps the document out of every request made for the broker portal. A model cannot leak a document that was never in its context.

The rule is that permission is checked at retrieval time, in code, for the person the run acts for. A filter applied after the model has read the text is too late. And the check uses the caller's identity, never anything the model wrote. How that identity is established is the subject of Guardrails.

The same reasoning applies to what is stored at all, because anything in a store can come back in a prompt. In the full build, the reason text of a decision is redacted before it is written: emails, phones, addresses, then names. The precedent text holds property-risk factors only.

The store is a copy, and a copy goes stale#

A retrieval store is a second copy of the data, prepared for search. When the source changes, the copy is wrong until something updates it. A cancelled policy is still returned as a comparable home. A rewritten rule still matches through its old chunk.

So a retrieval system has a write path that needs the same care as the read path. The full build's has four parts.

The cost is that freshness becomes a number you have to choose. "Nightly" means a document can be a day out of date. Whether that is acceptable is a business decision, and it should be written down.

The model names a source it was never given#

The last failure happens after retrieval worked. The model reads six precedents and writes a recommendation that cites seven. The seventh has a plausible id, and it does not exist.

The defence starts with the brackets in section 1. Every retrieved item enters the context with its id, so the harness knows the set of ids it supplied. After the model answers, code compares. In the full build, a precedent id that the model cites and the search did not return is dropped.

That check proves the id was supplied. It does not prove the model read the precedent correctly. For that, a person needs the cited passage itself, and some APIs return it. On the Claude API, a document block with "citations": {"enabled": true} makes the response carry, for each claim, the cited_text and where it sits in the document. For passages your own code retrieved there is a content block of type search_result, with a source, a title and the content, which the documentation describes as meant for "RAG (Retrieval-Augmented Generation) applications where Claude needs to attribute answers to your documents".

One limit from the same documentation matters for the quote example: "Citations and structured outputs are incompatible." A step that must return a strict JSON decision has to carry ids in its own output fields.

The table collects the seven steps, now that each has been explained.

The failureWhat removes itWhat it costs
The document is too long to sendChunksMeaning is lost at the boundaries
Different words, same meaningEmbeddings and vector searchA model commitment: change it and embed everything again
The exact token is missedHybrid searchA second index and a merge rule to tune
Nearest is not most usefulRe-rankingWeights or a second model, tested against known cases
Wrong state, or wrong readerFilters and permission checks at retrieval timeToo few rows can come back, silently
The copy is out of dateA write path: ingest, re-embed, re-indexA freshness delay you must choose
An invented sourceIds on every item, checked by code; citationsThe check proves the id was given, not that it was read well

Read the right-hand column. Not one of the costs is paid in model quality. Each is a decision about your own data: what a document is, what "similar" means, who may read what, how stale is acceptable.

5. Two ways a harness uses retrieval#

A pipeline answers "how are the records found". A harness has a second question: who decides that a search happens, and with what query? There are two answers, and the full build uses both.

Diagram: Two ways a harness uses retrieval · code decides, or the model asks

Top lane: fixed retrieval, a workflow step. Code searches before the model call and the model reads the result. Bottom lane: agentic retrieval. The model asks for a search through a tool, the harness runs it, and the result comes back as a tool result.

  1. Fixed · code searches before the call (job 1)
    1. Request arrives: The fields of the request are all that code knows when it builds the query.
    2. Code runs the search: One search, built and run by code. In the full build it runs only when the valuation is missing or its confidence is below 0.7.
    3. Results placed in the context: Context assembly writes the results into the request, each with its id.
    4. Model call: The model reads the results. It did not ask for them and cannot ask for more.
  2. Agentic · search is a tool the model may ask for (job 2)
    1. Model call: The model has read the facts so far and decides it needs past decisions on one flagged point.
    2. Tool request: search_precedents: The model asks. It writes the query; nothing has been searched yet.
    3. Harness decides and runs it: The harness checks the request and calls the tool. The permission filter and the business filter are applied in code, inside the tool, not taken from the model's query.
    4. Tool result: the precedents: The precedents return as a tool result, each with its id. The model may answer now, or ask for another search on the next turn.

Fixed retrieval: code searches before the model call. This is a workflow step, where code fixes the order. The miniature does it on every run: assemble_context calls retrieve_rules, and the model reads the result. The full build does it at the classify stage. When the valuation is weak, code searches customer_profiles and gets 8 similar homes. The model reads them. It did not ask for them.

Its strength is that it is predictable. There is one search, its cost is known in advance, and the query is built by code from fields of the request, so it can be tested like any other function. It is job 1, context assembly.

Its cost is that the query is written before the model has thought. If the useful question appears halfway through the run, a fixed step cannot ask it. It also runs whether or not the result is needed, unless code adds a condition, as the full build does with confidence below 0.7.

Agentic retrieval: search is a tool the model may ask for. At the underwriting stage the model is offered search_precedents. For each flagged point it writes a tool request with a query. The harness decides, runs the search, and returns the precedents as a tool result. The model asks, the harness decides and calls, the tool does. This is job 2.

The strength is that the model writes the query from what it has learned so far. It can search per flagged point, and search again with a better question.

The costs are those of any tool. Each search is another turn, and every turn sends the whole context again. The model may search five times, or not at all, and a run that never searched looks normal. The query is text a model wrote, so the hard conditions cannot be left to it: the permission filter and the business filter stay in code, inside the tool. And the results are tool results, text from outside that must be treated as untrusted, as Tools explained.

FixedAgentic
Who decides to searchCodeThe model, by asking
Who writes the queryCode, from the requestThe model, from what it knows so far
Number of searchesKnownBounded only by the turn limit
Which job1, context assembly2, tools
In the full buildClassify: similar homes, as a fallbackUnderwriting: search_precedents

The choice follows from one question: does the search depend on something only the model will find out? If not, a fixed step is cheaper and easier to test. The full build decides stage by stage, not once for the whole system.

6. How to know retrieval works#

A wrong answer has two possible causes that need different fixes: the right record never reached the context, or it did and the model used it badly. One score for answer quality cannot tell these apart, so retrieval is measured on its own, before any model reads the results. The full build keeps golden cases in JSON, each a query with the record that should come back, and scores three things: hit@1 and hit@3, whether the right record is first or in the top three, and MRR, the average of 1 divided by the rank of the right answer. The build fails if a case gets worse. A good retrieval score does not prove the answers are good. It proves the model was given what it needed. Scoring the answers themselves, with golden sets and judge models, is the subject of Observability and evals.

7. Who runs retrieval#

Each part of the pipeline can be run by someone else: the chunking, the embedding model, the store, the search, the citation. The table uses the site's fixed words. BUILT IN means the product does it in your process. INTEGRATES means it connects to another product for it. MANAGED means the vendor runs it. YOU BUILD means it stays with you.

ProductWho runs retrievalWhat its documentation names
The miniatureYOU BUILDA keyword match over three documents in the file
The full build, a designYOU BUILDPostgreSQL with pgvector, an embedding model in the service, a re-ranker in code
Claude APIYOU BUILD the search. BUILT IN: citing what you pass inCitations on document blocks; search_result blocks. "Anthropic does not offer its own embedding model"; the page names Voyage AI as a provider
OpenAI Responses APIMANAGEDThe file_search tool, "a hosted tool managed by OpenAI", over vector stores. A file added to a vector store is "automatically chunked, embedded, and indexed"
OpenAI Agents SDKINTEGRATESFileSearchTool, a hosted tool that retrieves from OpenAI Vector Stores
Gemini APIMANAGEDThe File Search tool, which "imports, chunks, and indexes your data"; a File Search store holds the embeddings
Amazon Bedrock Knowledge BasesMANAGED"Amazon Bedrock manages the underlying data ingestion, indexing, storage, and retrieval infrastructure"; citations in the response
LangChainBUILT IN: the parts as interfacesDocument loaders, text splitters, embedding models, vector stores, retrievers
LlamaIndexBUILT INRetrieval over your data
Claude Managed AgentsThe overview page read does not sayNo retrieval or vector store is named on it
Google ADKThe page read does not sayIts home page names grounding with Google Search, not search over your own documents

The Claude, OpenAI, Gemini, Bedrock and LangChain rows were read on 2026-11-16; the LlamaIndex row is from the baseline check of 2026-11-14. "Does not say" describes the one page read, not the product. This is part of the job 1 column of the matrix on Build or adopt.

The products differ for real. Some model APIs will hold your files and search them for you, and one does not offer an embedding model at all. A managed store removes the write path from your code: chunking, embedding and indexing happen when a file is uploaded.

Now compare that with the cost column at the end of section 4. A managed store runs the machinery. It does not decide what one document is, what text represents a house, which filter is a hard rule, who may read which record, or how the result is measured. A framework's retriever, in LangChain's words "an interface that returns documents given an unstructured query", saves the plumbing and leaves the same decisions. None of them is a product feature.

What you can do now, and what is still open#

You can now read any retrieval system as a short list of questions. What is one document? How is "similar" computed? What is filtered, and for whom? How old can the copy be? Does code search, or does the model ask? In the quote example each has an answer you can point to, in one line of the miniature or in the two stores of the full build.

One idea carries the rest. Retrieval does not make a model know more. It decides what the model is shown, and a model can only be as right as what it was shown.

Agentic retrieval leaves a question this chapter did not answer. A model that may search again can keep searching: a better query, one more precedent, another turn. Something other than the model has to decide that the run is over, and something has to remember where the run was if it is interrupted before then. Control flow and state is the next chapter because a loop needs a reason to stop and a way to continue.