Lab 87 — Agente com ferramenta: quem executa é o seu código

// Policy real anexada à role "cadencia-agente-execucao" — a mesma que gerou o
// reembolso triplicado. Uma única statement cobre as tres ferramentas, porque
// ninguem parou para separar o que cada uma precisa.
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AmploParaConseguirAgir",
      "Effect": "Allow",
      "Action": [
        "dynamodb:*",
        "rds-db:connect",
        "secretsmanager:GetSecretValue"
      ],
      "Resource": "*"
      // dynamodb:* sequer e usado hoje — foi deixado "por garantia". rds-db:connect
      // sem Resource especifico deixa a role logar como QUALQUER usuario do banco,
      // inclusive um usuario com permissao de escrita que a ferramenta de consulta
      // nunca deveria alcançar. secretsmanager:GetSecretValue com "*" deixa a
      // ferramenta de consulta ler o mesmo segredo do gateway de pagamento que só
      // a ferramenta de reembolso deveria tocar.
    }
  ]
}

{
  "evento": "TENTATIVA_DE_FERRAMENTA_REGISTRADA",
  "timestamp": "2026-08-08T09:14:02.118Z",
  "conversaId": "conv-77f1",
  "pedidoId": "4821",
  "ferramenta": "emitir-reembolso",
  "tentativaNumero": 1,
  "resultado": "executado",
  "chaveIdempotencia": "conv-77f1#4821#reembolso",
  "_comentario": "1a chamada real: o PutItem condicional teve sucesso, o gateway foi debitado."
}
{
  "evento": "TENTATIVA_DE_FERRAMENTA_REGISTRADA",
  "timestamp": "2026-08-08T09:16:41.902Z",
  "conversaId": "conv-77f1",
  "pedidoId": "4821",
  "ferramenta": "emitir-reembolso",
  "tentativaNumero": 2,
  "resultado": "bloqueado_por_idempotencia",
  "chaveIdempotencia": "conv-77f1#4821#reembolso",
  "_comentario": "cliente perguntou 'ja caiu?' de novo; PutItem condicional falhou porque a\nchave ja existia -- o gateway NUNCA foi chamado nesta tentativa."
}

# ferramentas.tf -- uma role e uma funcao por ferramenta. Nenhuma das tres
# roles concede dynamodb:* nem secretsmanager:* de forma ampla -- cada uma so
# alcança exatamente o que aquela ferramenta usa.

locals {
  ledger_arn = aws_dynamodb_table.execucoes.arn
}

# -- Ferramenta 1: consultar-status-pedido (so leitura) ----------------------
resource "aws_iam_role" "agente_consulta" {
  name               = "cadencia-agente-consulta-role"
  assume_role_policy = data.aws_iam_policy_document.confianca_lambda.json
  tags = { squad = "atendimento", lab = "L87", ferramenta = "consulta" }
}

resource "aws_iam_role_policy" "agente_consulta_policy" {
  role = aws_iam_role.agente_consulta.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["rds-db:connect"]
        # Resource inclui o NOME DO USUARIO DE BANCO -- a mesma role nao
        # consegue logar como cadencia_agente_reembolso nem cadencia_agente_cadastro,
        # mesmo que alguem tente forcar isso no codigo da Lambda.
        Resource = ["${data.aws_rds_cluster.erp.arn}/cadencia_agente_consulta"]
      },
      {
        Effect   = "Allow"
        Action   = ["dynamodb:PutItem", "dynamodb:GetItem"]
        Resource = [local.ledger_arn]
      },
    ]
  })
}

resource "aws_lambda_function" "consultar_status" {
  function_name = "cadencia-consultar-status-pedido"
  role          = aws_iam_role.agente_consulta.arn
  runtime       = "dotnet8"
  handler       = "ConsultarStatus::Handler::Executar"
  timeout       = 5
}

# -- Ferramenta 2: emitir-reembolso (irreversivel -- a mais restrita) --------
resource "aws_iam_role" "agente_reembolso" {
  name               = "cadencia-agente-reembolso-role"
  assume_role_policy = data.aws_iam_policy_document.confianca_lambda.json
  tags = { squad = "atendimento", lab = "L87", ferramenta = "reembolso" }
}

