2026/05/21 - Amazon Bedrock AgentCore Control - 11 new api methods
Changes Adds dataset management APIs for creating, versioning, and managing evaluation datasets.
Creates a new Dataset resource asynchronously.
Returns immediately with status CREATING. Poll GetDataset until status transitions to ACTIVE or CREATE_FAILED (with failureReason).
See also: AWS API Documentation
Request Syntax
client.create_dataset(
clientToken='string',
datasetName='string',
description='string',
source={
'inlineExamples': {
'examples': [
{...}|[...]|123|123.4|'string'|True|None,
]
},
's3Source': {
's3Uri': 'string'
}
},
schemaType='AGENTCORE_EVALUATION_PREDEFINED_V1'|'AGENTCORE_EVALUATION_SIMULATED_V1',
kmsKeyArn='string',
tags={
'string': 'string'
}
)
string
Optional idempotency token.
This field is autopopulated if not provided.
string
[REQUIRED]
Human-readable name for the dataset. Unique within the account (case-insensitive). Immutable after creation.
string
A description of the dataset.
dict
[REQUIRED]
Source of initial examples. Provide either inline examples or an S3 URI pointing to a JSONL file.
inlineExamples (dict) --
Inline examples provided directly in the request body.
examples (list) -- [REQUIRED]
Examples to add. Each example is assigned an auto-generated UUID.
(:ref:`document<document>`) --
s3Source (dict) --
S3 URI pointing to a JSONL file in the customer's bucket. The service reads this file using the caller's FAS credentials.
s3Uri (string) -- [REQUIRED]
S3 URI of the JSONL file (e.g. s3://my-bucket/path/to/examples.jsonl).
string
[REQUIRED]
Versioned schema type governing the structure of examples. Immutable after creation.
string
Optional AWS KMS key ARN for SSE-KMS on service S3 writes.
dict
A map of tag keys and values to assign to the dataset.
(string) --
(string) --
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'createdAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the created dataset.
datasetId (string) --
The unique identifier of the created dataset.
status (string) --
Always CREATING immediately after this call. Poll GetDataset until status == ACTIVE (draftStatus=MODIFIED) or CREATE_FAILED.
createdAt (datetime) --
The timestamp when the dataset was created.
Deletes specific examples by ID from DRAFT.
Validation: All example IDs are validated before any deletes occur. If any ID does not exist in DRAFT, the entire batch is rejected with ResourceNotFoundException — no examples are deleted (all-or-nothing semantics).
Asynchronous: Operates in-place on DRAFT. No version bump occurs. Use CreateDatasetVersion to publish DRAFT as a new numbered version.
State guard: Returns ConflictException (DATASET_NOT_READY) if the dataset status is not in {DRAFT, ACTIVE}.
See also: AWS API Documentation
Request Syntax
client.delete_dataset_examples(
datasetId='string',
clientToken='string',
exampleIds=[
'string',
]
)
string
[REQUIRED]
The unique identifier of the dataset.
string
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
list
[REQUIRED]
The IDs of the examples to delete.
(string) --
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'deletedCount': 123,
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
status (string) --
The current status of the dataset.
deletedCount (integer) --
The number of examples deleted.
updatedAt (datetime) --
The timestamp when the examples were deleted.
Publishes the current DRAFT as a new numbered version.
Snapshots the DRAFT examples as the next version (1, 2, 3, ...). The DRAFT is preserved and remains editable after publishing. Returns immediately with status UPDATING. Poll GetDataset until status transitions to ACTIVE (draftStatus=UNMODIFIED) or UPDATE_FAILED.
State guard: Returns ConflictException (DATASET_NOT_READY) if status is in {CREATING, UPDATING, DELETING}, or DATASET_IN_FAILED_STATE if status is in {CREATE_FAILED, DELETE_FAILED}.
Quota: MAX_VERSIONS_PER_DATASET applies to published versions only (not DRAFT).
See also: AWS API Documentation
Request Syntax
client.create_dataset_version(
datasetId='string',
clientToken='string'
)
string
[REQUIRED]
The unique identifier of the dataset to publish a version for.
string
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'datasetVersion': 'string',
'createdAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
status (string) --
Always UPDATING immediately after this call. Poll GetDataset until status == ACTIVE (draftStatus=UNMODIFIED) or UPDATE_FAILED.
datasetVersion (string) --
The version being created.
createdAt (datetime) --
The timestamp when the version creation was initiated.
Lists all datasets in the caller's account, paginated. No presigned URLs in list results.
See also: AWS API Documentation
Request Syntax
client.list_datasets(
nextToken='string',
maxResults=123
)
string
The token for the next page of results.
integer
The maximum number of datasets to return per page.
dict
Response Syntax
{
'datasets': [
{
'datasetArn': 'string',
'datasetId': 'string',
'datasetName': 'string',
'description': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'draftStatus': 'MODIFIED'|'UNMODIFIED',
'schemaType': 'AGENTCORE_EVALUATION_PREDEFINED_V1'|'AGENTCORE_EVALUATION_SIMULATED_V1',
'exampleCount': 123,
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
datasets (list) --
The list of datasets.
(dict) --
Summary information about a dataset.
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
datasetName (string) --
The name of the dataset.
description (string) --
The description of the dataset.
status (string) --
The current status of the dataset.
draftStatus (string) --
Publish synchronization state. Only authoritative when status == ACTIVE.
schemaType (string) --
The schema type of the dataset.
exampleCount (integer) --
The number of examples in the dataset.
createdAt (datetime) --
The timestamp when the dataset was created.
updatedAt (datetime) --
The timestamp when the dataset was last updated.
nextToken (string) --
The token for the next page of results, or null if there are no more results.
Lists all published versions of a dataset, sorted by version number descending (newest first). Does not include the DRAFT working copy.
State guard: Allowed for all statuses including DELETING.
See also: AWS API Documentation
Request Syntax
client.list_dataset_versions(
datasetId='string',
nextToken='string',
maxResults=123
)
string
[REQUIRED]
The unique identifier of the dataset.
string
The token for the next page of results.
integer
The maximum number of versions to return per page.
dict
Response Syntax
{
'versions': [
{
'datasetVersion': 'string',
'exampleCount': 123,
'createdAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
versions (list) --
The list of published dataset versions.
(dict) --
Summary information about a published dataset version.
datasetVersion (string) --
Dataset version identifier. Accepts "DRAFT" or a non-negative integer string.
"DRAFT" refers to the single mutable working copy of the dataset.
Always present after CreateDataset ingestion completes.
Content changes in-place when examples are added, updated, or deleted.
NOT tracked as a DDB DatasetVersionItem — state lives in S3 (draft/manifest.json, draft/dataset.jsonl) and the DatasetItem.exampleCount field.
Default for read operations when ?datasetVersion is absent.
An integer string (e.g. "1", "2", "3") refers to a published, immutable snapshot created by CreateDatasetVersion. Once created, a published version's content never changes. Stored as a DDB DatasetVersionItem (SK=VERSION#{zero-padded-N}).
exampleCount (integer) --
The number of examples in this version.
createdAt (datetime) --
The timestamp when this version was published.
nextToken (string) --
The token for the next page of results, or null if there are no more results.
Retrieves dataset metadata only.
Use ?datasetVersion=DRAFT or ?datasetVersion=N to retrieve a specific version's metadata. If absent, defaults to DRAFT (the mutable working copy). Returns ResourceNotFoundException if the specified version is not found.
Initial state after CreateDataset: When CreateDataset completes successfully (status transitions to ACTIVE), only a DRAFT working copy exists. No published versions exist until CreateDatasetVersion is called. At this point draftStatus is MODIFIED because the DRAFT has content that has never been published.
Default version behavior: When datasetVersion is omitted, the operation returns the DRAFT working copy. To retrieve a specific published version, pass the version number as a string (e.g. ?datasetVersion=1).
State guard: Allowed for all statuses including DELETING. Returns the dataset record with its current status so callers can observe the deletion in progress.
For paginated example IDs use ListDatasetExamples.
See also: AWS API Documentation
Request Syntax
client.get_dataset(
datasetId='string',
datasetVersion='string'
)
string
[REQUIRED]
The unique identifier of the dataset to retrieve.
string
Version to retrieve: "DRAFT" or a version number. Defaults to DRAFT if absent.
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'datasetVersion': 'string',
'datasetName': 'string',
'description': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'draftStatus': 'MODIFIED'|'UNMODIFIED',
'failureReason': 'string',
'schemaType': 'AGENTCORE_EVALUATION_PREDEFINED_V1'|'AGENTCORE_EVALUATION_SIMULATED_V1',
'kmsKeyArn': 'string',
'exampleCount': 123,
'downloadUrl': 'string',
'downloadUrlExpiresAt': datetime(2015, 1, 1),
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1),
'tags': {
'string': 'string'
}
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
datasetVersion (string) --
The resolved version: "DRAFT" (default) or the requested version number.
datasetName (string) --
The name of the dataset.
description (string) --
The description of the dataset.
status (string) --
The current status of the dataset.
draftStatus (string) --
Publish synchronization state. Only authoritative when status == ACTIVE. MODIFIED — DRAFT has unpublished changes (or no published versions yet). UNMODIFIED — DRAFT matches the latest published version exactly.
failureReason (string) --
Populated when status is CREATE_FAILED, UPDATE_FAILED, or DELETE_FAILED.
schemaType (string) --
The schema type declared at create time. Immutable after creation.
kmsKeyArn (string) --
AWS KMS key ARN used for SSE-KMS on service S3 writes, if configured.
exampleCount (integer) --
Example count for DRAFT.
downloadUrl (string) --
Presigned S3 URL to download the consolidated dataset.jsonl file for the resolved version (DRAFT or published). TTL: 5 minutes. Omitted if the file does not yet exist (e.g. during CREATING) or on presign failure.
downloadUrlExpiresAt (datetime) --
Expiry timestamp for downloadUrl.
createdAt (datetime) --
The timestamp when the dataset was created.
updatedAt (datetime) --
The timestamp when the dataset was last updated.
tags (dict) --
The tags associated with the dataset.
(string) --
(string) --
Returns paginated examples from the dataset.
Version-pinned pagination: The server embeds the resolved version in the nextToken. Once pagination begins, all subsequent pages are pinned to that version regardless of concurrent mutations or whether datasetVersion is passed on subsequent requests. The datasetVersion query parameter is only used for the first request (when nextToken is absent); if omitted, defaults to DRAFT.
State guard: Allowed for all statuses including DELETING.
See also: AWS API Documentation
Request Syntax
client.list_dataset_examples(
datasetId='string',
datasetVersion='string',
maxResults=123,
nextToken='string'
)
string
[REQUIRED]
The unique identifier of the dataset.
string
Version to paginate: "DRAFT" or a version number. Defaults to DRAFT if absent. Only used on the first request (when nextToken is absent). For subsequent pages, the version is extracted from the nextToken and this parameter is ignored.
integer
Maximum number of examples to return per page. Default: 1000. Min: 1, max: 1000. Response size is validated against 5 MB limit after reading. For bulk access to all examples, use the downloadUrl field from GetDataset.
string
The token for the next page of results.
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'datasetVersion': 'string',
'examples': [
{...}|[...]|123|123.4|'string'|True|None,
],
'nextToken': 'string'
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
datasetVersion (string) --
The version returned.
examples (list) --
Paginated example content. Each element is a JSON object containing at least an exampleId field plus the schema-specific content fields.
(:ref:`document<document>`) --
nextToken (string) --
The token for the next page of results, or null if there are no more results.
Adds examples to the dataset's DRAFT.
Validation: All examples are validated against the dataset's schemaType before any writes occur. If any example fails validation, the entire batch is rejected with ValidationException — no examples are written (all-or-nothing semantics).
Asynchronous: Operates in-place on DRAFT. No version bump occurs. Use CreateDatasetVersion to publish DRAFT as a new numbered version.
State guard: Returns ConflictException (DATASET_NOT_READY) if the dataset status is not in {DRAFT, ACTIVE}.
Request size limit: Max 5 MB total request body. Max 1000 examples per call.
See also: AWS API Documentation
Request Syntax
client.add_dataset_examples(
datasetId='string',
clientToken='string',
source={
'inlineExamples': {
'examples': [
{...}|[...]|123|123.4|'string'|True|None,
]
},
's3Source': {
's3Uri': 'string'
}
}
)
string
[REQUIRED]
The unique identifier of the dataset to add examples to.
string
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
dict
[REQUIRED]
Source of examples to add. Provide either inline examples or an S3 URI pointing to a JSONL file.
inlineExamples (dict) --
Inline examples provided directly in the request body.
examples (list) -- [REQUIRED]
Examples to add. Each example is assigned an auto-generated UUID.
(:ref:`document<document>`) --
s3Source (dict) --
S3 URI pointing to a JSONL file in the customer's bucket. The service reads this file using the caller's FAS credentials.
s3Uri (string) -- [REQUIRED]
S3 URI of the JSONL file (e.g. s3://my-bucket/path/to/examples.jsonl).
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'addedCount': 123,
'updatedAt': datetime(2015, 1, 1),
'exampleIds': [
'string',
]
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
status (string) --
The current status of the dataset.
addedCount (integer) --
The number of examples added.
updatedAt (datetime) --
The timestamp when the examples were added.
exampleIds (list) --
IDs of all added examples (auto-generated UUIDs).
(string) --
Deletes a dataset version or an entire dataset (all versions + name claim). Asynchronous 202.
State transitions:
If datasetVersion is absent (full delete): status transitions to DELETING immediately.
If datasetVersion is provided (version-specific delete): status transitions to UPDATING.
State guard (full delete): Returns ConflictException (DATASET_NOT_READY) if the dataset status is in {CREATING, UPDATING}. Deletion is allowed from ACTIVE, CREATE_FAILED, UPDATE_FAILED, and DELETE_FAILED states.
State guard (version-specific delete): Returns ConflictException (DATASET_NOT_READY) if the dataset status is not in {ACTIVE, CREATE_FAILED, UPDATE_FAILED}.
Fails with ConflictException (REFERENCED_BY_EVAL_JOB) if referenced by an active evaluation job (full delete only).
If the delete workflow fails after retries, status is set to DELETE_FAILED (full delete) or UPDATE_FAILED (version-specific delete). Calling DeleteDataset on a DELETE_FAILED dataset re-triggers the delete workflow (idempotent retry path).
Version parameter:
If datasetVersion is absent: deletes ALL versions and the Dataset record itself.
If datasetVersion is provided: deletes only that specific DatasetVersion. Returns ResourceNotFoundException if the specified version does not exist.
See also: AWS API Documentation
Request Syntax
client.delete_dataset(
datasetId='string',
datasetVersion='string'
)
string
[REQUIRED]
The unique identifier of the dataset to delete.
string
Optional version to delete. Use "DRAFT" or omit to delete the draft. Returns ResourceNotFoundException if the specified version does not exist.
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'datasetVersion': 'string',
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
status (string) --
The current status of the dataset after the delete request.
datasetVersion (string) --
The version deleted.
updatedAt (datetime) --
The timestamp when the delete was initiated.
Updates multiple existing examples in-place on DRAFT.
Validation: All examples are validated against the dataset's schemaType before any writes occur. If any example fails validation, the entire batch is rejected with ValidationException — no examples are updated (all-or-nothing semantics).
Asynchronous: Operates in-place on DRAFT. No version bump occurs. Use CreateDatasetVersion to publish DRAFT as a new numbered version.
Fails with ResourceNotFoundException if any exampleId does not exist in DRAFT. To add new examples, use AddDatasetExamples instead.
State guard: Returns ConflictException (DATASET_NOT_READY) if the dataset status is not in {DRAFT, ACTIVE}.
Request size limit: Max 5 MB total request body. Max 1000 examples per call.
See also: AWS API Documentation
Request Syntax
client.update_dataset_examples(
datasetId='string',
clientToken='string',
examples=[
{...}|[...]|123|123.4|'string'|True|None,
]
)
string
[REQUIRED]
The unique identifier of the dataset.
string
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
list
[REQUIRED]
Examples to update. Each element is a JSON object containing a required exampleId string field identifying the existing example, plus the replacement fields. The exampleId is extracted and removed before persistence; the remaining document is validated against the dataset's schemaType. Max 1000 examples per call. Total request body must not exceed 5 MB.
(:ref:`document<document>`) --
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'status': 'CREATING'|'UPDATING'|'DELETING'|'ACTIVE'|'CREATE_FAILED'|'UPDATE_FAILED'|'DELETE_FAILED',
'updatedCount': 123,
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the dataset.
datasetId (string) --
The unique identifier of the dataset.
status (string) --
The current status of the dataset.
updatedCount (integer) --
The number of examples updated.
updatedAt (datetime) --
The timestamp when the examples were updated.
Updates a dataset's metadata. Synchronous operation. Only provided fields are updated; omitted fields remain unchanged.
To modify dataset content, use AddDatasetExamples, UpdateDatasetExamples, or DeleteDatasetExamples.
Cannot update: name, schemaType, kmsKeyArn (immutable after creation).
See also: AWS API Documentation
Request Syntax
client.update_dataset(
datasetId='string',
clientToken='string',
description='string'
)
string
[REQUIRED]
The unique identifier of the dataset to update.
string
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If you don't specify this field, a value is randomly generated for you. If this token matches a previous request, the service ignores the request, but doesn't return an error. For more information, see Ensuring idempotency.
This field is autopopulated if not provided.
string
The updated description for the dataset.
dict
Response Syntax
{
'datasetArn': 'string',
'datasetId': 'string',
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
datasetArn (string) --
The Amazon Resource Name (ARN) of the updated dataset.
datasetId (string) --
The unique identifier of the updated dataset.
updatedAt (datetime) --
The timestamp when the dataset was updated.