AWS Builder Center

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)

  1. 1
    Bedrock Tool Use in Python: A Working Guide This article
Lead Data Scientist

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:InvokeModel  on the model ARN.

The mental model

The tool-use loop is four steps:
  1. You send the user's message plus a tool definition ( toolConfig ).
  1. The model replies with  stopReason == "tool_use"  and a  toolUse  block naming the tool and the arguments it wants.
  1. You run the actual function and send the answer back as a  toolResult  block.
  1. 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-1
export MODEL_ID=us.anthropic.claude-sonnet-5-v1:0
If 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  messages  before you add the tool result. The  toolUseId  in your  toolResult  must 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 raises  TypeError , and on a tool that writes it's a real hole. Validate arguments first —  tool_use.py  in the repo does this in its  dispatch()  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)

  1. 1
    Bedrock Tool Use in Python: A Working Guide This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article