Google search tool for LangChain
To give a LangChain agent Google search, wrap a BestSERP call in a function decorated with @tool from langchain_core.tools. The function POSTs the query to /search and returns compact results (title, link, snippet) that the model reads and cites. Bind the tool to any chat model that supports tool calling.
Last updated:
Key takeaways
- No SDK to install: a tool function around one HTTP call is enough.
- Send the key in the X-API-KEY header, never in a URL or in browser code.
- 202 means the search is still running: poll GET /requests/{requestId}.
- 60 searches per minute per account by default; 429 and 503 are not charged.
Step by step
Install
pip install langchain-core requestsDefine the tool
The docstring becomes the tool description the model sees, so keep it precise.
tools.pyimport os import requests from langchain_core.tools import tool API = "https://api.bestserp.com" HEADERS = {"X-API-KEY": os.environ["BESTSERP_API_KEY"]} @tool def google_search(query: str, country: str = "us") -> list[dict]: """Search Google and return the top results with title, link and snippet. Use it for current facts, prices, news or anything not in your training data.""" r = requests.post(f"{API}/search", headers=HEADERS, json={"q": query, "gl": country, "hl": "en", "timeout": 120}, timeout=130) r.raise_for_status() data = r.json() return [{"title": i.get("title"), "link": i.get("link"), "snippet": i.get("snippet")} for i in data.get("organic", [])[:8]] if __name__ == "__main__": print(google_search.invoke({"query": "latest LangChain release"}))Bind it to a model
With any LangChain chat model that supports tool calling: model.bind_tools([google_search]). When the model asks for the tool, run it and pass the results back, or use a prebuilt agent that does this loop for you.
Keep answers grounded
Ask the model to cite the links it used. Limit how many searches one conversation may run to control cost (1 credit each).
Status codes to handle
| Status | Code | Meaning | Credits |
|---|---|---|---|
| 202 | - | Not finished within timeout (or async: true). Poll pollUrl. | Reserved |
| 400 | invalid_request | Malformed body or a parameter out of range. | No |
| 400 | unknown_parameter | A field the API does not know (typo?). | No |
| 400 | unsupported_parameter | A known field that this endpoint does not support yet (e.g. location). | No |
| 401 | missing_api_key / invalid_api_key | No key, or the key is wrong or revoked. | No |
| 402 | insufficient_credits | Your balance is too low for this request. | No |
| 403 | account_suspended | The account is suspended. | No |
| 404 | not_found | Unknown requestId, or it belongs to another account. | - |
| 429 | rate_limited | Too many requests this minute. See Retry-After. | No |
| 502 | search_failed | The search could not be completed (blocked or timed out). | Refunded |
| 503 | busy | No capacity right now. Retry after Retry-After seconds. | Refunded |
Frequently asked questions
Is there a ready-made LangChain integration package?
Why return only title, link and snippet?
Can the tool search news instead?
What happens if a search takes long?
Start with 3,000 free searches
No credit card. Sign in with Google, create a key, send your first request.