Переглянути документацію
Посібники
Створіть робочу форму пошуку, зберігайте ключ API на задній панелі, і повторно використовуйте ту саму функцію пошуку в інструменті агента.
На цій сторінці
Що ви збудете
Місцева пошукова форма з рядовими посиланнями, хіппе та кредитним використанням. Вимагає Node.js 22+, ключ з дозволом google_search і доступні кредити. Пакети npm потрібні. В розділі Додаткового агента з’являється однакова функція зворотного зв’язку.
| Заощаджуйте в флешки-пошуку-демо | Мета |
|---|---|
| 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. Додати локальний бекенд
Заощаджуйте як server.mjs beside search.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. Запуск першого пошуку
Запуск з флешки-пошуку-демо в терміналі, де ви встановлюєте ключ. Відкрийте URL і натисніть кнопку Пошук один раз. Кожна подача робить оплачену запиту; відкриття сторінки або редагування вводу не робить. Запуск локального сервера з Ctrl+C при закінченні.
- Введіть конкретну тему, таку як швидкість відновлення акумулятора.
- Визначте пов’язані заголовки, хіппети і кредити, які повернулися в usage.credits. Варіюватися результати; нульові джерела є дійсним завершеним пошуком.
node server.mjshttp://127.0.0.1:8787В результаті отримується ваш додаток
Зведена форма; URLs і використання нижче є ілюстративним. Пошук повертає фрагменти та посилання. Використовуйте зчитувач сторінки, коли ваша функція потребує повного тексту сторінки.
{
"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);
};
}Спробуйте інструмент безпосередньо
Заощаджуйте tool-demo.mjs в флеш-довіднику, потім запустіть команду нижче з цієї папки з тим же ключем API. Ця додаткова перевірка робить додаткову запит FlashData без виклику моделі. Витратити JSON з запитом, джерелами, використанням та retrievedAt — так само форма результату, як форма.
// 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 підходить до цієї інтерактивної форми; використання асинхрону для фонової роботи.
| Ситуація | Поведінка додатка |
|---|---|
| ERR_MODULE_NOT_FOUND / ENOENT | Зберігайте всі файли в флеш-дослідження та запустіть з цієї папки. Заощаджуйте index.html перед відкриттям сторінки. |
| EADDRINUSE | Порт 8787 зайнято. Припиніть свій попередній демо-процес перед початком іншого. |
| Досягнення ліміту виклику | Заява дала можливість її спробам. Оздоблення зібраними доказами або звітувати ліміт; створення нового бігуна буде скидати кількість. |
| Зручні результати | Показати порожній стан і нехай користувач автоматично рефтінує запит; не повторювати. |
| 401 / 403 / 402 | Перевірити ключ сервера, дозвіл google_search і рахункові кредити. |
| 429 | Очікується Retry-After при наданні; обмеження запитів на користувача перед викликом FlashData. |
| Часовий / мережева помилка | Показати невизначений результат. Перевірте History, перш ніж надіслати той же платний запит знову. |