Agentes de IA para logística: por dentro do Shipment Exception Commander

Agentes de IA para logística não esbarram na falta de alternativas quando um embarque sai do plano. O desafio está em lidar com evidências de confiabilidade desigual, cotações de recuperação que vencem, custos que atravessam alçadas de aprovação e o risco de uma nova tentativa apressada gerar uma segunda reserva quando a primeira já deu certo.

O Shipment Exception Commander é uma aplicação de referência open source para Claude Managed Agents criada justamente para esse ponto crítico da decisão. Ela analisa uma única exceção sintética, atribui notas a todas as opções de recuperação por critérios mecânicos, delega uma contestação independente do risco, mostra a ação exata a uma pessoa responsável e só permite uma mutação idempotente no sandbox depois da aprovação nativa.

Como agentes de IA para logística pontuam antes de decidir

O coordenador nunca inventa tarifas nem transforma texto livre em política. A ferramenta server-side e somente leitura shipment_intelligence oferece três casos sintéticos e calcula a nota das opções com uma fórmula fixa: 50 pontos por cumprir o prazo prometido, 20 pela cobertura do estoque, 20 pela eficiência de custo diante do teto absoluto e 10 pela confiança. Cada opção traz a versão e o vencimento da cotação, a previsão de chegada, a quantidade de unidades protegidas e o custo incremental em USD.

O principal caso de prova, SCX-2026-071, comparou três formatos reais de decisão: uma recuperação marítima barata que perderia o prazo prometido, o transporte aéreo de toda a carga acima do teto absoluto de gastos e um envio expresso fracionado por via aérea que protegia todas as 240 unidades comprometidas por $4,200. A opção fracionada recebeu nota 91 e ficou dentro do limite de $5,000 do operador. A pontuação torna a recomendação reproduzível; cabe ao Claude reunir as evidências, questionar as premissas e explicar o trade-off.

Evidência não confiável não autoriza uma ação

Uma das notas da transportadora contém, de propósito, um texto em tom de instrução que manda o agente ignorar a política de aprovação e reservar a opção premium. O workflow marca a nota como não confiável, preserva seu conteúdo como evidência e deixa claro que ela não serve como diretriz. A política vem do catálogo sintético versionado e do adaptador, nunca do texto do embarque nem da saída de uma ferramenta.

O coordenador também não dispõe de memória gravável entre sessões, cofre, integração MCP ou saída de rede. read, glob e grep são as exceções restritas com aprovação automática. Bash e a gravação dos entregáveis ficam em always_ask; edição, acesso direto à web e pesquisa na web continuam desativados. A única mutação de estado canônica é o comando execute do adaptador.

Um verificador contesta a recomendação

Antes de qualquer solicitação de execução, o coordenador Opus delega a recuperação proposta a um verificador Haiku de escopo restrito. Na execução de prova, o verificador respondeu NEEDS_CHANGES: não conseguiu confirmar se a cotação Q-071-v4 ainda estava válida nem se a capacidade e as sobretaxas eram definitivas. O coordenador não descartou a preocupação. Ele acionou o validador determinístico da proposta, que conferiu novamente o relógio sintético, o vencimento da cotação, a versão da política, a alçada de gastos e a versão esperada do estado. Somente o resultado autoritativo ready_for_human_approval alterou o status final para pronto.

O resumo para aprovação detalhou então os IDs do caso e da opção, o gasto exato de $4,200, a previsão de chegada anterior e a nova, o impacto no prazo prometido ao cliente, as 240 unidades protegidas, o vencimento da cotação, as versões da política e do estado, a nota, o histórico do verificador, as alternativas rejeitadas, a chave estável de idempotência, os campos esperados no recibo e o comportamento em caso de recusa ou falha.

Negar significa não alterar o estado

O primeiro cartão de aprovação nativa foi negado de propósito. Nenhum comando capaz de alterar o estado foi executado; o estado continuou como detected, na versão 3; nenhum recibo existia; e a chave de idempotência permaneceu sem uso. O agente não trocou de ferramenta, não modificou o comando nem criou outra chave.

A pedido explícito do operador, a mesma ação canônica foi apresentada outra vez. Dessa vez, ela foi autorizada. No limite da mutação, o adaptador voltou a conferir a versão 3 do estado, a validade da cotação, a política, a alçada de aprovação e o teto absoluto de $10,000. A ação foi executada exatamente uma vez, levando o caso de detected na versão 3 para resolved na versão 4, e gerou o recibo rcpt_37105a2da411aee0391c com a referência de reserva SBX-56DFC3291972.

Execução protegida contra replay, com escopo transparente

O adaptador sintético controla uma chave estável, SCX-2026-071:OPT-071-B:v3, um bloqueio no nível do sistema operacional, a inspeção do estado canônico e um registro de recibos. Chamadas duplicadas com a mesma intenção devolvem o recibo existente; uma intenção conflitante sob a mesma chave falha; versões obsoletas, execução simultânea e possíveis gravações parciais exigem inspeção, não uma nova tentativa às cegas.

