Context Handlers

Execute standalone knowledge retrieval outside of agent runs. Useful for building custom RAG pipelines.

Context handlers provide standalone RAG retrieval without requiring an agent. Send a query with one or more knowledge base configurations, and the handler retrieves the most relevant chunks from each knowledge base. This is useful when you want to implement your own LLM integration but still leverage the platform’s vector search.

Common Patterns

Execute a context handler with POST /api/context-handlers, providing a query and an array of knowledge_base_configs (each specifying a knowledge_base_id and optional top_k). The response includes the retrieved chunks ranked by relevance, which you can inject into your own LLM prompts.

GET /api/context-handlers

List context handlers with pagination.

Python

response = requests.get(f"{BASE_URL}/api/context-handlers", headers=headers)

POST /api/context-handlers

Create and execute a context handler — retrieves relevant chunks from one or more knowledge bases.

Request

{
  "query": "How to get started?",
  "knowledge_base_configs": [
    { "id": "kb-uuid", "top_k": 5 }
  ],
  "max_context_tokens": 8000
}

Python

response = requests.post(f"{BASE_URL}/api/context-handlers", headers=headers, json={
    "query": "How to get started?",
    "knowledge_base_configs": [{"id": kb_id, "top_k": 5}],
    "max_context_tokens": 8000,
})

GET /api/context-handlers/

Get a context handler result by ID.

id · string · required

Handler ID

Python

response = requests.get(f"{BASE_URL}/api/context-handlers/{handler_id}", headers=headers)

Error Responses

Status	Code	Description
400	invalid_config	Invalid knowledge base configuration (e.g., missing knowledge_base_id or invalid top_k)