DEV Community: Pedro Ribeiro

Tooling with Amazon Bedrock

Pedro Ribeiro — Mon, 28 Sep 2026 05:13:45 +0000

This post is part of my notes from Formação AWS, a course by Henrylle Maia. It covers a class from Desafio Labs, one of the course's sections, that focuses on Amazon Bedrock.

In this class, I continue building the ticket-selling script for the AWS course from my previous article. This time, I add tools to it, giving the agent access to systems and actions that would otherwise be out of its reach.

The Tools

A tool gives the model a way to get information it has no other means of reaching. Imagine a user asks a financial agent for last quarter's earnings. That data lives in a database, and the only way to get it is to query the earnings and filter them by quarter.

Note: Tools aren't limited to reading data. They can also perform actions, > such as sending an email or placing an order. In this post, I only use tools > that return data: one reads from a mock database and the other returns a > payment link.

Giving the model direct access to the database would be risky. It could run queries beyond what the user asked for, and we would have no control over what it executes. The safer approach is to write a function that runs a specific, controlled query and returns only the data needed to answer the user.

To expose that function to the model, we wrap it in a tool definition: a name, a description of what it does, and the inputs it expects. The agent sends the available tool definitions to the model along with the user's message, so the model knows which tools it can use.

Here's what a tool definition looks like for the earnings example, in the format the Bedrock Converse API expects:

const toolConfig = {
  tools: [
    {
      toolSpec: {
        name: "get_quarterly_earnings",
        description:
          "Returns the company's earnings for a given quarter. " +
          "Use when the user asks about earnings for a specific period.",
        inputSchema: {
          json: {
            type: "object",
            properties: {
              year: { type: "integer", description: "Fiscal year, e.g. 2026" },
              quarter: { type: "integer", enum: [1, 2, 3, 4], description: "Fiscal quarter" },
            },
            required: ["year", "quarter"],
          },
        },
      },
    },
  ],
};

The model never sees the function itself, only this definition. It reads the description to decide when to call the tool, and the inputSchema (a JSON Schema) to know which inputs to send.

When the model decides it needs a tool, it doesn't answer the user right away. Instead, it responds with the tool's name and the inputs to pass to it. The agent runs the matching function with those inputs and sends the result back to the model, which uses it to write the final answer.

The Single Tool Example

The best way to learn something is to put it into practice. So to see how tools work with the Amazon Bedrock Converse API, I modified the Ticket Clerk Agent to call a tool that checks the status of the user's registration.

The code in this section is just a simple implementation to test the usage of tools.

The database is just a constant object named STUDENTS.

// Students "Database"
const STUDENTS = {
  "mary@email.com": {name: "Mary", ticket: "VIP", status: "confirmed", request: "VP-23842", payment_date: "20/09/2026"},
  "john@email.com": {name: "John", ticket: "Regular", status: "pending", request: "RG-24251"}
}

For the tool declaration, I defined a constant object, where the tools key has a list of tool specifications. In this example I only have one toolSpec, for a function that should be called when the model wants to check the registration status of the user. It requires an email to be given so it can search for the user.

// Declaring the tool for the model
const toolConfig = {
  tools: [
    {
      toolSpec: {
        name: "check_registration",
        description: 
          "Check the registration of a student by the email of purchase" +
          "use when the person asks if their purchase was confirmed, what ticket they have, or the request number" +
          "only call if the person has already given their email",
        inputSchema: {
          json: {
            type: "object",
            properties: {
              email: { type: "string", description: "email used on ticket purchase" },
            },
            required: ["email"],
          },
        },
      },
    },
  ]
}

Then I created a constant to work as a lookup table, associating each tool name with its function. So when the model returns the name of the tool it wants to run, the code checks this table and executes the corresponding function.

const EXECUTORS = { check_registration: checkRegistration };

The next important part is the tool loop. This is where the agent and the model go back and forth until the model has everything it needs to answer the user. Since it's a bit long, I'll go through it in parts.