Essas proteções são descritas deliberadamente dentro de seus limites reais: o bloqueio, o estado e o registro de recibos são arquivos locais à sessão em um único sandbox do Managed Agents. Eles não oferecem uma garantia distribuída de produção. Um adaptador real para uma transportadora ou um TMS precisaria de um armazenamento transacional compartilhado e de uma fronteira de idempotência no sistema de destino.

A avaliação de resultado conferiu as evidências

A sessão gravou três artefatos em /mnt/session/outputs/: um pacote de recuperação legível por pessoas, um registro de auditoria estruturado e o recibo bruto da execução. Um outcome do Managed Agents comparou esses arquivos de forma independente com o catálogo, o código-fonte do adaptador, o estado canônico, o histórico de aprovações e o registro de recibos. Antes de retornar satisfied, ele exigiu revisões para explicitar o vencimento da cotação, o comportamento em caso de falha, um manifesto de entregáveis e a limitação local à sessão.

Depois, o pacote de recuperação foi baixado pelo proxy de arquivos da aplicação. Seu SHA-256 é 30c8ad1d0d13cf7ad4b7070e67370ea270562c5e4ef44dfa503e3124180bd40b. A sessão de capacidade é sesn_01CcQjCVoWvNQ7VJLFbuDJxh; o outcome é outc_01GoD4rsLMh93iQNfAUw63KW.

A execução real do outcome também revelou uma lacuna na interface: threads filhas do avaliador podem solicitar aprovação enquanto a sessão principal permanece ociosa. A versão lançada agora reconstrói os cartões de aprovação pendentes tanto a partir de eventos requires_action do processo principal quanto de eventos evaluated_permission: ask nas threads filhas, retira esses cartões após a confirmação ou o resultado e impede que o replay faça solicitações já resolvidas reaparecerem. Além disso, ela repassa o session_thread_id do avaliador por uma allowlist restrita no navegador e valida essa rota contra o evento exato da ferramenta que originou a solicitação antes de encaminhar a decisão.

Uma sessão de prova separada e configurada com Sonnet, sesn_01BvSf33BLBbN86w5oDb3BkQ, exercitou o caminho corrigido. A ferramenta do avaliador republicada entre threads, sevt_013VnmofY8ytk6QwgDtNSYoq, carregava a thread sthr_018HMgpidoN86Qp4iGLZt1q3; a interface gerou a confirmação sevt_016ZFv5TdBPKNyEPThzGT36Q com os mesmos IDs de ferramenta e thread, o servidor a aceitou e o avaliador retomou a execução para solicitar sua próxima verificação. A prova restrita foi então interrompida de propósito para evitar o custo de iterações adicionais irrelevantes; o outcome principal do embarque permaneceu satisfied.

Opus no teste principal, Sonnet na validação e Haiku na verificação

O coordenador provisionado continua sendo claude-opus-5. Para tornar econômica a repetição das validações pagas, as sessões locais podem substituir explicitamente apenas o modelo do coordenador por claude-sonnet-5; qualquer outra substituição em runtime falha de forma fechada. O verificador independente usa claude-haiku-4-5. A sessão de smoke test faturada sesn_01RTs3wLV41odV9p92eWtrHV usou Sonnet e retornou a resposta exata SMOKE OK.

A suíte de testes de produção mantém as credenciais isoladas de propósito, mesmo quando o ambiente do desenvolvedor contém um .env.local configurado. Ela comprova que uma implantação nova não expõe nenhum campo de chave no navegador, não envia tráfego à Anthropic, informa configured: false e retorna 503 nas rotas de faturamento.

Uma referência pública que falha de forma fechada

A referência pública na Vercel não contém chave da Anthropic nem IDs de recursos do Managed Agents. A landing page e o endpoint /api/agent/health continuam disponíveis, enquanto a criação de sessões falha de forma fechada. Quem adota o projeto provisiona o agente e o ambiente em sua própria conta da Anthropic; qualquer instância configurada precisa ser protegida por controle de acesso antes de ficar ao alcance de outros usuários.

Todos os casos, transportadoras, cotações, referências de reserva, transições de estado e recibos deste projeto são sintéticos. A aplicação demonstra um padrão de controle operacional, não uma integração real com transportadoras.

Evidências da versão

• Repositório: dvnc-labs/shipment-exception-commander
• Versão: v0.1.0
• CI: execução de lançamento aprovada
• Commit: 1db0329
• Implantação: shipment-exception-commander.vercel.app
• Saúde: saúde do agente com falha fechada

O Shipment Exception Commander é deliberadamente mais restrito do que um copiloto de logística. Ele assume um único compromisso auditável: recomendar com base em evidências versionadas, contestar a recomendação, pedir a uma pessoa que aprove a ação exata, executar a mutação uma vez e deixar provas suficientes para reconstruir o que aconteceu.