Skip to main content

LangChain

Kapa has a native LangChain integration, the langchain-kapa-ai Python package, that gives your LangChain chains and agents access to Kapa's retrieval over the knowledge sources in your Kapa project. It offers the same functionality as the hosted MCP server and the HTTP API, and it is the most native way to use Kapa's retrieval inside LangChain. Its source code, examples, and changelog are in the kapa-ai/langchain-kapa-ai repository on GitHub.

For a full walkthrough of installing the package and using it in an agent, see Add knowledge base search to a LangChain agent.

Requirements​

  • Python 3.10 or later.
  • langchain-core 1.4 or later, before 2.0.
  • A Kapa project with indexed knowledge sources. To set one up, follow Index your first source.

Installation​

Install the package from PyPI:

pip install langchain-kapa-ai

The import name is langchain_kapa_ai.

Components​

The package provides three components:

  • KapaRetriever: returns the most relevant chunks for a query as LangChain documents.
  • KapaGetDocumentsTool: an agent tool that fetches whole documents by source link or document ID.
  • KapaToolkit: returns search and document lookup as agent tools, configured from one set of settings.

The examples below read the API key and project ID from the environment; Connection settings lists all settings.

KapaRetriever​

KapaRetriever searches all knowledge sources connected to your Kapa project for a query and returns the most relevant chunks, each with the URL of its source. It is Kapa's retrieval, the same one the hosted MCP server exposes as its search tool.

The retriever extends LangChain's BaseRetriever, supports invoke, ainvoke, batch, and abatch, and calls the Retrieval endpoint, whose reference page defines the server-side defaults, limits, and fields.

You can configure the following parameters on the retriever:

SettingTypeDefaultDescription
mode"default" or "deep""default"default is faster; deep searches further and returns only relevant chunks. See Choose a retrieval mode.
top_kint (1-15)15The maximum number of chunks to return. Fewer may be returned if max_chars or the deep mode reduce the result set.
max_charsint (1-60000)35,000Maximum number of characters across all returned chunks. Chunks are included in order, but only up to the point where the total character count stays within this limit. Chunks are never truncated. This is an upper bound, not a target: especially in the deep mode, the returned total may be well below this limit.
source_group_idslist[str]All sourcesOnly return results from sources in these groups.
integration_idstrNoneIntegration that analytics attributes queries to.
redact_queryboolFalseIf True, the query text is redacted from analytics. Use for sensitive queries.
end_userKapaEndUserNoneAssociates queries with an end user in your analytics: email (the user's email address), unique_client_id (your own identifier for the user), and metadata (company_name, first_name, and last_name; other keys are ignored).

mode, top_k, and max_chars can also be overridden for a single call, for example retriever.invoke(query, top_k=3). Other keyword arguments on invoke raise TypeError.

from langchain_kapa_ai import KapaRetriever

retriever = KapaRetriever()
for document in retriever.invoke("How do I rotate an API key?", top_k=3):
    print(document.metadata["source"])
    print(document.page_content)

Results​

The retriever returns a list of LangChain Document objects, best match first. Each document's page_content is the chunk text in Markdown, and metadata["source"] is the URL of its source, exactly as Kapa returns it. The URL can point inside the document, for example to a heading, a line range, or a PDF page. A call can return fewer chunks than top_k, or none.

To show the source URLs to a model, include {source} in the document prompt of LangChain's create_retriever_tool, which otherwise passes only the chunk text.

KapaGetDocumentsTool​

KapaGetDocumentsTool is an agent tool that fetches whole documents from your knowledge sources by their source URL or document ID. An agent uses it when a chunk from search is not enough and it needs the complete page.

The tool extends LangChain's BaseTool, is named get_knowledge_documents, and calls the Documents endpoint, whose reference page defines the server-side defaults, limits, and fields. Credentials, the project, and source groups stay in application settings, so the agent cannot change them.

You can configure the following parameters on the tool:

SettingTypeDefaultDescription
source_group_idslist[str]All sourcesOnly return documents from sources in these groups.
max_chars_per_documentint (1-200000)50,000Maximum number of characters returned per document. Longer documents are truncated and flagged with truncated.
page_sizeint, minimum 15The number of requested URLs and document IDs per page. The tool splits a page into as many endpoint requests as needed.

The agent passes these arguments on each call:

ArgumentTypeDescription
urlslist[str]Source URLs as search results cite them.
document_idslist[str]The IDs of the documents to fetch.
pageintThe page of requested documents to return, starting at 1. Defaults to 1.

At least one URL or document ID is required. Duplicate URLs and IDs are ignored. A URL or ID that matches no document has no entry in documents.

from langchain_kapa_ai import KapaGetDocumentsTool

tool = KapaGetDocumentsTool()
message = tool.invoke(
    {
        "name": "get_knowledge_documents",
        "args": {"urls": ["https://docs.example.com/guide"]},
        "id": "call-1",
        "type": "tool_call",
    }
)

message.content  # JSON text for the model
page = message.artifact  # KapaDocumentsPage for your code
for document in page.documents:
    print(document.title, document.source_url)

Results​

The tool returns a LangChain ToolMessage. Its content is a JSON string for the model, and its artifact is a KapaDocumentsPage object for your code, which the model does not see. Both carry the same fields:

FieldDescription
page, page_sizeThe returned page and the page size.
total_requestedThe number of distinct requested URLs and document IDs.
has_more, next_pageWhether another page of requested URLs and IDs exists, and its number.
documentsEach document found on this page, once, as a KapaDocument, in request order.

Each KapaDocument has these fields:

FieldDescription
document_idThe ID of the document.
source_urlThe URL of the document, or None if it has no URL.
titleThe title of the document.
contentThe document in Markdown, truncated to max_chars_per_document, or None when the content is unavailable, such as for PDFs.
content_availableWhether the document text is available.
total_charsThe length of the full document before truncation, or 0 when the content is unavailable.
truncatedWhether content was truncated to max_chars_per_document.

KapaToolkit​

KapaToolkit gives an agent both search and document lookup in one step. It creates a KapaRetriever and a KapaGetDocumentsTool from one set of parameters and returns them as two agent tools.

The toolkit extends LangChain's BaseToolkit. A retriever on its own is not an agent tool, so the toolkit wraps the KapaRetriever in a search tool with LangChain's create_retriever_tool. The KapaGetDocumentsTool is already a tool and is returned unchanged.

You can configure the following parameters on the toolkit: the connection settings, every KapaRetriever parameter, and every KapaGetDocumentsTool parameter. The toolkit passes each parameter to the tool that uses it, and source_group_ids to both.

This example also needs langchain and your model provider's LangChain package. Replace <provider>:<model> with a tool-capable model and configure the provider's credentials.

from langchain.agents import create_agent
from langchain.chat_models import init_chat_model
from langchain_kapa_ai import KapaToolkit

agent = create_agent(
    init_chat_model("<provider>:<model>"),
    tools=KapaToolkit().get_tools(),
    system_prompt="Search the knowledge base before answering and cite your sources.",
)

Results​

get_tools() returns a list of two tools:

ToolNameBuilt fromReturns
Search toolsearch_knowledge_sourcesA KapaRetriever, wrapped with create_retriever_toolA ToolMessage whose content lists the chunks as text, each as Source: {source} followed by the chunk text, and whose artifact is the list of LangChain Document objects described in KapaRetriever results.
Document toolget_knowledge_documentsA KapaGetDocumentsTool, unchangedThe ToolMessage described in KapaGetDocumentsTool results.

The model reads each tool's description to decide when to call it. The search tool's description explains what a chunk is and that chunks come back in order of relevance; the document tool's description says when to look up a whole document.

Connection settings​

All three components accept these settings. By default, they read the API key and project ID from the environment:

export KAPA_API_KEY="your-api-key"
export KAPA_PROJECT_ID="your-project-id"

Pass a setting to override its default, for example to read the key from another variable or to search a different project:

import os

from langchain_kapa_ai import KapaRetriever

retriever = KapaRetriever(
    api_key=os.environ["SUPPORT_KAPA_API_KEY"],
    project_id="your-project-id",
    timeout=30.0,
)
SettingTypeDefaultDescription
api_keystrKAPA_API_KEY environment variableProject API key, sent in the X-API-KEY header. It is never shown in representations or error messages.
project_idstrKAPA_PROJECT_ID environment variableThe project to search.
base_urlstrhttps://api.kapa.aiAPI base URL.
timeoutfloat60.0Timeout in seconds for each request.
http_clienthttpx.ClientNoneClient for synchronous requests. Without one, each call opens and closes its own client.
http_async_clienthttpx.AsyncClientNoneClient for asynchronous requests, with the same default.

No component retries a failed request. In a chain, wrap a component with LangChain's with_retry() to retry. In an agent, retry tool calls with LangChain's ToolRetryMiddleware. To turn a KapaError into a message the model can read, use wrap_tool_call.

Errors​

Programming errors are raised before any request is sent, as standard Python exceptions: a missing API key or project ID raises ValueError, invalid settings or tool input raise pydantic's ValidationError, and an unsupported per-call argument raises TypeError. A value outside Kapa's limits raises KapaValidationError instead.

A failed request raises an exception that derives from KapaError; it never becomes an empty result. Exceptions for an error status derive from KapaAPIError, which carries status_code and the server's detail.

ExceptionRaised when
KapaAuthenticationErrorThe server rejects the API key or its access to the project (HTTP 401 or 403).
KapaNotFoundErrorThe project, or the integration in integration_id, does not exist for the key (HTTP 404).
KapaValidationErrorKapa rejects the request parameters (other HTTP 4xx).
KapaRateLimitErrorA rate limit or quota is exceeded (HTTP 429). retry_after holds the server's wait time in seconds, when given.
KapaServiceErrorKapa fails to process the request (HTTP 5xx).
KapaConnectionErrorThe request does not reach Kapa or times out.
KapaResponseErrorThe response does not match the expected format.

Rate limits​

The package shares the rate limits of the Retrieval and Documents endpoints, which apply per team across all projects and integrations.