दस्तावेज़ देखें
गाइड
एक कार्य खोज फ़ॉर्म का निर्माण करें, अपने बैकएंड पर API कुंजी को रखें और एक एजेंट टूल में उसी खोज फ़ंक्शन का पुन: उपयोग करें।
इस पेज पर
आप क्या करेंगे?
स्थानिक लिंक, स्निपेट्स और क्रेडिट उपयोग के साथ एक स्थानीय खोज फॉर्म। Node.js 22+, google_search अनुमति और उपलब्ध क्रेडिट के साथ एक कुंजी की आवश्यकता है। नहीं npm संकुल की आवश्यकता है। वैकल्पिक एजेंट अनुभाग उसी बैकएंड फ़ंक्शन का पुन: उपयोग करता है।
| Flashdata-search-demo में सहेजें | उद्देश्य |
|---|---|
| search.mjs | बैकएंड से FlashData को कॉल करता है; फॉर्म और एजेंट टूल द्वारा साझा किया गया। |
| server.mjs | स्थानीय पृष्ठ और GET /search समापन बिंदु को बचाता है। |
| index.html | स्रोत, खाली परिणाम और त्रुटियों को प्रदर्शित करता है। |
node --version
mkdir flashdata-search-demo
cd flashdata-search-demoअपने API कुंजी सेट करें
यदि पहले से ही सेट किया गया है तो FLASHDATA_API_KEY का पुन: उपयोग करें। अन्यथा टर्मिनल में नीचे छिपे हुए संकेत का उपयोग करता है जो कोड चला जाएगा। एक एजेंट अपने गुप्त स्टोर से एक ही चर को लोड कर सकता है।
# 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. खोज समारोह बनाएँ
अपने प्रोजेक्ट फ़ोल्डर में search.mjs के रूप में सहेजें। एक कॉल पांच वेब परिणामों तक लौटता है, उनके URLs और वास्तविक उपयोग। फ़ंक्शन इनपुट को मान्य करता है, परिणाम ऑर्डर को संरक्षित करता है, डुप्लिकेट URLs को हटा देता है और वापस किए गए डेटा से कुंजी रखता है। 500-character सीमा एक ऐप विकल्प है।
// 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. स्थानीय बैकएंड जोड़ें
search.mjs के बगल में server.mjs के रूप में सहेजें। GET /search?q=... फ़ंक्शन को कॉल करता है; GET/ वह फॉर्म है जिसे आप अगले बना सकते हैं। सर्वर केवल 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. अपने ऐप में परिणाम प्रदर्शित करें
उसी फ़ोल्डर में index.html के रूप में सहेजें। यह फॉर्म लोड हो रहा है, खाली परिणाम और त्रुटियों को संभालता है। यह आपके बैकेंड को कॉल करता है और स्निपेट्स को टेक्स्ट के रूप में सम्मिलित करता है, इसलिए न तो API कुंजी और न ही बाहरी 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. अपनी पहली खोज चलायें
टर्मिनल जहां आप कुंजी सेट में flashdata-search-demo से भागो। URL खोलें और एक बार खोज पर क्लिक करें। प्रत्येक जमा एक भुगतान क्वेरी बनाता है; पृष्ठ खोलने या इनपुट संपादन कोई नहीं बनाता है। जब समाप्त हो जाता है तो Ctrl+C के साथ स्थानीय सर्वर को रोकें।
- बैटरी रीसाइक्लिंग वसूली दरों जैसे विशिष्ट विषय दर्ज करें।
- संबद्ध शीर्षकों, स्निपेट्स और क्रेडिट्स को usage.credits में वापस लेने की उम्मीद है। परिणाम भिन्न होते हैं; शून्य स्रोत एक वैध पूर्ण खोज है।
node server.mjshttp://127.0.0.1:8787जिसके परिणामस्वरूप आपका ऐप प्राप्त होता है
संक्षिप्त आकार; URLs और नीचे उपयोग illustrative हैं। एक खोज रिटर्न स्निपेट्स और लिंक देता है। जब आपकी सुविधा को पूर्ण पृष्ठ पाठ की आवश्यकता होती है तो एक पृष्ठ रीडर का उपयोग करें।
{
"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"
}एक एजेंट टूल में खोज का पुन: उपयोग करें
वैकल्पिक: search-tool.mjs को search.mjs के बगल में बचाओ। धावक केवल search_web और इसके क्वेरी को स्वीकार करता है। प्रति कार्य एक रनर बनाएं और उस कार्य के मॉडल में बदलाव करें; maxCalls सीमा ने असफल प्रयासों सहित खोजों का प्रयास किया। यह क्रेडिट खर्च करने की सीमा निर्धारित नहीं करता है।
// 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);
};
}सीधे टूल आज़माएं
Flashdata-search-demo में tool-demo.mjs सेव करें, फिर उसी API कुंजी के साथ उस फ़ोल्डर से नीचे कमांड चलाएं। यह वैकल्पिक चेक एक मॉडल को बुलाए बिना एक अतिरिक्त FlashData क्वेरी बनाता है। क्वेरी, सूत्रों, उपयोग और retrievedAt के साथ JSON का चयन करें- फॉर्म के समान परिणाम आकार।
// 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"इसे अपने मॉडल से कनेक्ट करें
डेमो टूल फंक्शन का प्रयोग करता है। आपका ढांचा मॉडल कनेक्शन और संदेश लूप की आपूर्ति करता है। रिटर्न लिंक और स्निपेट्स खोजें; उत्तर में अपनी पूरी सामग्री का उपयोग करने से पहले चयनित पृष्ठों को पढ़ें। फिर से शुरू या वितरित कार्यों के लिए, कार्य ID के साथ प्रयास गिनती और परिणाम जारी रखता है।
- अपने ढांचे के टूल-डेफिनिशन प्रारूप का उपयोग करके searchTool.name, विवरण और inputSchema रजिस्टर करें। बैकएंड वातावरण में API कुंजी रखें।
- कार्य प्रारंभ में, createSearchToolRunner ({ maxCalls: 2 }) को कॉल करें। प्रत्येक मॉडल टूल कॉल के लिए, अपने JSON तर्कों को पार्स करें और उस समान धावक को नाम और पार्सेड ऑब्जेक्ट पास करें। प्रेषक से पहले JSON को अस्वीकार करें।
- JSON को लौटाने के परिणामस्वरूप मॉडल को मूल कॉल ID के साथ एक टूल परिणाम के रूप में जाना जाता है। संरक्षण sources[].url उद्धरण के लिए। यदि निष्पादन विफल हो जाता है या सीमा तक पहुंचता है, तो त्रुटि को वापस कर देता है; इसे पुनः प्राप्त करने के लिए एक नया धावक नहीं बनाता है।
असफलताओं को संभालना और उसे जहाज करना
तैनाती के लिए, अपने आवेदन के साइन-इन और प्रति उपयोगकर्ता सीमाओं के पीछे /search को स्थानांतरित करें। सर्वर विन्यास में API कुंजी रखें, अनुरोध के साथ उपयोग को बनाए रखें और पाठ के रूप में बाहरी सामग्री प्रदान करें। Realtime इस इंटरैक्टिव रूप के लिए उपयुक्त है; पृष्ठभूमि के काम के लिए async का उपयोग करें।
| स्थिति | ऐप व्यवहार |
|---|---|
| ERR_MODULE_NOT_FOUND / ENOENT | सभी फ़ाइलों को flashdata-search-demo में रखें और उस फ़ोल्डर से चलाएं। पृष्ठ खोलने से पहले index.html को सेव करें। |
| EADDRINUSE | पोर्ट 8787 पर कब्जा कर लिया गया है। शुरू करने से पहले अपनी पहले की डेमो प्रक्रिया को रोकें। |
| खोज कॉल सीमा तक पहुंच गई | कार्य ने अपने अनुमत प्रयासों का इस्तेमाल किया। एकत्रित साक्ष्यों के साथ समाप्त करें या सीमा की रिपोर्ट करें; एक नया धावक बनाना गिनती को रीसेट करेगा। |
| खाली परिणाम | एक खाली स्थिति दिखाएं और उपयोगकर्ता को क्वेरी को परिष्कृत करने दें; स्वचालित रूप से पुनः प्रयास न करें। |
| 401 / 403 / 402 | सर्वर कुंजी, google_search अनुमति और खाता क्रेडिट की जाँच करें। |
| 429 | जब प्रदान की जाती है तो Retry-After के लिए प्रतीक्षा करें; FlashData को कॉल करने से पहले प्रति उपयोगकर्ता को अनुरोध सीमित करें। |
| टाइमआउट / नेटवर्क त्रुटि | अनिश्चित परिणाम दिखाएं। उसी भुगतान क्वेरी को फिर से भेजने से पहले History का निरीक्षण करें। |