Before I Build My First Bedrock Agent: 5 Rules I Locked Down First

I opened the Bedrock docs three times and closed the tab three times. Not because it was hard. Because I already knew how this ends: I ship a prompt that works on a Tuesday, it breaks on a Wednesday, and I lose a day debugging a str that used to be a dict.

I have not built the agent yet. This is the contract I wrote before opening boto3, so the happy path is not the only path I know how to walk.

Context, so you can judge how much of this is engineering and how much is scar tissue: I run three client sites — a nutrition clinic, a diet and training centre with an admin dashboard, a phone-accessory shop — on Railway and Vercel. Not AWS. I have $30 of AWS student credits and one rule: if an EC2 instance, an RDS database or a NAT gateway is not needed today, I stop it or I delete it. I write software for a living. I am a beginner at this specific thing.

Every time a model hands me JSON I asked for in a prompt, I remember a month of CSS bugs where a class existed and nothing ever used it. Same bug with a nicer name: defined but never wired.

"Reply with JSON only" does not mean JSON. It means JSON wrapped in a markdown fence, or JSON preceded by "Sure!", or JSON with a trailing comma. So the output contract lives in a model, and a response that fails validation is an exception I handle — not a string I clean up on a Friday afternoon.

The model does not get to decide whether it uses a tool. toolChoice decides. Without it I am writing a program where a percentage decides which branch runs, and I have shipped enough of those already.

response["stopReason"] being "tool_use" is the normal path, not an error. I validate response["output"]["message"]["content"][0]["toolUse"]["input"] against the same schema, run the tool, and send the result back as a toolResult block in the next turn. If I skip that second turn the agent just talks to itself, which is a sentence I would like to avoid saying about my own code.

I want a lookup agent, not a creative writing partner. Zero temperature, and a hard maxTokens — because the cheapest way to survive a runaway loop is to make each step unable to run away. That cap also protects the budget, which brings me to the boring section.

Not after the first incident. My incidents are always cheaper to prevent than to explain, and I have spent one whole Sunday reading my own Supabase logs because a policy was missing. guardrailConfig is four lines. There is no version of me that has an excuse for putting it in later, only the version that was in a hurry, and that version never wins.

I score myself 0% at testing, so I made this a rule instead of an aspiration. Ten questions written down before I write the agent, with the shape of the answer I expect. Run all ten after every change. If the shape moves, I stop and read the diff. A prompt is code with worse error messages.

Where each rule actually lives:

The budget alarm goes on before the first converse call. Not after I understand the dashboard — after I understand that I do not understand the dashboard. Bill the guardrail, bill the agent, and the alarm email is the whole safety system.

On top of that: log response["usage"] into a table on every call, so I can see the cost per question instead of guessing. And keep the stable prefix stable — system prompt and tool definitions go in front, unchanged, so models that support prompt caching can reuse them. Every time I "just tweaked one clause", the cache went cold and I paid full price for the same text. Put the instructions in a versioned file. Diff them like code.

I will retry a throttled call and run the tool twice. Not because I am careless — because the retry is two lines and the failure mode is invisible. The first invoice lookup succeeds, the response times out on the way back, and I resend the same turn. My lookup_invoice now has an invoice twice, or a notification sent twice, and my logs show two clean successes.

Prevention: every tool call carries an idempotency key I generate, and a turn retries at most twice with jittered backoff. That is written in the README before the first line of agent code, not discovered on a Sunday. I have rebuilt this whole contract in my head three times already — once when a Prisma version drifted under me, once for a rate limiter that leaked memory, once for a Map I shared across every endpoint because sharing was easier. The prevention is always the same: make the bad thing structurally impossible before the first commit, not carefully avoided after the third incident.

I have not built this yet. When I do, the README will link back to this post, and it will either prove these five rules were right or show which one I broke first. My bet is on the second one, the tool choice, because that is the one that looks like it does not need writing down.

If it turns out I was wrong, I will edit this post and say so. That part I am not worried about.