Web Search API di Cloudflare AI Gateway: Cara Grounding Agen dengan Sumber Nyata

Ada satu kebiasaan agen AI yang jarang disadari pengguna: ketika butuh halaman web, agen biasanya menebak URL-nya lalu memanggil curl. Kalau tebakannya salah, yang muncul adalah 404. Cara ini jelas tidak efisien, karena agen membuang satu putaran penuh hanya untuk menemukan alamat yang benar. Cloudflare menyoroti masalah ini secara langsung dalam pengumuman Web Search API via AI Gateway pada 2 Oktober 2026.

Gagasan di balik fitur ini sederhana: manusia memulai pencarian dari mesin pencari, bukan dari menebak alamat. Agen seharusnya bekerja dengan cara yang sama. Web Search API memberi agen kemampuan mencari data relevan di internet, lalu menjawab berdasarkan informasi yang masih segar. Alih-alih mengandalkan ingatan model yang beku pada titik waktu tertentu, agen mendapat lapisan konteks dinamis yang diisi ulang setiap kali dipanggil.

Masalah yang Diselesaikan

Model bahasa dilatih lalu dibekukan. Setelah itu, ia hanya tahu informasi yang ada sebelum tanggal batas pengetahuannya. Untuk topik yang bergerak cepat seperti rilis API baru, perubahan harga, atau berita teknologi harian, cara ini cepat usang. Menyuntikkan hasil pencarian web langsung ke pipeline inferensi membuat aplikasi bisa mengakses informasi terkini tanpa harus melatih ulang model.

Cloudflare memberi contoh yang cukup relevan dengan konteks mereka sendiri: agen yang sedang membangun sesuatu dengan alat developer Cloudflare bisa melewatkan semua produk dan fitur baru yang dirilis selama Birthday Week. Dengan web search, dokumentasi dan rilis terbaru bisa diambil saat itu juga. Pola yang sama berlaku untuk dokumentasi pustaka yang berubah, catatan rilis, atau informasi operasional yang tidak pernah masuk ke data latih.

Bagaimana Bentuk Datanya

Yang dikembalikan bukan halaman penuh, melainkan snippet terstruktur dari web yang disuntikkan ke konteks. Ini penting karena halaman penuh boros token dan sering penuh elemen yang tidak relevan. Snippet yang terstruktur memudahkan model menilai relevansi dan menyusun jawaban tanpa harus memproses ribuan kata yang tidak perlu.

Cloudflare memposisikan fitur ini sebagai bagian dari ekosistem AI Gateway. AI Gateway sendiri dirancang sebagai control plane untuk aplikasi: ada observability, penagihan terpadu, keamanan, dan kontrol akses di dalamnya. Web search dimasukkan ke situ karena cocok dengan pola tersebut. Kamu bisa memakai kredit AI Gateway untuk mengonsumsi web search, mengumpulkan log dan data request dari panggilan web search, serta mengatur siapa yang boleh mengakses penyedia mana.

Mitra dan Standar Crawler

Peluncuran ini dimulai bersama tiga mitra: Ceramic.ai, Exa, dan Linkup. Yang menarik, Cloudflare tidak sekadar menambahkan API pihak ketiga. Mereka mensyaratkan agar crawler yang dipakai penyedia web search mematuhi standar bot mereka.

Secara konkret, crawler tersebut harus memenuhi persyaratan "Verified bots" yang didefinisikan dalam dokumentasi developer Cloudflare, dan respons web search wajib menyertakan tautan ke lokasi konten yang di-crawl. Aturannya sederhana tetapi berdampak: crawler harus mengidentifikasi diri, menghormati robots.txt, dan memberi sumber hasil pencarian. Pemilik situs punya kendali lebih besar atas bagaimana konten mereka dipakai.

Bagi pengguna, konsekuensinya adalah kamu memilih untuk mengonsumsi pengetahuan pencarian dari operator yang berkomitmen pada transparansi, kontrol, dan visibilitas. Cloudflare menyebut ini langkah untuk menaikkan standar soal apa artinya menjadi crawler yang baik di internet.

Memakai Lewat AI Gateway

AI Gateway adalah titik integrasi utama untuk produk Web Search API ini. Beberapa hal yang perlu dicatat sebelum memakainya:

• Konsumsi web search menarik dari saldo kredit AI Gateway kamu, dan panggilannya muncul di log observability yang sama seperti panggilan model.
• Ada kontrol akses: kamu bisa mengatur siapa yang boleh mengakses penyedia web search mana.
• Cloudflare menandai mitra yang mendukung Zero Data Retention, sehingga kamu tahu data kamu tidak disimpan.
• Web search juga ditawarkan langsung dengan harga list dari mitra, tanpa markup tambahan dari Cloudflare.
• Dukungan Bring-Your-Own-Key (BYOK) tersedia untuk penyedia web search, sama seperti untuk model.

