bedrock-agent-starter

Chamar um modelo no Bedrock é uma linha de SDK. Entregar um agente é outra coisa. Entre o converse() e um endpoint que alguém opera em produção existe uma lista de peças que todo time acaba montando do zero: registro de tools, memória entre turnos, log com session_id, métrica de tokens por turno, tratamento de erro de tool, IaC e alguma forma de saber se a mudança de prompt de ontem quebrou o comportamento de hoje.

O problema não é o esforço de escrever cada peça uma vez, é manter as peças coerentes entre si quando o modelo muda, quando entra uma tool nova ou quando alguém troca o backend de memória. Montei este starter para que essas decisões estejam tomadas e visíveis no código, num formato que dá para ler numa tarde.

A proposta é ser opinativo onde a opinião economiza tempo (Converse API, Pydantic para schema de tool, JSON estruturado no log) e substituível onde o contexto de cada empresa manda (backend de estado do Terraform, tags, naming, limites de IAM). Faça fork, configure AWS_REGION e o modelo, e você tem um agente respondendo no terminal antes de pensar em infraestrutura.

A escolha central foi a Converse API em vez de InvokeModel. Com InvokeModel, cada família de modelo tem seu próprio formato de payload, e trocar Claude por Nova vira refatoração. A Converse normaliza mensagens, toolConfig e blocos toolUse/toolResult, então BEDROCK_MODEL_ID passa a ser configuração, não código.

O turno segue o ciclo clássico: o agente envia o histórico e a lista de tools, o modelo responde com texto ou com um ou mais toolUse, o registro executa a função Python correspondente, o resultado volta como toolResult e o ciclo repete até o modelo devolver texto final. Na pergunta do exemplo, get_time e calculator entram no mesmo turno.

O histórico mora atrás de uma interface de memória. Local, fica num dicionário e some quando o processo termina. Na Lambda, vai para a tabela DynamoDB de sessões, chaveada por session_id, que é o que permite conversa de vários turnos sobre uma função sem estado.

O CLI e o handler Lambda chamam o mesmo núcleo em src/agent/. Isso importa mais do que parece: o comportamento que você valida no terminal é o que vai para produção, e as evals exercitam o mesmo código.

Cada turno emite uma linha JSON com session_id, turn, model_id, input_tokens, output_tokens, tool_calls e duration_ms. Com isso, uma busca no CloudWatch Logs Insights por session_id reconstrói a conversa inteira de um usuário que reclamou, sem guardar prompt em texto livre em outro lugar.

As métricas vão em formato EMF para o namespace BedrockAgent: Turns, InputTokens, OutputTokens, Duration e ToolErrors. EMF evita chamar PutMetricData no caminho da requisição; a métrica sai do próprio log. InputTokens é a que vira alarme de custo, porque histórico longo cresce o input a cada turno sem ninguém perceber. ToolErrors é a que avisa de falha silenciosa: o modelo costuma contornar uma tool quebrada e responder algo plausível, e sem essa métrica o erro só aparece na reclamação.

O harness de evals é deliberadamente simples: um golden.jsonl com prompt, substring esperada e tool esperada, executado pelo pytest. Não mede qualidade semântica. Mede regressão, que é o defeito mais comum quando alguém troca o modelo ou reescreve o system prompt numa sexta-feira.