Conteúdo para agentes: Markdown e llms.txt

Aula 1

Por que HTML é caro para um agente

Quando um agente busca uma página, o conteúdo vai para a janela de contexto do modelo. Tudo o que entra ali tem custo duplo: custo financeiro, porque o processamento é cobrado por token, e custo de qualidade, porque contexto cheio de ruído piora o raciocínio. Uma página de blog com 1.500 palavras de texto pode ter 80 KB de HTML, dos quais o texto útil é uma fração pequena.

A Cloudflare relata que a versão em Markdown pode usar até 80% menos tokens que o HTML em alguns casos. No próprio portal de documentação, depois de servir Markdown, ela mediu 31% menos tokens e respostas 66% mais rápidas do que a média de sites não otimizados, num teste com um agente de código. São números da própria empresa, mas a direção é consistente com o que qualquer pessoa observa ao comparar os dois formatos.

O segundo caso da tabela merece atenção. Sites feitos só com renderização no cliente são praticamente invisíveis para agentes que fazem uma requisição simples. Renderização no servidor ou geração estática, como faz este próprio site com templates compilados, resolve o problema na raiz.

Fontes desta aula: Cloudflare: Agent Readiness score · Cloudflare: Markdown for Agents

Aula 2

Negociação de conteúdo com Accept: text/markdown

A negociação de conteúdo é um mecanismo antigo do HTTP, definido hoje na RFC 9110: o cliente diz no cabeçalho Accept quais formatos prefere, e o servidor escolhe a representação. A mesma URL pode devolver HTML para o navegador e Markdown para o agente. É exatamente isso que a checagem "Negociação de Markdown" verifica.

GET /curso-o4ai.html HTTP/1.1
Host: exemplo.com.br
Accept: text/markdown, text/html;q=0.8

HTTP/1.1 200 OK
Content-Type: text/markdown; charset=utf-8
Content-Location: /curso-o4ai.md
Vary: Accept
Link: </curso-o4ai.html>; rel="canonical"

# Curso O4AI: Optimization for AI Agents
...

Os cabeçalhos que importam

• Content-Type: text/markdown; charset=utf-8: o tipo registrado para Markdown.
• Vary: Accept: obrigatório na prática. Sem ele, um CDN pode guardar a versão Markdown em cache e entregá-la a um navegador, ou o contrário.
• Content-Location: informa a URL própria da representação Markdown, se ela existir.
• Na versão HTML, um <link rel="alternate" type="text/markdown" href="..."> e o cabeçalho Link equivalente ajudam agentes que não enviam Accept.

Duas estratégias complementares

A recomendação é ter as duas: gerar o Markdown no build (URL própria) e fazer a negociação apontar para ele. Segundo um teste citado pela Cloudflare, feito em fevereiro de 2026, só três de sete agentes testados (Claude Code, OpenCode e Cursor) pediam Accept: text/markdown por padrão. Os outros só se beneficiam se encontrarem o link para a versão .md.

Como gerar o Markdown

• No build: para sites estáticos, converta o conteúdo principal de cada página (não o layout) com uma biblioteca como Turndown e grave ao lado do .html.
• Na borda: a Cloudflare oferece conversão automática de HTML para Markdown para quem envia Accept: text/markdown, ativável por zona.
• No CMS: no WordPress, um filtro que detecta o Accept e devolve o conteúdo do post convertido, sem tema.

Fontes desta aula: RFC 9110: Content Negotiation · Cloudflare Docs: Markdown for Agents · specification.website: Markdown source endpoints

Aula 3

llms.txt e llms-full.txt

O llms.txt foi proposto em setembro de 2024 por Jeremy Howard como um arquivo em Markdown na raiz do site, pensado para modelos de linguagem. Em vez de listar todas as URLs, como o sitemap, ele apresenta o site e organiza os links mais importantes em seções, com uma frase sobre cada um. É uma convenção de comunidade, não uma RFC, mas já é publicada por muitos portais de documentação.

# ER Soluções Web

> Software house fullstack: integrações, automações, infraestrutura web
> e conteúdos gratuitos sobre marketing, IA e agentes.

