Bir OpenAI veya Claude Ajanına Gerçek Zamanlı Web Search 4 Adımda Nasıl Eklenir

Ajanınızın yanıtlarını güncel bilgiye dayandırmasını mı istiyorsunuz? Tam olarak iki şeye ihtiyacınız var: LLM'e hazır snippet'ler döndüren bir arama API'si ve modelin çağırabileceği bir araç tanımı. Bu rehber ikisini de 4 adımda yapıyor.
Özet
- •Adım 1: bir API key (ücretsiz) alın ve endpoint'i curl ile deneyin.
- •Adım 2: OpenAI/Claude tool schema'sını doğrudan API'den çekin — JSON'u elle yazmayın.
- •Adım 3: aracı ajanınıza kaydedin (OpenAI Assistants, Anthropic Messages, LangChain veya n8n).
- •Adım 4: /api/search/web'i çağıran ve sonuçları modele döndüren araç handler'ını uygulayın.
Neden kısa
Çoğu \"LLM'inize web search ekleyin\" rehberi uzundur çünkü aslında bir arama API SDK'sı ya da ağır bir ajan framework'ü hakkındadır. Bu öyle değil. Bütün iş şu: bir endpoint seçin, onu araç olarak kaydedin, 5 satırlık bir handler yazın.
1Bir API key (ücretsiz) alın ve endpoint'i çağırın
apipick.com/dashboard/api-keys adresinden kaydolun. Yeni hesaplar 100 ücretsiz credit alır — kredi kartı gerekmez. Bir key oluşturup endpoint'i deneyin:
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"}'Başlık, URL ve snippet'lerden oluşan küçük, sıralı bir liste alacaksınız. Bunun curl'de çalıştığını doğrulamak ilerideki debugging süresini kısaltır.
2tool schema'yı çekin (elle yazmayın)
API Pick, yapıştırmaya hazır tool schema'ları GET /api/search/web/tool-schema üzerinde sunar. Yanıt hem OpenAI tarzı bir function tanımı hem de bir Claude tool use tanımı içerir.
curl https://www.apipick.com/api/search/web/tool-schemaSonucu cache'leyin — çağrılar arasında değişmez. function schema'ları elle yazmak, ajan kodundaki bug'ların en yaygın kaynağıdır (yanlış type, yanlış required alanlar, eksik açıklama).
3Aracı ajanınıza kaydedin
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
Bir HTTP Request düğümü ekleyin: method POST, URL https://www.apipick.com/api/search/web, header x-api-key: pk_yourkey, JSON gövdesi {"query": "{{ $json.query }}"}. Onu ajan veya LLM Chain düğümünüze bağlayın. SDK gerekmez.
4Araç çağrısını işleyin
OpenAI Assistants için, run requires_action durumuyla duraklarsa aramayı çalıştırıp çıktıyı gönderin:
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)Anthropic Messages API döngüsü benzerdir — yanıt bir tool_use bloğu içerdiğinde API'yi çağırın, ardından sonucu bir sonraki turda tool_result içerik bloğu olarak geri gönderin.
Döngüyü sıkılaştırma
- Araç açıklamasını modelin bakış açısından yazın: \"Use this when the user asks about current events, breaking news, or anything that may have changed after your training cutoff.\" \"Bu bir web search API'sidir\" demeyin.
- Aynı query bir oturumda iki kez geçtiğinde handler'ınızda sonuçları cache'leyin. Web search sonuçları ~dakikalar boyunca kararlıdır; aynı konuşmada 15 credit'i iki kez ödemeniz gerekmez.
- Tazelik önemli olduğunda bir
start_datefiltresi ekleyin. Tarih filtresi olmayan \"bu haftanın haberleri\" çoğu zaman geçen yılın manşetlerini döndürür.
Bundan sonrası
Ajanınız arama yapabildiğinde doğal sonraki adım, bağlı sayfaları okumaktır. İkinci bir araç olarak URL Content Extraction API'yi ekleyin — aynı auth, aynı JSON biçimi, çağrı başına en fazla 25 URL. \"search + extract\" kombinasyonu, en küçük kullanışlı research ajanıdır.
Sıkça Sorulan Sorular
Bunu Assistants yerine OpenAI Responses API ile kullanabilir miyim?
Evet. Aynı tool schema client.responses.create() içinde çalışır — OpenAI belgelerinde gösterildiği gibi onu tools=[{...}] aracılığıyla geçirin. Handler'ın biçimi aynıdır: tool_calls'ı parse edin, POST /api/search/web'i çalıştırın, JSON'u döndürün.
Sonuçları modele döndürmeden önce biçimlendirmem gerekir mi?
Hayır. POST /api/search/web, sıralanmış title + URL + LLM dostu snippet döndürür. Ham JSON'u araç sonucu olarak geri geçin. Model snippet'leri alıntılar ve URL'leri bağlar.
Her ajan turu ne kadara mal olur?
Her web search çağrısı 15 credits'tir (5.000 credits için 5$ üzerinden ~0,015$). Aracı bir kez kullanan tipik bir ajan turu, arama maliyeti olarak bir ABD sentinin hayli altındadır — LLM token'ları baskındır.
Model aracı hiç çağırmazsa ne olur?
Araç açıklamasını belirgin yapın. "Use this for any question that requires current or post-training information", "web search"e kıyasla çok daha iyi çalışır. Modeller amacını anladıkları araçlara yönelir.
Sonuçları bir ülke ya da tarih aralığıyla sınırlayabilir miyim?
Evet. country_code (ISO 3166-1 alpha-2) ve/veya start_date / end_date (YYYY-MM-DD) geçin. Modelin seçmesini istiyorsanız bunları tool schema'nıza parametre olarak ekleyin; ajanınızın sabit bir locale veya tazelik gereksinimi varsa handler'da hard-code edin.
Bu makalede kullanılan API'ler
Sarah Choy, API Pick'in CEO'sudur. Yapay zeka ajanları ve LLM iş akışları için üretime hazır API'ler geliştirme üzerine yazılar yazar.