AWS HubAWS HubSão Paulo operando · 2 eventos no mundo

Agentes de códigoComunidade

Nível de dificuldade: Avançado (4 de 5)

Como testar agentes de código contra o DynamoDB sem expor credenciais da AWS

Por AWS Hub8 min de leitura

Uma sessão do grupo Quito Lambda mostrou como rodar o DynamoDB localmente com LocalStack para que um agente de IA reproduza bugs reais e teste correções, sem tocar numa conta AWS de verdade.

Nota da redação: três afirmações deste texto sobre comportamento de produtos de terceiros (a precondição do DynamoDB para mapas aninhados, a restrição do plano Hobby do LocalStack a uso não comercial e a variação de serviços disponíveis por plano no LocalStack) foram atribuídas à documentação oficial da AWS e à página de preços da LocalStack, mas essas fontes oficiais não puderam ser confirmadas diretamente; a única fonte disponível foi um post da DEV Community que as menciona de passagem. Trate essas afirmações como prováveis, não confirmadas, e verifique na documentação oficial antes de depender delas.

Em 28 de outubro, Gandhy García, desenvolvedor de software na Stack Builders, conduziu uma sessão do grupo de usuários Quito Lambda chamada "LocalStack: A safe environment for experimenting with AI agents and AWS". O relato, publicado na DEV Community, mostra um agente de código reproduzindo dois bugs reais numa API de jogo escrita em Python e FastAPI, rodando testes de integração contra uma emulação local do DynamoDB, sem jamais precisar de credenciais de uma conta AWS de verdade.

Este tutorial reconstrói essa abordagem passo a passo: como montar um ambiente onde o agente tem evidência real de comportamento do DynamoDB (não um mock que aceita qualquer coisa), e como limitar para onde os comandos do agente podem apontar.

O que você vai construir

Você vai montar um ambiente local onde um agente de código (Cursor, Claude Code, Copilot Workspace, ou o assistente que você usa) pode rodar testes de integração contra uma emulação do DynamoDB via LocalStack, usando o boto3 normal, sem nenhuma credencial de uma conta AWS real.

O exemplo segue a mesma superfície do demo original: uma tabela DynamoDB com um item por jogo, contendo jogadores, anfitrião, palavra secreta e um mapa de votes. Você vai reproduzir os dois bugs que apareceram na sessão: a remoção acidental do dicionário vazio votes (que quebra a escrita aninhada seguinte) e a ausência de uma regra que impedia um jogador de votar em si mesmo.

Pré-requisitos

  • Docker e Docker Compose instalados.
  • Python, com boto3, pytest e pydantic-settings no requirements.txt (ou requirements-dev.txt).
  • Nenhuma conta AWS é necessária para este tutorial. Você vai usar apenas credenciais fictícias (dummy credentials, como test/test), combinadas com o endpoint_url local, que fazem o boto3 rotear as chamadas para o LocalStack em vez da AWS real.
  • Se depois você quiser apontar o mesmo código para uma conta AWS real (não recomendado para o agente, só para deploy manual), restrinja o papel IAM da aplicação ao mínimo necessário para as operações da tabela, limitado por Resource à tabela específica.
  • Uma imagem do LocalStack fixada numa versão específica (nunca latest): o setup da sessão usava uma tag pinada, exatamente para que uma atualização do emulador não mude o comportamento do teste sem aviso.

Passo a passo

Nota da redação: o código desta seção não foi executado em ambiente real. Valide antes de usar em produção.

1. Suba o LocalStack com Docker Compose, isolado da sua configuração AWS normal.

yaml
# docker-compose.yml
services:
 localstack:
 image: localstack/localstack:3.8 # fixe numa versão, não use latest
 ports:
 - "4566:4566"
 environment:
 - SERVICES=dynamodb
 - DEBUG=0
 volumes:
 - "./.localstack:/var/lib/localstack"

2. Separe as credenciais de teste das credenciais reais num arquivo próprio.

# .env.test
AWS_ACCESS_KEY_ID=test
AWS_SECRET_ACCESS_KEY=test
AWS_DEFAULT_REGION=us-east-1
DYNAMODB_ENDPOINT_URL=http://localhost:4566

Esse é o ponto que o relato da DEV Community destaca como decisivo: dummy credentials sozinhas não roteiam nada para o LocalStack. É a combinação de endpoint_url apontando para localhost:4566 com as credenciais fictícias que faz o boto3 conversar com o emulador em vez de tentar (e falhar) uma chamada real.

