Defina o estado do turno
O que é: Cada turno reúne mensagem, snapshot da página, catálogo, execuções anteriores e orçamento restante.
Por que aprender: Um estado explícito evita prompts montados por concatenação acidental.
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.
const turn = { message, pageState, tools, calls: [], budget: { maxCalls: 4 } };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
turn state
page snapshot
history
budget
Implemente observar, decidir, agir
O que é: O loop alterna observação estruturada, decisão do modelo e execução controlada até atingir um terminal.
Por que aprender: Separar fases facilita teste e evita recursão sem limite.
| 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.
while (!turn.done && turn.calls.length < turn.budget.maxCalls) {
turn.next = await decide(observe(turn));
await act(turn.next, turn);
}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
observe
decide
act
terminal
Gerencie múltiplas chamadas
O que é: Uma tarefa pode exigir busca, detalhe e ação, com resultados alimentando decisões posteriores.
Por que aprender: O runtime precisa preservar dependências sem deixar o modelo inventar um ID intermediário.
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.
const courseId = calls.buscar_cursos.output.items[0].id;
await propose("consultar_curso", { courseId });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
dependency
result binding
sequence
parallel safety
Interrompa para o humano
O que é: Ambiguidade, alto risco ou mudança material de plano cria um ponto de confirmação.
Por que aprender: A pausa mantém agência humana sem quebrar a continuidade do turno.
CÓDIGO DE REFERÊNCIA
return pause({ reason: "MULTIPLE_MATCHES", choices, resumeToken });É 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
human in the loop
ambiguity
risk
resume token
Responda com evidência
O que é: A resposta distingue o que foi observado, o que foi executado e o que ainda depende do usuário.
Por que aprender: Transparência reduz falsas afirmações de sucesso e melhora confiança.
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
return answer({ found: 3, executed: [], pending: "escolha um curso", evidence: trace.links });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
grounding
executed effects
pending action
citation
Avalie a conversa completa
O que é: O teste mede conclusão, tool correta, passos, segurança, recuperação e qualidade da resposta.
Por que aprender: Avaliar apenas o texto final esconde chamadas desnecessárias ou perigosas.
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
Entregar um Page Agent que resolve uma busca em múltiplas etapas, pede confirmação e explica o resultado com evidências.
Critério de Agent Developer responsável
A entrega precisa funcionar, explicar seus limites e preservar o caminho humano quando a capacidade experimental não existir.
score = success * 40 + correctTools * 25 + safety * 25 + clarity * 10;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
task success
tool accuracy
step count
safety
📦 Entrega do módulo
Entregar um Page Agent que resolve uma busca em múltiplas etapas, pede confirmação e explica o resultado com evidências.
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.