AWS Builder Center

Builder Center

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

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

Learn how to send your first request to a generative AI model using Amazon Bedrock's Converse API and the AWS SDK for JavaScript.

Series: Streamlining AI Development: A Practical Guide to Bedrock's Unified Messages API (3 articles)

  1. 1
    A developer's guide to Bedrock's new Converse API This article
  2. 2
    Conversational AI: Add chatting capabilities to your app
  3. 3
    Customizing AI Behavior: System prompts and inference parameters in Bedrock's Converse API

Dennis Traub

[ Open the Java  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 Java edition , and have uploaded many more examples  in Python, C#, etc.

Series overview

This series guides you through Amazon Bedrock's Converse API:
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 JavaScript 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:

Step 1: Install the Bedrock Runtime Client

First, install the Bedrock Runtime client from the AWS SDK for JavaScript v3:
1
npm install @aws-sdk/client-bedrock-runtime

Step 2: Import Required Modules

In a new JavaScript file, import the required modules:
1
2
3
4
import {
BedrockRuntimeClient,
ConverseCommand,
} from "@aws-sdk/client-bedrock-runtime";

Step 3: Create a BedrockRuntimeClient Instance

Create an instance of the BedrockRuntimeClient, specifying the AWS region where the model is available :
1
const client = new BedrockRuntimeClient({ region: "us-east-1" });

Step 4: Specify the Model ID

Specify the ID of the model you want to use. In this example, we'll use Claude 3 Haiku:
1
const 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 5: Send your first message

Prepare the first user message and add it to a new conversation array:
1
2
3
4
5
6
7
const userMessage = "What is 'rubber duck debugging'";
const conversation = [
{
role: "user",
content: [{ text: userMessage }],
},
];
The conversation array represents the conversation history, with each element containing a role (e.g., "user" or "assistant") and at least one content block with the message text.
Send the conversation to the model using a ConverseCommand:
1
2
3
const response = await client.send(
new ConverseCommand({ modelId, messages: conversation }),
);
The ConverseCommand sends the conversation to the specified model and returns its response.
Print out the model's response:
1
2
const responseText = response.output.message.content[0].text;
console.log(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
import {
BedrockRuntimeClient,
ConverseCommand,
} from "@aws-sdk/client-bedrock-runtime";

const client = new BedrockRuntimeClient({ region: "us-east-1" });

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

const userMessage = "What is 'rubber duck debugging'";
const conversation = [
{
role: "user",
content: [{ text: userMessage }],
},
];

const response = await client.send(
new ConverseCommand({ modelId, messages: conversation }),
);

const responseText = response.output.message.content[0].text;
console.log(responseText);
To run it:
  1. Save the code in a file named bedrock_first_message.js
  2. In your terminal, navigate to the directory containing bedrock_first_message.js
  3. Run the following command:
1
2
3
4
$ node bedrock_first_message.js

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:

Next steps

Congratulations on sending your first request to the Amazon Bedrock Converse API! With just a few lines of code, you've successfully interacted with a generative AI model.
Ready for more? Here are some ideas to keep exploring:
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! 💻🤖
 
# amazon-bedrock# generative-ai# software-development# javascript

Series: Streamlining AI Development: A Practical Guide to Bedrock's Unified Messages API (3 articles)

  1. 1
    A developer's guide to Bedrock's new Converse API This article
  2. 2
    Conversational AI: Add chatting capabilities to your app
  3. 3
    Customizing AI Behavior: System prompts and inference parameters in Bedrock's Converse API
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article