AI ajanları için hazırlanmış dokümantasyon, sadece insanlar için değil

Her içerik belge sayfası, aynı yolda .md sonekiyle birlikte ham bir Markdown çiftine sahiptir. /agent-setup’ı açarsanız - /agent-setup.md de vardır, aynı metin HTML sarmalayıcı olmadan, MDX içe aktarmaları kesilmiş, text/markdown olarak sunulur.

Bu, sayfa menüsündeki iki eylemi besler: Copy as Markdown (temiz metni modelle sohbet için panoya kopyalar) ve View as Markdown (.md sürümünü doğrudan açar). Agente DOM ayrıştırmaya gerek yok - hazır metni alır.

Her sayfanın sağ üst köşesinde, tamamen ajan iş akışı için tasarlanmış bir eylem menüsü vardır:

• Copy as Markdown - sayfanın temiz metnini panoya kopyalar
• View as Markdown - .md çiftini açar
• Open in ChatGPT - sayfayı tek tıkla ChatGPT’ye aktarır
• Open in Claude - bunu Claude için yapar
• Connect MCP - MCP sunucusu ayarlarına geçiş

“URL’yi kopyala, sohbeti aç, sayfaya gitmesini iste” yerine - tek bir eylem.

llmstxt.org standardına göre iki dosya sunuyoruz:

• /llms.txt - tüm belge sayfalarının indeksi, bölümlere göre gruplanmış (API Reference, Use Cases, Examples, Products). Ajansın nereden başlayacağına dair bir harita.
• /llms-full.txt - tüm belgeler tek bir düz metin dosyasında. Vektör veritabanında çevrimdışı indeksleme veya modele bir kez bağlam eklemek için.

API’mız üzerinde RAG inşa ediyorsanız, llms-full.txt hazır bir korpusdur, siteyi taramanıza gerek yok.

Sözleşme, farklı araçlar için çeşitli formatlarda sunulur:

• /v1/openapi.json - örnekler ve code-samples ile birlikte kanonik OpenAPI 3.1 özelliği. İstemci kod oluşturma ve herhangi bir OpenAPI aracı için.
• Swagger takma adları - /v1/swagger.json, /v1/v3/api-docs ve diğerleri, alışılmış yolları arayan araçların takılmaması için kanonik dosyaya 301 yönlendirir.
• Postman koleksiyonu - Postman’a tek tıkla içe aktarmak için /postman/astroway-api.json.

/agent-setup/ sayfası - tek genel bir kılavuz değil, yedi istemci için ayrı talimatlar: Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Cline, Codex. Her biri, kod yazmadan önce bağlantıyı kontrol etmek için doğru yapılandırma ve tools/list curl örneği sağlar.

API referans sayfalarında her işlem, yerleşik bir try-it widget’ına sahiptir: sandbox anahtarını girersiniz, istek gövdesini düzenlersiniz, “Send” butonuna basarsınız - ve docs’tan çıkmadan gerçek yanıtı görürsünüz. Metot, yol ve gövde örneği, zaten oluşturulmuş bir curl snippet’tan alınır, bu yüzden widget openapi.json üzerinden gereksiz istek yapmaz.

Basit tez: ürününüz bir API ise, belgeler sadece gözle okunmak için değil, aynı zamanda ajan tarafından tüketilmek için de uygun olmalı. Bugünkü entegrasyonların yarısı, geliştirici docs linkini Claude veya Cursor’a atıp “bunu bağla” demesiyle başlıyor. Biz de öyle yaptık ki diğer uçta ayrıştırılması gereken HTML yerine temiz metin ve makine sözleşmesi olsun.

Kendi deney: herhangi bir docs sayfasını açın, sağ üstteki eylem menüsüne basın - ve “Open in Claude” göreceksiniz.