resource "aws_iam_role_policy" "agente_reembolso_policy" {
  role = aws_iam_role.agente_reembolso.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["rds-db:connect"]
        Resource = ["${data.aws_rds_cluster.erp.arn}/cadencia_agente_reembolso"]
      },
      {
        Effect   = "Allow"
        Action   = ["secretsmanager:GetSecretValue"]
        # Unica das tres roles com este Statement -- consulta e cadastro nao tem.
        Resource = [aws_secretsmanager_secret.gateway_pagamento.arn]
      },
      {
        Effect   = "Allow"
        Action   = ["dynamodb:PutItem", "dynamodb:GetItem", "dynamodb:UpdateItem"]
        Resource = [local.ledger_arn]
      },
    ]
  })
}

resource "aws_lambda_function" "emitir_reembolso" {
  function_name = "cadencia-emitir-reembolso"
  role          = aws_iam_role.agente_reembolso.arn
  runtime       = "dotnet8"
  handler       = "EmitirReembolso::Handler::Executar"
  timeout       = 8
}

# -- Ferramenta 3: atualizar-cadastro -----------------------------------------
resource "aws_iam_role" "agente_cadastro" {
  name               = "cadencia-agente-cadastro-role"
  assume_role_policy = data.aws_iam_policy_document.confianca_lambda.json
  tags = { squad = "atendimento", lab = "L87", ferramenta = "cadastro" }
}

resource "aws_iam_role_policy" "agente_cadastro_policy" {
  role = aws_iam_role.agente_cadastro.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = ["rds-db:connect"]
        Resource = ["${data.aws_rds_cluster.erp.arn}/cadencia_agente_cadastro"]
      },
      {
        Effect   = "Allow"
        Action   = ["dynamodb:PutItem", "dynamodb:GetItem"]
        Resource = [local.ledger_arn]
      },
    ]
  })
}

resource "aws_lambda_function" "atualizar_cadastro" {
  function_name = "cadencia-atualizar-cadastro"
  role          = aws_iam_role.agente_cadastro.arn
  runtime       = "dotnet8"
  handler       = "AtualizarCadastro::Handler::Executar"
  timeout       = 5
}

resource "aws_dynamodb_table" "execucoes" {
  name         = "cadencia-agente-execucoes"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "chaveIdempotencia"

  attribute {
    name = "chaveIdempotencia"
    type = "S"
  }
  # chaveIdempotencia = "{conversaId}#{pedidoId}#{ferramenta}" -- e o PutItem
  # condicional sobre esta chave (attribute_not_exists) que bloqueia repeticao.

  tags = { squad = "atendimento", lab = "L87" }
}

# grants-postgres.sh -- a segunda camada de menor privilegio, que o IAM
# sozinho nao cobre. rds-db:connect restringe QUEM loga como qual usuario;
# o GRANT do proprio Postgres restringe O QUE aquele usuario pode fazer
# depois de logado -- sem isso, um usuario com IAM auth restrito ainda
# poderia rodar qualquer SQL se tivesse sido criado com privilegio amplo.

psql -h $ERP_ENDPOINT -U admin -d cadencia <<'SQL'
-- Usuario da ferramenta de consulta: SELECT, nada mais.
CREATE USER cadencia_agente_consulta WITH LOGIN;
GRANT rds_iam TO cadencia_agente_consulta;
GRANT SELECT ON pedidos, clientes TO cadencia_agente_consulta;

-- Usuario da ferramenta de reembolso: so a coluna de status de reembolso.
CREATE USER cadencia_agente_reembolso WITH LOGIN;
GRANT rds_iam TO cadencia_agente_reembolso;
GRANT SELECT (id, valor_pedido) ON pedidos TO cadencia_agente_reembolso;
GRANT UPDATE (status_reembolso, valor_reembolsado) ON pedidos TO cadencia_agente_reembolso;

-- Usuario da ferramenta de cadastro: so colunas de endereco e contato.
CREATE USER cadencia_agente_cadastro WITH LOGIN;
GRANT rds_iam TO cadencia_agente_cadastro;
GRANT UPDATE (endereco, telefone, email) ON clientes TO cadencia_agente_cadastro;
SQL
# Confira depois: nenhum dos tres usuarios tem GRANT em nenhuma tabela alem
# das listadas acima -- \dp pedidos e \dp clientes no psql mostram exatamente
# isso, e e o que a auditoria vai conferir.