3. Carregue essas configurações no harness de teste com Pydantic, para que o agente nunca precise lembrar disso manualmente.

python
# conftest.py
import uuid
import boto3
import pytest
from pydantic_settings import BaseSettings

class TestSettings(BaseSettings):
 aws_access_key_id: str
 aws_secret_access_key: str
 aws_default_region: str
 dynamodb_endpoint_url: str

 class Config:
 env_file = ".env.test"

settings = TestSettings()

@pytest.fixture(scope="session")
def dynamodb_table():
 client = boto3.client(
 "dynamodb",
 endpoint_url=settings.dynamodb_endpoint_url,
 region_name=settings.aws_default_region,
 aws_access_key_id=settings.aws_access_key_id,
 aws_secret_access_key=settings.aws_secret_access_key,
 )
 table_name = f"chameleon-games-{uuid.uuid4().hex[:8]}"
 client.create_table(
 TableName=table_name,
 KeySchema=[{"AttributeName": "game_id", "KeyType": "HASH"}],
 AttributeDefinitions=[{"AttributeName": "game_id", "AttributeType": "S"}],
 BillingMode="PAY_PER_REQUEST",
 )
 yield table_name
 client.delete_table(TableName=table_name)

O nome da tabela leva um sufixo aleatório porque é assim que o setup da sessão evitava colidir com a tabela de jogo semeada manualmente por Gandhy García para a demonstração ao vivo: a suíte de testes cria e apaga a sua própria tabela, sem tocar nos dados que você está inspecionando manualmente na mesma instância do LocalStack.

4. Escreva a função de repositório que o agente vai quebrar e consertar.

python
def cast_vote(table, game_id: str, voter: str, target: str):
 if voter == target:
 raise ValueError("Player cannot vote for themselves")
 table.update_item(
 Key={"game_id": game_id},
 UpdateExpression="SET votes.#voter = :target",
 ConditionExpression="attribute_not_exists(votes.#voter)",
 ExpressionAttributeNames={"#voter": voter},
 ExpressionAttributeValues={":target": target},
 )

Repare na cláusula UpdateExpression="SET votes.#voter = :target": ela escreve dentro de um mapa chamado votes. Se o item do jogo nunca tiver esse mapa (por exemplo, porque alguém removeu "votes": {} na criação, achando que era um refactor inofensivo), o update_item falha. A documentação da AWS confirma essa regra: um atributo de mapa aninhado não pode ser atualizado se o mapa pai não existir. Não é uma exigência genérica de inicializar tudo; é uma precondição específica do DynamoDB para esse tipo de escrita.

5. Restrinja o que o agente pode executar.

markdown
# AGENTS.md
- Rode `pytest -q` para validar qualquer mudança antes de reportar sucesso.
- Nunca execute `aws configure` nem leia credenciais fora de `.env.test`.
- Não faça chamadas para endpoints diferentes de `http://localhost:4566`.

Essa camada de instruções não substitui a configuração técnica: ela soma-se às permissões de comando do próprio agente e ao fato de que o endpoint_url do teste já aponta só para o LocalStack. Um emulador local, sozinho, não isola o agente do resto da máquina nem o impede de alcançar a AWS por outro caminho; é a combinação de instruções, permissões de comando e configuração de destino que fecha a fresta.

Testando

Com o bug do mapa ausente, o teste falha porque a precondição do DynamoDB não é satisfeita:

python
def test_cast_vote_fails_when_votes_map_is_missing(table_resource):
 table_resource.put_item(Item={"game_id": "g1", "players": ["bob", "carol"]})
 with pytest.raises(ClientError):
 cast_vote(table_resource, "g1", "bob", "carol")

No relato da sessão, essa era exatamente a situação: quatro testes falhando depois de um refactor que parecia uma limpeza razoável. O agente rodou a suíte, identificou o refactor como causa e restaurou a inicialização do dicionário vazio. Ao final, a conferência reportou 30 testes passando, além de uma checagem de formatação.

Para o segundo bug (voto em si mesmo), o teste cobre a regra de jogo que nunca tinha sido implementada:

python
def test_player_cannot_vote_for_self(table_resource):
 table_resource.put_item(Item={"game_id": "g1", "players": ["bob"], "votes": {}})
 with pytest.raises(ValueError):
 cast_vote(table_resource, "g1", "bob", "bob")

