Interface BedrockRuntimeClient
- All Superinterfaces:
AutoCloseable,AwsClient,SdkAutoCloseable,SdkClient
builder() method.
Describes the API operations for running inference using Amazon Bedrock models.
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final StringValue for looking up the service's metadata from theServiceMetadataProvider.static final String -
Method Summary
Modifier and TypeMethodDescriptiondefault ApplyGuardrailResponseapplyGuardrail(Consumer<ApplyGuardrailRequest.Builder> applyGuardrailRequest) The action to apply a guardrail.default ApplyGuardrailResponseapplyGuardrail(ApplyGuardrailRequest applyGuardrailRequest) The action to apply a guardrail.static BedrockRuntimeClientBuilderbuilder()Create a builder that can be used to configure and create aBedrockRuntimeClient.default ConverseResponseconverse(Consumer<ConverseRequest.Builder> converseRequest) Sends messages to the specified Amazon Bedrock model.default ConverseResponseconverse(ConverseRequest converseRequest) Sends messages to the specified Amazon Bedrock model.default CountTokensResponsecountTokens(Consumer<CountTokensRequest.Builder> countTokensRequest) Returns the token count for a given inference request.default CountTokensResponsecountTokens(CountTokensRequest countTokensRequest) Returns the token count for a given inference request.static BedrockRuntimeClientcreate()Create aBedrockRuntimeClientwith the region loaded from theDefaultAwsRegionProviderChainand credentials loaded from theDefaultCredentialsProvider.default GetAsyncInvokeResponsegetAsyncInvoke(Consumer<GetAsyncInvokeRequest.Builder> getAsyncInvokeRequest) Retrieve information about an asynchronous invocation.default GetAsyncInvokeResponsegetAsyncInvoke(GetAsyncInvokeRequest getAsyncInvokeRequest) Retrieve information about an asynchronous invocation.default InvokeModelResponseinvokeModel(Consumer<InvokeModelRequest.Builder> invokeModelRequest) Invokes the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body.default InvokeModelResponseinvokeModel(InvokeModelRequest invokeModelRequest) Invokes the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body.default ListAsyncInvokesResponselistAsyncInvokes(Consumer<ListAsyncInvokesRequest.Builder> listAsyncInvokesRequest) Lists asynchronous invocations.default ListAsyncInvokesResponselistAsyncInvokes(ListAsyncInvokesRequest listAsyncInvokesRequest) Lists asynchronous invocations.default ListAsyncInvokesIterablelistAsyncInvokesPaginator(Consumer<ListAsyncInvokesRequest.Builder> listAsyncInvokesRequest) This is a variant oflistAsyncInvokes(software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesRequest)operation.default ListAsyncInvokesIterablelistAsyncInvokesPaginator(ListAsyncInvokesRequest listAsyncInvokesRequest) This is a variant oflistAsyncInvokes(software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesRequest)operation.The SDK service client configuration exposes client settings to the user, e.g., ClientOverrideConfigurationstatic ServiceMetadatadefault StartAsyncInvokeResponsestartAsyncInvoke(Consumer<StartAsyncInvokeRequest.Builder> startAsyncInvokeRequest) Starts an asynchronous invocation.default StartAsyncInvokeResponsestartAsyncInvoke(StartAsyncInvokeRequest startAsyncInvokeRequest) Starts an asynchronous invocation.Methods inherited from interface software.amazon.awssdk.utils.SdkAutoCloseable
closeMethods inherited from interface software.amazon.awssdk.core.SdkClient
serviceName
-
Field Details
-
SERVICE_NAME
- See Also:
-
SERVICE_METADATA_ID
Value for looking up the service's metadata from theServiceMetadataProvider.- See Also:
-
-
Method Details
-
applyGuardrail
default ApplyGuardrailResponse applyGuardrail(ApplyGuardrailRequest applyGuardrailRequest) throws AccessDeniedException, ResourceNotFoundException, ThrottlingException, InternalServerException, ServiceUnavailableException, ValidationException, ServiceQuotaExceededException, AwsServiceException, SdkClientException, BedrockRuntimeException The action to apply a guardrail.
For troubleshooting some of the common errors you might encounter when using the
ApplyGuardrailAPI, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide- Parameters:
applyGuardrailRequest-- Returns:
- Result of the ApplyGuardrail operation returned by the service.
- See Also:
-
applyGuardrail
default ApplyGuardrailResponse applyGuardrail(Consumer<ApplyGuardrailRequest.Builder> applyGuardrailRequest) throws AccessDeniedException, ResourceNotFoundException, ThrottlingException, InternalServerException, ServiceUnavailableException, ValidationException, ServiceQuotaExceededException, AwsServiceException, SdkClientException, BedrockRuntimeException The action to apply a guardrail.
For troubleshooting some of the common errors you might encounter when using the
ApplyGuardrailAPI, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide
This is a convenience which creates an instance of the
ApplyGuardrailRequest.Builderavoiding the need to create one manually viaApplyGuardrailRequest.builder()- Parameters:
applyGuardrailRequest- AConsumerthat will call methods onApplyGuardrailRequest.Builderto create a request.- Returns:
- Result of the ApplyGuardrail operation returned by the service.
- See Also:
-
converse
default ConverseResponse converse(ConverseRequest converseRequest) throws AccessDeniedException, ThrottlingException, ResourceNotFoundException, ModelTimeoutException, InternalServerException, ServiceUnavailableException, ValidationException, ModelNotReadyException, ModelErrorException, AwsServiceException, SdkClientException, BedrockRuntimeException Sends messages to the specified Amazon Bedrock model.
Converseprovides a consistent interface that works with all models that support messages. This allows you to write code once and use it with different models. If a model has unique inference parameters, you can also pass those unique parameters to the model.Amazon Bedrock doesn't store any text, images, or documents that you provide as content. The data is only used to generate the response.
You can submit a prompt by including it in the
messagesfield, specifying themodelIdof a foundation model or inference profile to run inference on it, and including any other fields that are relevant to your use case.You can also submit a prompt from Prompt management by specifying the ARN of the prompt version and including a map of variables to values in the
promptVariablesfield. You can append more messages to the prompt by using themessagesfield. If you use a prompt from Prompt management, you can't include the following fields in the request:additionalModelRequestFields,inferenceConfig,system, ortoolConfig. Instead, these fields must be defined through Prompt management. For more information, see Use a prompt from Prompt management.For information about the Converse API, see Use the Converse API in the Amazon Bedrock User Guide. To use a guardrail, see Use a guardrail with the Converse API in the Amazon Bedrock User Guide. To use a tool with a model, see Tool use (Function calling) in the Amazon Bedrock User Guide
For example code, see Converse API examples in the Amazon Bedrock User Guide.
This operation requires permission for the
bedrock:InvokeModelaction.To deny all inference access to resources that you specify in the modelId field, you need to deny access to the
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamactions. Doing this also denies access to the resource through the base inference actions (InvokeModel and InvokeModelWithResponseStream). For more information see Deny access for inference on specific models.For troubleshooting some of the common errors you might encounter when using the
ConverseAPI, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide- Parameters:
converseRequest-- Returns:
- Result of the Converse operation returned by the service.
- See Also:
-
converse
default ConverseResponse converse(Consumer<ConverseRequest.Builder> converseRequest) throws AccessDeniedException, ThrottlingException, ResourceNotFoundException, ModelTimeoutException, InternalServerException, ServiceUnavailableException, ValidationException, ModelNotReadyException, ModelErrorException, AwsServiceException, SdkClientException, BedrockRuntimeException Sends messages to the specified Amazon Bedrock model.
Converseprovides a consistent interface that works with all models that support messages. This allows you to write code once and use it with different models. If a model has unique inference parameters, you can also pass those unique parameters to the model.Amazon Bedrock doesn't store any text, images, or documents that you provide as content. The data is only used to generate the response.
You can submit a prompt by including it in the
messagesfield, specifying themodelIdof a foundation model or inference profile to run inference on it, and including any other fields that are relevant to your use case.You can also submit a prompt from Prompt management by specifying the ARN of the prompt version and including a map of variables to values in the
promptVariablesfield. You can append more messages to the prompt by using themessagesfield. If you use a prompt from Prompt management, you can't include the following fields in the request:additionalModelRequestFields,inferenceConfig,system, ortoolConfig. Instead, these fields must be defined through Prompt management. For more information, see Use a prompt from Prompt management.For information about the Converse API, see Use the Converse API in the Amazon Bedrock User Guide. To use a guardrail, see Use a guardrail with the Converse API in the Amazon Bedrock User Guide. To use a tool with a model, see Tool use (Function calling) in the Amazon Bedrock User Guide
For example code, see Converse API examples in the Amazon Bedrock User Guide.
This operation requires permission for the
bedrock:InvokeModelaction.To deny all inference access to resources that you specify in the modelId field, you need to deny access to the
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamactions. Doing this also denies access to the resource through the base inference actions (InvokeModel and InvokeModelWithResponseStream). For more information see Deny access for inference on specific models.For troubleshooting some of the common errors you might encounter when using the
ConverseAPI, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide
This is a convenience which creates an instance of the
ConverseRequest.Builderavoiding the need to create one manually viaConverseRequest.builder()- Parameters:
converseRequest- AConsumerthat will call methods onConverseRequest.Builderto create a request.- Returns:
- Result of the Converse operation returned by the service.
- See Also:
-
countTokens
default CountTokensResponse countTokens(CountTokensRequest countTokensRequest) throws AccessDeniedException, ResourceNotFoundException, ThrottlingException, InternalServerException, ServiceUnavailableException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException Returns the token count for a given inference request. This operation helps you estimate token usage before sending requests to foundation models by returning the token count that would be used if the same input were sent to the model in an inference request.
Token counting is model-specific because different models use different tokenization strategies. The token count returned by this operation will match the token count that would be charged if the same input were sent to the model in an
InvokeModelorConverserequest.You can use this operation to:
-
Estimate costs before sending inference requests.
-
Optimize prompts to fit within token limits.
-
Plan for token usage in your applications.
This operation accepts the same input formats as
InvokeModelandConverse, allowing you to count tokens for both raw text inputs and structured conversation formats.The following operations are related to
CountTokens:-
InvokeModel - Sends inference requests to foundation models
-
Converse - Sends conversation-based inference requests to foundation models
- Parameters:
countTokensRequest-- Returns:
- Result of the CountTokens operation returned by the service.
- See Also:
-
-
countTokens
default CountTokensResponse countTokens(Consumer<CountTokensRequest.Builder> countTokensRequest) throws AccessDeniedException, ResourceNotFoundException, ThrottlingException, InternalServerException, ServiceUnavailableException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException Returns the token count for a given inference request. This operation helps you estimate token usage before sending requests to foundation models by returning the token count that would be used if the same input were sent to the model in an inference request.
Token counting is model-specific because different models use different tokenization strategies. The token count returned by this operation will match the token count that would be charged if the same input were sent to the model in an
InvokeModelorConverserequest.You can use this operation to:
-
Estimate costs before sending inference requests.
-
Optimize prompts to fit within token limits.
-
Plan for token usage in your applications.
This operation accepts the same input formats as
InvokeModelandConverse, allowing you to count tokens for both raw text inputs and structured conversation formats.The following operations are related to
CountTokens:-
InvokeModel - Sends inference requests to foundation models
-
Converse - Sends conversation-based inference requests to foundation models
This is a convenience which creates an instance of the
CountTokensRequest.Builderavoiding the need to create one manually viaCountTokensRequest.builder()- Parameters:
countTokensRequest- AConsumerthat will call methods onCountTokensRequest.Builderto create a request.- Returns:
- Result of the CountTokens operation returned by the service.
- See Also:
-
-
getAsyncInvoke
default GetAsyncInvokeResponse getAsyncInvoke(GetAsyncInvokeRequest getAsyncInvokeRequest) throws AccessDeniedException, ThrottlingException, InternalServerException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException Retrieve information about an asynchronous invocation.
- Parameters:
getAsyncInvokeRequest-- Returns:
- Result of the GetAsyncInvoke operation returned by the service.
- See Also:
-
getAsyncInvoke
default GetAsyncInvokeResponse getAsyncInvoke(Consumer<GetAsyncInvokeRequest.Builder> getAsyncInvokeRequest) throws AccessDeniedException, ThrottlingException, InternalServerException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException Retrieve information about an asynchronous invocation.
This is a convenience which creates an instance of the
GetAsyncInvokeRequest.Builderavoiding the need to create one manually viaGetAsyncInvokeRequest.builder()- Parameters:
getAsyncInvokeRequest- AConsumerthat will call methods onGetAsyncInvokeRequest.Builderto create a request.- Returns:
- Result of the GetAsyncInvoke operation returned by the service.
- See Also:
-
invokeModel
default InvokeModelResponse invokeModel(InvokeModelRequest invokeModelRequest) throws AccessDeniedException, ResourceNotFoundException, ThrottlingException, ModelTimeoutException, InternalServerException, ServiceUnavailableException, ValidationException, ServiceQuotaExceededException, ModelNotReadyException, ModelErrorException, AwsServiceException, SdkClientException, BedrockRuntimeException Invokes the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body. You use model inference to generate text, images, and embeddings.
For example code, see Invoke model code examples in the Amazon Bedrock User Guide.
This operation requires permission for the
bedrock:InvokeModelaction.To deny all inference access to resources that you specify in the modelId field, you need to deny access to the
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamactions. Doing this also denies access to the resource through the Converse API actions (Converse and ConverseStream). For more information see Deny access for inference on specific models.For troubleshooting some of the common errors you might encounter when using the
InvokeModelAPI, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide- Parameters:
invokeModelRequest-- Returns:
- Result of the InvokeModel operation returned by the service.
- See Also:
-
invokeModel
default InvokeModelResponse invokeModel(Consumer<InvokeModelRequest.Builder> invokeModelRequest) throws AccessDeniedException, ResourceNotFoundException, ThrottlingException, ModelTimeoutException, InternalServerException, ServiceUnavailableException, ValidationException, ServiceQuotaExceededException, ModelNotReadyException, ModelErrorException, AwsServiceException, SdkClientException, BedrockRuntimeException Invokes the specified Amazon Bedrock model to run inference using the prompt and inference parameters provided in the request body. You use model inference to generate text, images, and embeddings.
For example code, see Invoke model code examples in the Amazon Bedrock User Guide.
This operation requires permission for the
bedrock:InvokeModelaction.To deny all inference access to resources that you specify in the modelId field, you need to deny access to the
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamactions. Doing this also denies access to the resource through the Converse API actions (Converse and ConverseStream). For more information see Deny access for inference on specific models.For troubleshooting some of the common errors you might encounter when using the
InvokeModelAPI, see Troubleshooting Amazon Bedrock API Error Codes in the Amazon Bedrock User Guide
This is a convenience which creates an instance of the
InvokeModelRequest.Builderavoiding the need to create one manually viaInvokeModelRequest.builder()- Parameters:
invokeModelRequest- AConsumerthat will call methods onInvokeModelRequest.Builderto create a request.- Returns:
- Result of the InvokeModel operation returned by the service.
- See Also:
-
listAsyncInvokes
default ListAsyncInvokesResponse listAsyncInvokes(ListAsyncInvokesRequest listAsyncInvokesRequest) throws AccessDeniedException, ThrottlingException, InternalServerException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException Lists asynchronous invocations.
- Parameters:
listAsyncInvokesRequest-- Returns:
- Result of the ListAsyncInvokes operation returned by the service.
- See Also:
-
listAsyncInvokes
default ListAsyncInvokesResponse listAsyncInvokes(Consumer<ListAsyncInvokesRequest.Builder> listAsyncInvokesRequest) throws AccessDeniedException, ThrottlingException, InternalServerException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException Lists asynchronous invocations.
This is a convenience which creates an instance of the
ListAsyncInvokesRequest.Builderavoiding the need to create one manually viaListAsyncInvokesRequest.builder()- Parameters:
listAsyncInvokesRequest- AConsumerthat will call methods onListAsyncInvokesRequest.Builderto create a request.- Returns:
- Result of the ListAsyncInvokes operation returned by the service.
- See Also:
-
listAsyncInvokesPaginator
default ListAsyncInvokesIterable listAsyncInvokesPaginator(ListAsyncInvokesRequest listAsyncInvokesRequest) throws AccessDeniedException, ThrottlingException, InternalServerException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException This is a variant of
listAsyncInvokes(software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesRequest)operation. The return type is a custom iterable that can be used to iterate through all the pages. SDK will internally handle making service calls for you.When this operation is called, a custom iterable is returned but no service calls are made yet. So there is no guarantee that the request is valid. As you iterate through the iterable, SDK will start lazily loading response pages by making service calls until there are no pages left or your iteration stops. If there are errors in your request, you will see the failures only after you start iterating through the iterable.
The following are few ways to iterate through the response pages:
1) Using a Stream
2) Using For loopsoftware.amazon.awssdk.services.bedrockruntime.paginators.ListAsyncInvokesIterable responses = client.listAsyncInvokesPaginator(request); responses.stream().forEach(....);{ @code software.amazon.awssdk.services.bedrockruntime.paginators.ListAsyncInvokesIterable responses = client .listAsyncInvokesPaginator(request); for (software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesResponse response : responses) { // do something; } }3) Use iterator directlysoftware.amazon.awssdk.services.bedrockruntime.paginators.ListAsyncInvokesIterable responses = client.listAsyncInvokesPaginator(request); responses.iterator().forEachRemaining(....);Please notice that the configuration of maxResults won't limit the number of results you get with the paginator. It only limits the number of results in each page.
Note: If you prefer to have control on service calls, use the
listAsyncInvokes(software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesRequest)operation.- Parameters:
listAsyncInvokesRequest-- Returns:
- A custom iterable that can be used to iterate through all the response pages.
- See Also:
-
listAsyncInvokesPaginator
default ListAsyncInvokesIterable listAsyncInvokesPaginator(Consumer<ListAsyncInvokesRequest.Builder> listAsyncInvokesRequest) throws AccessDeniedException, ThrottlingException, InternalServerException, ValidationException, AwsServiceException, SdkClientException, BedrockRuntimeException This is a variant of
listAsyncInvokes(software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesRequest)operation. The return type is a custom iterable that can be used to iterate through all the pages. SDK will internally handle making service calls for you.When this operation is called, a custom iterable is returned but no service calls are made yet. So there is no guarantee that the request is valid. As you iterate through the iterable, SDK will start lazily loading response pages by making service calls until there are no pages left or your iteration stops. If there are errors in your request, you will see the failures only after you start iterating through the iterable.
The following are few ways to iterate through the response pages:
1) Using a Stream
2) Using For loopsoftware.amazon.awssdk.services.bedrockruntime.paginators.ListAsyncInvokesIterable responses = client.listAsyncInvokesPaginator(request); responses.stream().forEach(....);{ @code software.amazon.awssdk.services.bedrockruntime.paginators.ListAsyncInvokesIterable responses = client .listAsyncInvokesPaginator(request); for (software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesResponse response : responses) { // do something; } }3) Use iterator directlysoftware.amazon.awssdk.services.bedrockruntime.paginators.ListAsyncInvokesIterable responses = client.listAsyncInvokesPaginator(request); responses.iterator().forEachRemaining(....);Please notice that the configuration of maxResults won't limit the number of results you get with the paginator. It only limits the number of results in each page.
Note: If you prefer to have control on service calls, use the
listAsyncInvokes(software.amazon.awssdk.services.bedrockruntime.model.ListAsyncInvokesRequest)operation.
This is a convenience which creates an instance of the
ListAsyncInvokesRequest.Builderavoiding the need to create one manually viaListAsyncInvokesRequest.builder()- Parameters:
listAsyncInvokesRequest- AConsumerthat will call methods onListAsyncInvokesRequest.Builderto create a request.- Returns:
- A custom iterable that can be used to iterate through all the response pages.
- See Also:
-
startAsyncInvoke
default StartAsyncInvokeResponse startAsyncInvoke(StartAsyncInvokeRequest startAsyncInvokeRequest) throws AccessDeniedException, ThrottlingException, ResourceNotFoundException, InternalServerException, ServiceUnavailableException, ValidationException, ServiceQuotaExceededException, ConflictException, AwsServiceException, SdkClientException, BedrockRuntimeException Starts an asynchronous invocation.
This operation requires permission for the
bedrock:InvokeModelaction.To deny all inference access to resources that you specify in the modelId field, you need to deny access to the
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamactions. Doing this also denies access to the resource through the Converse API actions (Converse and ConverseStream). For more information see Deny access for inference on specific models.- Parameters:
startAsyncInvokeRequest-- Returns:
- Result of the StartAsyncInvoke operation returned by the service.
- See Also:
-
startAsyncInvoke
default StartAsyncInvokeResponse startAsyncInvoke(Consumer<StartAsyncInvokeRequest.Builder> startAsyncInvokeRequest) throws AccessDeniedException, ThrottlingException, ResourceNotFoundException, InternalServerException, ServiceUnavailableException, ValidationException, ServiceQuotaExceededException, ConflictException, AwsServiceException, SdkClientException, BedrockRuntimeException Starts an asynchronous invocation.
This operation requires permission for the
bedrock:InvokeModelaction.To deny all inference access to resources that you specify in the modelId field, you need to deny access to the
bedrock:InvokeModelandbedrock:InvokeModelWithResponseStreamactions. Doing this also denies access to the resource through the Converse API actions (Converse and ConverseStream). For more information see Deny access for inference on specific models.
This is a convenience which creates an instance of the
StartAsyncInvokeRequest.Builderavoiding the need to create one manually viaStartAsyncInvokeRequest.builder()- Parameters:
startAsyncInvokeRequest- AConsumerthat will call methods onStartAsyncInvokeRequest.Builderto create a request.- Returns:
- Result of the StartAsyncInvoke operation returned by the service.
- See Also:
-
create
Create aBedrockRuntimeClientwith the region loaded from theDefaultAwsRegionProviderChainand credentials loaded from theDefaultCredentialsProvider. -
builder
Create a builder that can be used to configure and create aBedrockRuntimeClient. -
serviceMetadata
-
serviceClientConfiguration
Description copied from interface:SdkClientThe SDK service client configuration exposes client settings to the user, e.g., ClientOverrideConfiguration- Specified by:
serviceClientConfigurationin interfaceAwsClient- Specified by:
serviceClientConfigurationin interfaceSdkClient- Returns:
- SdkServiceClientConfiguration
-