Salta al contenuto
IT
Ottieni la chiave API
Sfoglia la documentazione

Guide

Aggiungi ricerca a un'applicazione

Costruire un modulo di ricerca di lavoro, mantenere la chiave API sul backend e riutilizzare la stessa funzione di ricerca in uno strumento agente.

In questa pagina

Che cosa costruirete

Un modulo di ricerca locale con link classificati, frammenti e utilizzo del credito. Richiede Node.js 22+, una chiave con il permesso google_search e i crediti disponibili. Non sono necessari pacchetti npm. La sezione agente opzionale riutilizza la stessa funzione di backend.

Salva in flashdata-search-demoOggetto
search.mjsChiama FlashData dal backend; condiviso dallo strumento forma e agente.
server.mjsServe la pagina locale e il punto finale GET /search.
index.htmlVisualizza fonti, risultati e errori vuoti.
Bash o PowerShell · creare il progetto
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Impostare il tasto API

Riutilizzare FLASHDATA_API_KEY se già impostato. Altrimenti utilizzare il prompt nascosto qui sotto nel terminale che eseguirà il codice. Un agente può caricare la stessa variabile dal suo negozio segreto.

Impostare la chiave
# 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. Creare la funzione di ricerca

Salvare come search.mjs nella cartella del progetto. Una chiamata restituisce fino a cinque risultati web, il loro URLs e l'utilizzo effettivo. La funzione convalida l'ingresso, conserva l'ordine dei risultati, rimuove il duplicato URLs e tiene la chiave fuori dei dati restituiti. Il limite 500-character è una scelta di app.

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. Aggiungi un backend locale

Salvare come server.mjs accanto a search.mjs. GET /search?q=... chiama la funzione; GET / serve il modulo che creerai dopo. Il server ascolta solo su 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. Visualizza i risultati nella tua app

Salvare come index.html nella stessa cartella. Questo modulo gestisce il carico, i risultati vuoti e gli errori. Chiama il tuo backend e inserisce i frammenti come testo, così né il tasto API né HTML esterno raggiunge la pagina.

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. Eseguire la prima ricerca

Eseguire da flashdata-search-demo nel terminale in cui si imposta la chiave. Aprire la URL e fare clic su Cerca una volta. Ogni presentazione fa una domanda a pagamento; l'apertura della pagina o la modifica dell'ingresso non ne fa. Interrompere il server locale con Ctrl+C al termine.

  1. Inserire un argomento specifico, come i tassi di recupero del riciclo della batteria.
  2. Aspettatevi titoli collegati, frammenti e i crediti restituiti in usage.credits. I risultati variano; zero fonti è una ricerca completa valida.
In flashdata-search-demo · mantenere questo terminale in esecuzione
node server.mjs
Apri il tuo browser
http://127.0.0.1:8787

Il risultato che la tua app riceve

Forma abortita; URLs e l'utilizzo qui sotto sono illustrativi. Una ricerca restituisce frammenti e link. Utilizzare un lettore di pagina quando la funzione ha bisogno del testo di pagina completa.

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

Riutilizzare la ricerca in uno strumento agente

Opzionale: salvare search-tool.mjs accanto a search.mjs. Il corridore accetta solo search_web e la sua query. Creare un corridore per compito e tenerlo attraverso le curve del modello di quell'attività; maxCalls limita le ricerche tentate, compresi i tentativi falliti. Non imposta un limite di spesa di credito.

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

Prova direttamente lo strumento

Salvare tool-demo.mjs in flashdata-search-demo, quindi eseguire il comando qui sotto da quella cartella con la stessa chiave API. Questo controllo facoltativo rende una domanda aggiuntiva FlashData senza chiamare un modello. Aspettatevi JSON con query, sorgenti, utilizzo e retrievedAt—la stessa forma di risultato del modulo.

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));
Esegui una volta da flashdata-search-demo
node tool-demo.mjs "battery recycling research"

Collegalo al tuo modello

La demo esercita la funzione di strumento. Il vostro quadro fornisce il modello di connessione e loop di messaggi. Ricerca restituisce i link e snippets; leggere le pagine selezionate prima di utilizzare il loro contenuto completo in una risposta. Per le attività riprese o distribuite, persistono il conteggio dei tentativi e i risultati con l'attività ID.

  1. Registrare searchTool.name, descrizione e inputSchema utilizzando il formato di definizione degli strumenti del framework. Tenere il tasto API nell'ambiente backend.
  2. All'inizio del compito, chiama createSearchToolRunner ({ maxCalls: 2 }). Per ogni chiamata di strumento di modello, parse i suoi argomenti JSON e passare il nome e l'oggetto parsed a quello stesso corridore. Rifiutare JSON non valido prima della spedizione.
  3. Riportare il risultato JSON al modello come risultato utensile con la chiamata originale ID. Conservare sources[].url per le citazioni. Se l'esecuzione fallisce o raggiunge il limite, restituire l'errore; non creare un nuovo corridore per riprovare.

Maneggiare guasti e spedirlo

Per l'implementazione, spostare /search dietro i limiti di accesso e per utente della vostra applicazione. Mantenere il tasto API nella configurazione del server, mantenere l'utilizzo con la richiesta e rendere il contenuto esterno come testo. Realtime è adatto a questa forma interattiva; utilizzare asincastro per il lavoro di sfondo.

SituazioneComportamento dell'app
ERR_MODULE_NOT_FOUND / ENOENTTenere tutti i file in flashdata-search-demo ed eseguire da quella cartella. Salvare index.html prima di aprire la pagina.
EADDRINUSEPort 8787 è occupato. Ferma il tuo precedente processo demo prima di iniziare un altro.
Limite di chiamata di ricerca raggiuntoIl compito ha usato i suoi tentativi consentiti. Terminare con le prove raccolte o segnalare il limite; la creazione di un nuovo corridore avrebbe resettato il conteggio.
Risultati vuotiMostrare uno stato vuoto e lasciare che l'utente raffina la query; non riprovare automaticamente.
401 / 403 / 402Controllare la chiave del server, il permesso google_search e i crediti dell'account.
429Attendere Retry-After quando fornito; limitare le richieste per utente prima di chiamare FlashData.
Timeout / errore di reteMostra un risultato incerto. Ispezionare History prima di inviare nuovamente la stessa domanda pagata.