Menyiapkan Situs agar Siap Dipakai Agen: llms.txt, Halaman Markdown, OpenAPI, api-catalog, dan MCP Server Card

Situs yang siap dipakai agen memberi perangkat lunak jalur yang singkat dan bisa ditebak, dari "ini apa?" sampai "bagaimana cara memakainya?". Dalam praktiknya, itu berarti lima file atau konvensi: ringkasan /llms.txt, versi Markdown yang bersih untuk setiap halaman, deskripsi API dalam format OpenAPI, /.well-known/api-catalog sesuai RFC 9727 yang menunjuk ke deskripsi itu, dan MCP server card yang menjelaskan cara terhubung. Tak satu pun sulit dipublikasikan. Bersama-sama, kelimanya memungkinkan agen menemukan, memahami, dan mulai memakai sebuah produk tanpa ada manusia yang menyalin URL ke jendela chat.

Sepanjang artikel ini saya memakai shager.ai sebagai contoh, karena setiap bagian yang dibahas di sini sudah aktif di sana dan Anda bisa mengambil masing-masing dengan curl sambil membaca.

Untuk apa repot, kalau tidak ada mesin yang berjanji membaca file-file ini?

Mari jujur dulu. llms.txt masih berupa usulan, bukan standar resmi, dan sejauh yang saya tahu belum ada penyedia model besar yang secara terbuka berkomitmen memakainya untuk pengambilan informasi. api-catalog adalah RFC IETF sungguhan, dan MCP server card adalah ekstensi MCP yang sudah diterima, tetapi adopsinya oleh crawler dan klien masih di tahap awal.

Alasan untuk tetap melakukannya bersifat praktis. Semakin sering agen datang ke sebuah situs karena disuruh seseorang, misalnya "daftar di sini lalu hubungkan". Saat itu, agen mengambil halaman secara langsung. Situs yang menjawab dengan Markdown yang bersih, deskripsi API yang eksplisit, dan petunjuk koneksi akan dipakai dengan benar. Situs yang menjawab dengan 400 KB JavaScript hanya akan ditebak-tebak.

Geser ke samping untuk melihat seluruh diagram

llms.txt: pintu depan

Formatnya didefinisikan di llmstxt.org. Ini adalah file Markdown di /llms.txt yang berisi H1 dengan nama situs (satu-satunya bagian wajib), ringkasan dalam blockquote, teks bebas opsional, dan bagian-bagian H2 berisi daftar tautan dengan catatan singkat. Bagian berjudul "Optional" menandai tautan yang boleh dilewati agen saat butuh konteks yang lebih pendek.

File Shager mengikuti bentuk itu. Bagian atasnya seperti ini:

# Shager

> Shager (שגר) is agent-first distribution infrastructure for agencies and
> marketers: your agent creates, Shager ships it everywhere. ...

## For AI agents
- MCP server: https://app.shager.ai/api/mcp (OAuth sign-in for any MCP client that supports it, or Authorization: Bearer <api key>)
- REST API: https://app.shager.ai/api/v1 ...
- Self sign-up: POST https://app.shager.ai/api/v1/agent/signup ...

Beberapa pilihan yang layak ditiru. Bagian untuk agen diletakkan sebelum halaman pemasaran, karena agen yang membaca file ini biasanya ingin langsung bertindak. Harga ditulis dengan angka jelas di dalam file itu sendiri, bukan disembunyikan di balik tautan. Batasan disebutkan apa adanya (misalnya, postingan TikTok tetap privat sampai TikTok menyetujui aplikasinya), supaya agen tidak menjanjikan kepada pengguna sesuatu yang belum bisa dilakukan produk. Lalu ada pendamping berupa /llms-full.txt yang memuat seluruh konten dalam satu file, untuk agen yang lebih suka sekali ambil.

Versi Markdown untuk setiap halaman

Usulan yang sama menyarankan agar setiap halaman disajikan juga dalam versi Markdown yang bersih, dan merekomendasikan agar versi itu diumumkan dengan rel="alternate" dan type="text/markdown", ditambah rel="describedby" yang menunjuk ke llms.txt yang mencakup halaman tersebut. Keduanya bisa berupa elemen HTML <link> atau header HTTP Link.