No demo, Bob votou em Bob e recebeu HTTP 204, confirmação de que a escrita tinha sido aceita. Depois do fix, a verificação pela API mostrou Carol tentando votar em Carol e recebendo erro, enquanto o voto de Carol em Alice continuava retornando 204 normalmente.

Os dois bugs são de naturezas diferentes, e essa diferença importa para quem revisa o trabalho do agente:

BugOnde a falha apareceO que corrigiu
Mapa votes removidoPrecondição do DynamoDB (attribute_not_exists)Reinicialização do campo na criação do jogo
Auto-voto permitidoRegra de produto nunca implementadaChecagem voter == target no repositório

Um emulador de serviço expõe o comportamento de armazenamento; não diz sozinho se a regra de negócio implementada está certa. Isso ainda é trabalho de quem revisa o teste que o agente escreveu, não só o código que ele mudou. Um teste passando é evidência mais fraca se o agente simplesmente removeu a asserção que expunha o bug em vez de corrigi-lo.

Limpando os recursos

Como tudo roda contra o LocalStack, não há cobrança de AWS em nenhuma etapa deste tutorial: nenhuma chamada sai da sua máquina. Ainda assim, vale encerrar de forma explícita:

bash
docker compose down -v
rm -rf .localstack

O down -v remove o container do LocalStack e o volume onde ele persiste estado entre execuções. A fixture dynamodb_table já apaga a tabela temporária (client.delete_table) ao final de cada sessão de pytest, mas a tabela semeada manualmente para inspeção (como a que Gandhy García usava para testar pela API durante a demonstração) continua lá até você apagá-la de propósito, e não é tocada pelo cleanup automático dos testes.

Um ponto de atenção que não é sobre AWS, mas sobre custo de ferramenta: o plano gratuito (Hobby) do LocalStack é restrito a uso não comercial, segundo a página de preços da própria LocalStack citada no relato original. Para um fluxo de trabalho comercial, isso pode significar assinar um plano pago mesmo sem gerar nenhuma cobrança de recursos AWS. Se a sua necessidade é só DynamoDB, vale avaliar o DynamoDB Local como outra opção a considerar.

Próximos passos

Uma pergunta da plateia na sessão levantou um cenário comum: parte do fluxo usando serviço local, parte batendo na AWS de verdade, por exemplo DynamoDB local e Amazon Bedrock real na mesma aplicação. Isso cria uma segunda fronteira, além da do agente: é preciso deixar explícito, na configuração, quais chamadas usam endpoint_url local e quais seguem para a AWS, porque os serviços disponíveis no LocalStack variam por plano.

Vale também lembrar que um teste local não substitui a validação no ambiente de destino. Ele não estabelece desempenho em produção; estabelece que o código lida corretamente com o comportamento do DynamoDB que foi exercitado. Para fechar o ciclo, rode a mesma suíte (ou um subconjunto dela) contra uma tabela real na AWS antes do deploy, mesmo que o grosso do trabalho de debugging com o agente tenha acontecido inteiramente local.

Se quiser aprofundar, o relato original na DEV Community linka a gravação completa da sessão do Quito Lambda, em espanhol, com os dois exercícios de debugging na íntegra.

Fonte: DEV Community — #aws

Serviços neste textoAgentes de códigoDeploy

Leve para a sua IA

Decida com o seu assistente, com o contexto deste texto já montado.

1. O que você quer saber

Ver o prompt
Li no AWS Hub: "Como testar agentes de código contra o DynamoDB sem expor credenciais da AWS" (https://awshub.com.br/comunidade/como-testar-agentes-de-codigo-contra-o-dynamodb-sem-expor-credenciais-da-aws).
Resumo: Uma sessão do grupo Quito Lambda mostrou como rodar o DynamoDB localmente com LocalStack para que um agente de IA reproduza bugs reais e teste correções, sem tocar numa conta AWS de verdade.
Serviços: Agentes de código, Deploy

Minha stack: [descreva em uma linha: serviços, linguagem, volume, região]

Isso muda alguma coisa na minha arquitetura? O que eu faria diferente a partir de amanhã?

Newsletter semanal

A semana da AWS, em português

Os lançamentos que importam, o que chegou à região São Paulo e o melhor tutorial da semana. Toda sexta, gratuita.