JavaScriptv3: Bedrock agent runtime tool use scenario example

.doc_gen/metadata/bedrock-runtime_metadata.yaml

@@ -206,6 +206,15 @@ bedrock-runtime_Scenario_ToolUse:
               genai: some
               snippet_tags:
                 - Bedrock.ConverseTool.dotnetv3.SendConverseRequest
+    JavaScript:
+      versions:
+        - sdk_version: 3
+          github: javascriptv3/example_code/bedrock-runtime/scenarios/converse_tool_scenario
+          excerpts:
+            - description: "The primary execution of the scenario flow. This scenario orchestrates the conversation between the user, the &BR; Converse API, and a weather tool."
+              genai: some
+              snippet_tags:
+                - Bedrock.ConverseTool.javascript.Scenario
     Python:
       versions:
         - sdk_version: 3

.doc_gen/validation.yaml

@@ -1,5 +1,6 @@
 allow_list:
   # Git commits
+  - "cad7e7ba2c59a54837212e789a5304b9108fac47"
   - "cd5e746ec203c8c3c61647e0886a8df8c1e78e41"
   - "725feb26d6f73bc1d83dbbe075ae8ea991efb245"
   - "e9772d140489982e0e3704fea5ee93d536f1e275"

.tools/readmes/requirements.txt

@@ -1,4 +1,4 @@
 jinja2>=3.0.3
 pyyaml>=5.3.1
 typer==0.15.1
-aws-doc-sdk-examples-tools @ git+https://github.com/awsdocs/aws-doc-sdk-examples-tools
+aws-doc-sdk-examples-tools @ git+https://github.com/awsdocs/aws-doc-sdk-examples-tools

.tools/readmes/requirements_freeze.txt

@@ -1,12 +1,24 @@
-aws_doc_sdk_examples_tools @ git+https://github.com/awsdocs/[email protected]
+amazon-dax-client==2.0.3
+antlr4-python3-runtime==4.9.3
+attrs==22.1.0
+aws-doc-sdk-examples-tools @ git+https://github.com/awsdocs/aws-doc-sdk-examples-tools@cad7e7ba2c59a54837212e789a5304b9108fac47
 black==24.3.0
+boto3==1.35.98
+botocore==1.35.98
 certifi==2025.1.31
 charset-normalizer==3.4.1
 click==8.1.8
+colorama==0.4.6
+distlib==0.3.8
+exceptiongroup==1.2.2
+filelock==3.13.4
 flake8==6.1.0
+gitdb==4.0.11
+GitPython==3.1.43
 idna==3.10
 iniconfig==2.0.0
 Jinja2==3.1.6
+jmespath==1.0.1
 markdown-it-py==3.0.0
 MarkupSafe==3.0.2
 mccabe==0.7.0
@@ -17,16 +29,29 @@ packaging==24.2
 pathspec==0.11.2
 platformdirs==4.3.6
 pluggy==1.5.0
+psutil==5.8.0
 pycodestyle==2.11.1
 pyflakes==3.1.0
 Pygments==2.19.1
+pyparsing==3.0.9
 pytest==8.0.0
+python-dateutil==2.8.2
+pytz==2023.3.post1
 PyYAML==6.0.1
 requests==2.32.0
 rich==13.9.4
+ruamel.yaml==0.18.5
+ruamel.yaml.clib==0.2.8
+s3transfer==0.10.4
 shellingham==1.5.4
+six==1.16.0
+smmap==5.0.1
+tomli==2.2.1
 typer==0.15.1
 types-PyYAML==6.0.12.12
 typing_extensions==4.12.2
+tzdata==2023.3
 urllib3==2.3.0
-yamale==4.0.4
+virtualenv==20.25.1
+virtualenvwrapper-win==1.2.7
+yamale==4.0.4

javascriptv3/example_code/bedrock-runtime/README.md

@@ -44,6 +44,7 @@ Code examples that show you how to accomplish a specific task by calling multipl
 functions within the same service.
 
 - [Invoke multiple foundation models on Amazon Bedrock](scenarios/cli_text_playground.js)
+- [Tool use with the Converse API](scenarios/converse_tool_scenario/converse-tool-scenario.js)
 
 ### AI21 Labs Jurassic-2
 
@@ -148,6 +149,18 @@ This example shows you how to prepare and send a prompt to a variety of large-la
 <!--custom.scenarios.bedrock-runtime_Scenario_InvokeModels.start-->
 <!--custom.scenarios.bedrock-runtime_Scenario_InvokeModels.end-->
 
+#### Tool use with the Converse API
+
+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.
+
+
+<!--custom.scenario_prereqs.bedrock-runtime_Scenario_ToolUse.start-->
+<!--custom.scenario_prereqs.bedrock-runtime_Scenario_ToolUse.end-->
+
+
+<!--custom.scenarios.bedrock-runtime_Scenario_ToolUse.start-->
+<!--custom.scenarios.bedrock-runtime_Scenario_ToolUse.end-->
+
 ### Tests
 
 ⚠ Running tests might result in charges to your AWS account.

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

@@ -0,0 +1,53 @@
+# Amazon S3 Directory Bucket Basics for the SDK for JavaScript (v3)
+
+## Overview
+
+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.
+
+## ⚠ Important
+
+- 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/).
+- Running the tests might result in charges to your AWS account.
+- 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).
+- 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).
+
+## Scenario
+
+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:
+
+1. Set up the system prompt and tool configuration. 
+2. Specify the AI model to be used (e.g., Anthropic Claude 3 Sonnet). 
+3. Create a client to interact with Amazon Bedrock. 
+4. Prompt the user for their weather request. 
+5. Send the user input including the conversation history to the model.
+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.
+7. The scenario application invokes the tool to fetch weather data, and append the response and tool use ID to the conversation.
+8. The model uses the tool response to generate a final response. If additional tool requests are needed, the process is repeated.
+9. Once the final response is received and printed, the application returns to the prompt.
+
+### Prerequisites
+
+For prerequisites, see the [README](../../../../README.md#prerequisites) in the `javascriptv3` folder.
+
+## Run the example
+
+```bash
+node converse-tool-scenario.js
+```
+## Tests
+
+⚠ Running tests might result in charges to your AWS account.
+
+To find instructions for running these tests, see the [README](../../../../README.md#tests) in the `javascriptv3` folder.
+
+## Additional resources
+
+- [Documentation: The Amazon Bedrock User Guide](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html)
+- [Tutorials: A developer's guide to Bedrock's new Converse API](https://community.aws/content/2dtauBCeDa703x7fDS9Q30MJoBA/amazon-bedrock-converse-api-developer-guide)
+- [More examples: Amazon Bedrock code examples and scenarios in multiple programming languages](https://docs.aws.amazon.com/bedrock/latest/userguide/service_code_examples.html)
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0