bedrock-agent-starter

A Bedrock resolve bem um problema: chamar um modelo. O que ela não resolve é o resto — e o resto é o que consome semanas quando você tenta colocar um agente em produção. Quem já tentou sabe a lista: registro de tools com schema JSON, memória entre turnos, log que dá para consultar no CloudWatch às 2h da manhã, um conjunto de casos para provar que a mudança no prompt não regrediu nada, IaC, tratamento de erro, fallback de modelo.

Eu escrevi este starter depois de montar essa mesma base mais de uma vez em projetos diferentes. Cada vez a estrutura era 80% igual e os 20% restantes eram a decisão de negócio de verdade. O template cristaliza os 80%.

A pergunta que ele responde não é "como chamo o Claude pela Bedrock?" — é "o que preciso ter em volta da chamada para confiar nela em produção?". Por isso o loop do agente usa a Converse API, que é estável entre Claude, Nova, Llama e Mistral e trata tool-use como cidadão de primeira classe. Trocar de modelo é mudar BEDROCK_MODEL_ID, não reescrever o parser de resposta.

Opinativo onde deve, substituível onde não deve: o registro de tools, a observabilidade e o harness de evals são opiniões fortes. A memória (in-memory local, DynamoDB em produção) e o backend do Terraform são pontos de troca deliberados.

O loop: cada turno monta a lista de mensagens a partir da memória, anexa os specs das tools registradas e chama Converse. Se a resposta contém um bloco toolUse, o registro despacha a função Python correspondente, devolve um toolResult e chama o modelo de novo — até vir uma resposta final sem tool-use. É o mesmo ciclo que você faria à mão, só que com um teto de iterações e tratamento de erro no lugar certo.

As tools: o decorator @tool lê as anotações de tipo da função e pede ao Pydantic o schema JSON que a Converse API espera. Isso elimina a classe de bug mais comum em agentes caseiros — schema declarado à mão que diverge da assinatura real. As três tools que vêm no repo existem para provar o caminho, não para serem usadas como estão: web_search é um stub e você troca por Tavily, Brave ou o AgentCore Gateway conforme o caso.

A memória: a interface é uma só; a implementação in-memory serve para o CLI e a DynamoDB serve para o Lambda, onde cada invocação é sem estado e o histórico precisa viver fora do processo, chaveado por session_id.

A observabilidade: cada turno vira uma linha JSON com session_id, turn, model_id, input_tokens, output_tokens, tool_calls e duration_ms. Em paralelo, métricas EMF (Turns, InputTokens, OutputTokens, Duration, ToolErrors) vão para o namespace BedrockAgent no CloudWatch sem chamada extra de API — o formato embutido faz o CloudWatch extrair a métrica do próprio log. É o que permite um alarme em ToolErrors > 0 no primeiro dia, e um gráfico de custo por sessão no segundo.

O custo de um agente não está na primeira versão que funciona — está em cada mudança de prompt, de modelo ou de tool feita depois, sem saber o que quebrou. Por isso o harness de evals é parte do template e não um apêndice.

tests/evals/golden.jsonl guarda prompts com a saída esperada: substrings que devem aparecer na resposta e tools que devem ter sido chamadas. pytest tests/evals/ replaya cada linha contra o agente real e falha se algum caso regrediu. Não é benchmark de qualidade absoluta; é detector de regressão, e detector de regressão é o que você precisa para trocar claude-3-5-sonnet por Nova com alguma confiança.

O CI roda ruff, mypy e pytest a cada push. O workflow de docs publica o MkDocs Material no GitHub Pages. A landing em frontend/ é HTML estático sem dependência — sobe na Vercel sem build.

O repositório também carrega automação de higiene DevSecOps (checks de dependência, Conventional Commits) que vem do meu portfólio como um todo; ela é útil, mas não é o que faz o agente funcionar — pode remover sem perder nada do núcleo.