A Java developer's guide to Bedrock's new Converse API

[ Open the JavaScript edition | Jump directly to the code 💻 ]

Introduction

The Converse API is a new addition to the Amazon Bedrock Runtime, designed to simplify the interaction with text-based generative AI models. It offers a cohesive set of functionality through a common and strongly-typed request format, regardless of the specific foundation model being used.

In this tutorial, we'll explore the Converse API and learn how to leverage its capabilities to build engaging and interactive applications. Whether you're new to AI or an experienced developer, this guide will walk you through the process of sending your first request to a generative AI model.

This edition of the tutorial uses JavaScript. I've also prepared a JavaScript edition, and have uploaded many more examples in Python, C#, etc.

Series overview

This series guides you through Amazon Bedrock's Converse API:

In Part 1: Getting Started (this post), you will learn how to send your first request.
In Part 2: Conversational AI, I'll show you how to implement conversational turns.
In Part 3: Customizing AI Behavior (upcoming), we'll configure the model with a system prompt and additional inference parameters.

Future posts will cover extracting invocation metrics and metadata, sending and receiving model-specific parameters and fields, processing model responses in real-time, the new tool-use feature, and more.

Let's dive in and start building! 💻

Step-by-step: Send your first prompt with the Converse API

Throughout the following steps, you will learn how to use the Amazon Bedrock Runtime client for Java to send a message to a foundation model and print the response.

Let's get started!

Prerequisites

Before you begin, ensure all prerequisites are in place. You should have:

An AWS account
The AWS CLI installed and configured with your credentials
A Java Development Kit (JDK) version 17 or later and a build tool like Apache Maven installed.
Requested access to the model you want to use

Step 1: Set up a new Java project

First, create a new Java project using Maven and add the Bedrock Runtime and STS dependencies to your pom.xml file:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
...
<properties>
    <aws.sdk.version>2.26.4</aws.sdk.version>
</properties>

<dependencies>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>bedrockruntime</artifactId>
        <version>${aws.sdk.version}</version>
    </dependency>
    <dependency>
        <groupId>software.amazon.awssdk</groupId>
        <artifactId>sts</artifactId>
        <version>${aws.sdk.version}</version>
    </dependency>
</dependencies>
...

Note: Replace the aws.sdk.version with the latest version of the AWS SDK for Java.

Step 2: Create an instance of the Bedrock Runtime client

Create an instance of the BedrockRuntimeClient, specifying the AWS region where the model is available:

1
2
3
4
5
6
7
8
9
10
11
12
import ... // You can find all required imports in the complete example below.

public class BedrockFirstMessage {
    public static void main(String[] args) {
        BedrockRuntimeClient client = BedrockRuntimeClient.builder()
                .credentialsProvider(DefaultCredentialsProvider.create())
                .region(Region.US_EAST_1)
                .build();

        // ...
    }
}

Step 3: Specify the model ID

Specify the ID of the model you want to use.

In this example, we'll use Claude 3 Haiku:

1
String modelId = "anthropic.claude-3-haiku-20240307-v1:0";

You can find the complete list of models supporting the Converse API and a list of all available model IDs in the documentation.

Step 4: Send your first message

Prepare a user message with your input text:

1
2
3
4
5
6
String inputText = "Explain 'rubber duck debugging' in one line.";

Message message = Message.builder()
        .content(ContentBlock.fromText(inputText))
        .role(ConversationRole.USER)
        .build();

Each message must contain a role (ConversationRole.USER or ConversationRole.ASSISTANT) and at least one content block with the message text.

Send the message to the model using the Bedrock Runtime client's converse() method:

1
2
3
ConverseResponse response = client.converse(
    request -> request.modelId(modelId).messages(message)
);

The converse method sends the conversation to the specified model and returns its response.

Print out the model's response:

1
2
String responseText = response.output().message().content().get(0).text();
System.out.println(responseText);

Let's run the program

With the code complete, let's run it and see the AI engage in a multi-turn conversation!

Here's the full code for reference:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.bedrockruntime.BedrockRuntimeClient;
import software.amazon.awssdk.services.bedrockruntime.model.ContentBlock;
import software.amazon.awssdk.services.bedrockruntime.model.ConversationRole;
import software.amazon.awssdk.services.bedrockruntime.model.ConverseResponse;
import software.amazon.awssdk.services.bedrockruntime.model.Message;

public class BedrockFirstMessage {
    public static void main(String[] args) {
        BedrockRuntimeClient client = BedrockRuntimeClient.builder()
                .credentialsProvider(DefaultCredentialsProvider.create())
                .region(Region.US_EAST_1)
                .build();

        String modelId = "anthropic.claude-3-haiku-20240307-v1:0";

        String inputText = "Explain 'rubber duck debugging' in one line.";

        Message message = Message.builder()
                .content(ContentBlock.fromText(inputText))
                .role(ConversationRole.USER)
                .build();

        ConverseResponse response = client.converse(
                request -> request.modelId(modelId).messages(message)
        );

        String responseText = response.output().message().content().get(0).text();
        System.out.println(responseText);
    }
}

To run it:

Save the code in a file named BedrockFirstMessage.java
Compile and run the Java application using your preferred IDE or command-line tools.

If everything is set up correctly, you should see the model's responses printed in the console:

1
2
Rubber duck debugging is the process of explaining your code to
a rubber duck (or any inanimate object) to identify and fix bugs.

If you encounter any errors, double check that you have:

Configured your AWS credentials
Requested access to the model you are using
Installed the required dependencies
Specified the correct region and model ID

Next steps

Congratulations on implementing a multi-turn conversation with Bedrock's Converse API!

Ready for more? Here are some ideas to keep exploring:

Experiment with different models and compare their responses. Here's the list of all models supporting the Converse API.
Challenge yourself to rewrite this program in another language. Here are examples in Python, JavaScript, C#, and more.
Dive deeper into the Converse API in the Amazon Bedrock User Guide.

In Part 2 of this series, we'll dive deeper into the Converse API and learn how to maintain a conversation history and handle multi-turn conversations.

I'd love to see what you build with Amazon Bedrock! Feel free to share your projects or ask questions in the comments.

Thanks for following along and happy building! 💻🤖

Any opinions in this post are those of the individual author and may not reflect the opinions of AWS.

Select your cookie preferences

Site Terms, Privacy, and more.