DEV Community

André Vinicius
André Vinicius

Posted on Edited on

Como construir agentes de atendimento que não alucinam dinheiro: regras em código, guardrails MCP e avaliação τ-bench em português

Quando colocamos um LLM para atender clientes de um app de delivery, um chatbot comum resolve o caminho feliz, mas cria dois riscos inaceitáveis para a operação: conceder reembolso indevido sob pressão ou prompt injection, e prometer valores ou prazos fora da política.

Construí o Comanda — um sistema multi-agente de pós-venda de delivery sobre o Claude Agent SDK e o Model Context Protocol (MCP) — partindo de um princípio simples: o modelo conduz a conversa, mas o dinheiro e a segurança vivem em código determinístico.

Neste artigo, mostro as quatro decisões de engenharia que tornaram o sistema auditável e como uma suíte de avaliação estilo τ-bench (30 cenários, 8 adversariais) encontrou um bug sutil de fuso/relógio que nenhum teste manual havia pego.


1. A ferramenta de reembolso não aceita valor (ADR-0001)

Em muitos protótipos de agentes, a ferramenta tem a assinatura issue_refund(order_id, amount). Se o cliente convencer o modelo de que merece R$ 150,00 em vez da taxa de entrega de R$ 6,99, o modelo passa 150.00.

No Comanda, issue_refund recebe apenas (order_id, issue, item_ids). Não existe parâmetro de valor:

  • Quem calcula os centavos é uma função pura (evaluate_refund), que lê o pedido no SQLite, mede o atraso contra o ETA, confere a janela de 48 horas após a entrega e aplica a regra (R-ITEM, R-QUALITY, R-LATE-30, R-LATE-60, R-CANCELLED, R-LOST).
  • Se o valor passar de R$ 80,00 ou se o cliente tiver 3+ reembolsos nos últimos 30 dias, o reembolso nasce como pending_approval na Fila do atendente humano.
  • No banco, um trigger SQLite recusa qualquer UPDATE em refunds.amount_cents. Nem o agente nem o atendente humano podem alterar o valor calculado pela regra.

2. Topologia Supervisor–Especialistas com isolamento em código (ADR-0003, ADR-0018, ADR-0020)

Dar todas as ferramentas a um único agente mistura papéis e encarece cada turno. O Comanda divide o atendimento em três agentes:

  1. Recepção (Claude Haiku): único agente que conversa com o cliente. Busca na política (search_policies com BM25 + stemmer Snowball do português escrito do zero) e delega aos especialistas.
  2. Pedidos (Claude Sonnet): somente leitura (list_my_orders, get_order_details, track_delivery, get_restaurant_info).
  3. Reembolsos (Claude Sonnet): check_refund_eligibility, issue_refund e escalate_to_human.

Essa divisão não depende só do prompt. Quatro guardrails em código protegem o atendimento:

  • customer_id fixo no ToolContext: nenhuma ferramenta aceita customer_id como argumento. Quando o cenário adversarial C023 tenta pedir reembolso do pedido O-10002 de outro cliente, _own_order nega na hora.
  • Isolamento por servidor MCP e hook PreToolUse: cada agente tem seu servidor MCP em processo, e o hook bloqueia qualquer chamada fora do papel ou tentativa de delegar com run_in_background ou troca de modelo.
  • Guardrail de elegibilidade (eligibility_check): Session.authorize nega issue_refund se check_refund_eligibility não tiver sido chamado na mesma sessão para o mesmo (order_id, issue, frozenset(item_ids)).
  • Máscara determinística de PII (CustomersMask): nome, e-mail e telefone são mascarados na criação de cada evento do Rastro (JSONL e SSE) e novamente na exportação para o replay público.

3. Avaliação estilo τ-bench e o bug do relógio fixo (ADR-0027)

Para medir o sistema sem depender de "olhômetro", criei 30 cenários em YAML (8 adversariais) com um Cliente simulado e um Juiz LLM, rodando sobre um banco SQLite determinístico cujo relógio é fixado em 05/11/2026 19:30 BRT.

Um cenário só passa se:

  1. O estado final do SQLite bater por código com os reembolsos e tickets esperados; e
  2. O Juiz não encontrar nenhuma violação grave na conversa (com verificação em código de que o trecho citado em evidence existe literalmente na fala do agente).

Na primeira rodada completa (50 atendimentos), o sistema teve 0 violações graves e 0 leves, conteve 7 dos 8 cenários adversariais e custou US$ 0,026 por atendimento (estimativa equivalente em API). Mas 9 cenários reprovaram por falta de reembolso no estado final.

Ao abrir os arquivos JSONL do Rastro, descobri a causa principal: o banco vivia em 05/11/2026, mas o runtime do Claude Code injetava no bloco <env> do modelo a data real da máquina (15/11/2026). Quando a Recepção lia um pedido entregue em 05/11/2026, ela calculava mentalmente que haviam se passado 10 dias (fora da janela de 48h!) ou dizia ao cliente que o pedido "não era de hoje", enquanto a ferramenta em Python usava Repository.now() (05/11/2026).

A correção (ADR-0027) foi passar AgentHost.now() explicitamente no prompt de todos os agentes, instruindo-os a usar o relógio do atendimento e ignorar qualquer data do ambiente. Sem o Rastro estruturado e a avaliação automatizada, esse conflito entre o relógio do domínio e o <env> do SDK passaria despercebido.


Links do projeto

Top comments (0)