Shager melakukannya dengan dua cara. Setiap halaman punya kembaran Markdown di bawah /md/, jadi /en/pricing juga tersedia di /md/en/pricing. Selain itu, permintaan ke URL biasa dengan Accept: text/markdown langsung mendapat versi Markdown:

curl -s -H "Accept: text/markdown" https://shager.ai/en/pricing | head -5

Setiap halaman HTML juga mengirim header Link yang mengumumkan versi alternatifnya:

link: </.well-known/api-catalog>; rel="api-catalog",
      </llms.txt>; rel="describedby"; type="text/plain",
      </md/en/agents>; rel="alternate"; type="text/markdown"

Satu detail penting untuk pencarian: respons Markdown membawa x-robots-tag: noindex, sehingga mesin pencari tidak mengindeks dua salinan dari setiap halaman. Markdown untuk agen; HTML tetap menjadi halaman kanonis untuk manusia dan hasil pencarian.

OpenAPI: kontraknya

Untuk apa pun yang akan dipanggil agen, dokumen OpenAPI masih menjadi hal paling berguna yang bisa Anda publikasikan. Dokumen ini menyajikan ID operasi, parameter, skema, dan autentikasi dalam bentuk yang bisa dibaca agen maupun generator kode.

Milik Shager ada di app.shager.ai/api/v1/openapi.json, versi 3.1. Ada tiga konvensi di dalamnya yang khusus membantu agen. ID operasi sama dengan nama tool MCP (create_post, get_analytics), jadi agen yang sudah mempelajari satu antarmuka otomatis mengenal yang lain. Setiap operasi mencantumkan cakupan kunci yang dibutuhkannya lewat ekstensi x-scope. Dan deskripsi kolom ditulis sebagai instruksi, misalnya deskripsi caption pengganti per_channel menyebutkan bahwa sebaiknya susunan kata dibuat berbeda untuk setiap akun. Deskripsi adalah ruang prompt; manfaatkan.

Geser ke samping untuk melihat seluruh diagram

api-catalog: memberi tahu perangkat lunak di mana API berada

RFC 9727, yang diterbitkan IETF pada Juni 2025, mendefinisikan URI well-known, /.well-known/api-catalog, dan relasi tautan api-catalog. Permintaan ke alamat itu mengembalikan dokumen yang mencantumkan API milik sebuah penerbit beserta tautan ke deskripsi dan dokumentasinya. RFC ini mewajibkan tipe media application/linkset+json untuk dokumen tersebut dan memakai relasi tautan seperti service-desc untuk deskripsi yang bisa dibaca mesin seperti OpenAPI, serta service-doc untuk dokumentasi bagi manusia.

Inilah katalog Shager selengkapnya:

{
  "linkset": [
    {
      "anchor": "https://app.shager.ai/api/v1",
      "service-desc": [
        { "href": "https://app.shager.ai/api/v1/openapi.json", "type": "application/openapi+json" }
      ],
      "service-doc": [
        { "href": "https://shager.ai/en/agents", "type": "text/html" },
        { "href": "https://shager.ai/md/en/agents", "type": "text/markdown" }
      ]
    }
  ]
}

Isinya singkat karena Shager hanya punya satu API. Perusahaan yang punya beberapa API akan mencantumkan satu entri untuk setiap API. Tautan rel="api-catalog" di header Link setiap halaman, seperti yang ditunjukkan di atas, adalah cara klien yang mendarat di halaman mana pun menemukan katalog tanpa menebak path-nya.

MCP server card: cara terhubung sebelum terhubung

Klien MCP perlu tahu di mana server berada dan bagaimana cara autentikasinya sebelum bisa memanggil tools/list. SEP-2127 mendefinisikan MCP Server Card persis untuk keperluan ini: dokumen JSON statis yang menjelaskan identitas server jarak jauh, endpoint transport-nya, header yang wajib, dan versi protokol yang didukung. SEP ini menetapkan <streamable-http-url>/server-card sebagai lokasi yang direkomendasikan dan menjelaskan penemuan di tingkat domain melalui AI Catalog yang menautkan ke card tersebut. Skema detailnya ada di repositori ekstensi.

