# Adicionar busca a um aplicativo

Construa um formulário de busca funcional, mantenha a chave API em sua infra-estrutura, e reutilize a mesma função de busca em uma ferramenta de agente.

Referência canônica: https://flashdata.dev/pt/docs/guides/search-in-an-app
2026-11-05 por FlashData

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

## O que você vai construir

Um formulário de busca local com links classificados, trechos e uso de crédito. Requer Node.js 22+, uma chave com permissão google_search e créditos disponíveis. Nenhum pacote npm é necessário. A seção de agentes opcionais reutiliza a mesma função de infraestrutura.

| Economize em flashdata-pesquisa-demo | Propósito |
| --- | --- |
| search.mjs | Chama FlashData da infra-estrutura, compartilhada pela ferramenta de formulário e agente. |
| server.mjs | Serve a página local e GET /search. |
| index.html | Mostra fontes, resultados vazios e erros. |

### Bash ou PowerShell · criar o projeto

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

- [Execute o aplicativo](https://flashdata.dev/pt/docs/guides/search-in-an-app/reference.md#output)
- [Use a função em um agente](https://flashdata.dev/pt/docs/guides/search-in-an-app/reference.md#tool)
- [Novo no API?](https://flashdata.dev/pt/docs/guides/http-quickstart/reference.md)

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

### Defina sua chave API

Reutilize FLASHDATA_API_KEY se já estiver pronto. Caso contrário, use o alerta escondido abaixo no terminal que irá executar o código. Um agente pode carregar a mesma variável de sua loja secreta.

#### Bash

##### Defina a chave

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

##### Defina a chave

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


- [Teclas API](https://flashdata.dev/app/api-keys)
- [Teste para agentes e vinculação](https://flashdata.dev/pt/docs/guides/agent-onboarding/reference.md)

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

## 1. Crie a função de busca

Salve como search.mjs em sua pasta de projeto. Uma chamada retorna até cinco resultados da web, seu URLs e uso real. A função valida a entrada, preserva a ordem do resultado, remove URLs duplicado e mantém a chave fora dos dados devolvidos. O limite de caracteres 500 é uma escolha de aplicativo.

### 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. Adicionar uma infra-estrutura local

Salve como server.mjs ao lado de search.mjs. GET /search?q=... chama a função; GET / serve o formulário que você vai criar em seguida. O servidor só ouve em 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. Exiba os resultados no aplicativo

Salve como index.html na mesma pasta. Este formulário lida com carga, resultados vazios e erros. Ele chama sua infra-estrutura e insere trechos como texto, então nem a chave API nem HTML externo alcançam a página.

### 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. Execute sua primeira pesquisa

Corra de flash data-search-demo no terminal onde você definir a chave. Abra o URL e clique em procurar uma vez. Cada envio faz uma consulta paga, abrir a página ou editar a entrada não faz nenhuma. Pare o servidor local com Ctrl+C quando terminar.

1. Digite um tópico específico, como taxas de recuperação de reciclagem de bateria.
2. Espere títulos ligados, trechos e os créditos retornados em usage.credits. Os resultados variam, zero fontes são uma busca completa válida.

### Em flashdata-pesquisa-demo · mantenha este terminal funcionando

```bash
node server.mjs
```

### Abra no seu navegador

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

- [Melhore a relevância](https://flashdata.dev/pt/docs/guides/google-search-guide/reference.md)
- [Verifique o histórico de pedidos](https://flashdata.dev/app/jobs)

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

### O resultado que seu aplicativo recebe

Forma abreviada; URLs e uso abaixo são ilustrativos. Uma busca devolve trechos e links. Use um leitor de página quando seu recurso precisar do texto da página inteira.

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

## Reutilizar busca em uma ferramenta de agente

Opcional: salve search-tool.mjs ao lado de search.mjs. O corredor aceita apenas search_web e sua consulta. Criar um corredor por tarefa e mantê-lo através do modelo da tarefa gira; maxCalls limita tentativas de busca, incluindo tentativas falhadas. Isso não estabelece um limite de gastos de crédito.

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

- [Tente a ferramenta diretamente](https://flashdata.dev/pt/docs/guides/search-in-an-app/reference.md#tool-test)
- [Conecte seu modelo](https://flashdata.dev/pt/docs/guides/search-in-an-app/reference.md#model-loop)
- [Já está usando um hospedeiro MCP?](https://flashdata.dev/pt/docs/integrations/mcp-clients/reference.md)

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

### Tente a ferramenta diretamente

Salve tool-demo.mjs em flashdata-pesquisa-demo, e execute o comando abaixo daquela pasta com a mesma chave API. Este verificação opcional faz uma consulta adicional FlashData sem chamar um modelo. Espere JSON com consulta, fontes, uso e retrievedAt - a mesma forma de resultado que o formulário.

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

#### Corra uma vez de flashdata-pesquisa-demo

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


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

### Conecte-o ao seu modelo

A demonstração exercita a função da ferramenta. Seu framework fornece o modelo de conexão e o loop de mensagem. Buscar retorna links e trechos, ler páginas selecionadas antes de usar seu conteúdo completo em uma resposta. Para tarefas retomadas ou distribuídas, persista na contagem de tentativas e resultados com a tarefa ID.

1. Registre searchTool.name, descrição e inputSchema usando o formato de definição de ferramentas do seu framework. Mantenha a chave API no ambiente de infraestrutura.
2. No início da tarefa, chame createSearchToolRunner ({ maxCalls: 2 }). Para cada chamada de ferramenta modelo, analise seus argumentos JSON e passe o nome e objeto analisado para o mesmo corredor. Rejeite o JSON inválido antes da expedição.
3. Devolva o resultado JSON ao modelo como um resultado de ferramenta com a chamada original ID. Preservar sources[].url para citações. Se a execução falhar ou atingir o limite, devolva o erro; não crie um novo corredor para tentar novamente.

- [Registros de tarefas recorrentes](https://flashdata.dev/pt/docs/guides/recurring-tasks/reference.md)
- [Pesquisa com citações](https://flashdata.dev/pt/docs/guides/google-youtube-research/reference.md)

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

## Lidar com falhas e enviá-lo

Para implantação, mova /search para trás dos limites de entrada e por usuário da sua aplicação. Mantenha a chave API na configuração do servidor, mantenha o uso com a solicitação e renderize conteúdo externo como texto. Realtime é adequado para este formulário interativo; use uma sincronização para o trabalho de fundo.

| Situação | Comportamento da aplicação |
| --- | --- |
| ERR_MODULE_NOT_FOUND / ENOENT | Mantenha todos os arquivos em flashdata-pesquisa-demo e corra dessa pasta. Salve index.html antes de abrir a página. |
| EADDRINUSE | O porto 8787 está ocupado. Pare seu processo de demonstração antes de começar outro. |
| O limite de busca foi atingido | A tarefa usou suas tentativas permitidas. Termine com as provas coletadas ou relate o limite, criar um novo corredor iria redefinir a contagem. |
| Resultados vazios | Mostre um estado vazio e deixe o usuário refinar a consulta; não tente novamente automaticamente. |
| 401 / 403 / 402 | Verifique a chave do servidor, permissão google_search e créditos de conta. |
| 429 | Aguarde Retry-After quando for fornecido; limite os pedidos por usuário antes de ligar para FlashData. |
| Tempo limite / erro de rede | Mostre um resultado incerto. Inspecione History antes de enviar a mesma consulta paga novamente. |

- [Realtime ou assincronia?](https://flashdata.dev/pt/docs/reference/realtime-and-async/reference.md#choose)
- [Pedidos Batch](https://flashdata.dev/pt/docs/reference/batch-and-bulk/reference.md#batch)
- [Códigos de erro e tentativas](https://flashdata.dev/pt/docs/errors/reference.md#retries)
- [Implementação da produção](https://flashdata.dev/pt/docs/guides/production-deployment/reference.md)
