[ blog · tutorial ]7 min read

Como adicionar Web Search em tempo real a um agente OpenAI ou Claude em 4 passos

Sarah ChoyPublicado em 2 de maio de 20267 min de leitura
Como adicionar Web Search em tempo real a um agente OpenAI ou Claude em 4 passos

Quer que seu agente fundamente as respostas em informações atuais? Você precisa de exatamente duas coisas: uma API de busca que retorne snippets prontos para LLM e uma definição de ferramenta que o modelo possa chamar. Este guia faz as duas em 4 passos.

TL;DR

  • Passo 1: obtenha uma API key (grátis) e teste o endpoint com curl.
  • Passo 2: baixe o tool schema OpenAI/Claude direto da API — sem escrever JSON à mão.
  • Passo 3: registre a ferramenta no seu agente (OpenAI Assistants, Anthropic Messages, LangChain ou n8n).
  • Passo 4: implemente o handler da ferramenta que chama /api/search/web e retorna os resultados ao modelo.

Por que este artigo é curto

A maioria dos tutoriais de \"adicione Web Search ao seu LLM\" é longa porque, na verdade, são tutoriais sobre um SDK de API de busca ou sobre um framework de agente pesado. Este não é. O trabalho todo é: escolher um endpoint, registrá-lo como ferramenta e escrever um handler de 5 linhas.

1Obtenha uma API key (grátis) e chame o endpoint

Cadastre-se em apipick.com/dashboard/api-keys. Contas novas recebem 100 créditos grátis — sem cartão de crédito. Crie uma key e teste o endpoint:

curl -X POST https://www.apipick.com/api/search/web \
  -H "x-api-key: pk_yourkey" \
  -H "Content-Type: application/json" \
  -d '{"query": "what is retrieval augmented generation"}'

Você receberá uma pequena lista ranqueada de títulos, URLs e snippets. Confirmar que isso funciona no curl economiza tempo de debugging mais tarde.

2Baixe o tool schema (não o escreva à mão)

A API Pick expõe tool schemas prontos para colar em GET /api/search/web/tool-schema. A resposta inclui tanto uma definição de função no estilo OpenAI quanto uma definição de tool use do Claude.

curl https://www.apipick.com/api/search/web/tool-schema

Faça cache do resultado — ele não muda entre chamadas. Escrever function schemas à mão é a fonte mais comum de bugs em código de agente (tipo errado, campos required errados, descrição ausente).

3Registre a ferramenta no seu agente

OpenAI Assistants

from openai import OpenAI
import requests

client = OpenAI()
schema = requests.get("https://www.apipick.com/api/search/web/tool-schema").json()

assistant = client.beta.assistants.create(
    name="Research Agent",
    model="gpt-4o",
    instructions="Use web_search whenever the user asks about current events or anything that changes after your training cutoff.",
    tools=[{"type": "function", "function": schema["openai"]}],
)

Anthropic Claude

import anthropic
import requests

schema = requests.get("https://www.apipick.com/api/search/web/tool-schema").json()
client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=[schema["claude"]],
    messages=[{"role": "user", "content": "Summarise this week's RAG research."}],
)

LangChain

from langchain.tools import tool
import requests

@tool
def web_search(query: str) -> dict:
    """Real-time web search. Use for any question that needs current information."""
    return requests.post(
        "https://www.apipick.com/api/search/web",
        headers={"x-api-key": "pk_yourkey"},
        json={"query": query},
    ).json()

n8n

Adicione um nó HTTP Request: método POST, URL https://www.apipick.com/api/search/web, header x-api-key: pk_yourkey, corpo JSON {"query": "{{ $json.query }}"}. Conecte-o ao seu nó de agente ou LLM Chain. Sem SDK necessário.

4Trate a chamada da ferramenta

Para OpenAI Assistants, quando o run pausa com status requires_action, execute a busca e envie o output:

import json, time, requests
from openai import OpenAI