The loop starts with a guard. The for has no stop condition of its own, so I check the turn counter against MAX_TOOL_TURNS (set to 5) and stop when the limit is reached. This keeps the model from calling tools forever if something goes wrong. Then the agent sends the whole conversation to the model with ConverseCommand, together with the toolConfig, so the model knows which tools it can use.

for (let turn = 0; ; turn++) {
  if (turn >= MAX_TOOL_TURNS ) {
    console.log(`⚠️ Reached the limit of ${MAX_TOOL_TURNS} tool calls. Stopping.`); 
    break;
  }

  const response = await client.send(
    new ConverseCommand({
      modelId: MODEL_ID,
      system: [
        { text: SYSTEM_PROMPT },
        { cachePoint: { type: "default", ttl: "1h" }},
      ],
      messages,
      toolConfig,
      inferenceConfig: { maxTokens: 512, temperature: 0.7 },
    })
  );
  ...
}

When the response comes back, I push the assistant message to the history. Then I check the stopReason. If it isn't "tool_use", the model is done, so I join the text blocks of the message, print the answer and leave the loop.

const assistantMessage = response.output.message;

messages.push(assistantMessage);

if (response.stopReason !== "tool_use") {
const assistantText = assistantMessage.content
  .filter((b) => b.text)
  .map((b) => b.text)
  .join("")

process.stdout.write("\n💳 Assistant:\n");
process.stdout.write(assistantText);
break;
}

If the stopReason is "tool_use", the model is asking to run one or more tools. The assistant message can have several content blocks, so I go through each one and skip anything that isn't a toolUse. For each tool request, I get the toolUseId, the tool name and its input, look up the function in EXECUTORS and run it. If the model asks for a tool that isn't in the table, the result is an error instead, so the model knows the call failed. Each result goes into a toolResult with the same toolUseId, so the model can match it with its request.

const toolResults = [];

for (const block of assistantMessage.content) {
if (!block.toolUse) continue;

const { toolUseId, name, input } = block.toolUse;

const executor = EXECUTORS[name];
const result = executor ? executor(input) : { error: `Unknown tool: ${name}` };

toolResults.push({
  toolResult: {
    toolUseId,
    content: [{ json: result }],
    status: executor ? "success" : "error",
  },
});
}

Finally, all the tool results go back together in a single user message. The loop then starts its next turn and sends the updated history to the model, which can either call another tool or write the final answer.

messages.push({role: "user", content: toolResults });

The full code is in this gist.

Results

For a first test, I asked for a registration status, and then the agent asked for my email and returned the correct data:

Then I asked for the registration status of a user that is not in the database:

So we can see that in both cases, the tool was called and provided the model with enough information for it to return the answer to the user.

Tool Chaining

Now, I added a new tool that generates a link for payment. But before generating the link, the model is instructed to call check_registration to check whether the user has already bought a ticket.

First I created the function to generate and return the payment link, if the email is in a valid format. In this example I am just returning a constant value, but in production, this function would generate a custom payment link.

const PAYMENT_LINK = "https://formacaoaws.com.br/payment-link";

function genPaymentLink({ email }) {
  const clean = (email ?? "").trim().toLowerCase();
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(clean)) {
    return { generated: false, reason: "invalid email" };
  }
  return { generated: true, email: clean, link: PAYMENT_LINK };
}

Then I added the new tool to toolConfig, so now the model has both tools to choose from.

