Padrões de produção

Os recursos mais fortes do framework são mais fáceis de lembrar como padrões de falha. Cada linha abaixo representa uma classe real de incidente em produção e um mecanismo concreto, não um slogan.

Falha parcial em uma operação de várias etapas

Failure: a primeira etapa funciona, a segunda falha e o agente não consegue saber qual efeito colateral já ocorreu.

Mechanism: componha o workflow em uma ação com um caminho explícito de compensação. Retorne f.error() com ações de recuperação disponíveis; não peça a um agente para adivinhar se é seguro tentar novamente. Uma transação ou chave de idempotência pertence ao seu handler e ao banco de dados.

Alucinação de parâmetros

Failure: o modelo inventa tenantId, emailAddress ou outro campo plausível.

Mechanism: todo esquema de ação é estrito. Chaves desconhecidas são rejeitadas antes do middleware e do handler, com <validation_error> explicando o que foi enviado e o que era esperado. A identidade do tenant deve vir de ctx, nunca da entrada da ferramenta.

Estouro de carga

Failure: muitos agentes tentam novamente o mesmo upstream lento até o conector esgotar seus próprios recursos.

Mechanism: .concurrency({ maxActive, maxQueue }) limita o trabalho ativo e enfileirado. A capacidade cheia retorna SERVER_BUSY com orientação de retry. Combine com timeouts do upstream e um limitador de taxa por tenant ou token.

Estouro da janela de contexto

Failure: uma resposta de coleção é grande demais, o modelo perde a linha importante e toma uma decisão ruim.

Mechanism: Presenter .agentLimit() trunca antes da serialização e acrescenta um resumo informando quantas linhas foram ocultadas e que filtros devem ser usados. .enableSelect() permite que o modelo solicite apenas campos de primeiro nível. A proteção de bytes de saída captura uma resposta de texto final grande demais.

Dados obsoletos após uma mutação

Failure: depois de uma escrita bem-sucedida, o agente vê uma leitura antiga em seu próprio contexto.

Mechanism: marque leituras com .cached() ou .stale() e escritas com .invalidates('domain.pattern'). A camada de sincronização de estado decora descrições, emite um marcador de invalidação no primeiro bloco e publica atualizações de recursos somente depois de uma mutação bem-sucedida.

Loops de retry cegos

Failure: um modelo repete a mesma chamada inválida porque o erro apenas diz "falhou".

Mechanism: toolError(code, { suggestion, availableActions, retryAfter }) emite um contrato estruturado de recuperação em XML. A próxima ação é nomeada, o atraso é explícito e o cliente tipado pode analisá-lo em MCPFusionClientError.

Vazamento de dados para o modelo

Failure: um handler retorna uma linha do banco contendo um campo que o modelo nunca deveria ver.

Mechanism: anexe um Presenter com esquema de allowlist e .redactPII(). Campos não declarados nunca entram na saída validada; a redação mascara caminhos sensíveis declarados na cópia clonada enviada pela rede. Teste result.data com @mcpfusion/testing.

Corridas em operações destrutivas

Failure: dois agentes emitem um reembolso, fazem a transição de um workflow ou atualizam o mesmo registro ao mesmo tempo.

Mechanism: f.mutation() marca a ação como destrutiva por padrão e o builder cria um serializador FIFO de mutações por ação. Adicione idempotência também na camada de domínio: a serialização ordena chamadas, mas não torna uma API de pagamentos externa idempotente.

Checklist operacional

Antes de Deploy:

• entradas estritas e identidade do tenant vindas do contexto
• Presenter em toda ferramenta que retorna dados de domínio
• limites em toda coleção
• concorrência e limites de taxa nas chamadas upstream
• invalidação nas escritas
• campos de recuperação nos erros esperados
• lockfile e testes no CI
• telemetria e um sink de auditoria que nunca armazene segredos brutos

Próximos passos

• Testing: transforme cada linha em um teste de regressão
• Contracts: bloqueie divergências no CI
• Security pipeline: veja a ordem de execução