Cómo añadir Web Search en tiempo real a un agente OpenAI o Claude en 4 pasos

¿Quieres que tu agente fundamente respuestas con información actual? Necesitas exactamente dos cosas: una API de búsqueda que devuelva snippets listos para LLM y una definición de herramienta que el modelo pueda llamar. Esta guía hace ambas en 4 pasos.
Resumen
- •Paso 1: obtén una API key gratis y prueba el endpoint con curl.
- •Paso 2: descarga el tool schema OpenAI/Claude desde la API — sin escribir JSON a mano.
- •Paso 3: registra la herramienta en el agente (OpenAI Assistants, Anthropic Messages, LangChain o n8n).
- •Paso 4: implementa el handler que llama a /api/search/web y devuelve los resultados al modelo.
Por qué este artículo es corto
La mayoría de tutoriales de 'añade Web Search a tu LLM' son largos porque en realidad enseñan un SDK de búsqueda o un framework de agente pesado. Este no. El trabajo es: elegir un endpoint, registrarlo como tool, escribir un handler de 5 líneas.
1Obtén una API key gratis y llama al endpoint
Regístrate en apipick.com/dashboard/api-keys. Las cuentas nuevas reciben 100 créditos gratis — sin tarjeta. Crea una key y prueba:
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"}'Recibirás una pequeña lista ranked con título, URL y snippet. Confirmar que funciona en curl ahorra mucho debugging después.
2Descarga el tool schema (no lo escribas a mano)
API Pick expone tool schemas listos para pegar en GET /api/search/web/tool-schema. La respuesta incluye una definición OpenAI function y otra Claude tool use.
curl https://www.apipick.com/api/search/web/tool-schemaCachea el resultado — no cambia a menudo. Escribir function schemas a mano es la fuente más común de bugs en código de agente (tipo erróneo, required incorrecto, descripción ausente).
3Registra la herramienta en el 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
Añade un nodo HTTP Request: método POST, URL https://www.apipick.com/api/search/web, header x-api-key: pk_yourkey, body JSON {"query": "{{ $json.query }}"}. Conéctalo a tu nodo agente o LLM Chain. No hace falta SDK.
4Maneja la llamada a la herramienta
En OpenAI Assistants, cuando el run pausa con requires_action, ejecuta la búsqueda y envía el 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)El loop de la API Messages de Anthropic es similar — cuando la respuesta contiene un bloque tool_use, llama a la API y devuelve el resultado como bloque tool_result en el siguiente turno.
Apretando el loop
- Escribe la tool description en perspectiva del modelo: 'Use this when the user asks about current events, breaking news, or anything that may have changed after your training cutoff.' No digas 'esto es una API de Web Search'.
- Cachea en el handler las queries repetidas en la misma sesión. Los resultados son estables a nivel de minutos; no pagues 15 créditos dos veces en la misma conversación.
- Añade
start_datecuando importe la frescura. 'Las noticias de esta semana' sin filtro de fecha suele devolver titulares del año pasado.
Siguiente paso
Cuando tu agente sepa buscar, el siguiente paso natural es leer las páginas enlazadas. Añade URL Content Extract API como segunda herramienta — misma autenticación, misma forma JSON, hasta 25 URLs por llamada. 'Search + Extract' es el agente de research mínimo útil.
Preguntas frecuentes
¿Funciona con la OpenAI Responses API en vez de Assistants?
Sí. El mismo tool schema funciona en client.responses.create() vía tools=[{...}]. La forma del handler es idéntica: parsear tool_calls, llamar POST /api/search/web, devolver el JSON.
¿Hay que formatear los resultados antes de devolverlos al modelo?
No. POST /api/search/web ya devuelve title + URL + snippet LLM-friendly ranked. Pasa el JSON tal cual como tool result. El modelo cita los snippets y enlaza las URLs.
¿Cuánto cuesta cada turno de agente?
Cada llamada a Web Search son 15 créditos (~$0.015 a $5/5.000). Un turno típico con un único uso de la herramienta ronda menos de un centavo de búsqueda — los tokens del LLM dominan.
¿Y si el modelo nunca llama a la herramienta?
Haz la descripción específica. 'Use this for any question that requires current or post-training information' funciona mucho mejor que 'web search'. Los modelos usan herramientas cuyo propósito entienden.
¿Puedo limitar por país o rango de fechas?
Sí. Pasa country_code (ISO 3166-1 alpha-2) y/o start_date / end_date (YYYY-MM-DD). Para que el modelo los elija, agrégalos como parámetros del schema; o fíjalos en el handler si tu agente tiene locale o frescura fija.
APIs usadas en este artículo
Sarah Choy es la CEO de API Pick. Escribe sobre cómo construir APIs listas para producción para agentes de IA y flujos de trabajo con LLMs.