client = OpenAI()
KEY = "pk_yourkey"

def run_with_tool(thread_id: str, assistant_id: str):
    run = client.beta.threads.runs.create(thread_id=thread_id, assistant_id=assistant_id)
    while True:
        run = client.beta.threads.runs.retrieve(thread_id=thread_id, run_id=run.id)
        if run.status == "requires_action":
            outputs = []
            for call in run.required_action.submit_tool_outputs.tool_calls:
                if call.function.name == "web_search":
                    args = json.loads(call.function.arguments)
                    result = requests.post(
                        "https://www.apipick.com/api/search/web",
                        headers={"x-api-key": KEY},
                        json=args,
                    ).json()
                    outputs.append({"tool_call_id": call.id, "output": json.dumps(result)})
            client.beta.threads.runs.submit_tool_outputs(
                thread_id=thread_id, run_id=run.id, tool_outputs=outputs,
            )
        elif run.status in ("completed", "failed", "cancelled", "expired"):
            return run
        time.sleep(0.5)

O loop da API Messages da Anthropic é parecido — quando a resposta contém um bloco tool_use, chame a API e depois envie o resultado de volta como um bloco de conteúdo tool_result no turno seguinte.

Apertando o loop

  • Defina a descrição da ferramenta na perspectiva do modelo: \"Use this when the user asks about current events, breaking news, or anything that may have changed after your training cutoff.\" Não diga \"esta é uma API de Web Search\".
  • Faça cache dos resultados no seu handler quando a mesma query aparecer duas vezes numa sessão. Os resultados de Web Search são estáveis por ~minutos; você não precisa pagar 15 créditos duas vezes na mesma conversa.
  • Adicione um filtro start_date quando o frescor importa. \"As notícias desta semana\" sem filtro de data costuma retornar manchetes do ano passado.

Para onde ir depois

Quando seu agente já souber buscar, o próximo passo natural é ler as páginas referenciadas. Adicione a URL Content Extraction API como segunda ferramenta — mesma autenticação, mesmo formato JSON, até 25 URLs por chamada. A combinação \"search + extract\" é o menor agente de research útil.

Perguntas Frequentes

Posso usar isto com a OpenAI Responses API em vez de Assistants?

Sim. O mesmo tool schema funciona em client.responses.create() — passe-o via tools=[{...}] exatamente como mostrado na documentação da OpenAI. O formato do handler é idêntico: faça o parse de tool_calls, execute POST /api/search/web e retorne o JSON.

Preciso formatar os resultados antes de devolvê-los ao modelo?

Não. POST /api/search/web retorna título + URL + snippet LLM-friendly já ranqueados. Devolva o JSON bruto como resultado da ferramenta. O modelo vai citar os snippets e referenciar as URLs.

Quanto custa cada turno de agente?

Cada chamada de Web Search são 15 créditos (~US$ 0,015 a US$ 5/5.000 créditos). Um turno típico que usa a ferramenta uma vez fica bem abaixo de um centavo de dólar em custo de busca — os tokens do LLM dominam.

E se o modelo nunca chamar a ferramenta?

Deixe a descrição da ferramenta específica. "Use this for any question that requires current or post-training information" funciona muito melhor que "web search". Os modelos roteiam para ferramentas cujo propósito eles entendem.

Posso limitar os resultados a um país ou intervalo de datas?

Sim. Passe country_code (ISO 3166-1 alpha-2) e/ou start_date / end_date (YYYY-MM-DD). Adicione-os como parâmetros no seu tool schema se quiser que o modelo os escolha; ou fixe-os no handler se seu agente tiver um locale ou requisito de frescor fixos.

APIs usadas neste artigo

Sarah Choy
Escrito por
Sarah Choy
CEO, API Pick

Sarah Choy é a CEO da API Pick. Ela escreve sobre a construção de APIs prontas para produção para agentes de IA e fluxos de trabalho com LLMs.