--- title: "POST /agenticRetrieveStream" method: POST path: "/agenticRetrieveStream" --- # POST /agenticRetrieveStream `POST /agenticRetrieveStream` Retrieves information from one or more knowledge bases using an agentic approach. Agentic retrieval uses a foundation model to intelligently decompose complex queries into sub-queries and iteratively retrieve relevant information from your knowledge bases. This approach improves retrieval accuracy for complex, multi-step questions that a single retrieval pass might not fully address. The operation returns results through a stream that includes retrieval results, trace events for visibility into the process, and a generated response synthesized from the results by default, which can be turned off. ## Request body - object - `agenticRetrieveConfiguration` object, required — Configuration settings for the agentic retrieval operation. - `foundationModelConfiguration` object — The foundation model configuration. Required when foundationModelType is CUSTOM. - `bedrockFoundationModelConfiguration` object — The Bedrock foundation model configuration. - `modelConfiguration` object, required — The model configuration containing the model ARN. - `modelArn` string, required — The ARN of the Bedrock foundation model. - `type` 'BEDROCK_FOUNDATION_MODEL', required — The type of foundation model configuration. - `foundationModelType` 'CUSTOM' | 'MANAGED' — The type of foundation model to use. CUSTOM uses a specified model, MANAGED uses the service default. - `maxAgentIteration` integer — The maximum number of agent iterations for retrieval. - `rerankingConfiguration` object — The reranking model configuration. Required when rerankingModelType is CUSTOM. - `bedrockRerankingConfiguration` object — The Bedrock reranking model configuration. - `modelConfiguration` object, required — The model configuration containing the model ARN. - `modelArn` string, required — The ARN of the Bedrock reranking model. - `type` 'BEDROCK_RERANKING_MODEL', required — The type of reranking configuration. - `rerankingModelType` 'CUSTOM' | 'MANAGED' | 'NONE' — The type of reranking model to use. CUSTOM uses a specified model, MANAGED uses the service default. If not specified, defaults to MANAGED for managed embedding knowledge bases and NONE for custom embedding knowledge bases. - `generateResponse` boolean — Whether to generate a response based on the retrieved results. - `messages` object[], required — List of messages in the agentic retrieval conversation. - `content` object, required — The content of the message. - `text` string — The text content of the message. - `role` 'user' | 'assistant', required — The role of the message sender (e.g., user or assistant). - `nextToken` string — Opaque continuation token for paginated results. - `policyConfiguration` object — Policy configuration for agentic retrieval. - `bedrockGuardrailConfiguration` object — Configuration for Bedrock guardrails to apply during retrieval. - `guardrailId` string, required — The unique identifier of the guardrail. - `guardrailVersion` string, required — The version of the guardrail to use. - `retrievers` object[], required — List of retrievers for agentic retrieval. - `configuration` object, required — The configuration for this retriever. - `knowledgeBase` object — Configuration for a knowledge base retriever. - `knowledgeBaseId` string, required — The unique identifier of the knowledge base. - `retrievalOverrides` object — Overrides for retrieval behavior such as filters and result limits. - `filter` object — A filter to apply to the retrieval results. - `andAll` RetrievalFilter[] — Knowledge base data sources are returned if their metadata attributes fulfill all the filter conditions inside this list. - … - `equals` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value matches the value in this object.

The following example would return data sources with an animal attribute whose value is cat:

"equals": { "key": "animal", "value": "cat" }

- … - `greaterThan` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is greater than the value in this object.

The following example would return data sources with an year attribute whose value is greater than 1989:

"greaterThan": { "key": "year", "value": 1989 }

- … - `greaterThanOrEquals` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is greater than or equal to the value in this object.

The following example would return data sources with an year attribute whose value is greater than or equal to 1989:

"greaterThanOrEquals": { "key": "year", "value": 1989 }

- … - `in` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is in the list specified in the value in this object.

The following example would return data sources with an animal attribute that is either cat or dog:

"in": { "key": "animal", "value": ["cat", "dog"] }

- … - `lessThan` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is less than the value in this object.

The following example would return data sources with an year attribute whose value is less than to 1989.

"lessThan": { "key": "year", "value": 1989 }

- … - `lessThanOrEquals` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is less than or equal to the value in this object.

The following example would return data sources with an year attribute whose value is less than or equal to 1989.

"lessThanOrEquals": { "key": "year", "value": 1989 }

- … - `listContains` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is a list that contains the value as one of its members.

The following example would return data sources with an animals attribute that is a list containing a cat member (for example ["dog", "cat"]).

"listContains": { "key": "animals", "value": "cat" }

- … - `notEquals` object —

Knowledge base data sources are returned when:

The following example would return data sources that don't contain an animal attribute whose value is cat.

"notEquals": { "key": "animal", "value": "cat" }

- … - `notIn` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value isn't in the list specified in the value in this object.

The following example would return data sources whose animal attribute is neither cat nor dog.

"notIn": { "key": "animal", "value": ["cat", "dog"] }

- … - `orAll` RetrievalFilter[] — Knowledge base data sources are returned if their metadata attributes fulfill at least one of the filter conditions inside this list. - … - `startsWith` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value starts with the value in this object. This filter is currently only supported for Amazon OpenSearch Serverless vector stores.

The following example would return data sources with an animal attribute starts with ca (for example, cat or camel).

