문서 둘러보기
가이드
작업 검색 양식을 작성하고, 당신의 백엔드에 API 키를 유지하고, 에이전트 도구에서 동일한 검색 기능을 재사용합니다.
이 페이지의 내용
당신이 구축 할 것
랭크된 링크, 스니펫 및 신용 사용과 현지 검색 양식. Node.js 22+, google_search 허가 및 사용 가능한 신용을 가진 열쇠를 요구하십시오. npm 패키지가 필요하지 않습니다. 선택적인 대리인 단면도는 동일한 backend 기능을 재사용합니다.
| flashdata-search-demo에서 저장 | 제품정보 |
|---|---|
| search.mjs | 백엔드에서 FlashData 호출; 양식 및 에이전트 도구에 의해 공유. |
| server.mjs | 로컬 페이지와 GET /search 엔드포인트를 제공합니다. |
| index.html | 표시 소스, 빈 결과 및 오류. |
node --version
mkdir flashdata-search-demo
cd flashdata-search-demoAPI 키 설정
이미 설정된 경우 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로 저장하십시오. 하나의 호출은 5 웹 결과까지 반환, 그들의 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에서 리턴된 관련 타이틀, 스니펫 및 크레딧을 기대합니다. 결과가 다를 수 있습니다. 0 소스는 유효 완료된 검색입니다.
node server.mjshttp://127.0.0.1:8787앱이 수신된 결과
Abbreviated 모양; 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.mjs 옆에 search-tool.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. 실행이 실패하거나 한계에 도달하면 오류를 반환합니다. 그것을 재발시키는 새로운 주자를 만들지 마십시오.
손잡이 실패와 배 그것
배포를 위해서는 애플리케이션의 로그인 및 per-user limits 뒤에 /search를 이동합니다. 서버 구성의 API 키 유지, 요청과 외부 콘텐츠를 텍스트로 유지. Realtime는 이 상호 작용하는 모양에 적응됩니다; 배경 일을 위한 원조를 사용하십시오.
| - 연혁 | 앱 행동 |
|---|---|
| ERR_MODULE_NOT_FOUND / ENOENT | flashdata-search-demo에서 모든 파일을 유지하고 그 폴더에서 실행하십시오. index.html 를 저장하여 페이지를 열 수 있습니다. |
| EADDRINUSE | 항구 8787는 점유됩니다. 다른 시작 전에 이전 데모 프로세스를 중지. |
| 연락처 제한 도달 | 작업은 허용 된 시도를 사용했습니다. 수집된 증거로 끝나거나 한계를 보고하십시오; 새로운 주자를 창조하는 것은 조사를 다시 놓을 것입니다. |
| 빈 결과 | 빈 상태를 표시하고 사용자가 쿼리를 제거 할 수 있습니다; 자동으로 재발하지 마십시오. |
| 401 / 403 / 402 | 서버 키 확인, google_search 권한 및 계정 크레딧. |
| 429 | 제공될 때 Retry-After를 기다리십시오; FlashData를 부르기 전에 사용자 당 한계 요구. |
| Timeout / 네트워크 오류 | 불확실한 결과를 보여주십시오. 동일한 유료 쿼리를 다시 보내기 전에 History를 검사합니다. |