Echtzeit-Web-Search in einen OpenAI- oder Claude-Agenten einbauen — in 4 Schritten

Du willst, dass dein Agent Antworten mit aktuellen Informationen stützt? Du brauchst genau zwei Dinge: eine Such-API mit LLM-fertigen Snippets und eine Tool-Definition, die das Modell aufrufen kann. Diese Anleitung erledigt beides in 4 Schritten.
Auf einen Blick
- •Schritt 1: API-Key erstellen (kostenlos) und Endpoint mit curl testen.
- •Schritt 2: OpenAI-/Claude-Tool-Schema direkt von der API holen — nicht von Hand schreiben.
- •Schritt 3: Tool im Agenten registrieren (OpenAI Assistants, Anthropic Messages, LangChain oder n8n).
- •Schritt 4: Tool-Handler aufrufen, /api/search/web abfragen, Ergebnis zurückreichen.
Warum dieses Tutorial kurz ist
Die meisten 'Add Web Search to your LLM'-Tutorials sind lang, weil sie eigentlich ein SDK oder ein schweres Agentenframework erklären. Dieses ist anders. Die Aufgabe ist: Endpoint wählen, als Tool registrieren, einen 5-Zeilen-Handler schreiben.
1API-Key erstellen (kostenlos) und Endpoint testen
Auf apipick.com/dashboard/api-keys registrieren. Neue Konten erhalten 100 Credits — ohne Kreditkarte. Key anlegen und testen:
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"}'Du erhältst eine kompakte ranked Liste mit Titeln, URLs und Snippets. Das vorab in curl bestätigt zu haben spart später Debugging-Zeit.
2Tool-Schema holen — nicht von Hand schreiben
API Pick stellt einsatzfertige Tool-Schemas unter GET /api/search/web/tool-schema bereit. Antwort enthält OpenAI-Funktionsdefinition und Claude-Tool-Use-Definition.
curl https://www.apipick.com/api/search/web/tool-schemaErgebnis cachen — es ändert sich selten. Function-Schemas händisch zu schreiben ist die häufigste Fehlerquelle in Agentencode (falsche Typen, fehlende Required-Felder, leere Description).
3Tool im Agenten registrieren
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
HTTP-Request-Node hinzufügen: Methode POST, URL https://www.apipick.com/api/search/web, Header x-api-key: pk_yourkey, JSON-Body {"query": "{{ $json.query }}"}. Ans Agent- oder LLM-Chain-Node anschließen. Kein SDK nötig.
4Tool-Aufruf verarbeiten
Wenn der OpenAI-Assistants-Run mit requires_action pausiert, Search ausführen und Ergebnis einreichen:
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)Bei der Anthropic Messages API analog: erscheint ein tool_use-Block, API aufrufen und das Ergebnis im nächsten Turn als tool_result-Block zurücksenden.
Den Loop härten
- Tool-Description aus Modellsicht schreiben: 'Use this when the user asks about current events, breaking news, or anything that may have changed after your training cutoff.' — nicht 'this is a web search API'.
- Im Handler dieselbe Query in derselben Session cachen. Suchergebnisse sind minutenstabil; 15 Credits zweimal in einem Gespräch sind unnötig.
start_datesetzen, wenn Aktualität zählt. 'News dieser Woche' ohne Datumsfilter liefert gerne letztjährige Schlagzeilen.
Wie es weitergeht
Wenn der Agent suchen kann, ist der nächste Schritt das Lesen der verlinkten Seiten. URL Content Extract API als zweites Tool registrieren — gleiche Auth, gleiches JSON-Format, bis 25 URLs pro Aufruf. 'Search + Extract' ist der kleinste sinnvolle Recherche-Agent.
Häufig gestellte Fragen
Funktioniert das auch mit der OpenAI Responses API statt Assistants?
Ja. Dasselbe Tool-Schema funktioniert in client.responses.create() via tools=[{...}]. Der Handler ist identisch: tool_calls parsen, POST /api/search/web aufrufen, JSON zurückgeben.
Muss ich die Ergebnisse vor der Rückgabe an das Modell formatieren?
Nein. POST /api/search/web liefert bereits ranked title + URL + LLM-freundliches snippet. Rohes JSON als Tool-Result zurückgeben — das Modell zitiert die Snippets und verlinkt die URLs.
Was kostet eine Agentenrunde?
Ein Web-Search-Aufruf kostet 15 Credits (≈ $0.015 bei $5 / 5.000). Eine typische Runde mit einmaligem Tool-Use bleibt deutlich unter einem US-Cent Suche — die LLM-Tokens dominieren.
Was, wenn das Modell das Tool nie aufruft?
Mach die Tool-Description spezifisch. 'Use this for any question that requires current or post-training information' funktioniert deutlich besser als 'web search'. Modelle nutzen Tools, deren Zweck sie verstehen.
Kann ich nach Land oder Datum einschränken?
Ja. country_code (ISO 3166-1 alpha-2) und/oder start_date / end_date (YYYY-MM-DD) übergeben. Soll das Modell entscheiden, im Tool-Schema als Parameter aufnehmen — sonst direkt im Handler hardcoden, falls dein Agent feste Anforderungen hat.
APIs in diesem Artikel
Sarah Choy ist CEO von API Pick. Sie schreibt über produktionsreife APIs für KI-Agenten und LLM-Workflows.