Documentação feita para agentes de IA, não apenas para humanos

Cada página de documentação de conteúdo tem um twin Markdown bruto no mesmo caminho com sufixo .md. Abra /agent-setup - existe também /agent-setup.md, o mesmo texto sem envoltório HTML, imports MDX são removidos, servido como text/markdown.

Isto alimenta duas ações no menu da página: Copy as Markdown (coloca texto puro no clipboard para inserir num chat com o modelo) e View as Markdown (abre a versão .md diretamente). Ao agente não é necessário fazer parse do DOM - ele pega o texto pronto.

No canto superior direito de cada página, há um menu de ações feito especificamente para o fluxo de trabalho de agentes:

• Copy as Markdown - texto puro da página para o clipboard
• View as Markdown - abrir o twin .md
• Open in ChatGPT - enviar a página para o ChatGPT com um clique
• Open in Claude - o mesmo para Claude
• Connect MCP - ir para a configuração do servidor MCP

Em vez de “copia o URL, abre o chat, pede para ir à página” - uma única ação.

Segundo o padrão llmstxt.org, fornecemos dois arquivos:

• /llms.txt - índice de todas as páginas de documentação, agrupado em secções (API Reference, Use Cases, Examples, Products). Um mapa para o agente, para saber por onde começar.
• /llms-full.txt - toda a documentação num único ficheiro plain-text. Para indexação offline numa base de dados vetorial ou para inserção única no contexto do modelo.

Se estiver a construir RAG sobre a nossa API, llms-full.txt é um corpus pronto, não precisa de fazer crawling do site.

O contrato é fornecido em vários formatos para diferentes ferramentas:

• /v1/openapi.json - especificação canónica OpenAPI 3.1 com exemplos e code-samples. Para geração de código de clientes e qualquer ferramenta OpenAPI.
• Aliases Swagger - /v1/swagger.json, /v1/v3/api-docs e outros fazem 301 redirects para o canónico, para que ferramentas que procuram caminhos habituais não tropeçem.
• Coleção Postman - /postman/astroway-api.json para importação no Postman com um clique.

A página /agent-setup/ - não é um guia geral, mas instruções separadas para sete clientes: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Cada uma fornece uma configuração exata e um exemplo curl tools/list para verificar a conexão antes de escrever código.

Nas páginas de referência da API, cada operação tem um widget try-it incorporado: insere a chave sandbox, edita o corpo do pedido, pressiona ‘Send’ - e vê a resposta real, sem sair dos docs. O método, caminho e exemplo do corpo são obtidos do snippet curl já gerado, por isso o widget não faz pedidos extras ao openapi.json.

Uma tese simples: se o teu produto é uma API, a documentação deve ser adequada não apenas para leitura humana, mas também para consumo por agentes. Metade das integrações hoje começa quando um desenvolvedor lança um link para os docs e pede “liga isto”. Fizemos com que no outro lado haja texto puro e um contrato máquina, não HTML que precise de ser parsed.

Experimenta tu mesmo: abre qualquer página dos docs, pressiona o menu de ações no canto superior direito - e verás “Open in Claude”.