"startsWith": { "key": "animal", "value": "ca" }

- … - `stringContains` object —

Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is one of the following:

- … - `maxNumberOfResults` integer — The maximum number of results to return. - `description` string — A description of the retriever's purpose. - `userContext` object — Contains information about the user making the request. Use this to pass user identity information for access control filtering, so that retrieval results only include documents the user is authorized to access. - `userId` string — The identifier of the user making the retrieval request. ## Response `200` Success - AgenticRetrieveStreamResponse — Response structure for the agentic retrieve stream operation. - `stream` object, required — The output stream containing retrieval results and trace events. - `accessDeniedException` object — Access to the resource was denied. - `message` string - `badGatewayException` object — A bad gateway error occurred. - `message` string - `resourceName` string — The name of the dependency that caused the issue, such as Amazon Bedrock, Lambda, or STS. - `conflictException` object — A conflict occurred with the current state of the resource. - `message` string - `dependencyFailedException` object — A dependency failed during the operation. - `message` string - `resourceName` string — The name of the dependency that caused the issue, such as Amazon Bedrock, Lambda, or STS. - `internalServerException` object — An internal server error occurred. - `message` string - `reason` string — The reason for the exception. If the reason is BEDROCK_MODEL_INVOCATION_SERVICE_UNAVAILABLE, the model invocation service is unavailable. Retry your request. - `resourceNotFoundException` object — The specified resource was not found. - `message` string - `responseEvent` object — A chunk of the generated answer. Emitted only when generateResponse is true. - `text` string, required — The generated text chunk. - `result` object — A retrieval result event containing the retrieved items. - `generatedResponse` object — The generated response. Present only when generateResponse is true. - `answer` string, required — The generated answer text. - `citations` AgenticRetrieveCitation[] — Citations mapping spans of the answer to supporting results. - `endIndex` integer, required — Character offset end (exclusive) in the answer text. - `references` AgenticRetrieveCitationReference[], required — References to results that support this span. - `resultIndex` integer, required — Index into the results array on the same event. - `startIndex` integer, required — Character offset start in the answer text. - `nextToken` string — Opaque continuation token for paginated results. - `results` object[], required — The list of retrieved result items. - `content` object, required — The retrieved content. - `byteContent` string — The binary content of the retrieved item. - `mimeType` string, required — The MIME type of the retrieved content. - `text` string — The text content of the retrieved item. - `metadata` object — Metadata associated with the retrieved item. - `sourceRetriever` object, required — The source retriever that produced this result. - `identifier` string, required — The unique identifier of the source retriever. - `serviceQuotaExceededException` object — The service quota has been exceeded. - `message` string - `throttlingException` object — The request was throttled. - `message` string - `traceEvent` object — A trace event providing visibility into the retrieval process. - `attributes` object, required — The attributes describing the trace event details. - `actions` object[] — The list of actions taken during this step. - `fullDocumentExpansion` object — Details of a full document expansion action. - `documentId` string — The identifier of the document to expand. - `sourceRetriever` object — The source retriever associated with the document. - … - `retrieve` object — Details of the retrieve action. - `inputQuery` object, required — The input query used for retrieval. - … - `sourceRetrievers` object[], required — The list of source retrievers targeted by this action. - … - `failures` object[] — Failures that occurred during this step. - `message` string, required — A message describing the failure. - `message` string, required — A human-readable message describing the trace event. - `retrievalMetadata` object[] — Metadata about the retrieval sources used. - `identifier` string — The identifier of the retrieval source. - `retrievalType` 'BedrockKnowledgeBase' — The type of retrieval source. - `retrievalResponse` object[] — The retrieval results from this step. - `content` object — The retrieved content. - `byteContent` string — The binary content of the retrieved item. - `mimeType` string, required — The MIME type of the retrieved content. - `text` string — The text content of the retrieved item. - `metadata` object — Metadata associated with the retrieved item. - `sourceRetriever` object — The source retriever that produced this result. - `identifier` string, required — The unique identifier of the source retriever. - `status` 'IN_PROGRESS' | 'SUCCEEDED' | 'FAILED', required — The status of the current step. - `step` 'Planning' | 'Retrieval' | 'SpeculativeRetrieval' | 'FullDocumentExpansion', required — The current step in the retrieval process. - `warnings` object[] — Warnings generated during this step. - `guardrail` object — A warning from a guardrail evaluation. - `action` 'INTERVENED' | 'NONE', required — The action taken by the guardrail. - `id` string, required — The unique identifier of the guardrail. - `message` string — A message describing the guardrail evaluation result. - `version` string, required — The version of the guardrail. - `message` object — A general warning message. - `message` string, required — The warning message text. - `id` string, required — The unique identifier of the trace event. - `timestamp` integer, required — The timestamp when the trace event occurred. - `validationException` object — The request validation failed. - `message` string ## Other responses - `480` — ResourceNotFoundException - `481` — ConflictException - `482` — ValidationException - `483` — InternalServerException - `484` — DependencyFailedException - `485` — BadGatewayException - `486` — ThrottlingException - `487` — AccessDeniedException - `488` — ServiceQuotaExceededException --- [API](https://skmtc.net/aws/apis/bedrock-agent-runtime.md) · [All operations](https://skmtc.net/aws/apis/bedrock-agent-runtime/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/aws/bedrock-agent-runtime/versions/fe358131c0ad/schema)