bedrock-agent-starter

Amazon Bedrock makes it straightforward to call a foundation model. It does not make it straightforward to ship a real agent. The moment you move past a single-turn prompt you need to decide how to register tools, how to pass tool results back into the conversation, where to persist session state, how to emit metrics without littering your business logic with CloudWatch boilerplate, and how to know whether a model swap broke something.

Every team I have seen start from scratch spends the first two weeks solving exactly those plumbing problems. This starter solves them once, in a way that is easy to replace piece by piece. The agent loop is built on the Bedrock Converse API, which is stable across Claude, Nova, Llama, and Mistral — so swapping models is a one-line environment variable change, not a refactor.

The project is also a portfolio artifact. It is bilingual (English and Portuguese), documented with MkDocs Material on GitHub Pages, and has a static landing page on Vercel. Every commit follows Conventional Commits, every PR runs ruff, mypy, and pytest. The intent is to demonstrate not just that I can wire up a Bedrock agent, but that I can do it in a way a team can actually maintain.

The tool registry is the part of this starter I am most deliberate about. A common failure mode in agent projects is that tool definitions drift from their implementations — the schema says one thing, the function does another, and the model hallucinates parameters that do not exist.

Here, the schema is derived from the function signature at import time via Pydantic. You write one decorator and one function; the registry picks it up automatically on the next invocation:

from agent.tools import tool

@tool(description="Translate text between languages using a deterministic table.")
def translate(text: str, source_lang: str, target_lang: str) -> str:
    ...
    return translated

Pydantic infers text, source_lang, and target_lang as required string properties in the JSON schema that gets sent to Bedrock. If you add a parameter with a default value, it becomes optional in the schema. If you annotate with Literal["en", "pt", "es"], the schema gains an enum constraint — and the model will respect it.

This approach keeps the schema and the implementation co-located and in sync. It also means you can test a tool in pure Python without any Bedrock dependency, which is exactly what the unit tests do. The full walkthrough is in the docs.

Two things I have seen skipped most often in agent projects are structured observability and regression testing. Both are included here and both are lightweight enough that there is no excuse to remove them.

Observability: Every turn emits a JSON log line with session_id, turn, model_id, token counts, tool calls made, and wall-clock duration. These go to CloudWatch Logs. In parallel, CloudWatch EMF metrics are published under the BedrockAgent namespace — Turns, InputTokens, OutputTokens, Duration, and ToolErrors. EMF means you get metrics without a separate put_metric_data call; they are extracted from the log line by CloudWatch automatically. This is enough to build a dashboard and set alarms on token spend or error rate from day one.

Evals: The eval harness in tests/evals/ is intentionally simple. A golden.jsonl file contains prompt/expected-output pairs. The pytest runner sends each prompt through the real agent loop (or a mock, depending on your CI setup) and asserts that expected substrings appear in the response and that the expected tools were called. This is not a substitute for human evaluation, but it catches the class of regression where a prompt that worked with Claude 3.5 Sonnet stops working after you switch to Nova Pro or change a system prompt. Run pytest tests/evals/ before any model or prompt change.