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 Syntax

POST /agenticRetrieveStream HTTP/1.1
Content-type: application/json

{
   "agenticRetrieveConfiguration": { 
      "foundationModelConfiguration": { 
         "bedrockFoundationModelConfiguration": { 
            "modelConfiguration": { 
               "modelArn": "string"
            }
         },
         "type": "string"
      },
      "foundationModelType": "string",
      "maxAgentIteration": number,
      "rerankingConfiguration": { 
         "bedrockRerankingConfiguration": { 
            "modelConfiguration": { 
               "modelArn": "string"
            }
         },
         "type": "string"
      },
      "rerankingModelType": "string"
   },
   "generateResponse": boolean,
   "messages": [ 
      { 
         "content": { 
            "text": "string"
         },
         "role": "string"
      }
   ],
   "nextToken": "string",
   "policyConfiguration": { 
      "bedrockGuardrailConfiguration": { 
         "guardrailId": "string",
         "guardrailVersion": "string"
      }
   },
   "retrievers": [ 
      { 
         "configuration": { ... },
         "description": "string"
      }
   ],
   "userContext": { 
      "userId": "string"
   }
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

Response Syntax

HTTP/1.1 200
Content-type: application/json

{
   "accessDeniedException": { 
   },
   "badGatewayException": { 
   },
   "conflictException": { 
   },
   "dependencyFailedException": { 
   },
   "internalServerException": { 
   },
   "resourceNotFoundException": { 
   },
   "responseEvent": { 
      "text": "string"
   },
   "result": { 
      "generatedResponse": { 
         "answer": "string",
         "citations": [ 
            { 
               "endIndex": number,
               "references": [ 
                  { 
                     "resultIndex": number
                  }
               ],
               "startIndex": number
            }
         ]
      },
      "nextToken": "string",
      "results": [ 
         { 
            "content": { 
               "byteContent": blob,
               "mimeType": "string",
               "text": "string"
            },
            "metadata": { 
               "string" : JSON value 
            },
            "sourceRetriever": { 
               "identifier": "string"
            }
         }
      ]
   },
   "serviceQuotaExceededException": { 
   },
   "throttlingException": { 
   },
   "traceEvent": { 
      "attributes": { 
         "actions": [ 
            { 
               "fullDocumentExpansion": { 
                  "documentId": "string",
                  "sourceRetriever": { 
                     "identifier": "string"
                  }
               },
               "retrieve": { 
                  "inputQuery": { 
                     "text": "string"
                  },
                  "sourceRetrievers": [ 
                     { 
                        "identifier": "string"
                     }
                  ]
               }
            }
         ],
         "failures": [ 
            { 
               "message": "string"
            }
         ],
         "message": "string",
         "retrievalMetadata": [ 
            { 
               "identifier": "string",
               "retrievalType": "string"
            }
         ],
         "retrievalResponse": [ 
            { 
               "content": { 
                  "byteContent": blob,
                  "mimeType": "string",
                  "text": "string"
               },
               "metadata": { 
                  "string" : JSON value 
               },
               "sourceRetriever": { 
                  "identifier": "string"
               }
            }
         ],
         "status": "string",
         "step": "string",
         "warnings": [ 
            { ... }
         ]
      },
      "id": "string",
      "timestamp": number
   },
   "validationException": { 
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

Errors

For information about the errors that are common to all actions, see Common Error Types.

Examples

Send a basic query using a managed model

The following example uses the managed foundation model type to query a knowledge base with agentic retrieval. When you set foundationModelType to MANAGED, the service selects the optimal model for you.

Sample Request

POST /agenticRetrieveStream HTTP/1.1
Content-type: application/json

{
    "messages": [
        {
            "content": {
                "text": "What are the main benefits of using Amazon Bedrock?"
            },
            "role": "user"
        }
    ],
    "retrievers": [
        {
            "description": "Knowledge base about Amazon Bedrock documentation",
            "configuration": {
                "knowledgeBase": {
                    "knowledgeBaseId": "KB12345678"
                }
            }
        }
    ],
    "agenticRetrieveConfiguration": {
        "foundationModelType": "MANAGED",
        "rerankingModelType": "MANAGED"
    }
}

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: