Saltar al contenido
ES
Obtener clave API
Explorar documentación

Guías

Añade búsqueda a una aplicación

Crea un formulario de búsqueda, conserva la clave API en el backend y reutiliza la misma función como herramienta de un agente.

En esta página

Lo que construirás

Un formulario de búsqueda local con enlaces clasificados, fragmentos y uso de crédito. Requiere Node.js 22+, una clave con permiso google_search y créditos disponibles. No se necesitan paquetes npm. La sección de agente opcional reutiliza la misma función de backend.

Guardar en flashdata-search-demoPropósito
search.mjsLlama FlashData desde el backend; compartido por la herramienta forma y agente.
server.mjsSirve la página local y el punto final GET /search.
index.htmlMuestra fuentes, resultados vacíos y errores.
Bash o PowerShell · crear el proyecto
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo

Establecer la tecla API

Reutilizar FLASHDATA_API_KEY si ya está establecido. De lo contrario, utilice el indicador oculto debajo en el terminal que ejecutará el código. Un agente puede cargar la misma variable de su tienda secreta.

Establecer la clave
# 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. Cree la función de búsqueda

Guardar como search.mjs en su carpeta de proyecto. Una llamada devuelve hasta cinco resultados web, su URLs y el uso real. La función valida la entrada, preserva el orden de resultado, elimina URLs duplicado y mantiene la clave fuera de los datos devueltos. El límite de 500-character es una opción de la aplicación.

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. Añadir un backend local

Guardar como server.mjs junto a search.mjs. GET /search?q=... llama a la función; GET / sirve el formulario que creará a continuación. El servidor escucha sólo en 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. Visualización de resultados en su aplicación

Guardar como index.html en la misma carpeta. Este formulario maneja la carga, los resultados vacíos y los errores. Llama su backend e inserta fragmentos como texto, así que ni el API clave o externa HTML llega a la página.

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. Ejecute su primera búsqueda

Ejecutar desde flashdata-search-demo en el terminal donde se establece la clave. Abra el URL y haga clic en Buscar una vez. Cada envío hace una consulta pagada; abrir la página o editar la entrada no hace ninguno. Detén el servidor local con Ctrl+C cuando esté terminado.

  1. Ingrese un tema específico, como las tasas de recuperación del reciclaje de baterías.
  2. Se espera que los títulos vinculados, los francos y los créditos devueltos en usage.credits. Los resultados varían; cero fuentes es una búsqueda válida completa.
En flashdata-search-demo · mantener este terminal funcionando
node server.mjs
Abra en su navegador
http://127.0.0.1:8787

El resultado que recibe su aplicación

Forma abreviada; URLs y el uso a continuación son ilustrativos. Una búsqueda devuelve fragmentos y enlaces. Utilice un lector de página cuando su característica necesite el texto completo de la página.

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

Reutilizar la búsqueda en una herramienta agente

Opcional: guardar search-tool.mjs junto a search.mjs. El corredor acepta solamente search_web y su consulta. Cree un corredor por tarea y manténgalo al otro lado de los giros modelo de esa tarea; maxCalls límites intento búsquedas, incluyendo intentos fallidos. No establece un límite de gasto de crédito.

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

Prueba la herramienta directamente

Guardar tool-demo.mjs en flashdata-search-demo, luego ejecutar el comando abajo de esa carpeta con la misma tecla API. Este cheque opcional hace una consulta adicional FlashData sin llamar a un modelo. Espere JSON con consulta, fuentes, uso y retrievedAt, la misma forma de resultado que el formulario.

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));
Ejecutar una vez desde flashdata-search-demo
node tool-demo.mjs "battery recycling research"

Conéctelo a tu modelo

La demo ejerce la función de la herramienta. Su marco proporciona la conexión modelo y el bucle de mensaje. Búsqueda devuelve enlaces y fragmentos; lee páginas seleccionadas antes de usar su contenido completo en una respuesta. Para tareas reanudadas o distribuidas, persiste el recuento de intentos y resultados con la tarea ID.

  1. Registre searchTool.name, descripción y inputSchema utilizando el formato de definición de herramientas de su marco. Mantenga la tecla API en el entorno de backend.
  2. Al inicio de la tarea, llame createSearchToolRunner({ maxCalls: 2 }). Para cada llamada de herramienta modelo, pare su JSON argumentos y pasar el nombre y objeto parsed a ese mismo corredor. Rechazar inválido JSON antes del envío.
  3. Devuelve el resultado JSON al modelo como resultado de la herramienta con la llamada original ID. Preserve sources[].url para citas. Si la ejecución falla o alcanza el límite, devuelve el error; no crea un nuevo corredor para reiniciarlo.

Maneja fallas y enviarlas

Para el despliegue, mueva /search detrás de los límites de registro y de usuario de su aplicación. Mantenga la tecla API en la configuración del servidor, mantenga el uso con la solicitud y renderice el contenido externo como texto. Realtime es adecuado a esta forma interactiva; use async para el trabajo de fondo.

SituaciónComportamiento de la aplicación
ERR_MODULE_NOT_FOUND / ENOENTMantenga todos los archivos en flashdata-search-demo y se ejecutan desde esa carpeta. Guardar index.html antes de abrir la página.
EADDRINUSEPort 8787 está ocupado. Detenga su proceso de demostración anterior antes de comenzar otro.
Nivel de búsqueda alcanzadoLa tarea utilizó sus intentos permitidos. Terminar con la evidencia recolectada o informar el límite; crear un nuevo corredor se restablecería el conteo.
Resultado de los empleadosMostrar un estado vacío y dejar que el usuario refina la consulta; no vuelva a entrar automáticamente.
401 / 403 / 402Compruebe la clave del servidor, permiso google_search y créditos de cuenta.
429Espere a Retry-After cuando se proporcione; limite las solicitudes por usuario antes de llamar a FlashData.
Timeout / error de redMuestra un resultado incierto. Inspecciona la historia antes de enviar la misma consulta pagada de nuevo.