// OrquestradorDoLaco.cs -- o teto de voltas vive AQUI, no codigo que decide
// se uma ferramenta pode ser chamada, nunca numa frase do prompt do sistema.
// E chamado pelo AgentCore a cada passo do laço, antes de invocar a Lambda
// da ferramenta escolhida pelo modelo.

public class OrquestradorDoLaco
{
    private const int TetoDeVoltasPorFerramenta = 4;
    private readonly AmazonDynamoDBClient _dynamo = new();
    private const string TabelaLedger = "cadencia-agente-execucoes";

    public async Task<DecisaoDeChamada> AvaliarProximaChamadaAsync(
        string conversaId, string ferramenta, string pedidoId)
    {
        // Conta quantas tentativas ja existem para esta combinacao especifica --
        // nao para a conversa inteira, para nao punir um cliente que faz tres
        // perguntas legitimas sobre tres pedidos diferentes.
        var tentativas = await ContarTentativasAsync(conversaId, ferramenta, pedidoId);

        if (tentativas >= TetoDeVoltasPorFerramenta)
        {
            // A interrupcao acontece ANTES de invocar a Lambda -- a 5a tentativa
            // nunca chega perto da credencial da ferramenta.
            await RegistrarInterrupcaoPorTetoAsync(conversaId, ferramenta, pedidoId);
            return DecisaoDeChamada.Bloquear(
                motivo: "teto_de_voltas",
                mensagemAoAtendente: "Não consigo confirmar isso automaticamente depois de " +
                    "várias tentativas — vou encaminhar para um atendente humano revisar " +
                    $"o pedido {pedidoId}.");
        }

        return DecisaoDeChamada.Permitir(tentativas + 1);
    }

    private async Task<int> ContarTentativasAsync(string conversaId, string ferramenta, string pedidoId)
    {
        var prefixo = $"{conversaId}#{pedidoId}#{ferramenta}";
        var resposta = await _dynamo.QueryAsync(new QueryRequest
        {
            TableName = TabelaLedger,
            KeyConditionExpression = "begins_with(chaveIdempotencia, :prefixo)",
            ExpressionAttributeValues = new Dictionary<string, AttributeValue>
            {
                [":prefixo"] = new AttributeValue { S = prefixo },
            },
        });
        return resposta.Count;
    }

    private Task RegistrarInterrupcaoPorTetoAsync(string conversaId, string ferramenta, string pedidoId)
    {
        // Publica a metrica que alimenta o alarme do CloudWatch -- e o sinal de
        // que o LACO estava se comportando mal, nao so de que uma acao foi negada.
        return _cloudwatch.PutMetricDataAsync(new PutMetricDataRequest
        {
            Namespace = "Cadencia/AgenteAtendimento",
            MetricData = { new MetricDatum {
                MetricName = "InterrupcoesPorTeto",
                Value = 1,
                Dimensions = { new Dimension { Name = "Ferramenta", Value = ferramenta } },
            }},
        });
    }
}

// EmitirReembolso.cs -- a Lambda so executa depois que o orquestrador ja
// autorizou a chamada; e ela quem grava a chave de idempotencia ANTES de
// tocar o gateway, porque e a UNICA garantia de que a acao real nao repete.

public class EmitirReembolsoHandler
{
    private readonly AmazonDynamoDBClient _dynamo = new();
    private readonly SecretsManagerClient _segredos = new();
    private const string TabelaLedger = "cadencia-agente-execucoes";

