MÓDULO 1.2

🔄 Estado, erros e recuperação

Modele dependências, stale state, idempotência, timeout, cancelamento e recuperação.

6

Tópicos

3h

Carga

Integrator

Nível

Resiliência

Tipo

0 de 60%
1

Modele a jornada como estados

O que é: Cada etapa declara o que já aconteceu, quais ações estão disponíveis e qual transição é válida.

Por que aprender: Sem um modelo de estado, o agente pode confirmar antes de iniciar ou repetir um efeito já concluído.

Estado atual estado de partida Tool permitida decisão observável Próxima ação resultado verificável

Antes de modelar

Escreva o pedido da pessoa, o estado atual e a evidência que provará conclusão.

Erro de partida

Começar pelo nome de uma função ou por um botão produz uma tool sem objetivo humano claro.

Preveja antes de abrir o código

Qual informação muda a decisão? Qual efeito precisa aparecer na interface? Responda antes de implementar.

rascunho -> iniciado -> aguardando_confirmacao -> confirmado
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

estado explícito

02

transição válida

03

pré-condição

04

efeito

2

Separe erros recuperáveis e definitivos

O que é: Erros recuperáveis indicam uma próxima ação; erros definitivos encerram a tentativa com motivo verificável.

Por que aprender: A classificação evita loops cegos e permite que o agente explique alternativas reais ao usuário.

PerguntaContrato forteContrato fraco
Quando usar?A descrição nomeia intenção e contexto.“Faz coisas” ou “gerencia”.
O que recebe?Somente dados necessários.Objeto genérico e ilimitado.
O que devolve?Estado e próxima ação verificáveis.Texto sem protocolo.
Como falha?Código, motivo e recuperação.Exceção opaca.

Faça

  • ✓ Use verbos específicos.
  • ✓ Delimite entradas.
  • ✓ Declare a evidência.

Evite

  • ✗ Misturar intenções.
  • ✗ Aceitar qualquer objeto.
  • ✗ Esconder efeitos.
return {
  ok: false,
  code: "INSCRICAO_NAO_INICIADA",
  recovery: { tool: "iniciar_inscricao" }
};
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

código estável

02

mensagem acionável

03

próxima ação

04

fim honesto

3

Proteja contra stale state

O que é: O estado usado para decidir pode mudar antes da execução, especialmente em vagas, preços e permissões.

Por que aprender: Revalidar no momento do efeito impede que uma tool use uma fotografia antiga como autorização atual.

1

Observe

Capture estado, entrada e contexto antes da ação.

2

Decida

Valide pré-condições e escolha a transição permitida.

3

Execute

Aplique a regra compartilhada e respeite cancelamento.

4

Prove

Atualize a interface e devolva resultado estruturado.

Ponto de controle

Se a etapa 2 reprovar, a tool não tenta “dar um jeito”: ela devolve uma recuperação explícita.

if (input.version !== inscricao.version) {
  throw new ConflictError("Estado mudou; consulte novamente.");
}
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

revalidação

02

versão de estado

03

conflito

04

nova leitura

4

Faça mutações idempotentes

O que é: Uma chave de idempotência permite repetir uma solicitação sem duplicar inscrição, cobrança ou envio.

Por que aprender: Agentes, redes e usuários podem repetir chamadas; a operação precisa distinguir retry de novo efeito.

CÓDIGO DE REFERÊNCIA

headers: { "Idempotency-Key": executionId }
Entrada

É pequena, descrita e validável.

Execução

Reutiliza a regra real da aplicação.

Saída

Permite verificar efeito e continuar.

Leia o código como contrato

Sublinhe onde a entrada é validada, onde o efeito acontece, onde o cancelamento chega e onde a UI é atualizada.

Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

idempotency key

02

retry seguro

03

resultado anterior

04

efeito único

5

Cancele e limite o tempo

O que é: AbortSignal e timeout encerram trabalho que perdeu relevância ou excedeu a janela operacional.

Por que aprender: Cancelar de verdade preserva recursos e evita que a interface mostre sucesso depois que a pessoa desistiu.

Falha provocada

Execute o cenário com estado ausente, entrada inválida ou capacidade indisponível.

Recuperação esperada

A resposta informa o que falhou, o que permanece seguro e qual ação pode continuar.

Matriz mínima de teste

✓ caminho feliz reproduzível

✓ entrada inválida acionável

✓ cancelamento encerra trabalho

✓ fallback preserva a jornada

✓ interface reflete o estado

✓ backend mantém autorização

const signal = AbortSignal.any([
  executionSignal,
  AbortSignal.timeout(8000)
]);
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

AbortSignal

02

timeout

03

cleanup visual

04

resultado cancelado

6

Teste a recuperação ponta a ponta

O que é: A integração deve provar caminho feliz, ordem inválida, retry, cancelamento e mudança concorrente.

Por que aprender: Uma matriz de falhas transforma resiliência em comportamento verificável, não em intenção de arquitetura.

Exercício de síntese

  1. 1. Explique o problema sem usar o nome da tecnologia.
  2. 2. Desenhe o estado anterior e posterior.
  3. 3. Implemente a menor prova funcional.
  4. 4. Provoque uma falha e registre a recuperação.
  5. 5. Entregue código, evidência e uma limitação conhecida.

Desafio do módulo

Implementar uma inscrição em etapas que bloqueia chamadas fora de ordem e devolve instruções de recuperação.

Critério de Integrator responsável

A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.

confirmar antes de iniciar -> recovery: iniciar_inscricao
retry com mesma chave -> mesmo resultado
timeout -> interface volta ao estado estável
Indo mais fundo: evidência que vale guardar

Registre a entrada, o estado anterior, a decisão tomada, o resultado e a alteração visível da página.

Inclua também uma falha provocada e o comportamento observado sem suporte WebMCP.

Conceitos-chave

01

cenários

02

evidência

03

reprodução

04

regressão

📦 Entrega do módulo

Implementar uma inscrição em etapas que bloqueia chamadas fora de ordem e devolve instruções de recuperação.

Critério de aceite

A entrega funciona com suporte WebMCP e mantém o caminho manual quando a API não existe.

Evidência

Inclua código, cenário testado, resultado observado e uma limitação conhecida.

← Voltar para a trilhaPróximo módulo: 1.3 →

Fontes técnicas