Defina sucesso observável
O que é: Cada tarefa declara estado inicial, resultado esperado, efeitos proibidos e tolerâncias.
Por que aprender: Sem oráculo, fluência da resposta vira substituto enganoso para conclusão real.
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.
expected: { enrollmentStatus: "draft" }
forbidden: { chargeCreated: true }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
initial state
expected effect
forbidden effect
oracle
Construa um dataset representativo
O que é: Casos cobrem frequência, risco, ambiguidade, falhas e variação linguística real.
Por que aprender: Uma média dominada por casos fáceis esconde regressões críticas.
| Pergunta | Contrato forte | Contrato 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.
dataset = stratify(cases, ["happy", "ambiguous", "failure", "adversarial"]);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
strata
risk weighting
paraphrase
edge case
Avalie cada etapa do pipeline
O que é: Descoberta, escolha, argumentos, política, execução e resposta recebem métricas próprias.
Por que aprender: A decomposição localiza a regressão e orienta a correção.
Observe
Capture estado, entrada e contexto antes da ação.
Decida
Valide pré-condições e escolha a transição permitida.
Execute
Aplique a regra compartilhada e respeite cancelamento.
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.
metrics = { discoveryRecall, correctTool, validArgs, policyCompliance, taskSuccess };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
retrieval recall
tool accuracy
schema validity
task success
Instrumente traces sem vazar dados
O que é: Spans correlacionam turnos e chamadas com atributos sanitizados, versões e duração.
Por que aprender: Observabilidade útil preserva diagnóstico sem armazenar prompts ou PII desnecessários.
CÓDIGO DE REFERÊNCIA
span.setAttributes({ toolName, catalogVersion, outcome, durationMs });
span.addEvent("policy.denied", { reasonCode });É pequena, descrita e validável.
Reutiliza a regra real da aplicação.
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
OpenTelemetry
span
redaction
sampling
Detecte regressões e drift
O que é: Baselines versionadas permitem comparar modelos, prompts, catálogos e navegadores ao longo do tempo.
Por que aprender: Mudanças aparentemente isoladas podem alterar seleção e taxa de sucesso.
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
gate.failIf(taskSuccess < baseline - 0.02 || unauthorizedEffects > 0);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
baseline
confidence interval
drift
canary
Transforme avaliação em release gate
O que é: Critérios mínimos por risco bloqueiam publicação, enquanto alertas não críticos geram acompanhamento.
Por que aprender: Evals passam de relatório decorativo a controle operacional.
Exercício de síntese
- 1. Explique o problema sem usar o nome da tecnologia.
- 2. Desenhe o estado anterior e posterior.
- 3. Implemente a menor prova funcional.
- 4. Provoque uma falha e registre a recuperação.
- 5. Entregue código, evidência e uma limitação conhecida.
Desafio do módulo
Montar um harness de eval com casos felizes, ambíguos e adversariais e publicar um painel de decisão de release.
Critério de Expert responsável
A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.
release.requires([security.zeroUnauthorized, p95Latency.lt(3000), criticalTasks.gte(0.98)]);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
quality gate
risk tier
waiver
evidence
📦 Entrega do módulo
Montar um harness de eval com casos felizes, ambíguos e adversariais e publicar um painel de decisão de release.
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.
Fontes técnicas
- Draft e repositório oficial WebMCP
- Especificação renderizada
- Snapshot oficial: 26/08/2026 · commit 41d12f0. A API declarativa permanece experimental; valide o draft antes de produção.