.NET v3: Bedrock Converse API with Tool Feature Scenario Scout

.doc_gen/metadata/bedrock-runtime_metadata.yaml

@@ -108,6 +108,10 @@ bedrock-runtime_Converse_AmazonNovaText:
             - description: Send a text message to Amazon Nova, using Bedrock's Converse API.
               snippet_tags:
                 - BedrockRuntime.dotnetv3.Converse_AmazonNovaText
+            - description: Send a conversation of messages to Amazon Nova using Bedrock's Converse API with a tool configuration.
+              genai: some
+              snippet_tags:
+                - Bedrock.ConverseTool.dotnetv3.SendConverseRequest
     Python:
       versions:
         - sdk_version: 3
@@ -163,6 +167,60 @@ bedrock-runtime_Converse_AmazonTitanText:
   services:
     bedrock-runtime: {Converse}
 
+bedrock-runtime_Scenario_ToolUse:
+  title: "A tool use example illustrating how to connect AI models on &BR; with a custom tool or API"
+  title_abbrev: "Tool use with the Converse API"
+  synopsis: "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."
+  category: Scenarios
+  languages:
+    .NET:
+      versions:
+        - sdk_version: 3
+          github: dotnetv3/Bedrock-runtime/Scenarios/ConverseToolScenario
+          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.dotnetv3.Scenario
+            - description: "The weather tool used by the demo. This file defines the tool specification and implements the logic to retrieve weather data using from the Open-Meteo API."
+              genai: some
+              snippet_tags:
+                - Bedrock.ConverseTool.dotnetv3.WeatherTool
+            - description: "The Converse API action with a tool configuration."
+              genai: some
+              snippet_tags:
+                - Bedrock.ConverseTool.dotnetv3.SendConverseRequest
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/bedrock-runtime
+          excerpts:
+            - description: "The primary execution script of the demo. This script orchestrates the conversation between the user, the &BR; Converse API, and a weather tool."
+              snippet_files:
+                - python/example_code/bedrock-runtime/cross-model-scenarios/tool_use_demo/tool_use_demo.py
+            - description: "The weather tool used by the demo. This script defines the tool specification and implements the logic to retrieve weather data using from the Open-Meteo API."
+              snippet_files:
+                - python/example_code/bedrock-runtime/cross-model-scenarios/tool_use_demo/weather_tool.py
+    Rust:
+      versions:
+        - sdk_version: 1
+          github: rustv1/examples/bedrock-runtime
+          excerpts:
+            - description: "The primary scenario and logic for the demo. This orchestrates the conversation between the user, the &BR; Converse API, and a weather tool."
+              snippet_tags:
+                - rust.bedrock-runtime.Converse_AnthropicClaude.tool-use
+            - description: "The weather tool used by the demo. This script defines the tool specification and implements the logic to retrieve weather data using from the Open-Meteo API."
+              snippet_tags:
+                - rust.bedrock-runtime.Converse_AnthropicClaude.tool-use.weather-tool
+            - description: "Utilities to print the Message Content Blocks."
+              snippet_tags:
+                - rust.bedrock-runtime.Converse_AnthropicClaude.tool-use.user-interface
+            - description: "Use statements, Error utility, and constants."
+              snippet_tags:
+                - rust.bedrock-runtime.Converse_AnthropicClaude.tool-use.supporting
+  services:
+    bedrock-runtime: {Converse}
+
 bedrock-runtime_Converse_AnthropicClaude:
   title: Invoke Anthropic Claude on &BR; using Bedrock's Converse API
   title_abbrev: "Converse"
@@ -1315,6 +1373,32 @@ bedrock-runtime_InvokeModelWithResponseStream_TitanTextEmbeddings:
     bedrock-runtime: {InvokeModel}
 
 # Tool use scenarios
