Implementação, segurança e projeto final

Aula 1

Roteiro por nível de maturidade

A escala do módulo 1 vira um roteiro. A regra é não pular níveis: cada um depende do anterior e entrega valor sozinho.

Um site institucional, como o desta empresa, chega ao nível 3 em um ou dois dias de trabalho. Os níveis 4 a 6 dependem de ter API, área logada ou loja, e devem ser planejados como projeto de produto, não como ajuste técnico.

Aula 2

Implementação no Cloudflare, Nginx e WordPress

Cloudflare Pages: arquivos estáticos e _headers

Em sites estáticos no Cloudflare Pages, os arquivos .well-known entram na pasta publicada e os cabeçalhos são definidos no arquivo _headers.

/
  Link: </llms.txt>; rel="describedby"; type="text/plain", </.well-known/api-catalog>; rel="api-catalog"

/.well-known/api-catalog
  Content-Type: application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"
  Access-Control-Allow-Origin: *

/.well-known/*
  Access-Control-Allow-Origin: *

/*.md
  Content-Type: text/markdown; charset=utf-8

Cloudflare: negociação de Markdown com uma Pages Function

// functions/_middleware.js
export async function onRequest({ request, next, env }) {
  const accept = request.headers.get('Accept') || '';
  const url = new URL(request.url);
  if (accept.includes('text/markdown') && url.pathname.endsWith('.html')) {
    const mdUrl = new URL(url.pathname.replace(/\.html$/, '.md'), url);
    const md = await env.ASSETS.fetch(mdUrl);
    if (md.ok) {
      return new Response(md.body, {
        headers: {
          'Content-Type': 'text/markdown; charset=utf-8',
          'Content-Location': mdUrl.pathname,
          'Vary': 'Accept'
        }
      });
    }
  }
  const res = await next();
  const out = new Response(res.body, res);
  out.headers.append('Vary', 'Accept');
  return out;
}

Para quem não quer manter versões .md, a Cloudflare também oferece a conversão automática "Markdown for Agents" por zona. A vantagem da versão gerada no build é controlar exatamente o que entra, sem menus e rodapés.

Nginx

map $http_accept $md_suffix {
    default        "";
    "~*text/markdown" ".md";
}

server {
    location ~ ^(?<base>/.+)\.html$ {
        add_header Vary Accept always;
        try_files $base.html$md_suffix $uri =404;
    }

    location = /.well-known/api-catalog {
        default_type 'application/linkset+json; profile="https://www.rfc-editor.org/info/rfc9727"';
        add_header Access-Control-Allow-Origin * always;
    }

    location = / {
        add_header Link '</.well-known/api-catalog>; rel="api-catalog"' always;
        try_files /index.html =404;
    }
}

WordPress

• robots.txt: o filtro robots_txt permite acrescentar os grupos de IA e o Content-Signal ao arquivo virtual gerado pelo WordPress.
• Markdown: um hook em template_redirect que, ao detectar Accept: text/markdown num post, converte the_content e responde com os cabeçalhos corretos.
• Link: header('Link: ...', false) no hook send_headers.
• .well-known: rotas com add_rewrite_rule ou arquivos estáticos servidos pelo servidor web antes do PHP.
• llms.txt: gerado a partir dos posts e páginas principais e regenerado ao publicar.

add_filter('robots_txt', function ($output) {
    $output .= "\nUser-agent: GPTBot\nUser-agent: ClaudeBot\nDisallow: /\n";
    $output .= "\nUser-agent: *\nContent-Signal: search=yes, ai-input=yes, ai-train=no\n";
    return $output;
}, 20);

Fontes desta aula: Cloudflare Pages: _headers · Cloudflare Pages Functions · WordPress: filtro robots_txt

Aula 3

Segurança: o que não expor para agentes

Abrir o site para agentes amplia a superfície de ataque. Cada arquivo publicado é lido por agentes legítimos e por atacantes, e cada ferramenta é uma porta. Os riscos principais e as defesas:

A regra geral vem do curso de harness engineering: um agente que lê conteúdo não confiável, tem acesso a dados privados e consegue se comunicar com o exterior está exposto à chamada "tríade letal". Do lado do site, o seu papel é não ser a fonte do conteúdo malicioso e não oferecer ferramentas que completem a tríade sem confirmação.

Fontes desta aula: Simon Willison: The lethal trifecta · OWASP Top 10 para aplicações com LLM

Aula 4

Medição: logs, tokens e conversões de agentes

O4AI sem medição vira checklist. As métricas abaixo mostram se o trabalho está gerando uso real.

Um truque simples e poderoso: monitore os 404 em /.well-known/. Eles mostram o que os agentes que visitam o seu site esperam encontrar. Se aparecem pedidos frequentes de mcp/server-card.json, há demanda real por um servidor MCP.

# Agentes de IA no log de acesso do Nginx, por user-agent
grep -Ei 'GPTBot|ClaudeBot|Claude-User|Claude-SearchBot|OAI-SearchBot|ChatGPT-User|PerplexityBot|CCBot' \
  /var/log/nginx/access.log | awk -F'"' '{print $6}' | sort | uniq -c | sort -rn

# O que agentes procuram em .well-known
grep '/.well-known/' /var/log/nginx/access.log | awk '{print $9, $7}' | sort | uniq -c | sort -rn | head -30

Rode o scanner de prontidão mensalmente e guarde o histórico. Padrões mudam, e uma checagem aprovada hoje pode falhar amanhã por uma nova versão de esquema ou uma mudança de CDN.

Aula 5

Projeto final: deixe seu site pronto para agentes

O projeto final aplica o curso inteiro a um site real, de preferência um que você mantém. O objetivo é sair com o site um nível acima e um plano para os próximos.

1. Diagnóstico (módulo 1): rode o scanner e o script de curl, classifique o nível atual e defina o nível-alvo.
2. Descoberta (módulo 2): corrija robots.txt e sitemap, adicione cabeçalhos Link; avalie DNS-AID se houver serviço de agente.
3. Conteúdo (módulo 3): gere versões Markdown, configure a negociação com Vary e publique o llms.txt.
4. Controle (módulo 4): escreva a política de IA por finalidade e o Content-Signal; verifique bots assinados nos logs.
5. APIs e autenticação (módulo 5): se houver API ou login, publique api-catalog, metadados OAuth e auth.md.
6. Protocolos (módulo 6): escolha uma tarefa valiosa e exponha via MCP, WebMCP ou A2A, com o card correspondente.
7. Comércio (módulo 7): se vende algo, avalie o piloto de UCP, ACP, x402 ou MPP.
8. Segurança e medição (módulo 8): revise cada arquivo público, configure o monitoramento de agentes e de 404 em .well-known.
9. Relatório: compare o scanner antes e depois e registre o que ficou para o próximo ciclo.

Erros comuns na implementação

• Implementar no ambiente errado. Arquivos em .well-known que funcionam em homologação e são bloqueados pela regra de segurança do CDN em produção.
• Fallback de página única. Roteadores de SPA que devolvem o index.html com status 200 para caminhos inexistentes fazem os scanners e agentes lerem HTML onde esperavam JSON.
• Esquecer o cache. Mudanças no robots.txt e nos cards podem levar até 24 horas para serem lidas.
• Não versionar. Os arquivos de O4AI devem estar no repositório, passar por revisão e ser gerados no build quando possível.

Siglas e termos deste módulo

SPA:

Single Page Application, aplicação de página única.

Pages Function:

Código serverless executado na borda junto a um site do Cloudflare Pages.

Tríade letal:

Combinação de conteúdo não confiável, dados privados e comunicação externa em um mesmo agente.

OWASP:

Open Worldwide Application Security Project, referência em segurança de aplicações.