# 자주 묻는 질문

작업 검색 양식을 작성하고, 당신의 백엔드에 API 키를 유지하고, 에이전트 도구에서 동일한 검색 기능을 재사용합니다.

Canonical 참고: https://flashdata.dev/ko/docs/guides/search-in-an-app
검토: 2026-11-05 FlashData

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

## 당신이 구축 할 것

랭크된 링크, 스니펫 및 신용 사용과 현지 검색 양식. Node.js 22+, google_search 허가 및 사용 가능한 신용을 가진 열쇠를 요구하십시오. npm 패키지가 필요하지 않습니다. 선택적인 대리인 단면도는 동일한 backend 기능을 재사용합니다.

| flashdata-search-demo에서 저장 | 제품정보 |
| --- | --- |
| search.mjs | 백엔드에서 FlashData 호출; 양식 및 에이전트 도구에 의해 공유. |
| server.mjs | 로컬 페이지와 GET /search 엔드포인트를 제공합니다. |
| index.html | 표시 소스, 빈 결과 및 오류. |

### Bash 또는 PowerShell · 프로젝트 생성

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

- [앱 실행](https://flashdata.dev/ko/docs/guides/search-in-an-app/reference.md#output)
- [에이전트에서 함수를 사용](https://flashdata.dev/ko/docs/guides/search-in-an-app/reference.md#tool)
- [API에 새로운?](https://flashdata.dev/ko/docs/guides/http-quickstart/reference.md)

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

### API 키 설정

이미 설정된 경우 FLASHDATA_API_KEY를 재사용합니다. 그렇지 않으면 코드를 실행할 터미널에서 숨겨진 프롬프트를 사용합니다. 에이전트는 비밀 저장소에서 같은 변수를로드 할 수 있습니다.

#### Bash

##### 키 설정

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

##### 키 설정

```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 키](https://flashdata.dev/app/api-keys)
- [에이전트 체험 및 계정 연결](https://flashdata.dev/ko/docs/guides/agent-onboarding/reference.md)

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

## 1. 검색 기능 만들기

프로젝트 폴더에서 search.mjs로 저장하십시오. 하나의 호출은 5 웹 결과까지 반환, 그들의 URLs 및 실제 사용. 함수는 입력을 검증하고, 결과 순서를 보존하고, 중복된 URLs를 제거하고 반환된 데이터의 열쇠를 유지합니다. 500-character 제한은 앱 선택입니다.

### 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. 지역 후원 추가

search.mjs 옆에 server.mjs로 저장하십시오. GET /search?q=... 함수를 호출; GET / 다음을 만들 수있는 양식을 제공합니다. 서버는 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. 앱에서 결과를 표시

같은 폴더에 index.html로 저장합니다. 이 양식은 로딩, 빈 결과 및 오류를 처리합니다. 그것은 텍스트로 백엔드 및 삽입 스니펫을 호출, 그래서 API 키 또는 외부 HTML 페이지에 도달.

### 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. 첫 번째 검색을 실행

flashdata-search-demo에서 키 설정 터미널에서 실행합니다. URL를 열고 검색을 클릭합니다. 각 제출은 유료 쿼리를 만듭니다. 페이지를 열고 입력을 편집하지 않습니다. 완료 시 Ctrl+C로 로컬 서버를 중지합니다.

1. 배터리 재활용 회수율과 같은 특정 주제를 입력합니다.
2. usage.credits에서 리턴된 관련 타이틀, 스니펫 및 크레딧을 기대합니다. 결과가 다를 수 있습니다. 0 소스는 유효 완료된 검색입니다.

### flashdata-search-demo · 이 터미널 실행을 유지

```bash
node server.mjs
```

### 본문 바로가기

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

- [relevance 향상](https://flashdata.dev/ko/docs/guides/google-search-guide/reference.md)
- [자주 묻는 질문](https://flashdata.dev/app/jobs)

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

### 앱이 수신된 결과

Abbreviated 모양; URLs 및 아래의 사용은 설명입니다. 검색은 스니펫과 링크를 반환합니다. 기능이 전체 페이지 텍스트를 필요로 할 때 페이지 리더를 사용하십시오.

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

## 에이전트 도구에서 검색 재사용

옵션: search.mjs 옆에 search-tool.mjs를 저장하십시오. 런너는 search_web 및 쿼리 만 허용됩니다. 작업 당 하나의 런너를 만들고 그 작업의 모델이 턴을 가로지르는 것을 계속하십시오. maxCalls 제한은 실패한 시도를 포함하여 검색을 시도했습니다. 신용 지출 제한을 설정하지 않습니다.

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

- [직접 도구를 사용](https://flashdata.dev/ko/docs/guides/search-in-an-app/reference.md#tool-test)
- [당신의 모델을 연결](https://flashdata.dev/ko/docs/guides/search-in-an-app/reference.md#model-loop)
- [MCP 호스트를 사용하는 이미?](https://flashdata.dev/ko/docs/integrations/mcp-clients/reference.md)

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

### 직접 도구를 사용

Flashdata-search-demo에서 tool-demo.mjs를 저장하고 같은 API 키와 같은 폴더에서 아래 명령을 실행합니다. 이 옵션 체크는 모델을 호출하지 않고 하나의 추가 FlashData 쿼리를 만듭니다. 질의, 근원, 사용법 및 retrievedAt를 가진 JSON를 기대하십시오 - 모양과 동일한 결과 모양.

#### 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));
```

#### flashdata-search-demo에서 한 번 실행

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


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

### 당신의 모형에 연결하십시오

데모는 도구 함수를 연습합니다. 프레임 워크는 모델 연결 및 메시지 루프를 공급합니다. 검색은 링크와 스니펫을 반환합니다; 응답에 자신의 전체 콘텐츠를 사용하기 전에 선택한 페이지를 읽으십시오. 재시작 또는 배포 작업을 위해, 시도 수를 주장하고 작업 ID로 결과.

1. 프레임 워크의 도구 정의 형식을 사용하여 searchTool.name, 설명 및 inputSchema 등록. 백엔드 환경에서 API 키 유지.
2. 작업 시작시 createSearchToolRunner({ maxCalls: 2 })로 전화하십시오. 각 모델 도구 호출의 경우 JSON 인수를 파싱하고 이름을 전달하고 동일한 주자에 반대된 객체를 전달합니다. 파견하기 전에 잘못된 JSON를 거부합니다.
3. JSON의 결과를 원래 호출 ID로 공구 결과로 반환합니다. 인용을 위한 보존 sources[].url. 실행이 실패하거나 한계에 도달하면 오류를 반환합니다. 그것을 재발시키는 새로운 주자를 만들지 마십시오.

- [작업 기록](https://flashdata.dev/ko/docs/guides/recurring-tasks/reference.md)
- [인용 연구](https://flashdata.dev/ko/docs/guides/google-youtube-research/reference.md)

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

## 손잡이 실패와 배 그것

배포를 위해서는 애플리케이션의 로그인 및 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를 검사합니다. |

- [Realtime 또는 동기화?](https://flashdata.dev/ko/docs/reference/realtime-and-async/reference.md#choose)
- [Batch 요청](https://flashdata.dev/ko/docs/reference/batch-and-bulk/reference.md#batch)
- [오류 코드 및 retries](https://flashdata.dev/ko/docs/errors/reference.md#retries)
- [회사연혁](https://flashdata.dev/ko/docs/guides/production-deployment/reference.md)
