Construindo para o Desafio WebMCP? Exponha suas ações reais, não um chatbot

O WebMCP Challenge está ativo — OpenAI com Chrome, Cloudflare, Shopify, Vercel, Render e Netlify, ocorrendo de 25 de agosto a 3 de setembro no Devpost, com $35 mil em prêmios. Dez dias para construir algo com WebMCP: a API do navegador que permite que uma página forneça ferramentas reais para agentes de IA chamarem em vez de fazê-los clicar pela sua interface.

Eu mantenho uma ferramenta WebMCP de código aberto (viés divulgado — link no final), então assisti a muitos desses projetos. Os projetos que demonstram de forma clara e aqueles que desmoronam na frente de um agente diferem exatamente em duas coisas. Se você está construindo esta semana, aqui estão elas.

1. Exponha ações, não uma caixa de chat

O reflexo é registrar uma ferramenta chat ou ask que envolve uma caixa de pesquisa. Não faça isso. Um agente já é a interface de chat — não precisa de outra. O que ele não pode fazer é as ações do seu site: pesquisar seu catálogo, adicionar ao carrinho, verificar disponibilidade, reservar um horário, enviar o formulário. Registre essas ações.

document.modelContext.registerTool({
  name: "search_catalog",
  description: "Pesquisar produtos nesta loja",
  inputSchema: {
    type: "object",
    properties: { q: { type: "string" } },
    required: ["q"],
  },
  async execute({ q }) {
    const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`);
    const items = await res.json();
    return {
      content: [{ type: "text", text: `${items.length} resultados para "${q}"` }],
      structuredContent: { items },
    };
  },
});

(O getter de registro mudou de navigator.modelContext para document.modelContext em 10 de agosto — detecte ambos se quiser ser seguro e restrinja o suporte para que navegadores não agentes não sejam afetados.)

2. Seu valor de retorno é um contrato, não uma interface

Este é o que falha nas demonstrações. Um humano lê sua página; um agente lê o que sua ferramenta retorna. Portanto, uma ferramenta que faz seu trabalho e retorna { ok: true } — ou navega pela página e não retorna nada — não disse nada ao agente. O próximo passo no plano do agente não tem dados para agir, então ele para ou alucina.

Retorne o resultado real como structuredContent: os itens encontrados, o novo total do carrinho, o número de confirmação da reserva, o erro de validação. Trate o retorno de cada ferramenta como um contrato de API que você agora deve ao agente — porque é isso que é.

Três modos de falha para verificar antes de gravar sua demonstração:

• Flags de sucesso. { ok: true } de uma ferramenta de pesquisa. Retorne os resultados em vez disso.
• Leituras obsoletas. Retornando o estado em cache após uma ação ter o mutado. Retorne o estado pós-ação.
• Erros não tipados. Lançando uma string bruta. Retorne um erro estruturado que o agente possa ramificar.

O que o hackathon não avaliará — mas a produção sim

O desafio avalia uma demonstração funcional. Duas coisas que não serão evidentes e que podem causar problemas no momento em que um agente real acessa seu site:

• Desvio de cobertura. Cada ferramenta é escrita e mantida manualmente. No momento em que sua interface muda e uma ferramenta não, o agente chama uma ferramenta que mente. Em um site de várias páginas, isso é a maior parte do trabalho contínuo.
• Observabilidade. Você não tem ideia de qual agente chamou qual ferramenta, em que ordem, ou se a chamada retornou dados utilizáveis. Hoje isso é uma suposição — e é exatamente o que você vai querer no dia seguinte ao lançar.

Nenhuma das duas é difícil de raciocinar; ambas são fáceis de esquecer enquanto corre contra um relógio de 10 dias.

Atalho para a trilha "envolver meu site existente"

Se seu projeto é um site existente em vez de um aplicativo novo, você não precisa escrever manualmente um registerTool para cada ação. Latch é um script de uma linha licenciado pelo MIT que detecta automaticamente sua pesquisa, carrinho e formulários e os expõe como ferramentas WebMCP — útil quando você deseja cobertura rápida e o tempo é uma restrição (fonte). Escreva-os você mesmo se quiser controle total; de qualquer forma, as duas regras acima ainda decidem se sua demonstração funciona.

Boa sorte no desafio. Construa as ações, honre o contrato de retorno, e sua demonstração de agente funcionará na primeira tentativa.