    public async Task<ResultadoFerramenta> ExecutarAsync(PedidoDeReembolso pedido)
    {
        var chave = $"{pedido.ConversaId}#{pedido.PedidoId}#reembolso";

        // PutItem condicional: so grava se a chave NAO existir ainda. Se falhar,
        // outra chamada (desta ou de uma tentativa anterior) ja processou este
        // reembolso -- o gateway nunca e chamado nesta execucao.
        try
        {
            await _dynamo.PutItemAsync(new PutItemRequest
            {
                TableName = TabelaLedger,
                Item = new Dictionary<string, AttributeValue>
                {
                    ["chaveIdempotencia"] = new AttributeValue { S = chave },
                    ["status"] = new AttributeValue { S = "tentando" },
                    ["timestamp"] = new AttributeValue { S = DateTime.UtcNow.ToString("o") },
                },
                ConditionExpression = "attribute_not_exists(chaveIdempotencia)",
            });
        }
        catch (ConditionalCheckFailedException)
        {
            return ResultadoFerramenta.JaProcessado(
                $"O reembolso do pedido {pedido.PedidoId} já foi processado nesta conversa.");
        }

        // So a partir daqui o segredo do gateway e lido -- e so a role desta
        // Lambda tem permissao de IAM para faze-lo.
        var credencial = await _segredos.GetSecretValueAsync(
            new GetSecretValueRequest { SecretId = "cadencia/gateway-pagamento" });

        var resultadoGateway = await ChamarGatewayAsync(pedido.PedidoId, pedido.Valor, credencial);

        await AtualizarLedgerAsync(chave, resultadoGateway);
        return ResultadoFerramenta.Executado(resultadoGateway);
    }
}

# prova.sh -- reproduz de proposito um raciocinio malformado que insiste na
# mesma ferramenta, contra os DOIS desenhos, e conta quantas execucoes REAIS
# aconteceram em cada um. Nenhuma conclusao aqui vem de "parece que bloqueou".

CENARIO=cenario-reformulacao-ambigua.jsonl  # 20 execucoes do mesmo pedido de
                                              # reembolso, cada uma com o cliente
                                              # reformulando a pergunta 2 a 3 vezes

# -- Rodada 1: arquitetura minima (Figura 1), sem teto e sem idempotencia -----
python3 provocar_laco.py --arquitetura minima --cenario "$CENARIO" \
  --saida resultado-minima.json
# Resultado medido: media de 6,4 chamadas de emitir-reembolso por conversa;
# pior caso, 19 chamadas consecutivas antes do timeout interno do proprio
# Bedrock cortar a execucao -- nao um limite da aplicacao.
# Execucoes REAIS no gateway (nao simulado): 6,4 em media -- toda chamada
# aceita vira debito, porque nao ha idempotencia.

# -- Rodada 2: arquitetura de producao (Figura 2), teto=4 + idempotencia -----
python3 provocar_laco.py --arquitetura producao --cenario "$CENARIO" \
  --saida resultado-producao.json
# Resultado medido: 20 de 20 conversas interrompidas EXATAMENTE na 4a tentativa
# de emitir-reembolso quando o raciocinio insiste; 0 execucoes reais duplicadas
# no gateway -- so a 1a tentativa de cada conversa debita.

jq '.[] | select(.tentativaNumero > 1) | .resultado' resultado-producao.json | sort | uniq -c
#   19 "bloqueado_por_idempotencia"
#    1 "bloqueado_por_teto"
# Nas 20 conversas, 19 tiveram 2a tentativa bloqueada pela chave de
# idempotencia; em 1 conversa o raciocinio insistiu ate a 5a tentativa, e o
# teto (nao a idempotencia) foi quem interrompeu.

# limpeza.sh -- ordem importa: as tres Lambdas referenciam as tres roles e o
# ledger; remover a tabela do DynamoDB antes de remover as funcoes deixa
# invocacao de teste falhando sem necessidade.

# 1) Remover as tres funcoes e suas roles (Terraform cuida disso na ordem certa)
terraform destroy -target=aws_lambda_function.consultar_status \
  -target=aws_lambda_function.emitir_reembolso \
  -target=aws_lambda_function.atualizar_cadastro -auto-approve

# 2) Revogar os tres usuarios de banco -- terraform destroy NAO conhece usuario
#    de Postgres criado via psql fora do provider; isso fica de fora do state.
psql -h $ERP_ENDPOINT -U admin -d cadencia <<'SQL'
DROP USER IF EXISTS cadencia_agente_consulta;
DROP USER IF EXISTS cadencia_agente_reembolso;
DROP USER IF EXISTS cadencia_agente_cadastro;
SQL

# 3) terraform destroy cuida do resto: roles de IAM, tabela do ledger, segredo
#    do gateway, grupo de logs de cada Lambda
terraform destroy -auto-approve

# 4) Conferir que nao sobrou item nenhum no ledger cobrando leitura/escrita
aws dynamodb scan --table-name cadencia-agente-execucoes \
  --query 'Count' --output text
# Esperado: tabela ja removida -- o comando acima deve falhar com
# ResourceNotFoundException, nao retornar 0.