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-schemaFaç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_datequando 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 é 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.