WebMCP Agent Developer

Descoberta começa com intenção, restrições e estado atual, não com a enumeração cega de todas as tools.

Um objetivo normalizado reduz ruído antes mesmo de apresentar capacidades ao modelo.

intenção · restrições · contexto · critério de sucesso

Nome, descrição, inputSchema e annotations formam a interface que o agente consegue raciocinar.

Tratar o descritor como dado permite validar, indexar, comparar e registrar decisões.

name · description · inputSchema · annotations

Regras determinísticas eliminam tools incompatíveis com rota, autenticação, risco ou entidade.

O filtro diminui tokens e impede escolhas que já sabemos serem inválidas.

rota atual · sessão · risco · pré-condição

O agente precisa de descrições curtas, schemas íntegros e exemplos coerentes, sem despejar implementação interna.

Uma representação estável melhora escolha e permite comparar modelos ou prompts.

serialização · limite de contexto · exemplo · redação

Navegação, login e seleção podem alterar as tools disponíveis durante a mesma conversa.

O agente deve invalidar snapshots e redescobrir capacidades quando o documento sinaliza mudança.

toolchange · snapshot · invalidação · redescoberta

Cobertura, precisão e tool correta no top-k revelam se o pipeline recupera boas candidatas.

Sem evals de descoberta, uma resposta final ruim pode ser atribuída ao componente errado.

recall · precision · top-k · dataset

A chamada produzida pelo modelo é uma proposta não confiável até passar por validação e política.

A fronteira impede que texto probabilístico se transforme diretamente em efeito.

tool call · untrusted input · policy gate · execução

Mesmo quando o provedor aplica schemas, o runtime valida tipos, limites, enums e campos extras.

Defesa em profundidade contém divergências de provider e chamadas produzidas por código externo.

JSON Schema · coerção proibida · limites · erro estável

Risco, autenticação, escopo e necessidade de confirmação são decididos fora do modelo.

O LLM pode recomendar; a aplicação continua responsável por autorizar.

autorização · risco · confirmação · escopo

Toda execução recebe AbortSignal, deadline e limites compatíveis com a experiência.

Uma conversa abandonada não deve manter rede, UI ou backend trabalhando indefinidamente.

AbortSignal · deadline · resource budget · cleanup

O runtime converte retornos heterogêneos em envelopes com status, dados, evidência e próxima ação.

Uma forma comum simplifica o loop sem esconder o erro original.

envelope · erro recuperável · evidência · next action

Cada execução liga turno, catálogo, proposta, decisão de política, duração e resultado sanitizado.

O rastro permite depurar seleção, execução e efeito sem gravar segredos.

traceId · catalog version · latência · redaction

Página, agente, usuário e backend possuem identidades e autoridades diferentes.

Confundir essas identidades cria delegação excessiva e bugs de autorização.

principal · delegação · sessão · recurso

Origem combina esquema, host e porta e define uma fronteira central da Web.

Uma tool registrada por um documento não concede acesso livre a outras origens.

same-origin · scheme · host · port

Frames incorporados possuem documento, origem e ciclo de vida próprios.

O agente precisa saber qual contexto oferece a tool e onde o efeito será visível.

top frame · iframe · sandbox · context id

CORS controla leitura por scripts no navegador; o backend ainda valida identidade e permissão.

Uma resposta liberada por CORS pode continuar proibida para aquele usuário e operação.

CORS · credentials · backend auth · CSRF

Ações sensíveis exigem uma confirmação clara que mostre alvo, efeito e reversibilidade.

Consentimento genérico ou antecipado não cobre uma mutação específica.

just in time · efeito · alvo · reversibilidade

A suíte cobre tool spoofing, navegação durante execução, frame removido e resposta de origem inesperada.

Fronteiras só existem de verdade quando os caminhos adversariais são exercitados.

spoofing · navigation race · frame removal · origin check

Cada turno reúne mensagem, snapshot da página, catálogo, execuções anteriores e orçamento restante.

Um estado explícito evita prompts montados por concatenação acidental.

turn state · page snapshot · history · budget

O loop alterna observação estruturada, decisão do modelo e execução controlada até atingir um terminal.

Separar fases facilita teste e evita recursão sem limite.

observe · decide · act · terminal

Uma tarefa pode exigir busca, detalhe e ação, com resultados alimentando decisões posteriores.

O runtime precisa preservar dependências sem deixar o modelo inventar um ID intermediário.

dependency · result binding · sequence · parallel safety

Ambiguidade, alto risco ou mudança material de plano cria um ponto de confirmação.

A pausa mantém agência humana sem quebrar a continuidade do turno.

human in the loop · ambiguity · risk · resume token

A resposta distingue o que foi observado, o que foi executado e o que ainda depende do usuário.

Transparência reduz falsas afirmações de sucesso e melhora confiança.

grounding · executed effects · pending action · citation

O teste mede conclusão, tool correta, passos, segurança, recuperação e qualidade da resposta.

Avaliar apenas o texto final esconde chamadas desnecessárias ou perigosas.

task success · tool accuracy · step count · safety