langchain-kaer
langchain-kaer connects LangChain agents and chains to the Kaer Search API. It provides KaerSearch, a tool a model can call to search the web, and KaerSearchRetriever, which returns search results as LangChain documents. Both send one POST /v1/search request per query and work with sync and async code.
Install
pip install -U langchain-kaer
Get an API key
- Sign up at api.kaer.ai.
- Create a key in the dashboard and tick the
searchscope. - Add credit. Search opens after your account's first top-up; adding a card in Billing first gives you free web searches. See Search pricing for the price per query on each lane.
export KAER_API_KEY="kaer_live_..."
You can also pass the key in code: KaerSearch(kaer_api_key="...").
Use the search tool
from langchain_kaer import KaerSearch
tool = KaerSearch(max_results=5)
tool.invoke({"query": "latest results on perovskite solar cells"})
The tool returns the query, the lane that served it and a list of results. Each result has a title, url and snippet, plus published_date when it is known and the page's main text on the deep lane.
Give the tool to an agent
The agent and chain examples below also need LangChain and a model package:
pip install -U langchain langchain-anthropic
from langchain.agents import create_agent
from langchain_kaer import KaerSearch
agent = create_agent(
model="anthropic:claude-sonnet-5-5",
tools=[KaerSearch(max_results=5)],
)
result = agent.invoke(
{
"messages": [
{"role": "user", "content": "What changed in the EU AI Act this month?"}
]
}
)
print(result["messages"][-1].content)
When a model calls the tool, the ToolMessage content holds compact results for the model to read. Its artifact holds the full API response, including kaer.request_id and kaer.cost_usd, so your code can log what each search cost.
What the model can set
| Argument | Type | Description |
|---|---|---|
query |
string | What to search for, 1 to 512 characters. Required. |
lane |
string | web, fast, deep or auto. Optional. |
include_domains |
list of strings | Only return results from these host names or their subdomains. Optional. |
exclude_domains |
list of strings | Never return results from these host names. Optional. |
Settings you fix when you create the tool
| Setting | Default | Description |
|---|---|---|
max_results |
5 |
Results per query, 1 to 25. |
lane |
"auto" |
The lane used when the model does not choose one. |
allow_model_lane |
True |
Set False to always use lane, which keeps the price per query fixed. |
include_domains |
None |
Default host names to search within. |
exclude_domains |
None |
Default host names to leave out. |
kaer_api_key |
KAER_API_KEY |
Your key. |
timeout |
60 |
Seconds to wait for a response. |
Choose a lane
| Lane | What it does | Timeout |
|---|---|---|
web |
Searches Kaer's own index. Fastest and cheapest. | 6 s |
fast |
Races Kaer's index against the live web. | 12 s |
deep |
Runs every lane and re-ranks the results. Each result carries the page's main text, up to 4,000 characters, when the page could be read. | 40 s |
auto |
Kaer picks a lane for each query. You pay for the lane that served it. | 40 s |
A search that fails or times out is not charged.
Use the retriever
KaerSearchRetriever returns a list of Document objects. On the deep lane, page_content is the page's main text; on the other lanes it is the result snippet. metadata holds title, url, snippet, source, published_date and served_lane.
from langchain_kaer import KaerSearchRetriever
retriever = KaerSearchRetriever(k=5, lane="deep")
docs = retriever.invoke("How do heat pumps work in cold climates?")
for doc in docs:
print(doc.metadata["title"], doc.metadata["url"])
Pass k at call time to change how many documents come back: retriever.invoke(query, k=3).
Use the retriever in a chain
from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.runnables import RunnablePassthrough
from langchain.chat_models import init_chat_model
from langchain_kaer import KaerSearchRetriever
retriever = KaerSearchRetriever(k=5, lane="deep")
llm = init_chat_model("anthropic:claude-sonnet-5-5")
prompt = ChatPromptTemplate.from_template(
"Answer from the sources and cite their URLs.\n\n"
"Sources:\n{context}\n\nQuestion: {question}"
)
def format_docs(docs):
return "\n\n".join(f"{d.metadata['url']}\n{d.page_content}" for d in docs)
chain = (
{"context": retriever | format_docs, "question": RunnablePassthrough()}
| prompt
| llm
| StrOutputParser()
)
print(chain.invoke("How do heat pumps work in cold climates?"))
Call the API directly
KaerSearchAPIWrapper sends the request and returns the API's JSON response. It accepts every request field the API documents, including offset and page for paging on the web and fast lanes, and fields to choose which result keys come back.
from langchain_kaer import KaerSearchAPIWrapper
search = KaerSearchAPIWrapper()
data = search.search(
"solar panel efficiency records", lane="fast", num_results=10, offset=10
)
print(data["served_lane"], data["kaer"]["cost_usd"])
Use await search.asearch(...) in async code. To send requests through your own httpx client, for a proxy or retries, pass client= or async_client=.
Handle errors
KaerSearchAPIWrapper raises KaerAPIError, with the HTTP status_code, the API's error code, its message, the request_id and retry_after when the API sent one. The tool catches these errors and returns them to the model as an error ToolMessage, so an agent can recover. The retriever raises them.
| Status | Code | What to do |
|---|---|---|
| 401 | invalid_api_key |
Check the key, or create a new one. |
| 402 | insufficient_credits |
Add credit. |
| 403 | tier_required |
Search opens after your account's first top-up. |
| 403 | insufficient_scope |
Add the search scope to the key. |
| 429 | rate_limit_exceeded |
Wait for retry_after seconds, then retry. |
| 504 | search_timeout |
Retry, or use a faster lane. |
The full list is in the error reference.
Development
make test # unit tests, no network
make integration_tests # live tests, needs KAER_API_KEY
make lint
Set KAER_BASE_URL to send requests to another base URL, for example a proxy in front of the API.
Links
Licence
MIT. See LICENSE.
Metadata
Release files for langchain-kaer 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| langchain_kaer-0.1.0.tar.gz | 15.0 kB | With provenance | Details for langchain_kaer-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| langchain_kaer-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for langchain_kaer-0.1.0-py3-none-any.whl |
Total release size: 28.2 kB
Release files / langchain_kaer-0.1.0.tar.gz
| Download URL | langchain_kaer-0.1.0.tar.gz |
|---|---|
| Size | 15.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4c18a1f8d222f4e14b91cf87e31119a4e2176451b7f3710eb156a9a45df80c40
|
|
BLAKE2b-256 checksum How to use checksums |
682ea0aa92224885144e13b7c4244112372b35a3473587627f5f9b8f2c83b851
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logRelease files / langchain_kaer-0.1.0-py3-none-any.whl
| Download URL | langchain_kaer-0.1.0-py3-none-any.whl |
|---|---|
| Size | 13.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6488349b04ba4be9077ac3dd88005b57bb449ba759db960acb9d33f991486451
|
|
BLAKE2b-256 checksum How to use checksums |
737e907e2d0f0ce3213d1bc316f0050eb5757e80545068059d89ddea0f01805c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logSecurity for langchain-kaer 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for langchain_kaer-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.