Shager menyajikan card-nya di lokasi yang direkomendasikan, https://app.shager.ai/api/mcp/server-card, dan juga di https://shager.ai/.well-known/mcp/server-card.json, path yang dicek oleh sebagian alat penemuan. Bagian koneksinya berbunyi:

{
  "name": "ai.shager/shager",
  "title": "Shager",
  "version": "1.0.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": [
        { "name": "Authorization", "isRequired": true, "isSecret": true,
          "description": "Bearer shgr_… API key (self-signup: POST /api/v1/agent/signup)" }
      ]
    }
  ]
}

Card ini juga mencantumkan tool Shager dengan deskripsi satu baris. Perlu dicatat, SEP sengaja tidak memasukkan tool ke kolom standar card, karena apa yang diekspos server bisa berbeda tergantung pengguna dan sesi. Perlakukan daftar tool di card mana pun sebagai pratinjau; panggilan tools/list secara langsung adalah sumber kebenarannya.

Dua tambahan: auth.md dan file skill

Penemuan memberi tahu agen apa saja yang ada. Dua file lagi memberi tahu apa yang harus dilakukan.

/auth.md adalah petunjuk sederhana tentang cara agen mendapatkan akses: menemukan, mendaftar lewat panggilan pendaftaran mandiri, memakai kunci, menyerahkan tautan klaim ke manusia, dan cara manusia mencabut akses. File ini juga menyebutkan aturannya: batas permintaan, bentuk pesan galat, variasi caption, dan hanya API resmi. Agen bisa mengikutinya dari atas sampai bawah.

https://shager.ai/skills/shager/SKILL.md adalah file skill dalam format yang dipakai Claude Code untuk skills: frontmatter YAML berisi name dan description yang memberi tahu model kapan memakainya, lalu instruksi bernomor. Pasang file itu, dan agen langsung memahami alur kerja Shager tanpa prompt panjang. Cara membuat versi Anda sendiri dibahas di membuat skill Claude untuk Shager.

Daftar periksa untuk situs Anda

1. /llms.txt dengan H1, ringkasan satu paragraf, bagian untuk agen di urutan pertama, dan label yang jujur untuk apa pun yang belum aktif.
2. Versi Markdown untuk setiap halaman, diumumkan dengan rel="alternate" dan type="text/markdown", serta ditandai noindex.
3. Dokumen OpenAPI dengan ID operasi yang sama dengan tool MCP Anda dan deskripsi yang ditulis sebagai instruksi.
4. /.well-known/api-catalog sebagai application/linkset+json, ditautkan dari setiap halaman dengan rel="api-catalog".
5. MCP server card di <your MCP URL>/server-card.
6. Petunjuk akses dalam bahasa sederhana seperti auth.md, jika agen bisa mendaftar sendiri.

FAQ

Apakah llms.txt sama dengan robots.txt?

Tidak. robots.txt memberi tahu crawler apa yang boleh mereka ambil. llms.txt adalah panduan pilihan tentang apa yang layak dibaca, ditulis untuk model bahasa. File ini tidak memberi atau menolak izin apa pun.

Apakah memublikasikan file-file ini menaikkan peringkat di mesin pencari?

Belum ada bukti yang dipublikasikan, dan belum ada mesin pencari yang menyatakan memakai llms.txt sebagai sinyal peringkat. Nilainya ada pada agen yang memakai produk Anda dengan benar begitu mereka datang. Pastikan halaman HTML Anda tetap kuat untuk pencarian dengan kualitasnya sendiri.

Apakah saya perlu server MCP untuk mendapat manfaat dari ini?

Tidak. llms.txt, halaman Markdown, OpenAPI, dan api-catalog berguna untuk situs apa pun yang punya dokumentasi atau API. Server card hanya relevan jika Anda menjalankan server MCP jarak jauh.

Langkah selanjutnya

Ambil file-file Shager dengan curl dan bandingkan dengan situs Anda sendiri. Untuk apa yang dilakukan agen setelah tahap penemuan, titik masuk untuk agen adalah tujuan berikutnya.