Skip to content

Commit d75d2b4

Browse files
brmurbrmur
authored
JavaScriptv3: Bedrock agent runtime tool use scenario example (#7355)
1 parent 16818ae commit d75d2b4

File tree

14 files changed

+731
-4
lines changed

14 files changed

+731
-4
lines changed

‎.doc_gen/metadata/bedrock-runtime_metadata.yaml

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,10 @@ bedrock-runtime_Converse_AmazonNovaText:
100100
- description: Send a text message to Amazon Nova, using Bedrock's Converse API.
101101
snippet_tags:
102102
- javascript.v3.bedrock-runtime.Converse_AmazonNovaText
103+
- description: Send a conversation of messages to Amazon Nova using Bedrock's Converse API with a tool configuration.
104+
genai: some
105+
snippet_tags:
106+
- Bedrock.ConverseTool.javascriptv3.SendConverseRequest
103107
Kotlin:
104108
versions:
105109
- sdk_version: 1
@@ -214,6 +218,15 @@ bedrock-runtime_Scenario_ToolUse:
214218
genai: some
215219
snippet_tags:
216220
- Bedrock.ConverseTool.dotnetv3.SendConverseRequest
221+
JavaScript:
222+
versions:
223+
- sdk_version: 3
224+
github: javascriptv3/example_code/bedrock-runtime/scenarios/converse_tool_scenario
225+
excerpts:
226+
- description: "The primary execution of the scenario flow. This scenario orchestrates the conversation between the user, the &BR; Converse API, and a weather tool."
227+
genai: some
228+
snippet_tags:
229+
- Bedrock.ConverseTool.javascriptv3.Scenario
217230
Python:
218231
versions:
219232
- sdk_version: 3
@@ -1517,6 +1530,15 @@ bedrock-runtime_Scenario_ToolUseDemo_AmazonNova:
15171530
genai: some
15181531
snippet_tags:
15191532
- Bedrock.ConverseTool.dotnetv3.SendConverseRequest
1533+
JavaScript:
1534+
versions:
1535+
- sdk_version: 3
1536+
github: javascriptv3/example_code/bedrock-runtime/scenarios/converse_tool_scenario
1537+
excerpts:
1538+
- description: "The primary execution of the scenario flow. This scenario orchestrates the conversation between the user, the &BR; Converse API, and a weather tool."
1539+
genai: some
1540+
snippet_tags:
1541+
- Bedrock.ConverseTool.javascriptv3.Scenario
15201542
services:
15211543
bedrock-runtime: {Converse}
15221544

‎.doc_gen/validation.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
allow_list:
22
# Git commits
3+
- "cad7e7ba2c59a54837212e789a5304b9108fac47"
34
- "cd5e746ec203c8c3c61647e0886a8df8c1e78e41"
45
- "725feb26d6f73bc1d83dbbe075ae8ea991efb245"
56
- "e9772d140489982e0e3704fea5ee93d536f1e275"

‎.tools/base_requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ pathspec==0.11.2
55
PyYAML==6.0.1
66
requests==2.32.0
77
types-PyYAML==6.0.12.12
8-
yamale==4.0.4
8+
yamale==4.0.4

‎.tools/readmes/requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
jinja2>=3.0.3
22
pyyaml>=5.3.1
33
typer==0.15.1
4-
aws-doc-sdk-examples-tools @ git+https://github.com/awsdocs/aws-doc-sdk-examples-tools
4+
aws-doc-sdk-examples-tools @ git+https://github.com/awsdocs/aws-doc-sdk-examples-tools

‎.tools/readmes/requirements_freeze.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,4 +29,4 @@ typer==0.15.1
2929
types-PyYAML==6.0.12.12
3030
typing_extensions==4.12.2
3131
urllib3==2.3.0
32-
yamale==4.0.4
32+
yamale==4.0.4

‎javascriptv3/example_code/bedrock-runtime/README.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,7 @@ Code examples that show you how to accomplish a specific task by calling multipl
4444
functions within the same service.
4545

4646
- [Invoke multiple foundation models on Amazon Bedrock](scenarios/cli_text_playground.js)
47+
- [Tool use with the Converse API](scenarios/converse_tool_scenario/converse-tool-scenario.js)
4748

4849
### AI21 Labs Jurassic-2
4950

@@ -54,6 +55,7 @@ functions within the same service.
5455

5556
- [Converse](models/amazonNovaText/converse.js#L4)
5657
- [ConverseStream](models/amazonNovaText/converseStream.js#L4)
58+
- [Scenario: Tool use with the Converse API](scenarios/converse_tool_scenario/converse-tool-scenario.js#L4)
5759

5860
### Amazon Nova Canvas
5961

@@ -148,6 +150,18 @@ This example shows you how to prepare and send a prompt to a variety of large-la
148150
<!--custom.scenarios.bedrock-runtime_Scenario_InvokeModels.start-->
149151
<!--custom.scenarios.bedrock-runtime_Scenario_InvokeModels.end-->
150152

153+
#### Tool use with the Converse API
154+
155+
This example shows you how to build a typical interaction between an application, a generative AI model, and connected tools or APIs to mediate interactions between the AI and the outside world. It uses the example of connecting an external weather API to the AI model so it can provide real-time weather information based on user input.
156+
157+
158+
<!--custom.scenario_prereqs.bedrock-runtime_Scenario_ToolUse.start-->
159+
<!--custom.scenario_prereqs.bedrock-runtime_Scenario_ToolUse.end-->
160+
161+
162+
<!--custom.scenarios.bedrock-runtime_Scenario_ToolUse.start-->
163+
<!--custom.scenarios.bedrock-runtime_Scenario_ToolUse.end-->
164+
151165
### Tests
152166

153167
⚠ Running tests might result in charges to your AWS account.

‎javascriptv3/example_code/bedrock-runtime/models/amazonNovaText/converse-with-tool.js

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
// snippet-start:[Bedrock.ConverseTool.javascriptv3.SendConverseRequest]
5+
6+
// This example demonstrates how to send a conversation of messages to Amazon Nova using Bedrock's Converse API with a tool configuration.
7+
// It shows how to:
8+
// - 1. Set up the Amazon Bedrock runtime client
9+
// - 2. Define the parameters required enable Amazon Bedrock to use a tool when formulating its response (model ID, user input, system prompt, and the tool spec)
10+
// - 3. Send the request to Amazon Bedrock, and returns the response.
11+
// - 4. Add the tool response to the conversation, and send it back to Amazon Bedrock.
12+
// - 5. Publish the response.
13+
14+
import {
15+
BedrockRuntimeClient,
16+
ConverseCommand,
17+
} from "@aws-sdk/client-bedrock-runtime";
18+
19+
// Step 1: Create the Amazon Bedrock runtime client
20+
21+
// Credentials will be automatically loaded from the environment
22+
const bedRockRuntimeClient = new BedrockRuntimeClient({
23+
region: "us-east-1",
24+
});
25+
26+
// Step 2. Define the parameters required enable Amazon Bedrock to use a tool when formulating its response.
27+
28+
// The Bedrock Model ID.
29+
const modelId = "amazon.nova-lite-v1:0";
30+
31+
// The system prompt to help Amazon Bedrock craft it's response.
32+
const system_prompt = [
33+
{
34+
text:
35+
"You are a music expert that provides the most popular song played on a radio station, using only the\n" +
36+
"the top_song tool, which he call sign for the radio station for which you want the most popular song. " +
37+
"Example calls signs are WZPZ and WKRP. \n" +
38+
"- Only use the top_song tool. Never guess or make up information. \n" +
39+
"- If the tool errors, apologize, explain weather is unavailable, and suggest other options.\n" +
40+
"- Only respond to queries about the most popular song played on a radio station\n" +
41+
"Remind off-topic users of your purpose. \n" +
42+
"- Never claim to search online, access external data, or use tools besides the top_song tool.\n",
43+
},
44+
];
45+
// The user's question.
46+
const message = [
47+
{
48+
role: "user",
49+
content: [{ text: "What is the most popular song on WZPZ?" }],
50+
},
51+
];
52+
// The tool specification. In this case, it uses an example schema for
53+
// a tool that gets the most popular song played on a radio station.
54+
const tool_config = {
55+
tools: [
56+
{
57+
toolSpec: {
58+
name: "top_song",
59+
description: "Get the most popular song played on a radio station.",
60+
inputSchema: {
61+
json: {
62+
type: "object",
63+
properties: {
64+
sign: {
65+
type: "string",
66+
description:
67+
"The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKRP.",
68+
},
69+
},
70+
required: ["sign"],
71+
},
72+
},
73+
},
74+
},
75+
],
76+
};
77+
78+
// Helper function to return the song and artist from top_song tool.
79+
async function get_top_song(call_sign) {
80+
try {
81+
if (call_sign === "WZPZ") {
82+
const song = "Elemental Hotel";
83+
const artist = "8 Storey Hike";
84+
return { song, artist };
85+
}
86+
} catch (error) {
87+
console.log(`${error.message}`);
88+
}
89+
}
90+
91+
// 3. Send the request to Amazon Bedrock, and returns the response.
92+
export async function SendConversationtoBedrock(
93+
modelId,
94+
message,
95+
system_prompt,
96+
tool_config,
97+
) {
98+
try {
99+
const response = await bedRockRuntimeClient.send(
100+
new ConverseCommand({
101+
modelId: modelId,
102+
messages: message,
103+
system: system_prompt,
104+
toolConfig: tool_config,
105+
}),
106+
);
107+
if (response.stopReason === "tool_use") {
108+
const toolResultFinal = [];
109+
try {
110+
const output_message = response.output.message;
111+
message.push(output_message);
112+
const toolRequests = output_message.content;
113+
const toolMessage = toolRequests[0].text;
114+
console.log(toolMessage.replace(/<[^>]+>/g, ""));
115+
for (const toolRequest of toolRequests) {
116+
if (Object.hasOwn(toolRequest, "toolUse")) {
117+
const toolUse = toolRequest.toolUse;
118+
const sign = toolUse.input.sign;
119+
const toolUseID = toolUse.toolUseId;
120+
console.log(
121+
`Requesting tool ${toolUse.name}, Tool use id ${toolUseID}`,
122+
);
123+
if (toolUse.name === "top_song") {
124+
const toolResult = [];
125+
try {
126+
const top_song = await get_top_song(toolUse.input.sign).then(
127+
(top_song) => top_song,
128+
);
129+
const toolResult = {
130+
toolResult: {
131+
toolUseId: toolUseID,
132+
content: [
133+
{
134+
json: { song: top_song.song, artist: top_song.artist },
135+
},
136+
],
137+
},
138+
};
139+
toolResultFinal.push(toolResult);
140+
} catch (err) {
141+
const toolResult = {
142+
toolUseId: toolUseID,
143+
content: [{ json: { text: err.message } }],
144+
status: "error",
145+
};
146+
}
147+
}
148+
}
149+
}
150+
const toolResultMessage = {
151+
role: "user",
152+
content: toolResultFinal,
153+
};
154+
// Step 4. Add the tool response to the conversation, and send it back to Amazon Bedrock.
155+
156+
message.push(toolResultMessage);
157+
await SendConversationtoBedrock(
158+
modelId,
159+
message,
160+
system_prompt,
161+
tool_config,
162+
);
163+
} catch (caught) {
164+
console.error(`${caught.message}`);
165+
throw caught;
166+
}
167+
}
168+
169+
// 4. Publish the response.
170+
if (response.stopReason === "end_turn") {
171+
const finalMessage = response.output.message.content[0].text;
172+
const messageToPrint = finalMessage.replace(/<[^>]+>/g);
173+
console.log(messageToPrint.replace(/<[^>]+>/g));
174+
return messageToPrint;
175+
}
176+
} catch (caught) {
177+
if (caught.name === "ModelNotReady") {
178+
console.log(
179+
`${caught.name} - Model not ready, please wait and try again.`,
180+
);
181+
throw caught;
182+
}
183+
if (caught.name === "BedrockRuntimeException") {
184+
console.log(
185+
`${caught.name} - Error occurred while sending Converse request`,
186+
);
187+
throw caught;
188+
}
189+
}
190+
}
191+
await SendConversationtoBedrock(modelId, message, system_prompt, tool_config);
192+
193+
// snippet-end:[Bedrock.ConverseTool.javascriptv3.SendConverseRequest]

‎javascriptv3/example_code/bedrock-runtime/models/amazonNovaText/converse.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ import {
1616
} from "@aws-sdk/client-bedrock-runtime";
1717

1818
// Step 1: Create the Amazon Bedrock runtime client
19-
// Credentials will be automatically loaded from the environment
19+
// Credentials will be automatically loaded from the environment.
2020
const client = new BedrockRuntimeClient({ region: "us-east-1" });
2121

2222
// Step 2: Specify which model to use:

‎javascriptv3/example_code/bedrock-runtime/scenarios/converse_tool_scenario/README.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Amazon Bedrock Runtime Converse API with Tool for the SDK for JavaScript (v3)
2+
3+
## Overview
4+
5+
This example shows how to use AWS SDKs and the Amazon Bedrock Converse API to call a custom tool from a large language model (LLM) as part of a multistep conversation. The example creates a weather tool that leverages the Open-Meteo API to retrieve current weather information based on user input.
6+
7+
## ⚠ Important
8+
9+
- Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/).
10+
- Running the tests might result in charges to your AWS account.
11+
- We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
12+
- This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
13+
14+
## Scenario
15+
16+
This example illustrates a typical interaction between a generative AI model, an application, and connected tools or APIs to solve a problem or achieve a specific goal. The scenario follows these steps:
17+
18+
1. Set up the system prompt and tool configuration.
19+
2. Specify the AI model to be used (e.g., Anthropic Claude 3 Sonnet).
20+
3. Create a client to interact with Amazon Bedrock.
21+
4. Prompt the user for their weather request.
22+
5. Send the user input including the conversation history to the model.
23+
6. The model processes the input and determines if a connected tool or API needs to be used. If this is the case, the model returns a tool use request with specific parameters needed to invoke the tool, and a unique tool use ID to correlate tool responses to the request.
24+
7. The scenario application invokes the tool to fetch weather data, and append the response and tool use ID to the conversation.
25+
8. The model uses the tool response to generate a final response. If additional tool requests are needed, the process is repeated.
26+
9. Once the final response is received and printed, the application returns to the prompt.
27+
28+
### Prerequisites
29+
30+
For prerequisites, see the [README](../../../../README.md#prerequisites) in the `javascriptv3` folder.
31+
32+
## Run the example
33+
34+
```bash
35+
node converse-tool-scenario.js
36+
```
37+
## Tests
38+
39+
⚠ Running tests might result in charges to your AWS account.
40+
41+
To find instructions for running these tests, see the [README](../../../../README.md#tests) in the `javascriptv3` folder.
42+
43+
## Additional resources
44+
45+
- [Documentation: The Amazon Bedrock User Guide](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)
46+
- [Tutorials: A developer's guide to Bedrock's new Converse API](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide)
47+
- [More examples: Amazon Bedrock code examples and scenarios in multiple programming languages](https://docs.aws.amazon.com/bedrock/latest/userguide/service_code_examples.html)
48+
49+
---
50+
51+
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
52+
53+
SPDX-License-Identifier: Apache-2.0

0 commit comments

Comments
 (0)