const toolConfig = {
  tools: [
    {
      toolSpec: {
        name: "check_registration",
        description:
          "Check the registration of a student by the email of purchase " +
          "use when the person asks if their purchase was confirmed, what ticket they have, or the request number " +
          "only call if the person has already given their email ",
        inputSchema: {
          json: {
            type: "object",
            properties: {
              email: {
                type: "string",
                description: "email used on ticket purchase",
              },
            },
            required: ["email"],
          },
        },
      },
    },
    {
      toolSpec: {
        name: "gen_payment_link",
        description:
          "Generates ticket payment link. " +
          "Use it when the person wants to buy, pay or complete the purchase. " +
          "Only call this after the user provides their email. " +
          "MANDATORY before calling this tool: call check_registration with the same email. " +
          "If it returns status 'confirmed', DO NOT call this tool, the user has already paid; " +
          "Inform them of this and provide the order number. " +
          "Only generate the link if the registration does not exist or is not confirmed.",
        inputSchema: {
          json: {
            type: "object",
            properties: {
              email: {
                type: "string",
                description: "Email for sending the payment link",
              },
            },
            required: ["email"],
          },
        },
      },
    },
  ],
};

I also added it to the EXECUTORS object.

const EXECUTORS = {
  check_registration: checkRegistration,
  gen_payment_link: genPaymentLink,
};

The full code for this version is in this gist.

Results

For the first test, I said I wanted to buy a ticket and provided an email that is not registered. As you can see in the image below, both tools were called from just one prompt. The first one checked if the user existed, and the second one generated and returned the payment link.

When I asked to buy a ticket, providing an email that is already registered, it didn't even call the second tool.

Wrapping Up

With tools, the agent is no longer limited to what the model already knows. It can check a student's registration and generate a payment link, and the model decides when to call each tool just by reading their descriptions.

The tool chaining example shows this well. I didn't write any code to make check_registration run before gen_payment_link. The instruction in the tool description was enough for the model to call them in the right order, and to skip the second one when the user had already paid.

From Playground to Caching: Learning Amazon Bedrock

Pedro Ribeiro — Mon, 28 Sep 2026 05:10:36 +0000