Bagi tim yang sudah memakai AI Gateway untuk routing model, menambahkan web search berarti menggabungkan konteks live ke dalam pipeline yang sudah ada, tanpa membangun integrasi terpisah untuk tiap penyedia pencarian.

Contoh Orkestrasi di Worker

Kalau ingin mengorkestrasi web search sebagai server tool sendiri hari ini, Cloudflare menyediakan contoh di Worker. Alurnya: model diminta memanggil fungsi web_search, hasil pemanggilan itu dikirim ke API web search, lalu hasilnya disuntikkan kembali sebagai pesan tool sebelum model menyusun jawaban akhir. Potongan intinya kira-kira seperti ini:

const completion = await env.AI.run("@cf/google/gemma-4-26b-a4b-it", {
  messages: [{ role: "user", content: "Apa yang terjadi di Birthday Week 2025?" }],
  tools: [{
    type: "function",
    function: {
      name: "web_search",
      description: "Search the web for current information.",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"]
      }
    }
  }]
}, { gateway: { id: "default" } });

const toolCall = completion.tool_calls?.[0];

if (toolCall?.name === "web_search") {
  const response = await env.AI.websearch({
    gatewayId: "default",
    query: toolCall.arguments.query,
    limit: 5
  });
  const searchResults = await response.json();
  const finalResponse = await env.AI.run(model, {
    messages: [
      { role: "user", content: prompt },
      { role: "tool", name: "web_search", content: JSON.stringify(searchResults) }
    ]
  }, { gateway: { id: "default" } });
}

Pola dua putaran ini penting dipahami. Putaran pertama membuat model memutuskan kapan perlu mencari dan dengan kata kunci apa. Putaran kedua memberi model hasil pencarian sebagai konteks, lalu meminta jawaban final. Menyusun alur seperti ini sendiri memberi kontrol lebih besar atas berapa banyak hasil yang diambil dan bagaimana hasil itu diformat sebelum masuk ke konteks.

Kapan Web Search Justru Tidak Perlu

Tidak semua agen butuh akses web. Kalau tugasmu sepenuhnya bergantung pada data internal, misalnya menjawab pertanyaan dari basis pengetahuan perusahaan, menambahkan pencarian web justru memasukkan noise. Sumber eksternal bisa membawa informasi yang bertentangan dengan kebijakan internal, atau sekadar mengalihkan model dari konteks yang benar.

Web search paling berguna ketika jawabannya bergantung pada sesuatu yang berubah cepat: versi pustaka terbaru, harga terkini, catatan rilis, atau kejadian terkini. Sebaliknya, untuk konsep yang stabil dan terdokumentasi baik, retrieval dari indeks internal biasanya lebih dapat diandalkan dan lebih murah.

Ada juga pertimbangan kualitas sumber. Karena hasil pencarian datang dari web terbuka, model bisa saja mengutip halaman yang usang atau keliru. Praktik yang lebih aman adalah membatasi domain sumber untuk topik tertentu, memverifikasi angka penting, dan tidak menjadikan hasil pencarian sebagai satu-satunya dasar untuk klaim faktual. Hasil pencarian sebaiknya berperan sebagai petunjuk, bukan kebenaran final.

Kaitannya dengan Tren Agen 2026

Peluncuran ini mengikuti pola yang lebih besar: agen bergerak dari sekadar menjawab menjadi bertindak, dan bertindak butuh konteks yang hidup. Grounding lewat pencarian adalah salah satu cara paling langsung untuk menutup jurang antara data latih yang beku dan dunia yang bergerak. Yang membedakan pendekatan Cloudflare adalah penekanan pada standar crawler dan transparansi sumber, bukan sekadar menambah satu API pencarian lagi ke daftar.

Untuk developer Indonesia yang membangun aplikasi berbasis agen, ini relevan karena menyatukan pencarian, kredit, log, dan kontrol akses di satu tempat. Membangun integrasi pencarian sendiri untuk tiap penyedia memakan waktu dan menambah permukaan yang harus dijaga. Memakai satu control plane mengurangi kerja itu, dengan catatan kamu tetap perlu memahami bagaimana harga dan retensi data bekerja sebelum memakainya di produksi.

Menilai Kualitas Hasil Pencarian

