Przejdź do treści
PL
Uzyskaj klucz API
Przeglądaj dokumentację

Poradniki

Dodaj wyszukiwanie do aplikacji

Zbuduj działający formularz wyszukiwania, trzymaj klawisz API na swoim tle i ponownie używaj tej samej funkcji wyszukiwania w narzędziu agenta.

Na tej stronie

Co zbudujesz?

Lokalny formularz wyszukiwania z rankingu linków, snippetów i wykorzystania kredytu. Wymaga Node.js 22 +, klucza z pozwoleniem google_search i dostępnych kredytów. Nie są potrzebne żadne pakiety npm. Opcjonalna sekcja agenta ponownie używa tej samej funkcji backend.

Zapisz w flashdata- search- demoCel
search.mjsDzwoni FlashData z tyłu; współdzielony przez formularz i narzędzie agenta.
server.mjsPodaje lokalną stronę i punkt końcowy GET /search.
index.htmlWyświetla źródła, puste wyniki i błędy.
Bash lub PowerShell · utworzyć projekt
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Ustaw klawisz API

Ponowne użycie FLASHDATA_API_KEY, jeśli jest już ustawione. W przeciwnym razie użyj ukrytego sygnału poniżej w terminalu, który uruchomi kod. Agent może załadować tę samą zmienną ze swojego tajnego sklepu.

Ustaw klucz
# 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. Utwórz funkcję wyszukiwania

Zapisz jako search.mjs w folderze projektu. Jedno połączenie zwraca do pięciu wyników internetowych, ich URLs i rzeczywiste wykorzystanie. Funkcja waliduje wejście, zachowuje kolejność wyników, usuwa duplikat URLs i zatrzymuje klucz z zwracanych danych. Limit znaków 500- to wybór aplikacji.

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. Dodaj lokalny backend

Zapisz jako server.mjs obok search.mjs. GET /search? q =... wywołuje funkcję; GET / serwuje formę, którą będziesz tworzyć dalej. Serwer słucha tylko 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. Wyświetl wyniki w aplikacji

Zapisz jako index.html w tym samym katalogu. Ten formularz obsługuje ładowanie, puste wyniki i błędy. Wywołuje Twój backend i wkłada wyszczerbienia jako tekst, więc ani klucz API, ani zewnętrzny HTML nie dociera do strony.

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. Uruchom swoje pierwsze wyszukiwanie

Uruchom z flashdata- search- demo w terminalu, gdzie ustawić klucz. Otwórz URL i kliknij Wyszukaj raz. Każdy submit wykonuje płatne zapytanie; otwieranie strony lub edycja wejścia nie powoduje żadnych. Zatrzymać lokalny serwer za pomocą Ctrl + C po zakończeniu.

  1. Należy podać konkretny temat, taki jak wskaźniki odzysku akumulatorów.
  2. Oczekuj połączonych tytułów, snippetów i kredytów zwróconych w usage.credits. Wyniki różnią się; zerowe źródła to poprawne zakończone wyszukiwanie.
W flashdata- search- demo · utrzymać ten terminal uruchomiony
node server.mjs
Otwórz w przeglądarce
http://127.0.0.1:8787

Wynik otrzymywania aplikacji

Kształt skrócony; URLs i zastosowanie poniżej są ilustracyjne. Wyszukiwarka zwraca snippety i linki. Użyj czytnika stron, gdy Twoja funkcja wymaga pełnego tekstu strony.

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"
}

Ponownie użyj wyszukiwania w narzędziu agenta

Opcjonalnie: zapisać search-tool.mjs obok search.mjs. Biegacz akceptuje tylko search_web i jego zapytanie. Utwórz jednego biegacza na zadanie i utrzymaj go na zakrętach modelu zadania; ograniczenia maxCalls próby wyszukiwania, w tym nieudane próby. Nie określa ona limitu wydatków na kredyty.

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);
  };
}

Spróbuj bezpośrednio z narzędziem

Zapisz tool-demo.mjs w flashdata- search- demo, a następnie uruchom poniższe polecenie z tego folderu przy pomocy tego samego klucza API. Ten opcjonalny sprawdzanie sprawia, że jeden dodatkowy FlashData zapytanie bez wywołania modelu. Oczekuj JSON z zapytaniem, źródłami, użyciem i retrievedAt - ten sam kształt rezultatu co formularz.

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));
Uruchom raz z flashdata- search- demo
node tool-demo.mjs "battery recycling research"

Podłącz go do swojego modelu

Demo wykonuje funkcję narzędzia. Twoje ramy dostarczają wzorcowe połączenie i pętlę wiadomości. Wyszukiwanie zwraca linki i snippety; przeczytaj wybrane strony przed użyciem ich pełnej zawartości w odpowiedzi. Dla zadań wznowionych lub rozprowadzanych, kontynuować liczbę prób i wyniki z zadaniem ID.

  1. Zarejestruj searchTool.name, description i inputSchema w formacie definicji narzędzi swojego frameworka. Przechowuj klucz API w środowisku backendu.
  2. Na początku zadania, zadzwoń do createSearchToolRunner ({ maxCalls: 2 }). Dla każdego modelu wywołania narzędzia, przeanalizuj jego argumenty JSON i podaj nazwę i obiekt przeforsowany temu samemu biegaczowi. Przed wysyłką należy odrzucić niepoprawny JSON.
  3. JSON zwraca do modelu jako wynik narzędzia przy pomocy oryginalnego wywołania ID. Zachowaj sources[].url na cytaty. Jeśli wykonanie nie powiedzie się lub osiągnie limit, zwróć błąd; nie twórz nowego biegacza, aby go ponownie wypróbować.

Uszkodzenie obsługi i wysłać go

Przy wdrożeniu zabezpiecz /search logowaniem do aplikacji i limitami na użytkownika. Przechowuj klucz API w konfiguracji serwera, zapisuj zużycie z żądaniem i wyświetlaj treści zewnętrzne jako tekst. Realtime pasuje do tego interaktywnego formularza; do pracy w tle używaj async.

SytuacjaZachowanie aplikacji
ERR_MODULE_NOT_FOUND / ENOENTZachowaj wszystkie pliki w flashdata- search- demo i uruchom z tego folderu. Zapisz index.html przed otwarciem strony.
EADDRINUSEPort 8787 jest zajęty. Zatrzymaj swój wcześniejszy proces demo przed rozpoczęciem kolejnego.
Osiągnięty limit wyszukiwania połączeńZadanie wykorzystało swoje dozwolone próby. Zakończ zbierane dowody lub zgłoś limit; utworzenie nowego biegacza zresetowałoby liczbę.
Puste wynikiPokaż pusty stan i pozwól użytkownikowi poprawić zapytanie; nie próbuj ponownie automatycznie.
401 / 403 / 402Sprawdź klucz serwera, pozwolenie google_search i kredyty na konto.
429Poczekaj na Retry-After, gdy jest dostępny; przed wywołaniem FlashData należy ograniczyć żądania użytkownika.
Błąd czasu / sieciPokaż niepewny wynik. Sprawdź History przed wysłaniem tego samego zapytania.