AWS bedrock documentation change
Summary
Complete rewrite of the tool-use documentation. Removed detailed implementation examples and replaced with high-level overview of tool use modes. Added categorization table showing client-side, server-side, and Anthropic Claude tool use approaches.
Security assessment
The changes restructure documentation without addressing specific security vulnerabilities. While server-side tool use inherently improves security by centralizing execution, the changes don't reference any new vulnerabilities, security incidents, or specific security enhancements. The rewrite focuses on conceptual organization rather than security improvements.
Diff
diff --git a/bedrock/latest/userguide/tool-use.md b/bedrock/latest/userguide/tool-use.md index f82e81644..cf05a8924 100644 --- a//bedrock/latest/userguide/tool-use.md +++ b//bedrock/latest/userguide/tool-use.md @@ -7,2 +6,0 @@ -Server-side tool-use integration with AgentCore Gateway - @@ -17,627 +15 @@ You can now use structured outputs with tool use. See [Get validated JSON result -In Amazon Bedrock, the model doesn't directly call the tool. Rather, when you send a message to a model, you also supply a definition for one or more tools that could potentially help the model generate a response. In this example, you would supply a definition for a tool that returns the most popular song for a specified radio station. If the model determines that it needs the tool to generate a response for the message, the model, depending on the API used to invoke the model, can perform either client-side calling or ask Bedrock to call the tool using server-side tool calling. Let us discuss these two options in more detail. - -**Client-side tool calling** - -If you use the Responses API, Chat Completions API, Converse API, or InvokeModel API to send the request, then the model uses client-side tool calling. This means that in your code, you call the tool on the model's behalf. In this scenario, assume the tool implementation is an API. The tool could just as easily be a database, Lambda function, or some other software. You decide how you want to implement the tool. You then continue the conversation with the model by supplying a message with the result from the tool. Finally, the model generates a response for the original message that includes the tool results that you sent to the model. - -Let us define the tool we will use for tool use. The following Python examples show how to use a tool that returns the most popular song on a fictional radio station. - - - def get_most_popular_song(station_name: str) -> str: - stations = { - "Radio Free Mars": "Starman – David Bowie", - "Neo Tokyo FM": "Plastic Love – Mariya Takeuchi", - "Cloud Nine Radio": "Blinding Lights – The Weeknd", - } - return stations.get(station_name, "Unknown Station – No chart data available") - -**Using Responses API for client-side tooling** - -You can use the [Function calling](https://platform.openai.com/docs/guides/function-calling) feature provided by OpenAI to call this tool. Responses API is OpenAI's preferred API. Here is the Python code for Responses API for client-side tooling: - - - from openai import OpenAI - import json - - client = OpenAI() - - response = client.responses.create( - model="oss-gpt-120b", - input="What is the most popular song on Radio Free Mars?", - tools=[ - { - "type": "function", - "name": "get_most_popular_song", - "description": "Returns the most popular song on a radio station", - "parameters": { - "type": "object", - "properties": { - "station_name": { - "type": "string", - "description": "Name of the radio station" - } - }, - "required": ["station_name"] - } - } - ] - ) - - if response.output and response.output[0].content: - tool_call = response.output[0].content[0] - args = json.loads(tool_call["arguments"]) - result = get_most_popular_song(args["station_name"]) - - final_response = client.responses.create( - model="oss-gpt-120b", - input=[ - { - "role": "tool", - "tool_call_id": tool_call["id"], - "content": result - } - ] - ) - - print(final_response.output_text) - -**Using Chat Completions API for client-side tooling** - -You can use the Chat Completions API also. Here is the Python code for using Chat Completions: - - - from openai import OpenAI - import json - - client = OpenAI() - - completion = client.chat.completions.create( - model="oss-gpt-120b", - messages=[{"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"}], - tools=[{ - "type": "function", - "function": { - "name": "get_most_popular_song", - "description": "Returns the most popular song on a radio station", - "parameters": { - "type": "object", - "properties": { - "station_name": {"type": "string", "description": "Name of the radio station"} - }, - "required": ["station_name"] - } - } - }] - ) - - message = completion.choices[0].message - - if message.tool_calls: - tool_call = message.tool_calls[0] - args = json.loads(tool_call.function.arguments) - result = get_most_popular_song(args["station_name"]) - - followup = client.chat.completions.create( - model="oss-gpt-120b", - messages=[ - {"role": "user", "content": "What is the most popular song on Neo Tokyo FM?"}, - message, - {"role": "tool", "tool_call_id": tool_call.id, "content": result} - ] - ) - - print(followup.choices[0].message.content) - - -For more details on the using Function Calling on Responses API and Chat Completions API, see [Function Calling](https://platform.openai.com/docs/guides/function-calling) in OpenAI. - -**Using Converse API for client-side tooling** - -You can use the [Converse API](https://docs.aws.amazon.com/bedrock/latest/userguide/conversation-inference.html) to let a model use a tool in a conversation. The following Python examples show how to use a tool that returns the most popular song on a fictional radio station. - - - # Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. - # SPDX-License-Identifier: Apache-2.0 - """Shows how to use tools with the Converse API and the Cohere Command R model.""" - - import logging - import json - import boto3 - from botocore.exceptions import ClientError - - - class StationNotFoundError(Exception): - """Raised when a radio station isn't found.""" - pass - - - logger = logging.getLogger(__name__) - logging.basicConfig(level=logging.INFO) - - - def get_top_song(call_sign): - """Returns the most popular song for the requested station. - - Args: - call_sign (str): The call sign for the station for which you want - the most popular song. - - Returns: - response (json): The most popular song and artist. - """ - song = "" - artist = "" - - if call_sign == 'WZPZ': - song = "Elemental Hotel" - artist = "8 Storey Hike" - else: - raise StationNotFoundError(f"Station {call_sign} not found.") - - return song, artist - - - def generate_text(bedrock_client, model_id, tool_config, input_text): - """Generates text using the supplied Amazon Bedrock model. If necessary, - the function handles tool use requests and sends the result to the model. - - Args: - bedrock_client: The Boto3 Bedrock runtime client. - model_id (str): The Amazon Bedrock model ID. - tool_config (dict): The tool configuration. - input_text (str): The input text. - - Returns: - Nothing. - """ - logger.info("Generating text with model %s", model_id) - - # Create the initial message from the user input. - messages = [{"role": "user", - "content": [{"text": input_text}]}] - - response = bedrock_client.converse(modelId=model_id, - messages=messages, - toolConfig=tool_config) - - output_message = response['output']['message'] - messages.append(output_message) - - stop_reason = response['stopReason'] - - if stop_reason == 'tool_use':