bedrock-agent-starter

Bedrock solves one problem well: calling a model. What it doesn't solve is everything else — and everything else is what eats weeks when you try to put an agent in production. Anyone who has tried knows the list: a tool registry with JSON schemas, memory across turns, logs you can actually query in CloudWatch at 2 AM, a set of cases proving your prompt change didn't regress anything, IaC, error handling, model fallbacks.

I wrote this starter after building that same foundation more than once across different projects. Each time the structure was 80% identical and the remaining 20% was the actual business decision. The template crystallises the 80%.

The question it answers isn't "how do I call Claude through Bedrock?" — it's "what do I need around that call to trust it in production?". That's why the agent loop uses the Converse API, which is stable across Claude, Nova, Llama and Mistral and treats tool-use as a first-class citizen. Switching models means changing BEDROCK_MODEL_ID, not rewriting the response parser.

Opinionated where it should be, replaceable where it shouldn't: the tool registry, observability and eval harness are strong opinions. Memory (in-memory locally, DynamoDB in production) and the Terraform backend are deliberate swap points.

The loop: each turn builds the message list from memory, attaches the specs of the registered tools and calls Converse. If the response contains a toolUse block, the registry dispatches the matching Python function, returns a toolResult and calls the model again — until a final answer arrives with no tool-use. It's the same cycle you'd write by hand, but with an iteration cap and error handling in the right place.

The tools: the @tool decorator reads the function's type annotations and asks Pydantic for the JSON schema the Converse API expects. That removes the most common bug class in home-grown agents — a hand-declared schema drifting from the real signature. The three tools that ship in the repo exist to prove the path, not to be used as-is: web_search is a stub and you swap it for Tavily, Brave or the AgentCore Gateway depending on the case.

Memory: one interface; the in-memory implementation serves the CLI and DynamoDB serves Lambda, where every invocation is stateless and history has to live outside the process, keyed by session_id.

Observability: every turn becomes a JSON line with session_id, turn, model_id, input_tokens, output_tokens, tool_calls and duration_ms. In parallel, EMF metrics (Turns, InputTokens, OutputTokens, Duration, ToolErrors) land in the BedrockAgent CloudWatch namespace with no extra API call — the embedded format has CloudWatch extract the metric from the log itself. That's what lets you put an alarm on ToolErrors > 0 on day one, and a cost-per-session graph on day two.

The cost of an agent isn't in the first version that works — it's in every prompt, model or tool change made afterwards without knowing what broke. That's why the eval harness is part of the template and not an appendix.

tests/evals/golden.jsonl holds prompts with expected output: substrings that must appear in the answer and tools that must have been called. pytest tests/evals/ replays each line against the real agent and fails if any case regressed. It's not an absolute quality benchmark; it's a regression detector, and a regression detector is what you need to swap claude-3-5-sonnet for Nova with any confidence.

CI runs ruff, mypy and pytest on every push. The docs workflow publishes MkDocs Material to GitHub Pages. The landing in frontend/ is dependency-free static HTML — it deploys to Vercel with no build step.

The repository also carries DevSecOps hygiene automation (dependency checks, Conventional Commits) inherited from my portfolio as a whole; it's useful, but it isn't what makes the agent work — you can strip it without losing anything from the core.