Bedrock Tool Use in Python: A Working Guide
A copy-pasteable Amazon Bedrock tutorial: wire up tool use (function calling) with the Converse API in Python, handle the tool loop, and control cost.
Series: Bedrock Builder's Log (6 articles)
- 1Bedrock Tool Use in Python: A Working Guide This article
Give a Bedrock Model Hands: Tool Use in Python, End to End
📦 Companion repo: github.com/AashimaYuthika/bedrock-converse-tool-use-starter — clone it and run the exact code from this article.
A language model on its own can only produce text. The moment you want it to do something — check live inventory, call your pricing service, look up a customer record — you need tool use (also called function calling). Amazon Bedrock's Converse API makes this refreshingly uniform: the same request/response shape works across Claude, Command, Nova, and other models, so you learn the loop once and reuse it everywhere.
This is a complete, reproducible walkthrough. Copy it, run it, and you'll have a model that decides when to call your Python function and then reasons over the result. Everything here is in the companion repo,
bedrock-converse-tool-use-starter — clone it if you'd rather run than paste.Prerequisites
- An AWS account with Amazon Bedrock model access granted for at least one tool-capable model (Console → Bedrock → Model access). We'll use Anthropic Claude here.
- Python 3.9+ and
boto3≥ 1.34:pip install boto3
- Credentials configured (
aws configure) for a Region where your model is available, e.g.us-east-1.
- An IAM policy allowing
bedrock:InvokeModelon the model ARN.
The mental model
The tool-use loop is four steps:
- You send the user's message plus a tool definition (
toolConfig).
- The model replies with
stopReason == "tool_use"and atoolUseblock naming the tool and the arguments it wants.
- You run the actual function and send the answer back as a
toolResultblock.
- The model reads your result and produces a final natural-language answer.
The model never runs your code — it only asks you to. That boundary is the whole security story of tool use, and it's why you stay in control.
Pick a model ID that actually resolves
This is the step most likely to bite you, and it burned me while building the repo. Bedrock model IDs vary by Region and by what your account has been granted — and most current Claude models are reachable only through a cross-region inference profile (the
us. prefix), not a bare model ID. The older anthropic.claude-3-5-sonnet-20240620-v1:0 string you'll see in many tutorials has since been retired and now 404s. Use a current one:bash
export AWS_REGION=us-east-1export MODEL_ID=us.anthropic.claude-sonnet-5-v1:0If a call fails with
ValidationException , AccessDeniedException , or ResourceNotFoundException , run list_models.py from the repo to print the IDs your account can actually reach, then export one of those.The code
python
import boto3
brt = boto3.client("bedrock-runtime", region_name="us-east-1")MODEL_ID = "us.anthropic.claude-sonnet-5-v1:0" # a cross-region inference profile
# 1. Your real function. Here it's mocked; swap in a live API call.def get_weather(city: str) -> dict: fake_db = {"Mumbai": {"tempC": 31, "sky": "humid"}, "Bengaluru": {"tempC": 24, "sky": "cloudy"}} return fake_db.get(city, {"error": f"No data for {city}"})
# 2. Describe the tool to the model (JSON Schema input).tool_config = { "tools": [{ "toolSpec": { "name": "get_weather", "description": "Get current weather for a city.", "inputSchema": {"json": { "type": "object", "properties": { "city": {"type": "string", "description": "City name, e.g. Mumbai"} }, "required": ["city"] }} } }]}
def text_of(message: dict) -> str: # Don't assume content[0] is text — a model may emit other blocks first. return next(b["text"] for b in message["content"] if "text" in b)
def run(user_text: str): messages = [{"role": "user", "content": [{"text": user_text}]}]
resp = brt.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config) messages.append(resp["output"]["message"])
# 3. If the model asked for a tool, run it and reply. if resp["stopReason"] == "tool_use": tool_results = [] for block in resp["output"]["message"]["content"]: if "toolUse" not in block: continue tu = block["toolUse"] result = get_weather(**tu["input"]) # see note below tool_results.append({"toolResult": { "toolUseId": tu["toolUseId"], "content": [{"json": result}] }}) messages.append({"role": "user", "content": tool_results})
# 4. Send the result back for a final answer. resp = brt.converse(modelId=MODEL_ID, messages=messages, toolConfig=tool_config)
print(text_of(resp["output"]["message"]))
if __name__ == "__main__": run("What's the weather in Mumbai, and should I carry an umbrella?")Run it and the model calls
get_weather , gets back {"tempC": 31, "sky": "humid"} , and folds that into a sensible answer — no hard-coded "if the user asks about weather" branch anywhere.The details that trip people up
- Append the model's message to
messagesbefore you add the tool result. ThetoolUseIdin yourtoolResultmust match the one the model issued, and the history has to stay coherent or the second call errors.
- Don't splat model-supplied input into your function.
get_weather(**tu["input"])is fine for a demo, but on an unexpected key it raisesTypeError, and on a tool that writes it's a real hole. Validate arguments first —tool_use.pyin the repo does this in itsdispatch()function.
- Return
{"json": ...}for structured data,{"text": ...}for a string. On failure add"status": "error"so the model recovers instead of trusting garbage.
- Loop — don't assume one round trip. A capable model may chain several tool calls. The minimal snippet handles exactly one; wrap steps 2–4 in
while resp["stopReason"] == "tool_use"with a hop cap for production.
Cost implications
Converse is billed as normal Bedrock inference — per input and output token, no separate tool-use surcharge. The hidden multiplier: every tool round trip re-sends the full conversation, including your tool schema and prior results, as input tokens. A three-hop chain can quietly 3–4x your input token count. In the repo,
tool_use.py caps this with MAX_TOOL_HOPS and prints a [usage] line so the multiplier is visible per run. Keep tool descriptions tight, and don't attach ten tools when one will do.Cleanup
Nothing to tear down — Converse is fully serverless, so you pay only for the calls you made. If you created a dedicated IAM policy or user for the tutorial, delete it. If you enabled model access purely to test, you can leave it (free until you invoke) or revoke it under Model access.
Why I'd build it this way
The win here isn't the API — it's the discipline of keeping the model as a planner and your code as the executor. That separation gives you a natural audit point (log every
toolUse request), a natural security boundary (validate arguments before running anything), and a natural cost lever (cap the loop). Start with one tool and a hard hop limit; add tools only when a real request demands them. The full bedrock-converse-tool-use-starter repo shows both the minimal version and the hardened one side by side.What's the first internal function you'd hand to a Bedrock model — a read-only lookup, or would you trust it with something that writes? Where do you draw that line?
#AWS #Bedrock #GenAI #Python #ToolUse #FunctionCalling #MachineLearning #boto3
Series: Bedrock Builder's Log (6 articles)
- 1Bedrock Tool Use in Python: A Working Guide This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article