This post is part of my notes from Formação AWS, a course by Henrylle Maia. It covers a class from Desafio Labs (one of the course's sections) that focuses on Amazon Bedrock.

In this class, I start with the Playground to get a feel for how Bedrock behaves, and then move on to scripts to learn how to actually use the Bedrock API.

To learn by doing, I created a simple chatbot that works like a clerk selling tickets for an AWS Course. It starts as a single Bash script that sends one message and prints the response, then I make it interactive so I can actually chat with it. From there, I move it to Node so I can stream the answers as they come in, and finally add a cache checkpoint so the same System Prompt doesn't get billed at full price on every message.

Getting Started with Amazon Bedrock

Amazon Bedrock is a fully managed AWS service that provides API access to multiple foundation models. There are several models to choose from, but for this project I'm using Anthropic's Claude Sonnet 4.5.

The Cross-Region Quota

When I selected my preferred model in the Playground and tried to send a prompt, I received the following error message: ThrottlingException: "Too many tokens per day, please wait before trying again."

Digging into it, I discovered that there is a quota called Cross-region model inference tokens per minute for Anthropic Claude Sonnet 4.5 V1. It limits the combined input and output tokens that can be sent to that model per minute through the cross-region inference profile, across every API: Converse, ConverseStream, InvokeModel and InvokeModelWithResponseStream.

Cross-region inference is a Bedrock feature that routes requests across multiple AWS Regions instead of keeping them in just one, so if one Region is busy, another can still take the request. The routing is automatic, but the throughput is still limited per model and per Region, and that limit is what I was hitting.

To fix this, I went to the Service Quotas console, found that quota for Claude Sonnet 4.5, and requested an increase to 5,000,000 tokens per minute.

Once the request showed up as Case Closed, I could finally start testing in the Playground.

Note: It looks like every model comes with its own quota, and none of them are active on the account by default, so each one has to be requested separately. This isn't very well documented or explained by AWS. I only found out how it works by poking around Service Quotas myself.

The Playground

The Playground is where I can test the model's responses directly in the AWS console and easily adjust parameters like Temperature, Top P and Top K. These parameters help tune the kind of response I get from the model.

Temperature is a value between 0 and 1. At 0, the model sticks to less creative options and returns a cold, mechanical response. At 1, it leans toward more creative options and may hallucinate more.

Top P limits the model's vocabulary. A value of 0.5 means it only chooses from the pool of words whose probabilities add up to 50%, while 0.95 means it chooses from the pool of words that add up to 95%. So a higher value makes the response more unpredictable, as it can choose a word that had a probability of 5%, for example.

Top K works a bit differently: it limits the model to the K most probable words. The higher the value, the bigger that pool of words gets for each prediction.

For the tests below, I kept the default value of Top K and set the temperature to 0.7, which seems to work well for customer relations. The responses aren't rigid and cold, but they also aren't so creative that the model starts to hallucinate.

Besides these sampling parameters, the Playground also lets me set a System Prompt, which gives the model the context it needs to generate the response for any user query. To see how much difference it makes, I ran two tests.

For the first test, I used a very simple System Prompt, just "Act like a ticket clerk". Then I asked for tickets for the game on Sunday, and the model gave a generic response: it asked which game I meant, how many tickets I needed, my seating preference and my budget.

For the second test, I used a longer, more detailed System Prompt. I told the model that it sells tickets for an AWS Training Course with AI, and that it should talk ONLY about the regular and VIP tickets, including the price and what's included in each one.

This time, when I asked for tickets for the game on Sunday, the model didn't fall for it. It clarified that it only sells tickets for the AWS Training Course, not for a game, and presented the two ticket options instead. When I said I was interested in the VIP ticket, it went on to explain what's included in it.

So a detailed System Prompt makes a big difference in keeping the model focused on the task I actually want it to do.

Scripting with the Converse API

Moving from the console to code, I wrote a simple Bash script. It sets the System Prompt, sends a single user message, and prints the model's response along with the token metrics.

# V1 - Basic Chatbot with Converse API
# Demonstrates only the use of System Prompt

#Use inference profile (cross-region) - prefix "us."
MODEL_ID="us.anthropic.claude-sonnet-4-5-20250929-v1:0"
REGION="us-east-1"

# System Prompt: behavior + context
BEHAVIOR="Act like a ticket clerk."
CONTEXT="You will sell my AWS Training Course with AI.
Talk ONLY about the regular and VIP tickets.
Regular ticket: \$15
VIP ticket: \$30
Regular: Live Event + Recording available for 2 days
VIP: Same from regular + extra class + Recording available for 7 days."

SYSTEM_PROMPT="$BEHAVIOR. $CONTEXT"

USER_PROMPT="I want to buy a ticket for the event"

echo "🤖 Ticket Selling Chatbot - V1 Basic (Converse API)"
echo "==================================================="
echo ""
echo "📝 System Prompt: "
echo "$SYSTEM_PROMPT"
echo ""
echo "⏳ Sending to Bedrock..."
echo ""

SYSTEM_JSON=$(jq -n --arg text "$SYSTEM_PROMPT" '[{"text": $text}]')

# Calling Bedrock with Converse API
RESPONSE=$(aws bedrock-runtime converse \
    --region $REGION \
    --model-id $MODEL_ID \
    --system "$SYSTEM_JSON" \
    --messages '[{"role":"user","content":[{"text":"'"$USER_PROMPT"'"}]}]' \
    --inference-config '{"maxTokens":512,"temperature":0.7}' \
    --output json)

ASSISTANT_RESPONSE=$(echo $RESPONSE | jq -r '.output.message.content[0].text')

echo "💳 ASSISTANT:"
echo "$ASSISTANT_RESPONSE"
echo ""

# Metrics
INPUT_TOKENS=$(echo $RESPONSE | jq -r '.usage.inputTokens')
OUTPUT_TOKENS=$(echo $RESPONSE | jq -r '.usage.outputTokens')
TOTAL_TOKENS=$(echo $RESPONSE | jq -r '.usage.totalTokens')

echo "📊 Metrics"
echo " Input Tokens: $INPUT_TOKENS"
echo " Output Tokens: $OUTPUT_TOKENS"
echo " Total Tokens: $TOTAL_TOKENS"

As you can see in the image below, the response followed the System Prompt and used a total of only 243 tokens.

For something closer to a real chatbot, I modified the script to keep accepting user prompts until the user quits. The System Prompt is also read from a file now, though I didn't change its contents for this part.

#V2 - Chatbot with Converse API in Interactive Loop
...

# Read System Prompt from external file
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SYSTEM_PROMPT=$(cat "$SCRIPT_DIR/system_prompt.txt")
SYSTEM_JSON=$(jq -n --arg text "$SYSTEM_PROMPT" '[{text: $text}]')

# Initialize empty messages history
MESSAGES_JSON='[]'

echo "🤖 Ticket Selling Chatbot - V2 Interactive Loop"
echo "==================================================="
echo ""
echo "📄 System prompt carregado de: system-prompt.txt"
echo ""
echo "💡 Type 'quit' to exit"
echo ""

while true; do
    echo -n "👤 You: "
    read USER_INPUT

    if [[ "$USER_INPUT" == "quit" ]]; then
        echo "👋 Bye!"
        break
    fi

    MESSAGES_JSON=$(echo "$MESSAGES_JSON" | jq --arg text "$USER_INPUT" '. += [{role: "user", content: [{text: $text}]}]')

    # Calling Bedrock with Converse API
    RESPONSE=$(aws bedrock-runtime converse \
        --region $REGION \
        --model-id $MODEL_ID \
        --system "$SYSTEM_JSON" \
        --messages "$MESSAGES_JSON" \
        --inference-config '{"maxTokens":512,"temperature":0.7}' \
        --output json)

    ASSISTANT_RESPONSE=$(echo $RESPONSE | jq -r '.output.message.content[0].text')

    MESSAGES_JSON=$(echo "$MESSAGES_JSON" | jq --arg text "$ASSISTANT_RESPONSE" '. += [{role: "assistant", content: [{text: $text}]}]')

    # Show response
    echo "🤖 ASSISTANT:"
    echo "$ASSISTANT_RESPONSE"
    echo ""

done

The interactive version allows the user to ask follow-up questions within the same context.

Streaming with Node

Then I moved the project to JavaScript and ran it with Node. The AWS SDK for JavaScript lets me call the streaming version of the Converse API.

// V3 - Streaming with SDK Node.js
// Version with code streaming for real time responses

import { readFileSync } from "node:fs";
import { fileURLToPath } from "node:url";
import { dirname, join } from "node:path";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";
import {
  BedrockRuntimeClient,
  ConverseStreamCommand,
} from "@aws-sdk/client-bedrock-runtime";

// Use inference profile (cross-region) - prefix "us."
const MODEL_ID = "us.anthropic.claude-sonnet-4-5-20250929-v1:0";
const REGION = "us-east-1";

// Read System Prompt from external file
const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
const SYSTEM_PROMPT = readFileSync(join(SCRIPT_DIR, "complete_prompt.txt"), "utf-8");
const SYSTEM_JSON = [{ text: SYSTEM_PROMPT }];

// Initialize empty messages history
let messages = [];

const client = new BedrockRuntimeClient({
  region: REGION,
  maxAttempts: 5,
  retryMode: "adaptive",
});

const rl = readline.createInterface({ input, output });

console.log("🤖 Ticket Selling Chatbot - V3 Streaming");
console.log("===================================================");
console.log("");
console.log("📄 System prompt carregado de: complete_prompt.txt");
console.log("");
console.log("💡 Type 'quit' to exit");
console.log("");

while (true) {
  const userInput = await rl.question("👤 You: ");

  if (userInput === "quit") {
    console.log("👋 Bye!");
    break;
  }

  messages.push({ role: "user", content: [{ text: userInput }] });

  // Calling Bedrock with Converse API
  const response = await client.send(
    new ConverseStreamCommand({
      modelId: MODEL_ID,
      system: SYSTEM_JSON,
      messages,
      inferenceConfig: { maxTokens: 512, temperature: 0.7 },
    })
  );

  process.stdout.write("\n💳 Assistant:\n");

  let assistantText = "";
  for await (const event of response.stream) {
    if (event.contentBlockDelta?.delta?.text) {
      const chunk = event.contentBlockDelta.delta.text;
      process.stdout.write(chunk);
      assistantText += chunk;
    }
  }

  messages.push({ role: "assistant", content: [{ text: assistantText }] });
  console.log("\n");
}

rl.close();

A streaming response makes the chatbot feel more natural. It feels like the bot is actually typing the answer (really fast) instead of the whole thing just showing up on the screen at once.

Prompt Caching

Next, I added a cache checkpoint to the System Prompt to see how caching actually affects the token cost.

Caching works by writing content to the cache once, at a cache checkpoint (in this case, right after the System Prompt). On the following requests, the model can read that content from the cache instead of processing it again as new input. Each cache checkpoint has a Time To Live (TTL): if no request reuses it within that window, it expires, and the next request has to write it again.

There are two TTL options available, 5 minutes and 1 hour, and I tested both.

// V4 - Streaming with Cache Point on System Prompt (5m)
...

while (true) {
  ...

  // Calling Bedrock with Converse API
  const response = await client.send(
    new ConverseStreamCommand({
      modelId: MODEL_ID,
      system: [
        { text: SYSTEM_PROMPT },
        { cachePoint: { type: "default", ttl: "5m" }},
      ],
      messages,
      inferenceConfig: { maxTokens: 512, temperature: 0.7 },
    })
  );

  ...
  let usage = {};

  for await (const event of response.stream) {
    ...
    if (event.metadata?.usage) {
      usage = event.metadata.usage;
    }
  }

  ...

  const output = usage.outputTokens ?? 0;
  const cacheRead = usage.cacheReadInputTokens ?? 0;
  const cacheWrite = usage.cacheWriteInputTokens ?? 0;
  const inputNoCache = usage.inputTokens ?? 0;
  const input = inputNoCache + cacheRead;

  console.log("\n");
  console.log("┌──────────────────────────────────────────────────┐");
  console.log("│                 📊  Token Usage                  │");
  console.log("├──────────────────────────────────────────────────┤");
  console.log(`│ Input total:        ${String(input).padStart(8)}  tokens             │`);
  console.log(`│   ├ Cache read:     ${String(cacheRead).padStart(8)}  (10% of price)     │`);
  console.log(`│   ├ Cache write:    ${String(cacheWrite).padStart(8)}  (125% of price)    │`);
  console.log(`│   └ No cache:       ${String(inputNoCache).padStart(8)}  (full price)       │`);
  console.log(`│ Output:             ${String(output).padStart(8)}  tokens             │`);
  console.log("└──────────────────────────────────────────────────┘");
}

The cache checkpoint goes right after the System Prompt in the system array, with a ttl field. For the 1-hour test, I used the same script and just changed the ttl to "1h".

Results

With the 5-minute cache, the first request had nothing to read yet, so it wrote the System Prompt to the cache. That write costs 125% of the normal price.

On the next request, still inside the 5-minute window, the model read the System Prompt from the cache instead of writing it again. That cache read costs only 10% of the normal price.

The 1-hour cache write costs more, 200% of the normal price, but it lasts a full hour instead of just 5 minutes.

Just like with the 5-minute cache, reading from the 1-hour cache costs 10% of the normal price.

So the tradeoff is simple: a longer cache costs more to write, but it pays off when messages come in more than 5 minutes apart, since the 5-minute cache would have expired and been written again at full write price.

Wrapping Up

That's as far as I got in this class: the quota is sorted, the Playground is explored, and the ticket chatbot now streams its answers and reuses its System Prompt instead of paying full price for it on every message. More to come.