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 oETA, 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_approvalna Fila do atendente humano. - No banco, um trigger SQLite recusa qualquer
UPDATEemrefunds.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:
-
Recepção (
Claude Haiku): único agente que conversa com o cliente. Busca na política (search_policiescom BM25 + stemmer Snowball do português escrito do zero) e delega aos especialistas. -
Pedidos (
Claude Sonnet): somente leitura (list_my_orders,get_order_details,track_delivery,get_restaurant_info). -
Reembolsos (
Claude Sonnet):check_refund_eligibility,issue_refundeescalate_to_human.
Essa divisão não depende só do prompt. Quatro guardrails em código protegem o atendimento:
-
customer_idfixo noToolContext: nenhuma ferramenta aceitacustomer_idcomo argumento. Quando o cenário adversarialC023tenta pedir reembolso do pedidoO-10002de outro cliente,_own_ordernega 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 comrun_in_backgroundou troca de modelo. -
Guardrail de elegibilidade (
eligibility_check):Session.authorizenegaissue_refundsecheck_refund_eligibilitynã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:
- O estado final do SQLite bater por código com os reembolsos e tickets esperados; e
- O Juiz não encontrar nenhuma violação grave na conversa (com verificação em código de que o trecho citado em
evidenceexiste 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
- Replay Público Interativo (Vercel): comanda-blond.vercel.app
- Repositório, 29 ADRs e código: github.com/TheAndr3/comanda
- Benchmark e Rastros no Hugging Face: huggingface.co/datasets/TheAndr3/comanda-delivery-support-eval-ptbr
Top comments (0)