2026/10/19 - Agents for Amazon Bedrock - 7 new api methods
Changes Adds Retrieval Instructions for Amazon Bedrock Knowledge Bases. Create, get, update, delete, list, and version customer-authored instructions that guide how a knowledge base retrieves and answers, with content review before use.
Lists the numbered versions of a retrieval instruction, newest first. DRAFT is not listed; read it with GetRetrievalInstruction without retrievalInstructionVersion. Results are paginated. Use the nextToken parameter to retrieve additional results.
See also: AWS API Documentation
Request Syntax
client.list_retrieval_instruction_versions(
retrievalInstructionId='string',
maxResults=123,
nextToken='string'
)
string
[REQUIRED]
The identifier of the retrieval instruction whose versions to list.
integer
Specifies the maximum number of versions to return in a single page. The service enforces the effective upper bound.
string
The pagination token from a previous ListRetrievalInstructionVersions response.
dict
Response Syntax
{
'retrievalInstructionVersionSummaries': [
{
'version': 'string',
'createdAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
retrievalInstructionVersionSummaries (list) --
The version summaries in this page, newest first.
(dict) --
A summary of one numbered version of a retrieval instruction, without the content.
version (string) --
The version number.
createdAt (datetime) --
When this version was created.
nextToken (string) --
The pagination token to pass to the next ListRetrievalInstructionVersions call, absent on the last page.
Creates an immutable numbered version from the retrieval instruction's current reviewed content. The service creates the version synchronously.
The service numbers versions from 1 and assigns them in order, never reusing a number.
See also: AWS API Documentation
Request Syntax
client.create_retrieval_instruction_version(
retrievalInstructionId='string',
description='string',
clientToken='string'
)
string
[REQUIRED]
The identifier of the retrieval instruction to version.
string
A description of this version. Independent of the retrieval instruction's own description.
string
A caller-supplied token that makes a retried call return the version created by the first call rather than a second version. The window is 8 hours.
This field is autopopulated if not provided.
dict
Response Syntax
{
'retrievalInstructionId': 'string',
'retrievalInstructionArn': 'string',
'version': 'string',
'createdAt': datetime(2015, 1, 1),
'description': 'string'
}
Response Structure
(dict) --
retrievalInstructionId (string) --
The identifier of the retrieval instruction.
retrievalInstructionArn (string) --
The ARN of the retrieval instruction. Versions do not have their own ARN.
version (string) --
The number of the version created. Versions are numbered from 1 and allocated monotonically; a number is never reused, even after the version is deleted.
createdAt (datetime) --
When this version was created.
description (string) --
The description of this version, when one was supplied.
Gets a retrieval instruction. Also used to poll the terminal reporting of an asynchronous create or update.
See also: AWS API Documentation
Request Syntax
client.get_retrieval_instruction(
retrievalInstructionId='string',
retrievalInstructionVersion='string'
)
string
[REQUIRED]
The identifier of the retrieval instruction to get.
string
The version to return: a version number, or DRAFT for the retrieval instruction's current reviewed content. When omitted, DRAFT is used. This default is permanent: omitting retrievalInstructionVersion will never resolve to a numbered version.
dict
Response Syntax
{
'retrievalInstructionId': 'string',
'retrievalInstructionArn': 'string',
'name': 'string',
'status': 'ACTIVE'|'INACTIVE',
'lastTransitionStatus': 'CREATING'|'UPDATING'|'CREATE_SUCCESSFUL'|'CREATE_FAILED'|'UPDATE_SUCCESSFUL'|'UPDATE_FAILED',
'instruction': {
'retrievalGuidance': 'string',
'persona': 'string',
'answerFormat': 'string',
'answerPolicy': 'string'
},
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1),
'description': 'string',
'customerEncryptionKeyArn': 'string',
'lastTransitionStatusReasons': [
{
'fieldName': 'RETRIEVAL_GUIDANCE'|'PERSONA'|'ANSWER_FORMAT'|'ANSWER_POLICY',
'code': 'CONTENT_REJECTED'|'CLIENT_ERROR'|'INTERNAL_ERROR',
'message': 'string'
},
],
'version': 'string',
'latestVersion': 'string'
}
Response Structure
(dict) --
retrievalInstructionId (string) --
The identifier of the retrieval instruction.
retrievalInstructionArn (string) --
The ARN of the retrieval instruction.
name (string) --
The name of the retrieval instruction.
status (string) --
Specifies whether you can use the instruction. You can resolve only an ACTIVE instruction at retrieval time. Monotone: INACTIVE to ACTIVE once, never back. Numbered versions are always ACTIVE.
lastTransitionStatus (string) --
The outcome or in-progress state of the most recent create or update. CREATING or UPDATING means the operation is still running. Independent of status. Always has a value from the create 202 onward. On a numbered version this is always CREATE_SUCCESSFUL: a version is created once, from reviewed content, and is immutable.
instruction (dict) --
The reviewed content this instruction serves — what AgenticRetrieveStream resolves while status is ACTIVE. Absent until the first create review passes. Always present on a numbered version.
retrievalGuidance (string) --
How to interpret and decompose the question, and what to prioritise when searching.
persona (string) --
Who the assistant is: identity, tone and language.
answerFormat (string) --
How the answer is structured, including how sources are cited.
answerPolicy (string) --
Whether and how to answer: how strongly an answer must be supported, and what to do with questions outside scope.
createdAt (datetime) --
When the retrieval instruction was created. On a numbered version, when that version was created.
updatedAt (datetime) --
When the retrieval instruction was last updated. Equal to createdAt on a numbered version, which is immutable.
description (string) --
A description of the retrieval instruction. On a numbered version, the description of that version.
customerEncryptionKeyArn (string) --
The ARN of the customer managed KMS key protecting this content, when one was supplied at create.
lastTransitionStatusReasons (list) --
Why the most recent create or update was rejected. One entry for each rejected field, or a single entry when the review itself failed. Each entry has a machine-readable code and a message, and names the field when it applies to one. The service includes this field only when lastTransitionStatus is CREATE_FAILED or UPDATE_FAILED. Never present on a numbered version.
(dict) --
One reason the most recent create or update did not succeed. code drives programmatic branching (fix the text, fix the configuration, or retry); message carries the specific cause.
fieldName (string) --
The instruction field this entry is about. Present on review rejections of a specific field; absent when the failure applies to the whole review, because a client-side execution failure or a service fault has no single field.
code (string) --
Stable, machine-readable classification by fault attribution. Valid values:
CONTENT_REJECTED – The review rejected the named field's content; revise the text and resubmit.
CLIENT_ERROR – The review could not run for a customer-side reason, for example the customer managed AWS KMS key could not be used; fix the configuration and resubmit.
INTERNAL_ERROR – The review could not complete due to a service fault; retry the create or update.
New values may be added over time; your client should tolerate values it does not recognize and treat them as a failure.
message (string) --
Human-readable explanation of the specific cause. Never contains the customer's own text.
version (string) --
The version this response describes: a version number, or DRAFT.
latestVersion (string) --
The largest version number that currently exists for this retrieval instruction, that is, the newest version you can retrieve. Present only on a DRAFT read, and only when at least one version exists. Because version numbers are never reused, deleting versions can leave gaps: this is the newest existing version, not a count and not the highest number ever created.
Deletes a retrieval instruction or a single version of it. Omit retrievalInstructionVersion to delete the retrieval instruction itself; the service rejects that request with ConflictException while the retrieval instruction has versions or while lastTransitionStatus is CREATING or UPDATING. Specify retrievalInstructionVersion to delete only that version; the retrieval instruction and its other versions are unaffected.
See also: AWS API Documentation
Request Syntax
client.delete_retrieval_instruction(
retrievalInstructionId='string',
retrievalInstructionVersion='string'
)
string
[REQUIRED]
The identifier of the retrieval instruction to delete.
string
The version to delete. Omit this field to delete the retrieval instruction itself, which you can do only when it has no versions; while any version exists the service rejects the request with ConflictException. You cannot delete DRAFT on its own; deleting the retrieval instruction removes it.
dict
Response Syntax
{
'retrievalInstructionId': 'string',
'retrievalInstructionArn': 'string',
'version': 'string'
}
Response Structure
(dict) --
retrievalInstructionId (string) --
The identifier of the deleted retrieval instruction.
retrievalInstructionArn (string) --
The ARN of the retrieval instruction.
version (string) --
The version that you deleted. Absent when you deleted the whole retrieval instruction.
Creates a new retrieval instruction. The retrieval instruction is usable once its status becomes ACTIVE. Use GetRetrievalInstruction to check whether it is ready.
See also: AWS API Documentation
Request Syntax
client.create_retrieval_instruction(
clientToken='string',
name='string',
instruction={
'retrievalGuidance': 'string',
'persona': 'string',
'answerFormat': 'string',
'answerPolicy': 'string'
},
description='string',
customerEncryptionKeyArn='string',
tags={
'string': 'string'
}
)
string
A caller-supplied token that makes a retried create return the existing resource rather than a second one. The window is 8 hours.
This field is autopopulated if not provided.
string
[REQUIRED]
Specifies the name of the retrieval instruction.
dict
[REQUIRED]
The instruction content, as a set of named fields. Get does not return this field until the create review passes.
retrievalGuidance (string) --
How to interpret and decompose the question, and what to prioritise when searching.
persona (string) --
Who the assistant is: identity, tone and language.
answerFormat (string) --
How the answer is structured, including how sources are cited.
answerPolicy (string) --
Whether and how to answer: how strongly an answer must be supported, and what to do with questions outside scope.
string
Specifies a description of the retrieval instruction.
string
The Amazon Resource Name (ARN) of a customer managed AWS Key Management Service (AWS KMS) key used to encrypt the instruction content at rest. If you omit it, the service uses an AWS owned key. You fix the key at create and cannot change it later.
dict
Tags for the retrieval instruction.
(string) --
(string) --
dict
Response Syntax
{
'retrievalInstructionId': 'string',
'retrievalInstructionArn': 'string',
'name': 'string',
'status': 'ACTIVE'|'INACTIVE',
'lastTransitionStatus': 'CREATING'|'UPDATING'|'CREATE_SUCCESSFUL'|'CREATE_FAILED'|'UPDATE_SUCCESSFUL'|'UPDATE_FAILED',
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
retrievalInstructionId (string) --
The identifier of the newly created retrieval instruction.
retrievalInstructionArn (string) --
The ARN of the newly created retrieval instruction.
name (string) --
The name of the retrieval instruction.
status (string) --
Always INACTIVE on this response. The content review has not run when this call returns, so the resource is not yet usable.
lastTransitionStatus (string) --
Always CREATING on this response. Poll GetRetrievalInstruction until this member is neither CREATING nor UPDATING, then read the outcome from it.
createdAt (datetime) --
When you created the retrieval instruction.
updatedAt (datetime) --
When the retrieval instruction was last updated.
Lists the retrieval instructions in the caller's account. Results are paginated. Use the nextToken parameter to retrieve additional results.
See also: AWS API Documentation
Request Syntax
client.list_retrieval_instructions(
status='ACTIVE'|'INACTIVE',
maxResults=123,
nextToken='string'
)
string
Return only instructions with this availability status.
integer
The maximum number of results to return in a single page. The effective upper bound is enforced service-side.
string
The pagination token from a previous ListRetrievalInstructions response.
dict
Response Syntax
{
'retrievalInstructionSummaries': [
{
'retrievalInstructionId': 'string',
'retrievalInstructionArn': 'string',
'name': 'string',
'status': 'ACTIVE'|'INACTIVE',
'lastTransitionStatus': 'CREATING'|'UPDATING'|'CREATE_SUCCESSFUL'|'CREATE_FAILED'|'UPDATE_SUCCESSFUL'|'UPDATE_FAILED',
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1),
'description': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
retrievalInstructionSummaries (list) --
The retrieval instruction summaries in this page.
(dict) --
A summary of a retrieval instruction, without the content.
retrievalInstructionId (string) --
The identifier of the retrieval instruction.
retrievalInstructionArn (string) --
The ARN of the retrieval instruction.
name (string) --
The name of the retrieval instruction.
status (string) --
Whether the instruction can be used. Only ACTIVE is resolvable at retrieval time.
lastTransitionStatus (string) --
The outcome or in-progress state of the most recent create or update of the retrieval instruction.
createdAt (datetime) --
When you created the retrieval instruction.
updatedAt (datetime) --
When the retrieval instruction was last updated.
description (string) --
A description of the retrieval instruction.
nextToken (string) --
The pagination token to pass to the next ListRetrievalInstructions call, absent on the last page.
Updates the content of a retrieval instruction. The update is processed asynchronously; the stored content is a candidate until content review passes, and the served content does not change while the update is in flight. The service rejects the request with ConflictException while lastTransitionStatus is CREATING or UPDATING.
See also: AWS API Documentation
Request Syntax
client.update_retrieval_instruction(
retrievalInstructionId='string',
instruction={
'retrievalGuidance': 'string',
'persona': 'string',
'answerFormat': 'string',
'answerPolicy': 'string'
},
description='string'
)
string
[REQUIRED]
The identifier of the retrieval instruction to update.
dict
[REQUIRED]
The replacement instruction content. This is a full replacement of all four fields, not a patch. During UPDATING, Get continues to return the previously-served content until the update review passes.
retrievalGuidance (string) --
How to interpret and decompose the question, and what to prioritise when searching.
persona (string) --
Who the assistant is: identity, tone and language.
answerFormat (string) --
How the answer is structured, including how sources are cited.
answerPolicy (string) --
Whether and how to answer: how strongly an answer must be supported, and what to do with questions outside scope.
string
A replacement description; applied together with the content when the review passes. Omit to clear.
dict
Response Syntax
{
'retrievalInstructionId': 'string',
'retrievalInstructionArn': 'string',
'name': 'string',
'status': 'ACTIVE'|'INACTIVE',
'lastTransitionStatus': 'CREATING'|'UPDATING'|'CREATE_SUCCESSFUL'|'CREATE_FAILED'|'UPDATE_SUCCESSFUL'|'UPDATE_FAILED',
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
retrievalInstructionId (string) --
The identifier of the retrieval instruction.
retrievalInstructionArn (string) --
The ARN of the retrieval instruction.
name (string) --
The name of the retrieval instruction.
status (string) --
Whether the instruction can be used. An update never lowers status. Unchanged from the previous value on this response.
lastTransitionStatus (string) --
Always UPDATING on this response. Poll GetRetrievalInstruction until this member is neither CREATING nor UPDATING, then read the outcome from it.
createdAt (datetime) --
When you created the retrieval instruction.
updatedAt (datetime) --
When the retrieval instruction was last updated.