# Documentação de API para assistente de IA: llms.txt, Markdown e pacote por produto Guia · UNIFOKAL · 23 de setembro de 2026 · 7 min de leitura · Produto e integração Como preparar a documentação de uma API para o assistente de IA de quem integra: o llms.txt, a versão em Markdown de cada página, o anúncio por cabeçalho e o pacote por produto. Quem integra uma API hoje raramente começa lendo a documentação de ponta a ponta. O mais comum é colar a página no assistente de programação, ou pedir que ele mesmo a busque, e trabalhar a partir da resposta. Isso muda o que uma boa documentação precisa entregar: além de clara para a pessoa, ela precisa chegar ao assistente inteira, limpa e sem ruído de navegação. O problema é concreto. Uma página HTML carrega menu, rodapé, scripts e marcação que não dizem nada sobre a API, e o assistente gasta a janela de contexto com isso. A proposta do arquivo llms.txt, escrita por Jeremy Howard, da Answer.AI, parte do mesmo diagnóstico: páginas feitas para gente embrulham a informação em navegação e JavaScript, e converter isso de volta em texto limpo é difícil e impreciso. Este artigo reúne as convenções que já existem para resolver isso, o que cada uma pede de quem publica documentação e do que desconfiar quando o texto que o assistente lê não é o mesmo que a pessoa vê. ## O llms.txt: um mapa pequeno com links para o que importa A proposta, hoje na versão 2, publicada em agosto de 2026, pede um arquivo Markdown em /llms.txt na raiz do site, ou em qualquer caminho, e ele cobre as páginas abaixo desse caminho. O formato é fixo o bastante para ser lido por programa: um título de nível 1 com o nome do projeto é a única seção obrigatória, seguido de um resumo em citação e de seções com listas de links. A versão 2 mudou a forma de usar o arquivo. Em vez de expandir tudo num contexto só, o agente lê ou busca no llms.txt o que precisa e segue os links relevantes, que devem apontar para conteúdo legível por modelo de linguagem, como a versão em Markdown das páginas. O arquivo fica pequeno, e o detalhe mora atrás dos links. O ecossistema passou a tratar o arquivo como parte da qualidade do site. O Lighthouse, a ferramenta de auditoria do Chrome, verifica o llms.txt nas auditorias de navegação por agentes: a página é sinalizada quando o servidor responde erro ao buscar o arquivo, e a auditoria fica como não aplicável quando ele não existe, porque publicar o arquivo ainda é opcional. Para a especificação da API existe um caminho paralelo e padronizado: a RFC 9727 define o catálogo de API num endereço fixo, /.well-known/api-catalog, que aponta a descrição do serviço e a documentação numa leitura só. ## A versão em Markdown de cada página A segunda parte da proposta é a mais útil no dia a dia. Cada página com informação que um agente pode precisar ganha uma versão em Markdown limpo na mesma URL, com .md anexado ao endereço ou com a extensão trocada por ele. Quem publica em endereços sem extensão, como a maior parte das documentações atuais, anexa o sufixo ao caminho da página, e o endereço sem nome de arquivo, como o que termina em barra, recebe index.md. A versão 2 também resolveu a descoberta. A página aponta a sua versão em Markdown com a relação alternate e o tipo text/markdown, e aponta o llms.txt que a cobre com a relação describedby. As duas podem vir como elemento link no HTML ou no cabeçalho HTTP Link, cuja sintaxe com vários valores está na RFC 8288. O cabeçalho tem uma vantagem: funciona também na própria resposta em Markdown, que não tem cabeçalho HTML onde pendurar um link. Três detalhes separam uma versão em Markdown bem servida de uma mal servida: - O tipo de mídia é text/markdown, definido na RFC 7763, e nela o parâmetro charset é obrigatório. O parâmetro variant diz o dialeto, e o registro de variantes da IANA inclui o GFM, descrito na RFC 7764, um dialeto com tabela. - A versão em Markdown aponta a página original como canônica, pelo cabeçalho Link com a relação canonical e uma URL absoluta. É o que a documentação do Google Search Central recomenda para documento que não é HTML, e a mesma página desaconselha usar noindex para escolher a canônica. - O Markdown não pode ter conteúdo que a página não tem. Se ele for escrito à mão, ele envelhece no primeiro dia em que alguém mexer na página, e ninguém percebe. ## O pacote por produto Página por página resolve a consulta pontual. Quem vai escrever uma integração inteira precisa de outra coisa: tudo o que diz respeito ao produto que vai integrar, num arquivo só, sem o resto. É o pacote de contexto, a documentação recortada por produto, com o contrato, os exemplos de código, os códigos de erro e os webhooks daquele produto. Um pacote bom declara o próprio tamanho, porque a janela de contexto do assistente é finita. E declara com honestidade: o tamanho em bytes é medido no arquivo servido, e a contagem de tokens é estimativa, porque cada modelo usa um tokenizador diferente e o mesmo texto vira números diferentes de tokens em cada um. Estimativa apresentada como número exato engana quem está decidindo se o pacote cabe na janela. Na documentação da UNIFOKAL, por exemplo, cada página tem a versão em Markdown na mesma URL, e há um [pacote por família de produto](https://unifokal.com/docs/pacotes-para-ia), com o tamanho medido e a estimativa de tokens declarada como estimativa. ## Como usar, e do que desconfiar Para quem integra, o roteiro é curto: 1. Comece pelo llms.txt da documentação, se existir, para achar o que o assistente deve ler primeiro. 2. Prefira a versão em Markdown da página, ou o pacote do produto, ao HTML copiado da tela. 3. Confira a data e a versão da API no próprio texto. Documentação para agente tem o mesmo problema de qualquer documentação: pode estar velha. O risco que merece atenção é a documentação para agente que não sai da mesma fonte que a página nem do contrato da API. Um assistente não estranha o texto: ele obedece. Se o Markdown descreve uma rota que mudou, o código sai errado com toda a confiança. Por isso vale perguntar ao fornecedor como a versão para agentes é produzida e o que impede que ela divirja da página, do mesmo jeito que se pergunta como a API é versionada. O artigo sobre [versionamento de API e breaking changes](https://unifokal.com/blog/versionamento-de-api-e-breaking-changes) trata dessa segunda pergunta. Também vale lembrar que o assistente escreve o código, mas quem prova a integração é o teste. Rodar a primeira chamada no [sandbox antes de produção](https://unifokal.com/blog/sandbox-antes-de-producao) continua sendo o passo que separa o código gerado do código que funciona, e a escolha entre [widget ou API](https://unifokal.com/blog/widget-ou-api-de-kyc) continua sendo uma decisão de quem integra, não do assistente. ## Fontes citadas - Jeremy Howard (Answer.AI), "The /llms.txt file", versão 2, de agosto de 2026, e a página de mudanças, lidas em 23 de setembro de 2026: [llmstxt.org](https://llmstxt.org/) - Chrome for Developers, documentação do Lighthouse, auditoria llms.txt entre as auditorias de navegação por agentes: [developer.chrome.com](https://developer.chrome.com/docs/lighthouse/agentic-browsing/llms-txt) - IETF, RFC 9727, api-catalog: A Well-Known URI and Link Relation to Help Discovery of APIs (2025): [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9727) - IETF, RFC 8288, Web Linking (2017): [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc8288) - IETF, RFC 7763, The text/markdown Media Type (2016), seção 2, parâmetros: [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc7763) - IETF, RFC 7764, Guidance on Markdown: Design Philosophies, Stability Strategies, and Select Registrations (2016), seção 3.2, GitHub Flavored Markdown: [rfc-editor.org](https://www.rfc-editor.org/rfc/rfc7764) - IANA, registro Markdown Variants: [iana.org](https://www.iana.org/assignments/markdown-variants/) - Google Search Central, "How to specify a canonical URL with rel="canonical" and other methods": [developers.google.com](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)