Jelajahi dokumentasi
Panduan
Buat formulir pencarian, simpan kunci API pada backend Anda, dan gunakanlah fungsi pencarian yang sama dalam suatu alat agen.
Di halaman ini
What you will build
Bentuk pencarian lokal dengan link peringkat, snippet dan penggunaan kredit. Memerlukan Node.js 22+, sebuah kunci dengan google_search ijin dan kredit yang tersedia. Tidak. npm Paket dibutuhkan. Bagian agen opsional menggunakan fungsi backend yang sama.
| Simpan dalam format flashdata-search-demo | Tujuan |
|---|---|
| search.mjs | Memanggil FlashData dari backend; dibagikan oleh formulir dan alat agen. |
| server.mjs | Melayani halaman lokal dan GET /search titik akhir. |
| index.html | Tampilkan sumber, hasil dan galat kosong. |
node --version
mkdir flashdata-search-demo
cd flashdata-search-demoSet kunci API Anda
Gunakan FLASHDATA_API_KEY jika sudah diset. Jika tidak, gunakan prompt tersembunyi di bawah di terminal yang akan menjalankan kode. Seorang agen dapat memuat variabel yang sama dari toko rahasia.
# Bash: paste the key into a hidden prompt, not into this command.
read -r -s -p "FlashData API key: " FLASHDATA_API_KEY
printf '\n'
export FLASHDATA_API_KEY# PowerShell 7: paste the key into a hidden prompt.
$flashdataSecureKey = Read-Host "FlashData API key" -AsSecureString
$env:FLASHDATA_API_KEY = [System.Net.NetworkCredential]::new("", $flashdataSecureKey).Password
Remove-Variable flashdataSecureKey1. Buat fungsi pencarian
Simpan sebagai search.mjs dalam folder projek Anda. Satu panggilan kembali ke lima hasil web, mereka URLs dan penggunaan sebenarnya. Fungsi memvalidasi masukan, mempertahankan urutan hasil, menghapus duplikasi URLs dan menyimpan kunci dari data yang dikembalikan. The 500Batas karakter adalah pilihan aplikasi.
// search.mjs — server only; Node.js 22+
export async function searchWeb(query) {
if (typeof query !== "string" || !query.trim() || query.length > 500) {
throw Object.assign(new Error("Enter a query of 1–500 characters."), { status: 400 });
}
const apiKey = process.env.FLASHDATA_API_KEY;
if (!apiKey) throw new Error("Set FLASHDATA_API_KEY on the server.");
let response;
try {
response = await fetch("https://data.flashdata.dev/v1/queries/realtime", {
method: "POST", redirect: "error", signal: AbortSignal.timeout(70000),
headers: { "X-API-Key": apiKey, "Content-Type": "application/json" },
body: JSON.stringify({ source: "google_search", query: query.trim(),
params: { num: 5, gl: "us", hl: "en" } }),
});
} catch {
throw new Error("Search outcome unknown. Check FlashData History before retrying.");
}
if (!response.ok) {
throw Object.assign(new Error("Search failed: HTTP " + response.status), {
status: response.status, retryAfter: response.headers.get("retry-after"),
});
}
const data = await response.json();
if (data.status !== "done" || !Array.isArray(data.results)) {
throw new Error("Search did not finish. Check FlashData History.");
}
const seen = new Set();
const sources = [];
for (const [index, item] of (data.results[0]?.organic ?? []).entries()) {
let url;
try { url = new URL(item.link); } catch { continue; }
if (!["https:", "http:"].includes(url.protocol) || seen.has(item.link)) continue;
seen.add(item.link);
sources.push({ rank: item.position ?? index + 1, title: item.title ?? item.link,
url: item.link, snippet: item.snippet ?? "" });
}
return { query: query.trim(), sources, usage: data.usage,
retrievedAt: new Date().toISOString() };
}2. Tambahkan backend lokal
Simpan sebagai server.mjs di samping search.mjs. GET /search? q =... memanggil fungsi; GET / melayani formulir Anda akan membuat berikutnya. Server hanya mendengarkan 127.0.0.1.
// server.mjs — local demo; keep your existing app's authentication in production.
import { createServer } from "node:http";
import { readFile } from "node:fs/promises";
import { searchWeb } from "./search.mjs";
createServer(async (req, res) => {
const url = new URL(req.url, "http://127.0.0.1:8787");
res.setHeader("Cache-Control", "no-store");
try {
if (req.method === "GET" && url.pathname === "/") {
const html = await readFile(new URL("./index.html", import.meta.url));
res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
return res.end(html);
}
if (req.method !== "GET" || url.pathname !== "/search") {
res.writeHead(404); return res.end("Not found");
}
const result = await searchWeb(url.searchParams.get("q"));
res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify(result));
} catch (error) {
if (error.retryAfter) res.setHeader("Retry-After", error.retryAfter);
res.writeHead(error.status ?? 502, { "Content-Type": "application/json" });
res.end(JSON.stringify({ error: error.message }));
}
}).listen(8787, "127.0.0.1", () => console.log("Open http://127.0.0.1:8787"));3. Tampilkan hasil pada aplikasi Anda
Simpan sebagai index.html dalam folder yang sama. Formulir ini menangani pemuatan, hasil kosong dan kesalahan. Ini memanggil backend Anda dan memasukkan snippet sebagai teks, jadi bukan kunci API ataupun eksternal HTML mencapai halaman.
<!doctype html>
<html lang="en">
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Web search</title>
<h1>Search the web</h1>
<form id="search">
<label>Query <input name="q" required maxlength="500" value="battery recycling research"></label>
<button>Search</button>
</form>
<p id="status" role="status"></p>
<ol id="results"></ol>
<script type="module">
const form = document.querySelector("#search");
const status = document.querySelector("#status");
const results = document.querySelector("#results");
form.addEventListener("submit", async (event) => {
event.preventDefault();
form.querySelector("button").disabled = true;
results.replaceChildren(); status.textContent = "Searching…";
try {
const q = new FormData(form).get("q");
const response = await fetch("/search?q=" + encodeURIComponent(q));
const data = await response.json();
if (!response.ok) {
const retryAfter = response.headers.get("Retry-After");
throw new Error(data.error + (retryAfter ? " · Retry-After: " + retryAfter : ""));
}
for (const source of data.sources) {
const li = document.createElement("li");
const link = document.createElement("a");
link.href = source.url; link.textContent = source.title;
const excerpt = document.createElement("p");
excerpt.textContent = source.snippet;
li.append(link, excerpt); results.append(li);
}
const credits = data.usage?.credits ?? "not reported";
status.textContent = (data.sources.length
? data.sources.length + (data.sources.length === 1 ? " source" : " sources")
: "No matching pages. Try a broader query.") + " · Credits used: " + credits;
} catch (error) { status.textContent = error.message; }
finally { form.querySelector("button").disabled = false; }
});
</script>
</html>4. Jalankan pencarian pertama Anda
Jalankan dari flashdata-search-demo di terminal di mana Anda mengatur kunci. Buka URL dan klik Cari sekali. Setiap kirim membuat kuiri yang dibayar; membuka halaman atau mengedit masukan tidak membuat apapun. Menghentikan server lokal dengan Ctrl + C ketika selesai.
- Masukkan topik spesifik, seperti laju pemulihan daur ulang baterai.
- Berharap judul terkait, snippet dan kredit dikembalikan dalam usage.credits. Hasil bervariasi; nol sumber adalah pencarian selesai yang valid.
node server.mjshttp://127.0.0.1:8787Hasil aplikasi Anda menerima
(Dalam bentuk) lafal ayat ini menjadi Haal atau kata keterangan keadaan bagi Dhamir yang terkandung di dalam lafal Iqra '. URLs dan penggunaan di bawah ini adalah ilustratif. Sebuah pencarian mengembalikan snippet dan link. Gunakan pembaca halaman ketika fitur Anda memerlukan teks halaman penuh.
{
"query": "battery recycling research",
"sources": [
{
"rank": 1,
"title": "Example source",
"url": "https://example.org/research",
"snippet": "A returned search excerpt."
}
],
"usage": {
"credits": 0.02
},
"retrievedAt": "2026-11-04T00:00:00.000Z"
}Pakai ulang pencarian dalam suatu alat agen
Opsional: simpan search-tool.mjs di samping search.mjs. Pelari hanya menerima search_web dan kueri. Buat satu pelari per tugas dan tetap di atas model penukaran tugas itu; batas percobaan maxCalls, termasuk usaha gagal. Ini tidak menetapkan batas pengeluaran kredit.
// search-tool.mjs — one runner per task, reused across its model turns.
import { searchWeb } from "./search.mjs";
export const searchTool = {
name: "search_web",
description: "Find ranked web URLs and snippets for a focused query.",
inputSchema: {
type: "object", additionalProperties: false,
properties: { query: { type: "string", minLength: 1, maxLength: 500 } },
required: ["query"],
},
};
export function createSearchToolRunner({ maxCalls = 2 } = {}) {
if (!Number.isSafeInteger(maxCalls) || maxCalls < 1) {
throw new Error("maxCalls must be a positive integer.");
}
let attempts = 0;
return async function runTool(name, args) {
if (name !== searchTool.name) throw new Error("Unknown tool: " + name);
if (!args || typeof args !== "object" || Array.isArray(args) ||
Object.keys(args).some(key => key !== "query") ||
typeof args.query !== "string" || !args.query.trim() || args.query.length > 500) {
throw new Error("Expected only query: a string of 1–500 characters.");
}
if (attempts >= maxCalls) throw new Error("Search call limit reached for this task.");
attempts++; // Reserve before awaiting; a failed attempt still counts.
return searchWeb(args.query);
};
}Coba alat secara langsung
Simpan tool-demo.mjs dalam flashdata-search-demo, kemudian jalankan perintah di bawah dari folder dengan kunci API yang sama. Pemeriksaan opsional ini membuat satu query FlashData tambahan tanpa memanggil sebuah model. Mengharapkan JSON dengan kueri, sumber, penggunaan dan retrievedAt - bentuk hasil yang sama dengan formulir.
// tool-demo.mjs — one direct tool call; no model-provider dependency.
import { createSearchToolRunner, searchTool } from "./search-tool.mjs";
if (process.argv.length !== 3) {
console.error('Usage: node tool-demo.mjs "your search query"');
process.exit(1);
}
const runTool = createSearchToolRunner({ maxCalls: 1 });
const result = await runTool(searchTool.name, { query: process.argv[2] });
console.log(JSON.stringify(result, null, 2));node tool-demo.mjs "battery recycling research"Hubungkan ke model Anda
Latihan demo fungsi alat. Kerangka kerja Anda menyediakan koneksi model dan loop pesan. Cari kembali link dan snippet; membaca halaman yang dipilih sebelum menggunakan isi lengkap mereka dalam sebuah jawaban. Untuk melanjutkan atau didistribusikan tugas, pertahankan jumlah dan hasil percobaan dengan tugas ID.
- Register searchTool.name, deskripsi dan inputSchema menggunakan format definisi kerangka kerja Anda. Simpan kunci API di lingkungan backend.
- Pada awal tugas, panggil createSearchToolRunner ({ maxCalls: 2 }). Untuk setiap panggilan alat model, parse argumen JSON nya dan lulus nama dan parsed objek ke pelari yang sama. Tolak JSON yang tidak sah sebelum pengiriman.
- Kembalikan hasil JSON ke model sebagai hasil alat dengan panggilan asli ID. Menjaga sources[].url untuk kutipan. Jika eksekusi gagal atau mencapai batas, kembalikan error; jangan buat pelari baru untuk mencobanya kembali.
Menangani kegagalan dan kapal itu
Untuk penyebaran, pindahkan /search di belakang tanda aplikasi Anda masuk dan per- batas pengguna. Simpan kunci API dalam konfigurasi server, pertahankan penggunaan dengan permintaan dan buat isi eksternal sebagai teks. Realtime cocok untuk bentuk interaktif ini; gunakan asinc untuk pekerjaan latar belakang.
| Situasi | Perilaku app |
|---|---|
| ERR_MODULE_NOT_FOUND / ENOENT | Simpan semua berkas dalam flashdata-search- demo dan jalankan dari folder itu. Simpan index.html sebelum membuka halaman. |
| EADDRINUSE | Port 8787 dikuasai. Hentikan proses demo sebelumnya sebelum memulai proses lain. |
| Batas panggilan pencarian tercapai | Tugas itu digunakan untuk usaha yang diperbolehkan. Selesai dengan bukti dikumpulkan atau melaporkan limit; membuat pelari baru akan me-reset hitungannya. |
| Hasil kosong | Tampilkan keadaan kosong dan biarkan pengguna menyempurnakan permintaan; jangan coba secara otomatis. |
| 401 / 403 / 402 | Periksa kunci server, izin google_search dan kredit rekening. |
| 429 | Tunggu Retry-After ketika diberikan; permintaan batas per pengguna sebelum memanggil FlashData. |
| Galat waktu / jaringan | Tunjukkan hasil yang tidak pasti. Inspeksi History sebelum mengirim kuiri dibayar yang sama lagi. |