## Cursos
- [Curso O4AI](https://ersolucoesweb.com.br/curso-o4ai.md): como preparar sites para agentes de IA, em 8 módulos.
- [Growth Hacking](https://ersolucoesweb.com.br/growth-hacking.md): os 19 canais de tração.

## Serviços
- [Integração de sistemas](https://ersolucoesweb.com.br/integracao-de-sistemas-api.md): APIs e integrações.

## Optional
- [Blog](https://ersolucoesweb.com.br/blog.md): artigos técnicos.

A estrutura da proposta

• Um título # com o nome do site ou projeto (obrigatório).
• Um resumo em bloco de citação >.
• Parágrafos opcionais com contexto.
• Seções ## com listas de links no formato [nome](url): descrição.
• Uma seção chamada Optional para o que pode ser ignorado quando o contexto é curto.

O llms-full.txt é a variação com todo o conteúdo concatenado em um único arquivo, útil para documentação técnica que um agente quer carregar inteira. Para sites grandes, a Cloudflare publica um llms.txt por diretório e omite páginas que são só listagens. A lição vale para qualquer site: o llms.txt é curadoria, não despejo.

Fontes desta aula: llmstxt.org: a proposta · Exemplo: llms.txt da Cloudflare

Aula 4

HTML semântico e dados estruturados como base

Markdown e llms.txt são atalhos. A base continua sendo um HTML que qualquer máquina consegue entender, porque é ele que agentes em navegador, ferramentas de leitura e buscadores processam quando não há alternativa.

• Hierarquia de títulos real: um h1 por página, h2 e h3 em ordem. Conversores de HTML para Markdown dependem disso.
• Elementos semânticos: main, article, nav, table com th. Eles permitem separar conteúdo de navegação.
• Dados estruturados Schema.org em JSON-LD: Product com preço e disponibilidade, Organization, FAQPage, Course, Article. Agentes de compra e de resposta leem esses blocos para extrair fatos sem interpretar texto.
• Formulários acessíveis: label ligado a cada campo, name descritivo e botões com texto. O que é acessível para leitores de tela costuma ser utilizável por agentes, e é a base do WebMCP declarativo.
• Conteúdo no HTML inicial: renderização no servidor ou estática.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Plano Pro",
  "offers": {
    "@type": "Offer",
    "price": "199.00",
    "priceCurrency": "BRL",
    "availability": "https://schema.org/InStock"
  }
}
</script>

Fontes desta aula: Schema.org · MDN: Semântica em HTML

Erros comuns

• Negociar sem Vary: Accept. É a causa número um de navegadores recebendo Markdown cru depois de ativar a funcionalidade.
• Converter a página inteira. Markdown com menus, rodapé e texto de cookies perde boa parte da vantagem.
• Responder text/plain em vez de text/markdown. O scanner exige o tipo correto.
• llms.txt desatualizado. Links quebrados ou páginas antigas fazem o agente citar informação errada. Gere o arquivo no build.
• Esconder preço e disponibilidade em JavaScript. Agentes de compra não vão encontrar.

Aplicação prática: torne o site legível

1. Meça: baixe uma página em HTML e conte os tokens; depois faça o mesmo com o texto principal. Anote a diferença.
2. Gere uma versão .md de cada página de conteúdo no build.
3. Configure a negociação: Accept: text/markdown devolve a versão .md com Content-Type e Vary corretos.
4. Publique /llms.txt com as 10 a 30 páginas mais importantes e descrições de uma linha.
5. Teste com curl -H 'Accept: text/markdown' e com o scanner.

Siglas e termos deste módulo

Token:

Unidade de texto processada pelo modelo; a cobrança e o limite de contexto são medidos em tokens.

Content negotiation:

Mecanismo HTTP em que o cliente indica formatos aceitos e o servidor escolhe.

SSR:

Server-Side Rendering, renderização no servidor.

JSON-LD:

JSON for Linked Data, formato usado para dados estruturados Schema.org.

CDN:

Content Delivery Network, rede de cache e entrega de conteúdo.