Langkau ke kandungan
MS
Dapatkan kunci API
Semak dokumentasi

Panduan

Tak menambah pencarian ke aplikasi

Bina formulir pencarian kerja, simpan kunci API pada backend anda, dan gunakan kembali fungsi pencarian yang sama dalam alat agen.

Pada halaman ini

Apa yang akan kau bangun

OGDOS sebuah bentuk pencarian lokal dengan link ranking, snippet dan penggunaan kredit. Keanquires Node.js 22+, sebuah kunci dengan izin google_search dan kredit yang tersedia. Paket npm tidak diperlukan. Bagian agen opsional dogano menggunakan kembali fungsi backend yang sama.

Simpan dalam flashdata-search-demoTujuan
search.mjsNama dana FlashData dari backend; dibagikan oleh bentuk dan alat agen.
server.mjsWaquis melayani halaman lokal dan GET /search titik akhir.
index.htmlWhats Displays sources, hasil kosong dan errors.
Bash OR atau ORANG PowerShell Keluarkan proyek ini dari proyek
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Ketikkan kunci API anda

Gunakan kembali FLASHDATA_API_KEY jika sudah ditetapkan. Jika tidak, gunakan prom tersembunyi di bawah ini di terminal yang akan menjalankan kode. Agen agen bisa memuat variabel yang sama dari toko rahasianya.

Mematur kunci
# 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

1. Buat fungsi pencarian

Simpan sebagai search.mjs dalam folder projek Anda. Satu panggilan kembali mencapai lima hasil web, URLs dan penggunaan sebenarnya. Fungsi odefan menvalidasi input, menjaga urutan hasil, menghapus duplikasi URLs dan menjaga kunci keluar dari data yang dikembalikan. Batas karakter 500 adalah pilihan aplikasi.

search.mjs
// 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. Lubnan:

Simpan sebagai server.mjs di samping search.mjs. GET /search?q=... panggilan fungsi; GET / melayani bentuk yang akan Anda buat selanjutnya. Server ini hanya mendengarkan 127.0.0.1.

server.mjs
// 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 di aplikasi Anda

Simpan sebagai index.html dalam folder yang sama. Wiredia ini menangani pemuatan, hasil dan kesalahan kosong. Ini menyebut backend Anda dan menyisipkan snippet sebagai teks, sehingga baik kunci API maupun eksternal HTML tidak mencapai halaman.

index.html
<!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. Kau harus mencari

Lari dari flashdata-search-demo di terminal di mana Anda menetapkan kunci. Buka URL dan klik Search sekali. Setiap kiriman membuat pertanyaan terbayar; membuka halaman atau menyunting masukan tidak membuat apapun. XOVH menghentikan server lokal dengan Ctrl+C ketika selesai.

  1. Anda dapat memasukkan topik tertentu, seperti tingkat pemulihan daur ulang baterai.
  2. Terjangkakan gelar terkait, snippet dan kredit dikembalikan dalam usage.credits. Hasil bervariasi; nol sumber adalah pencarian yang valid selesai.
Dalam flashdata-search-demo · menjaga terminal ini berjalan
node server.mjs
Dibuka di dalam peramban Anda
http://127.0.0.1:8787

Hasil yang diterima oleh aplikasimu

Bentuk yang ada; Bahasa URLs dan penggunaan di bawah ini adalah ilustratif. MUKA DEFAAT Guna pembaca halaman bila fitur Anda membutuhkan teks halaman penuh.

GET /search?q=...
{
  "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"
}

Cari kembali pada alat agen

Opsional: simpan search-tool.mjs di samping search.mjs. Ia hanya menerima search_web dan pertanyaannya. Aquiza membuat satu pelari per tugas dan menyimpannya di seluruh putaran model tugas itu; maxCalls membatasi upaya pencarian, termasuk upaya yang gagal. Ini tidak menetapkan batas pengeluaran kredit.

flashdata-search-demo/search-tool.mjs
// 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);
  };
}

Cobalah alat itu secara langsung

Simpan tool-demo.mjs dalam flashdata-search-demo, kemudian jalankan arahan di bawah dari folder itu dengan kunci API yang sama. Semakan pilihan ini membuat satu pertanyaan FlashData tambahan tanpa memanggil model. Hasil yang dijangka ialah JSON dengan query, sources, usage dan retrievedAt—bentuk hasil yang sama seperti borang.

flashdata-search-demo/tool-demo.mjs
// 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));
Lari sekali dari flashdata-search-demo
node tool-demo.mjs "battery recycling research"

Hubungkan ke model Anda

Demo itu menjalankan fungsi alat. Rangka kerjamu membuat model koneksi dan loop pesan. Cari kembali link dan snippet; baca halaman yang dipilih sebelum menggunakan isi lengkap mereka dalam sebuah jawaban. Untuk melanjutkan atau mengedarkan tugas, terus lanjutkan hitungan percobaan dan hasil dengan tugas ID.

  1. Register searchTool.name, deskripsi dan inputSchema menggunakan format definisi-alat kerangka kerja Anda. Tetap jaga kunci API di lingkungan backend.
  2. Saat tugas dimulai, hubungi createSearchToolRunner({ maxCalls: 2 }). Untuk setiap model tool call, parse argumen JSON nya dan lulus nama dan parted objek ke pelari yang sama. Parameter tidak sah JSON sebelum pengiriman.
  3. Aventure hasil JSON ke model sebagai hasil alat dengan panggilan asli ID. Simpan sources[].url untuk kutipan. Jika eksekusi gagal atau mencapai batas, kembalikan kesalahan; jangan membuat pelari baru untuk mencobanya lagi.

Kegagalan penanganan dan kapal itu

Untuk penyebaran, pindahkan /search di belakang sign-in aplikasi Anda dan per-user batas. Wake kunci API dalam konfigurasi server, simpan penggunaan dengan permintaan dan buat konten eksternal sebagai teks. Realtime BAHASA interaktif ini cocok digunakan; gunakan async untuk pekerjaan latar belakang.

Situasi Orang AsingPerilaku Appa Aperia
ERR_MODULE_NOT_FOUND / ENOENTSimpan semua file dalam flashdata-search-demo dan jalankan dari folder itu. Simpan index.html sebelum membuka halaman.
EADDRINUSEPelabuhan 8787 diduduki. Hentikan proses demomu sebelumnya sebelum memulai yang lain.
batas panggilan pencarian vevany dicapaiTugas yang digunakan adalah upaya yang diperbolehkan. Finish dengan bukti yang dikumpulkan atau melaporkan batas; menciptakan pelari baru akan menetapkan ulang hitungan.
Hasil KosongTunjuk keadaan kosong dan biarkan pengguna menghaluskan pertanyaan; jangan coba lagi secara otomatis.
401 / 403 / 402Periksa kunci server, izin google_search dan kredit akun.
429Wait untuk Retry-After ketika disediakan; batas permintaan per pengguna sebelum memanggil FlashData.
Kesulitan jaringan/kesulitan Hadmasa Hadmasa Hadapan BBN / jaringanTunjukkan hasil yang tidak pasti. Periksa History sebelum mengirim pertanyaan berbayar yang sama lagi.