Resposta rápida
Como dou a um modelo da OpenAI uma ferramenta de pesquisa na web?
Declare uma função google_search com um JSON Schema em tools e então faça um loop: quando o modelo retornar tool_calls, execute cada pesquisa na https://serpcrypto.com/api/v1/search e anexe os resultados como mensagens tool até ele responder. A SerpCrypto cobra 1 crédito por pesquisa bem-sucedida, a partir de US$ 0,30/1K pesquisas, pago com cripto e sem KYC.
Como é o schema da ferramenta?
Uma function tool tem um nome, uma descrição e parâmetros em JSON Schema. O modelo vê apenas essas três coisas, então a descrição precisa dizer o que a ferramenta retorna e quando usá-la. Apenas query é obrigatório; país e idioma são opcionais e têm como padrão inglês dos EUA no código.
{
"type": "function",
"function": {
"name": "google_search",
"description": "Search Google for current information. Returns the top results with title, link and snippet. Use it for facts newer than your training data.",
"parameters": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "The search query, as a person would type it." },
"gl": { "type": "string", "description": "Two-letter country code of the results, e.g. us, gb, de." },
"hl": { "type": "string", "description": "Language code, e.g. en, de, pt-BR." }
},
"required": ["query"]
}
}
}Como funciona o loop de chamada de ferramentas?
Envie a pergunta com tools. Se a resposta contiver tool_calls, execute cada uma, acrescente a mensagem do assistente e uma mensagem tool por chamada com o tool_call_id correspondente, e então chame o modelo de novo. Quando uma resposta não tem chamada de ferramenta, ela é a resposta final.
O loop abaixo para após três pesquisas. Um limite protege seus créditos se um modelo continuar pesquisando, e três pesquisas respondem à maioria das perguntas factuais.
"""Tool-calling loop: the model asks for searches, this code runs them on SerpCrypto."""
import json
import os
import requests
from openai import OpenAI
client = OpenAI() # reads OPENAI_API_KEY
MODEL = os.environ["OPENAI_MODEL"] # any OpenAI chat model with tool calling
API_URL = "https://serpcrypto.com/api/v1/search"
TOOLS = [
{
"type": "function",
"function": {
"name": "google_search",
"description": "Search Google for current information. Returns the top results with title, link and snippet.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string", "description": "The search query."},
"gl": {"type": "string", "description": "Two-letter country code, e.g. us."},
"hl": {"type": "string", "description": "Language code, e.g. en."},
},
"required": ["query"],
},
},
}
]
def google_search(query, gl="us", hl="en"):
r = requests.get(
API_URL,
params={"q": query, "gl": gl, "hl": hl},
headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
timeout=90,
)
if r.status_code != 200:
return f"Search failed with HTTP {r.status_code}."
items = r.json().get("organic_results", [])[:5]
return "\n\n".join(f"{x['title']}\n{x['link']}\n{x.get('snippet', '')}" for x in items) or "No results."
def ask(question, max_searches=3):
messages = [{"role": "user", "content": question}]
for _ in range(max_searches + 1):
reply = client.chat.completions.create(model=MODEL, messages=messages, tools=TOOLS)
msg = reply.choices[0].message
if not msg.tool_calls:
return msg.content
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
messages.append({"role": "tool", "tool_call_id": call.id, "content": google_search(**args)})
return "Stopped: search limit reached."
print(ask("Which countries changed their data protection laws in 2026? Cite sources."))O mesmo schema funciona com Claude e outros modelos?
Sim, com um wrapper diferente. O uso de ferramentas do Claude aceita o mesmo JSON Schema em input_schema, ao lado de name e description. A maioria das outras APIs de chamada de ferramentas também aceita JSON Schema para parâmetros; só mudam os nomes dos campos externos. A função de pesquisa em si continua a mesma, porque ela só chama o endpoint SerpCrypto.
{
"name": "google_search",
"description": "Search Google for current information. Returns the top results with title, link and snippet.",
"input_schema": {
"type": "object",
"properties": {
"query": { "type": "string", "description": "The search query." },
"gl": { "type": "string", "description": "Two-letter country code, e.g. us." },
"hl": { "type": "string", "description": "Language code, e.g. en." }
},
"required": ["query"]
}
}O que a ferramenta deve retornar ao modelo?
Texto curto com links. Cinco resultados com título, link e snippet costumam bastar para o modelo responder e citar. Retornar o JSON completo funciona, mas custa mais tokens e dá ao modelo mais ruído para ler.
Acrescente o texto do AI Overview quando houver, se você quiser que o modelo veja o resumo do próprio Google, e mantenha os links das fontes para que a resposta possa citar páginas em vez do overview.
Como mantenho os custos de pesquisa previsíveis?
Conte as chamadas de ferramenta: cada uma que dá certo é um crédito. Limite as pesquisas por pergunta, como o loop faz, e registre cada chamada com a consulta para ver o que o modelo pede. No pack 100.000 pesquisas a taxa é US$ 0,56/1K pesquisas, e Os créditos de pesquisa pré-pagos nunca expiram: as pesquisas não utilizadas ficam na sua conta até você usá-las.
Erros não custam nada: 1 crédito = 1 solicitação de pesquisa bem-sucedida, que retorna uma página de resultados em qualquer engine compatível. Uma solicitação que falha não é cobrada.
Perguntas sobre function calling
Posso usar a Responses API em vez da Chat Completions?
Sim. A Responses API aceita function tools com o mesmo JSON Schema, com name, description e parameters no nível superior de cada ferramenta. A função de pesquisa e a ideia do loop não mudam.
Por que não usar a busca na web integrada do provedor do modelo?
As ferramentas de busca integradas escolhem suas próprias fontes e configurações. Uma função no SerpCrypto entrega resultados do Google para o país e o idioma que você escolher, como JSON que você pode registrar, a um preço conhecido por pesquisa.
O modelo pode escolher o país?
Sim. gl é um parâmetro da ferramenta, então o modelo pode defini-lo a partir da pergunta, por exemplo gb para uma pergunta sobre o Reino Unido. Mantenha um padrão no seu código para perguntas que não citam país.
Preciso de cartão de crédito para obter a chave de API de pesquisa?
Não. Os créditos SerpCrypto são pagos em BTC, USDT, USDC, ETH, SOL, LTC, sem documento de identidade, sem selfie e sem documentos. Login pelo número da conta; e-mail é opcional.