Sebelum memasukkan web search ke produksi, ada baiknya menyiapkan set pertanyaan uji yang mencerminkan kebutuhan nyata pengguna. Untuk setiap pertanyaan, catat beberapa hal: apakah hasil pencarian benar-benar relevan, apakah sumbernya kredibel, dan apakah jawaban akhir model lebih baik dibanding tanpa pencarian. Tanpa pembanding seperti ini, mudah terjebak pada kesan bahwa fitur baru selalu menambah nilai, padahal bisa jadi retrieval internal yang sudah ada justru lebih akurat untuk topik tertentu.

Perhatikan juga kasus ketika pencarian mengembalikan informasi yang benar tetapi tidak menjawab pertanyaan. Ini sering terjadi pada pertanyaan yang sangat spesifik atau bergantung konteks. Model yang baik akan mengakui keterbatasan itu, tetapi model yang buruk cenderung memaksakan jawaban dari sumber yang hanya mirip sekilas. Menguji perilaku ini secara sengaja, misalnya dengan pertanyaan yang jawabannya memang tidak ada di web, membantu kamu memahami seberapa besar risiko halusinasi yang tersisa.

Selain itu, penting menguji bagaimana sistem menangani hasil yang saling bertentangan. Web sering memuat klaim yang berbeda soal versi, harga, atau perilaku API. Kalau model diminta memilih tanpa panduan, ia bisa mengambil sumber yang salah. Menambahkan instruksi prioritas, misalnya mengutamakan dokumentasi resmi, mengurangi risiko ini secara signifikan.

Keamanan: Memperlakukan Konten Web sebagai Data

Konten dari web harus diperlakukan sebagai data, bukan instruksi. Halaman yang diambil bisa saja memuat teks yang dirancang untuk memanipulasi model, misalnya menyisipkan perintah tersembunyi agar agen melakukan sesuatu yang tidak diminta. Praktik yang aman adalah memisahkan secara jelas mana yang merupakan instruksi sistem dan mana yang merupakan hasil pencarian, lalu tidak pernah membiarkan konten eksternal mengubah perilaku inti agen.

Untuk aplikasi yang menangani tindakan sensitif, misalnya mengirim pesan, mengubah konfigurasi, atau memanggil API yang mengubah data, hasil pencarian sebaiknya tidak pernah menjadi satu-satunya dasar keputusan. Idealnya ada lapisan verifikasi atau persetujuan manusia untuk aksi yang tidak bisa dibatalkan. Web search memperkaya konteks, tetapi tidak menggantikan tanggung jawab atas tindakan yang diambil.

Soal data pribadi, penyedia yang mendukung Zero Data Retention memberi kejelasan bahwa data tidak disimpan. Tetap saja, tim perlu memastikan query yang dikirim tidak memuat informasi sensitif yang tidak seharusnya keluar dari sistem internal. Menyaring query sebelum dikirim adalah kebiasaan yang murah dan mencegah kebocoran yang tidak disengaja.

Soal Biaya dan Volume

Karena panggilan web search menarik dari kredit AI Gateway dan harganya mengikuti tarif mitra tanpa markup, biaya akan sangat bergantung pada seberapa sering agen mencari. Agen yang mencari di setiap putaran percakapan bisa menghabiskan anggaran jauh lebih cepat daripada agen yang hanya mencari ketika benar-benar perlu. Karena itu, keputusan model soal kapan memanggil pencarian, yang diatur lewat deskripsi fungsi pada tool, punya dampak langsung ke tagihan.

Cara yang lebih hemat adalah membatasi pencarian pada pemicu yang jelas: pertanyaan yang menyebut waktu relatif seperti "terbaru", permintaan yang menyebut versi atau rilis, atau pertanyaan yang jawabannya memang bergerak cepat. Untuk pertanyaan konseptual, retrieval internal biasanya cukup. Memisahkan dua jalur ini menjaga biaya tetap terprediksi.

Terakhir, catat bahwa limit jumlah hasil pada satu pencarian juga berpengaruh. Mengambil lima hasil biasanya cukup untuk menjawab dengan baik, sementara mengambil lebih banyak menambah token konteks dan biaya tanpa selalu memperbaiki kualitas jawaban. Menyetel limit sesuai kebutuhan adalah cara sederhana untuk mengendalikan keduanya sekaligus.

Fitur ini tersedia lewat AI Gateway, REST API mandiri, dan AI Playground. Kalau kamu sudah punya akun AI Gateway dan key, mencobanya cukup dengan beberapa panggilan. Langkah pertama yang masuk akal adalah menguji kualitas hasil pencarian untuk beberapa pertanyaan nyata dari domain kamu, lalu memutuskan apakah grounding eksternal benar-benar menambah nilai dibanding retrieval internal yang sudah ada.