# Zoekopdracht toevoegen aan een toepassing

Bouw een werkend zoekformulier, houd de API-toets op uw backend, en hergebruik dezelfde zoekfunctie in een agent tool.

Canonische referentie: https://flashdata.dev/nl/docs/guides/search-in-an-app
Beoordeeld: 2026-11-05 door FlashData

<a id="prepare"></a>

## Wat je zult bouwen

Een lokaal zoekformulier met gerankte links, knipsels en kredietgebruik. Vereist Node.js 22+, een sleutel met google_search toestemming en beschikbare credits. Er zijn geen npm-pakketten nodig. De optionele agent sectie gebruikt dezelfde backend functie.

| Opslaan in flashdata-search-demo | Betreft |
| --- | --- |
| search.mjs | Belt FlashData van de backend; gedeeld door de vorm en agent tool. |
| server.mjs | Serveert de lokale pagina en GET /search eindpunt. |
| index.html | Toont bronnen, lege resultaten en fouten. |

### Bash of PowerShell · maak het project aan

```bash
node --version
mkdir flashdata-search-demo
cd flashdata-search-demo
```

- [Start de app](https://flashdata.dev/nl/docs/guides/search-in-an-app/reference.md#output)
- [Gebruik de functie in een agent](https://flashdata.dev/nl/docs/guides/search-in-an-app/reference.md#tool)
- [Nieuw bij de API?](https://flashdata.dev/nl/docs/guides/http-quickstart/reference.md)

<a id="authenticate"></a>

### Stel uw API-sleutel in

Hergebruik FLASHDATA_API_KEY indien reeds ingesteld. Anders gebruik je de verborgen prompt hieronder in de terminal die de code zal uitvoeren. Een agent kan dezelfde variabele laden vanuit zijn geheime winkel.

#### Bash

##### De sleutel instellen

```bash
# 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

##### De sleutel instellen

```powershell
# 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 flashdataSecureKey
```


- [API-sleutels](https://flashdata.dev/app/api-keys)
- [Proefgebruik en accountkoppeling](https://flashdata.dev/nl/docs/guides/agent-onboarding/reference.md)

<a id="run"></a>

## 1. Zoekfunctie aanmaken

Opslaan als search.mjs in uw projectmap. Eén oproep geeft maximaal vijf webresultaten, hun URLs en het werkelijke gebruik terug. De functie valideert invoer, behoudt resultaatvolgorde, verwijdert duplicaten URLs en houdt de sleutel uit de geretourneerde gegevens. De limiet van het 500-karakter is een appkeuze.

### search.mjs

```javascript
// 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() };
}
```


<a id="endpoint"></a>

## 2. Een lokale backend toevoegen

Opslaan als server.mjs naast search.mjs. GET /search?q=... roept de functie aan; GET/dient het formulier dat u hierna aanmaakt. De server luistert alleen op 127.0.0.1.

### server.mjs

```javascript
// 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"));
```


<a id="display"></a>

## 3. Resultaten weergeven in uw app

Opslaan als index.html in dezelfde map. Dit formulier behandelt laden, lege resultaten en fouten. Het roept uw backend en voegt knipsels als tekst, zodat noch de API sleutel noch externe HTML bereikt de pagina.

### index.html

```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>
```


<a id="output"></a>

## 4. Voer je eerste zoekopdracht uit

Uitvoeren van flashdata-search-demo in de terminal waar u de sleutel. Open de URL en klik eenmaal op zoeken. Elke submit maakt een betaalde query; het openen van de pagina of het bewerken van de invoer maakt geen. Stop de lokale server met Ctrl+C als deze klaar is.

1. Voer een specifiek onderwerp in, zoals de recycling van batterijen.
2. Verwacht gekoppelde titels, knipsels en de credits terug in usage.credits. Resultaten variëren; nul bronnen is een geldige voltooide zoekopdracht.

### In flashdata-search-demo · deze terminal draaiende houden

```bash
node server.mjs
```

### Openen in uw browser

```text
http://127.0.0.1:8787
```

- [De relevantie verbeteren](https://flashdata.dev/nl/docs/guides/google-search-guide/reference.md)
- [Verzoekgeschiedenis controleren](https://flashdata.dev/app/jobs)

<a id="expected"></a>

### Het resultaat dat uw app ontvangt

verkorte vorm; URLs en het gebruik hieronder zijn illustratief. Een zoekopdracht geeft knipsels en links terug. Gebruik een paginalezer wanneer uw functie de volledige paginatekst nodig heeft.

#### GET /search?q=...

```json
{
  "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"
}
```


<a id="tool"></a>

## Zoekopdracht hergebruiken in een hulpmiddel

Optioneel: bewaar search-tool.mjs naast search.mjs. De runner accepteert alleen search_web en zijn query. Creëer één runner per taak en houd het over de modeldraaiingen van die taak; maxCalls beperkt pogingen, inclusief mislukte pogingen. Het stelt geen limiet voor kredietuitgaven vast.

### flashdata-search-demo/search-tool.mjs

```javascript
// 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);
  };
}
```

- [Probeer het gereedschap direct](https://flashdata.dev/nl/docs/guides/search-in-an-app/reference.md#tool-test)
- [Verbind uw model](https://flashdata.dev/nl/docs/guides/search-in-an-app/reference.md#model-loop)
- [Gebruik je al een MCP host?](https://flashdata.dev/nl/docs/integrations/mcp-clients/reference.md)

<a id="tool-test"></a>

### Probeer het gereedschap direct

Sla tool-demo.mjs op in flashdata-search-demo en voer het commando hieronder uit vanuit die map met dezelfde API-sleutel. Deze optionele controle maakt een extra FlashData query zonder een model te bellen. Verwacht JSON met query, bronnen, gebruik en retrievedAt. Dezelfde resultaatvorm als het formulier.

#### flashdata-search-demo/tool-demo.mjs

```javascript
// 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));
```

#### Eenmaal uitvoeren van flashdata-search-demo

```bash
node tool-demo.mjs "battery recycling research"
```


<a id="model-loop"></a>

### Verbind het met uw model

De demo oefent de gereedschapsfunctie uit. Uw kader levert de modelverbinding en message loop. Zoeken geeft links en knipsels terug; lees geselecteerde pagina's voordat u de volledige inhoud ervan in een antwoord gebruikt. Voor hervatte of gedistribueerde taken, blijven het aantal pogingen en de resultaten met de taak ID.

1. Registreer searchTool.name, beschrijving en inputSchema met behulp van uw framework-tool-definition formaat. Houd de API sleutel in de backend omgeving.
2. Bij taakstart, bel createSearchToolRunner({ maxCalls: 2 }). Voor elke aanroep van het model gereedschap, ontleed zijn JSON argumenten en geef de naam en het ontleed object door aan dezelfde runner. Weiger ongeldig JSON voor verzending.
3. Geef het JSON-resultaat terug naar het model als resultaat van het gereedschap met de originele aanroep ID. Bewaar sources[].url voor citaten. Als de uitvoering mislukt of de limiet bereikt, geef dan de foutmelding terug; maak geen nieuwe runner aan om het opnieuw te proberen.

- [Terugkerende takenbestanden](https://flashdata.dev/nl/docs/guides/recurring-tasks/reference.md)
- [Onderzoek met aanhalingen](https://flashdata.dev/nl/docs/guides/google-youtube-research/reference.md)

<a id="verify"></a>

## Faalt en verscheep het

Voor de implementatie, verplaatsen /search achter de inlog- en per-gebruiker grenzen van uw applicatie. Houd de API-sleutel in serverconfiguratie, behoud het gebruik met het verzoek en render externe inhoud als tekst. Realtime is geschikt voor dit interactieve formulier; gebruik async voor achtergrondwerk.

| Situatie | App gedrag |
| --- | --- |
| ERR_MODULE_NOT_FOUND / ENOENT | Houd alle bestanden in flashdata-search-demo en rennen uit die map. Bewaar index.html voordat u de pagina opent. |
| EADDRINUSE | Port 8787 is bezet. Stop uw eerdere demo-proces voordat u een andere start. |
| Zoekopdrachtlimiet bereikt | De taak gebruikte zijn toegestane pogingen. Eindig met het verzamelde bewijs of rapporteer de limiet; het creëren van een nieuwe loper zou de telling resetten. |
| Lege resultaten | Een lege status tonen en laat de gebruiker de query verfijnen; probeer het niet automatisch opnieuw. |
| 401 / 403 / 402 | Controleer de serversleutel, google_search-machtiging en accountcredits. |
| 429 | Wacht op Retry-After wanneer dit wordt geleverd; limiet verzoeken per gebruiker voordat u FlashData aanroept. |
| Timeout / netwerkfout | Toon een onzekere uitkomst. Inspecteer History voordat u dezelfde betaalde zoekopdracht opnieuw verstuurt. |

- [Realtime of async?](https://flashdata.dev/nl/docs/reference/realtime-and-async/reference.md#choose)
- [Batch verzoeken](https://flashdata.dev/nl/docs/reference/batch-and-bulk/reference.md#batch)
- [Foutcodes en herhalingen](https://flashdata.dev/nl/docs/errors/reference.md#retries)
- [Productie-uitrol](https://flashdata.dev/nl/docs/guides/production-deployment/reference.md)
