Bedrock's AgenticRetrieveStream now takes maxAgentIteration 0 or 1: passages only, or one retrieval plus one answer

AWS announced on November 9, 2026 that Amazon Bedrock Managed Knowledge Base now supports single‑shot retrieval augmented generation (RAG) and retrieval‑only requests through `AgenticRetrieveStream` [1](https://aws.amazon.com/blogs/machine‑learning/single‑shot‑and‑agentic‑retrieval‑with‑amazon‑bedrock‑managed‑knowledge‑base/). Until now this API was described as agentic retrieval: a foundation model splits a complex question into sub‑queries and retrieves iteratively [2](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent‑runtime_AgenticRetrieveStream.html). The change is in the `maxAgentIteration` parameter, whose range is now 0 to 5. Callers already on this API can choose a lighter path per request without switching to a second API. AWS says single‑shot RAG can reduce latency and model usage compared with agentic retrieval, and that retrieval‑only requests make no foundation model calls. It publishes no pricing comparison, so whether a given request costs less is something to measure. The retained API reference page lists `maxAgentIteration` as a number in the request syntax but does not describe its values. The 0 to 5 range and the behavior of each value come from the announcement, so treat them as AWS's account of the feature rather than something verified here.

Per the announcement 1:

• maxAgentIteration=0: one guaranteed retrieval, no foundation model call. Use it with generateResponse=false. Combining 0 with generateResponse=true is invalid and returns a 4xx error, because generating an answer needs a model call.
• maxAgentIteration=1: one retrieval, then one answer‑generation call, with no planning and no query rewriting. Pair it with generateResponse=true.
• maxAgentIteration=2 to 5: agentic mode, unchanged. Up to n minus 1 planning rounds, then an answer. Existing requests in this range keep their current behavior.

The API reference says a generated response is produced by default and can be turned off 2. The sources do not say what happens if a request sets 0 and omits generateResponse, so set it to false explicitly. They also do not state a default for maxAgentIteration.

AWS defines one iteration as one foundation model call. The loop always ends with a single answer‑generation call, so a value of n allows up to n minus 1 planning rounds. Each planning round is a query rewrite plus a retrieval 1.

Three things the number does not measure:

• Documents retrieved. An iteration is a model call, not a document.
• Knowledge bases. All three modes can query multiple knowledge bases, including 0 and 1. What agentic mode adds is query decomposition, evidence evaluation and iterative searches.
• Speculative retrieval. The initial retrieval that runs ahead of the first planning step is not an iteration and does not count against the limit.

AWS also says the parameter is not automatic routing. The application decides which value to send for each request.

With generation on, the stream can carry `responseEvent` chunks of the answer, a `result` event holding `generatedResponse` with its citations, and trace events for visibility into the process. The reference says `responseEvent` is emitted only when `generateResponse` is true [2](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent‑runtime_AgenticRetrieveStream.html). At `maxAgentIteration=1`, AWS says you consume the stream as before, but it contains a single retrieval and one grounded answer, with no planning trace events in between [1](https://aws.amazon.com/blogs/machine‑learning/single‑shot‑and‑agentic‑retrieval‑with‑amazon‑bedrock‑managed‑knowledge‑base/). At `maxAgentIteration=0`, AWS says the service returns deduplicated source passages and no generated answer. Retrieval behavior matches a direct Retrieve call, but the response format does not: passages arrive in the stream's `result` event without `score` or `location` fields. If your code reads relevance scores or source locations from Retrieve responses, switching to this mode is not a drop‑in change.

Retrieval‑only fits cases where the reader should see the source text rather than a model's summary. AWS's example is an employee reviewing an account‑opening procedure who wants the policy text itself. The application shows the passages and their source references and calls no model [1](https://aws.amazon.com/blogs/machine‑learning/single‑shot‑and‑agentic‑retrieval‑with‑amazon‑bedrock‑managed‑knowledge‑base/). AWS also describes the 0 setting as most useful for callers already standardized on `AgenticRetrieveStream` who would rather change a parameter than switch APIs. The banking assistant in the announcement is a fictional illustration. AWS says it is not a customer deployment or a measured result. It is a policy lookup and comparison tool and does not approve accounts.

AWS's guidance is to pick the lowest iteration limit that meets each workflow's quality needs 1:

• Well‑scoped, direct questions: 1 is suggested as a likely default if most traffic looks like that.
• Multi‑part, comparative, exploratory or cross‑knowledge‑base questions: 2 to 5. In the example, a question comparing sole proprietors and LLCs plus checks for nonresident owners uses 4, which allows up to three planning rounds.
• Source review: 0 with generation off.

AWS says lower values make calls faster and more predictable. The announcement publishes no latency, price or accuracy figures, and the retained sources include no independent test of the API. A higher value gives the planner more chances to decompose and refine a hard question, but AWS itself warns against assuming it always produces a better answer.

Its suggested evaluation is to run representative questions from your own documents against both single‑shot and your current agentic setting on the same knowledge base. Measure latency and request cost, and check that answers are correct and supported by the retrieved passages. Include questions that span several documents and questions the documents cannot answer, so a faster response does not hide missing evidence.