Dokumentation durchsuchen
Anleitungen
Erstellen Sie ein funktionierendes Suchformular, behalten Sie den API-Schlüssel in Ihrem Backend und verwenden Sie die gleiche Suchfunktion in einem Agenten-Tool wieder.
Auf dieser Seite
Was du bauen wirst
Ein lokales Suchformular mit Ranglistenlinks, Snippets und Kreditnutzung. Erfordert Node.js 22+, einen Schlüssel mit google_search-Berechtigung und verfügbaren Credits. Es werden keine npm-Pakete benötigt. Der optionale Agent-Abschnitt verwendet dieselbe Backend-Funktion wieder.
| Speichern Sie in flashdata-search-demo | Zweck |
|---|---|
| search.mjs | Ruft FlashData aus dem Backend auf; geteilt durch das Formular- und Agenten-Tool. |
| server.mjs | Serviert die lokale Seite und den GET /search-Endpunkt. |
| index.html | Zeigt Quellen, leere Ergebnisse und Fehler an. |
node --version
mkdir flashdata-search-demo
cd flashdata-search-demoStellen Sie Ihren API-Schlüssel ein
FLASHDATA_API_KEY wiederverwenden, wenn bereits eingestellt. Verwenden Sie ansonsten die versteckte Eingabeaufforderung unten im Terminal, auf dem der Code ausgeführt wird. Ein Agent kann die gleiche Variable aus seinem geheimen Speicher laden.
# 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. Erstellen Sie die Suchfunktion
Speichern Sie als search.mjs in Ihrem Projektordner. Ein Aufruf gibt bis zu fünf Web-Ergebnisse, ihre URLs und tatsächliche Nutzung. Die Funktion validiert die Eingabe, bewahrt die Ergebnisreihenfolge, entfernt das Duplikat URLs und hält den Schlüssel aus den zurückgegebenen Daten heraus. Das 500-Zeichenlimit ist eine App-Wahl.
// 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. Hinzufügen eines lokalen Backends
Speichern Sie als server.mjs neben search.mjs. GET /search?q=... ruft die Funktion auf; GET / dient dem Formular, das Sie als nächstes erstellen werden. Der Server hört nur auf 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. Anzeigeergebnisse in Ihrer App
Speichern Sie als index.html im selben Ordner. Dieses Formular behandelt das Laden, leere Ergebnisse und Fehler. Es ruft Ihr Backend auf und fügt Snippets als Text ein, so dass weder der API-Schlüssel noch das externe HTML die Seite erreichen.
<!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. Führen Sie Ihre erste Suche aus
Führen Sie von flashdata-search-demo in dem Terminal aus, in dem Sie den Schlüssel eingestellt haben. Öffnen Sie den URL und klicken Sie einmal auf Suchen. Jeder eintrag macht eine bezahlte abfrage; das öffnen der seite oder das bearbeiten der eingabe macht keine. Stoppen Sie den lokalen Server mit Ctrl + C, wenn Sie fertig sind.
- Geben Sie ein bestimmtes Thema ein, z. B. die Rückgewinnungsrate von Batterien.
- Erwarten Sie verlinkte Titel, Snippets und die in usage.credits zurückgegebenen Credits. Die Ergebnisse variieren; Nullquellen ist eine gültige abgeschlossene Suche.
node server.mjshttp://127.0.0.1:8787Das Ergebnis, das Ihre App erhält
abgekürzte Form; URLs und die Verwendung unten sind illustrativ. Eine Suche gibt Snippets und Links zurück. Verwenden Sie einen Seitenleser, wenn Ihr Feature den Vollseitentext benötigt.
{
"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"
}Wiederverwendung der Suche in einem Agenten-Tool
Optional: Speichern Sie search-tool.mjs neben search.mjs. Der Läufer akzeptiert nur search_web und seine Abfrage. Erstellen Sie einen Läufer pro Aufgabe und halten Sie ihn über die Modellkurven dieser Aufgabe hinweg; maxCalls begrenzt die versuchten Suchanfragen, einschließlich fehlgeschlagener Versuche. Es setzt kein Limit für Kreditausgaben.
// 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);
};
}Probieren Sie das Tool direkt
Speichern Sie tool-demo.mjs in flashdata-search-demo und führen Sie dann den Befehl unten aus diesem Ordner mit dem gleichen API-Schlüssel aus. Diese optionale Überprüfung führt eine zusätzliche FlashData-Abfrage durch, ohne ein Modell aufzurufen. Erwarten Sie JSON mit Abfrage, Quellen, Nutzung und retrievedAt - die gleiche Ergebnisform wie das Formular.
// 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"Verbinden Sie es mit Ihrem Modell
Die Demo übt die Werkzeugfunktion aus. Ihr Framework liefert die Modellverbindung und Nachrichtenschleife. Suche gibt Links und Snippets zurück; Lesen Sie ausgewählte Seiten, bevor Sie den vollständigen Inhalt in einer Antwort verwenden. Beharren Sie bei fortgesetzten oder verteilten Aufgaben auf der Versuchszählung und den Ergebnissen mit der Aufgabe ID.
- Registrieren Sie searchTool.name, Beschreibung und inputSchema mit dem Tool-Definitionsformat Ihres Frameworks. Behalten Sie den API-Schlüssel in der Backend-Umgebung.
- Beim Aufgabenstart rufen Sie createSearchToolRunner({ maxCalls: 2 }) auf. Für jeden Modell-Toolaufruf analysieren Sie seine JSON-Argumente und übergeben Sie den Namen und das analysierte Objekt an denselben Läufer. Ablehnen ungültig JSON vor dem Versand.
- Geben Sie das JSON-Ergebnis als Werkzeugergebnis mit dem ursprünglichen Aufruf ID an das Modell zurück. sources[].url für Zitate aufbewahren. Wenn die Ausführung fehlschlägt oder das Limit erreicht, geben Sie den Fehler zurück; erstellen Sie keinen neuen Läufer, um ihn erneut zu versuchen.
Behandeln Sie Fehler und versenden Sie es
Bewegen Sie /search für die Bereitstellung hinter die Anmelde- und Benutzergrenzen Ihrer Anwendung. Behalten Sie den API-Schlüssel in der Serverkonfiguration, behalten Sie die Verwendung mit der Anforderung bei und stellen Sie externe Inhalte als Text dar. Realtime eignet sich für dieses interaktive Formular; Verwenden Sie async für Hintergrundarbeiten.
| Lage | App Verhalten |
|---|---|
| ERR_MODULE_NOT_FOUND / ENOENT | Bewahren Sie alle Dateien in Flashdata-Such-Demo auf und führen Sie aus diesem Ordner aus. Speichern Sie index.html, bevor Sie die Seite öffnen. |
| EADDRINUSE | Port 8787 ist besetzt. Beenden Sie Ihren früheren Demo-Prozess, bevor Sie einen anderen starten. |
| Suchanruflimit erreicht | Die Aufgabe nutzte ihre erlaubten Versuche. Beenden Sie die gesammelten Beweise oder melden Sie das Limit; Das Erstellen eines neuen Läufers würde die Zählung zurücksetzen. |
| Leerergebnisse | Zeigen Sie einen leeren Zustand an und lassen Sie den Benutzer die Abfrage verfeinern; versuchen Sie es nicht automatisch. |
| 401 / 403 / 402 | Überprüfen Sie den Serverschlüssel, die google_search-Berechtigung und die Kontogutschriften. |
| 429 | Warten Sie auf Retry-After, wenn Sie bereitgestellt werden; begrenzen Sie die Anforderungen pro Benutzer, bevor Sie FlashData anrufen. |
| Timeout / Netzwerkfehler | Zeigen Sie ein unsicheres Ergebnis. Überprüfen Sie History, bevor Sie die gleiche bezahlte Abfrage erneut senden. |