Registre a primeira tool imperativa
O que é: document.modelContext.registerTool() recebe name, título, descrição, schema, execução e anotações. O nome tem de usar apenas letras ASCII, números, sublinhado, hífen ou ponto e possuir de 1 a 128 caracteres.
Por que aprender: A forma imperativa atende jornadas que não cabem num formulário ou dependem de lógica e estado ricos.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
await document.modelContext.registerTool({
name: 'buscar_cursos',
title: 'Buscar cursos',
description: 'Busca cursos por tema e nível.',
inputSchema: { type: 'object', properties: {} },
annotations: {
readOnlyHint: true,
untrustedContentHint: false
},
execute: async (input, { signal }) => buscar(input, signal)
});Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
nome único
descrição não vazia
execute obrigatório
registro é Promise
Projete um inputSchema útil
O que é: inputSchema usa JSON Schema para declarar propriedades, tipos, enums, descrições e campos obrigatórios.
Por que aprender: O schema é parte do raciocínio de escolha e geração de argumentos; validação real ainda deve ocorrer no código.
✓ Faça
- ✓ Declare type object de forma observável.
- ✓ Preserve propriedades focadas no fluxo manual.
- ✓ Teste o resultado e o cancelamento.
✗ Evite
- ✗ Esconder efeitos atrás de descrições vagas.
- ✗ Confiar na tool como autorização.
- ✗ Remover o fallback da interface.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
inputSchema: {
type: 'object',
properties: {
tema: { type: 'string', minLength: 2, description: 'Tema desejado.' },
nivel: { type: 'string', enum: ['iniciante', 'intermediario', 'avancado'] }
},
required: ['tema'],
additionalProperties: false
}Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
type object
propriedades focadas
required coerente
valide no execute
Execute assíncrono e responda estruturado
O que é: O callback execute pode retornar uma Promise; o valor resolvido é entregue ao agente.
Por que aprender: Resultados pequenos, tipados por convenção e acompanhados de evidência facilitam verificação e encadeamento.
Defina o contrato
Nome, descrição, entrada, resultado e limites ficam explícitos antes da implementação.
Observe a execução
Registre entrada, estado visível, cancelamento e saída sem expor dados sensíveis.
Verifique a evidência
A tool só está pronta quando o efeito e o retorno podem ser reproduzidos.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
execute: async ({ tema, nivel }, { signal }) => {
const cursos = await api.buscarCursos({ tema, nivel, signal });
renderResultados(cursos);
return { ok: true, total: cursos.length, cursos };
}Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
Promise é aceita
resultado é serializável
UI é atualizada
erros são úteis
Controle ciclo de vida com AbortSignal
O que é: O signal de registerTool remove a ferramenta quando abortado; o signal recebido por execute cancela a chamada em andamento.
Por que aprender: Esse modelo evita ferramentas obsoletas e trabalho continuando depois que o agente perdeu interesse.
💡 Teste de realidade
Implemente este tópico com um caminho feliz, uma entrada inválida e um cancelamento. Registre o que a pessoa viu e o que o agente recebeu.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
const registro = new AbortController();
await document.modelContext.registerTool(tool, { signal: registro.signal });
// desmontagem do componente
registro.abort('Tela encerrada');Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
signal de registro remove
signal de execução cancela
fetch aceita signal
cleanup é determinístico
Descubra e execute tools na página
O que é: getTools lista ferramentas expostas ao documento e executeTool executa uma RegisteredTool com entrada estruturada.
Por que aprender: Essas operações viabilizam agentes in-page e testes controlados sem simular um agente externo.
✓ Faça
- ✓ Declare getTools é assíncrono de forma observável.
- ✓ Preserve origem pode filtrar no fluxo manual.
- ✓ Teste o resultado e o cancelamento.
✗ Evite
- ✗ Esconder efeitos atrás de descrições vagas.
- ✗ Confiar na tool como autorização.
- ✗ Remover o fallback da interface.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
const tools = await document.modelContext.getTools({
fromOrigins: [location.origin]
});
const buscar = tools.find((tool) => tool.name === 'buscar_cursos');
if (!buscar) throw new Error('Tool indisponível neste contexto');
const raw = await document.modelContext.executeTool(buscar, { tema: 'WebMCP' });
console.log(JSON.parse(raw));Leia as anotações
readOnlyHint sinaliza ausência de mutação; untrustedContentHint avisa que a resposta exige tratamento reforçado. São sinais para o agente, não substitutos de autorização, validação ou sanitização.
Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
getTools é assíncrono
origem pode filtrar
execute usa RegisteredTool
cancelamento opcional
Entregue um catálogo pequeno e coerente
O que é: Buscar, consultar e verificar disponibilidade formam uma sequência com responsabilidades distintas e sem tool genérica.
Por que aprender: Um catálogo enxuto melhora a escolha do agente e cria uma base clara para a fase Integrator.
💡 Teste de realidade
Implemente este tópico com um caminho feliz, uma entrada inválida e um cancelamento. Registre o que a pessoa viu e o que o agente recebeu.
Conceito aplicado
O contrato deve ser compreensível por quem usa, testável por quem desenvolve e limitado por quem opera. A ferramenta não substitui autorização, validação nem experiência visual.
buscar_cursos({ tema, nivel })
consultar_curso({ cursoId })
consultar_disponibilidade({ cursoId, turmaId })
// Não criar: gerenciar_curso({ qualquerCoisa })Dica prática
Copie o exemplo, rode primeiro com dados locais e só depois conecte o backend. Mantenha logs sem dados pessoais e provoque pelo menos uma falha.
Checklist operacional
Indo mais fundo: evidência mínima
Guarde a entrada usada, o estado anterior, o resultado devolvido e a alteração visível da página.
Anote também o comportamento sem suporte, durante cancelamento e diante de uma resposta não autorizada do backend.
Conceitos-chave
buscar lista
consultar detalha
disponibilidade verifica
sem sobreposição
📦 Entrega do módulo
Entregar buscar_cursos, consultar_curso e consultar_disponibilidade, todas modificando a interface e retornando dados estruturados.
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.