+bedrock-runtime_Scenario_ToolUseDemo_AmazonNova:
+  title: "A tool use demo illustrating how to connect AI models on &BR; with a custom tool or API"
+  title_abbrev: "Scenario: Tool use with the Converse API"
+  synopsis: "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."
+  category: Amazon Nova
+  languages:
+    .NET:
+      versions:
+        - sdk_version: 3
+          github: dotnetv3/Bedrock-runtime/Scenarios/ConverseToolScenario
+          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.dotnetv3.Scenario
+            - description: "The weather tool used by the demo. This file defines the tool specification and implements the logic to retrieve weather data using from the Open-Meteo API."
+              genai: some
+              snippet_tags:
+                - Bedrock.ConverseTool.dotnetv3.WeatherTool
+            - description: "The Converse API action with a tool configuration."
+              genai: some
+              snippet_tags:
+                - Bedrock.ConverseTool.dotnetv3.SendConverseRequest
+  services:
+    bedrock-runtime: {Converse}
+
 bedrock-runtime_Scenario_ToolUseDemo_AnthropicClaude:
   title: "A tool use demo illustrating how to connect AI models on &BR; with a custom tool or API"
   title_abbrev: "Scenario: Tool use with the Converse API"
@@ -1349,7 +1433,6 @@ bedrock-runtime_Scenario_ToolUseDemo_AnthropicClaude:
             - description: "Use statements, Error utility, and constants."
               snippet_tags:
                 - rust.bedrock-runtime.Converse_AnthropicClaude.tool-use.supporting
-
   services:
     bedrock-runtime: {Converse}
 

dotnetv3/Bedrock-runtime/BedrockRuntimeExamples.sln

@@ -106,6 +106,14 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "AmazonNovaCanvas", "AmazonN
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "InvokeModel", "Models\AmazonNova\AmazonNovaCanvas\InvokeModel\InvokeModel.csproj", "{2B39D4E2-C6B6-4340-A9AD-5F5C25CA8C1D}"
 EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Actions", "Actions", "{FDC95D1E-41C6-45A5-BF29-F76FCC3DAEF9}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BedrockRuntimeActions", "Actions\BedrockRuntimeActions.csproj", "{ABA0C307-C7A1-4BBE-A7E2-4BA7163559FC}"
+EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Scenarios", "Scenarios", "{045D214B-6181-43B0-ABFE-246675F4D967}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "ConverseToolScenario", "Scenarios\ConverseToolScenario\ConverseToolScenario.csproj", "{C0A5B872-03F5-4865-9349-7A403591C50E}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -224,6 +232,14 @@ Global
 		{2B39D4E2-C6B6-4340-A9AD-5F5C25CA8C1D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{2B39D4E2-C6B6-4340-A9AD-5F5C25CA8C1D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{2B39D4E2-C6B6-4340-A9AD-5F5C25CA8C1D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{ABA0C307-C7A1-4BBE-A7E2-4BA7163559FC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{ABA0C307-C7A1-4BBE-A7E2-4BA7163559FC}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{ABA0C307-C7A1-4BBE-A7E2-4BA7163559FC}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{ABA0C307-C7A1-4BBE-A7E2-4BA7163559FC}.Release|Any CPU.Build.0 = Release|Any CPU
+		{C0A5B872-03F5-4865-9349-7A403591C50E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{C0A5B872-03F5-4865-9349-7A403591C50E}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{C0A5B872-03F5-4865-9349-7A403591C50E}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{C0A5B872-03F5-4865-9349-7A403591C50E}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -266,6 +282,8 @@ Global
 		{E144492A-337A-0755-EAB4-DA083C3A2DDB} = {02EA681E-C7D8-13C7-8484-4AC65E1B71E8}
 		{4D3E429C-CCAE-42DE-A062-4717E71D8403} = {3AF63EC9-2EB0-4A0B-8C3B-0CA3595080F6}
 		{2B39D4E2-C6B6-4340-A9AD-5F5C25CA8C1D} = {4D3E429C-CCAE-42DE-A062-4717E71D8403}
+		{ABA0C307-C7A1-4BBE-A7E2-4BA7163559FC} = {FDC95D1E-41C6-45A5-BF29-F76FCC3DAEF9}
+		{C0A5B872-03F5-4865-9349-7A403591C50E} = {045D214B-6181-43B0-ABFE-246675F4D967}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {E48A5088-1BBB-4A8B-9AB2-CC5CE0482466}

dotnetv3/Bedrock-runtime/README.md

@@ -28,6 +28,13 @@ For prerequisites, see the [README](../README.md#Prerequisites) in the `dotnetv3
 
 <!--custom.prerequisites.start-->
 <!--custom.prerequisites.end-->
+### Scenarios
+
+Code examples that show you how to accomplish a specific task by calling multiple
+functions within the same service.
+
+- [Tool use with the Converse API](Scenarios/ConverseToolScenario/ConverseToolScenario.cs)
+
 ### AI21 Labs Jurassic-2
 
 - [Converse](Models/Ai21LabsJurassic2/Converse/Converse.cs#L4)
@@ -37,6 +44,7 @@ For prerequisites, see the [README](../README.md#Prerequisites) in the `dotnetv3
 
 - [Converse](Models/AmazonNova/AmazonNovaText/Converse/Converse.cs#L4)
 - [ConverseStream](Models/AmazonNova/AmazonNovaText/ConverseStream/ConverseStream.cs#L4)
+- [Scenario: Tool use with the Converse API](Scenarios/ConverseToolScenario/ConverseToolScenario.cs#L4)
 
 ### Amazon Nova Canvas
 
@@ -110,6 +118,18 @@ Alternatively, you can run the example from within your IDE.
 
 
 
+#### 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.

dotnetv3/Bedrock-runtime/Scenarios/ConverseToolScenario/BedrockActionsWrapper.cs

@@ -0,0 +1,82 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. 
+// SPDX-License-Identifier: Apache-2.0
+
+using Amazon.BedrockRuntime;
+using Amazon.BedrockRuntime.Model;
+using Microsoft.Extensions.Logging;
+
+namespace ConverseToolScenario;
+
+// snippet-start:[Bedrock.ConverseTool.dotnetv3.SendConverseRequest]
+
+/// <summary>
+/// Wrapper class for interacting with the Amazon Bedrock Converse API.
+/// </summary>
+public class BedrockActionsWrapper
+{
+    private readonly IAmazonBedrockRuntime _bedrockClient;
+    private readonly ILogger<BedrockActionsWrapper> _logger;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="BedrockActionsWrapper"/> class.
+    /// </summary>
+    /// <param name="bedrockClient">The Bedrock Converse API client.</param>
+    /// <param name="logger">The logger instance.</param>
+    public BedrockActionsWrapper(IAmazonBedrockRuntime bedrockClient, ILogger<BedrockActionsWrapper> logger)
+    {
+        _bedrockClient = bedrockClient;
+        _logger = logger;
+    }
+
+    /// <summary>
+    /// Sends a Converse request to the Amazon Bedrock Converse API.
+    /// </summary>
+    /// <param name="modelId">The Bedrock Model Id.</param>
+    /// <param name="systemPrompt">A system prompt instruction.</param>
+    /// <param name="conversation">The array of messages in the conversation.</param>
+    /// <param name="toolSpec">The specification for a tool.</param>
+    /// <returns>The response of the model.</returns>
+    public async Task<ConverseResponse> SendConverseRequestAsync(string modelId, string systemPrompt, List<Message> conversation, ToolSpecification toolSpec)
+    {
+        try
+        {
+            var request = new ConverseRequest()
+            {
+                ModelId = modelId,
+                System = new List<SystemContentBlock>()
+                {
+                    new SystemContentBlock()
+                    {
+                        Text = systemPrompt
+                    }
+                },
+                Messages = conversation,
+                ToolConfig = new ToolConfiguration()
+                {
+                    Tools = new List<Tool>()
+                    {
+                        new Tool()
+                        {
+                            ToolSpec = toolSpec
+                        }
+                    }
+                }
+            };
+
+            var response = await _bedrockClient.ConverseAsync(request);
+
+            return response;
+        }
+        catch (ModelNotReadyException ex)
+        {
+            _logger.LogError(ex, "Model not ready, please wait and try again.");
+            throw;
+        }
+        catch (AmazonBedrockRuntimeException ex)
+        {
+            _logger.LogError(ex, "Error occurred while sending Converse request.");
+            throw;
+        }
+    }
+}
+// snippet-end:[Bedrock.ConverseTool.dotnetv3.SendConverseRequest]