Knowledge Gateway

A knowledge gateway lets an agent search a knowledge base that stays inside your own network. Examples are a vector database, an intranet search engine, or a document store that must never be copied to the cloud or opened to the internet.

You run a small program, the Qlar Knowledge Gateway, on a server in your network. It connects out to Qlar and never opens an inbound port. When the agent searches, Qlar hands the search to your gateway. The gateway calls your own search service with a simple HTTP request and sends the results back.

It is one of the three kinds of External Knowledge provider, next to another agent's Search API and a REST API.

How it works

Agent (Qlar) ──▶ Qlar Knowledge Hub ──▶ Knowledge Gateway (your server) ──▶ your search service (webhook)
                       ▲                  outbound connection only            POST {query, permissions, limit}
                       └────────────────── results ◀──────────────────────────────────────┘

1. During a conversation the agent decides that a question is about what this provider covers, and searches it.
2. Qlar sends the search terms, the provider's permission codes and its number of search results to the Qlar Knowledge Hub.
3. The hub passes the search to your gateway over the connection the gateway opened.
4. The gateway calls your search service (the webhook) at the address configured on the gateway, and returns its answer.
5. The agent answers from the results, exactly as with any other provider: reranking, citations and permissions all work the same.

Your search service is yours to build. It can sit in front of any knowledge base you like. It only has to answer one HTTP call, described in The webhook below.

What stays on your server

• The address of your search service and its key. You configure them on the gateway itself. Qlar sees only the host (for example http://kb.internal:8080) and whether the last search worked. Nobody in Qlar can point your gateway at another address.
• The gateway's identity key. It is created on the server and never leaves it.
• A log of every search in the gateway's log/ folder: the question, permissions, outcome, number of results and timing. The results themselves are never written to it.

Before you start

• A server or PC in your network that can reach your search service and make outbound HTTPS connections to Qlar. Supported systems:
  • Windows x64
  • Linux x64 or arm64
  • macOS on Apple silicon
• A search service that follows the webhook contract. To try the gateway first, you can use the example service in the qlar-knowledge-gateway repository (samples/FakeKnowledgeBase).
• Permission to manage the agent's knowledge (agent contributors, and organization Owners and Admins).

Connect a gateway

1. In the CMS, open Knowledge → External and select Add provider.

2. Choose Knowledge gateway and select Continue.

3. Fill in Name, What information to look up here, Permissions and Search results (see Shared fields). Pick the Server operating system.

4. Select Connect gateway. Qlar shows a one-line install command that contains a one-time code. The code is valid for 15 minutes.

5. Run the command on your server:

   # Windows (PowerShell 5.1 or 7)
   & ([scriptblock]::Create((irm 'https://<hub>/install.ps1'))) -Code 'XXXX-XXXX-XXXX' -Force
   

   # Linux / macOS
   curl -fsSL 'https://<hub>/install.sh' | sh -s -- --code 'XXXX-XXXX-XXXX' --force
   

   The script downloads the gateway, checks its SHA-256 checksum, installs it for the current user and enrols it. In a terminal it asks for your search service's address and key (see Configure the search service). It then prints a fingerprint of four lines.

6. Back in the CMS, the provider shows A server has enrolled. Confirm it is yours. with a fingerprint. Compare it with the one in your terminal. If they are identical, select It matches, approve.

7. Keep the command running. The gateway starts serving as soon as you approve it, and the provider shows Connected, with your search service's host.

8. Use Run test in the provider's Test section to try a real question.

The fingerprint check is what makes a leaked code useless. If the fingerprint in the CMS differs from your terminal, someone else used your code. Do not approve it: select It differs, get a new code.

Keep it running after logout and reboot

Configure the search service

The address and key of your search service are set on the gateway, not in Qlar:

qlar-knowledge-gateway configure endpoint --url http://kb.internal:8080/search --auth x-api-key
qlar-knowledge-gateway test "How many days of annual leave do I get?"

• --auth none|x-api-key|bearer controls how the key is sent:
  • x-api-key sends X-Api-Key: <key>.
  • bearer sends Authorization: Bearer <key>.
• The key is typed hidden and stored encrypted on the server. The gateway uses the system's key store where it can: Windows DPAPI, the macOS Keychain, or systemd-creds or the desktop keyring on Linux. You can also read it from an environment variable with --api-key-env NAME.
• Plain http:// and private addresses are allowed, because the service lives in your own network. For a self-signed certificate, add --insecure-skip-tls-verify.
• test runs one search without Qlar, so you can check the service on its own.
• A running gateway picks up a changed configuration within 30 seconds.

The webhook

For every search the gateway sends:

POST {your search service}
Content-Type: application/json
X-Api-Key: {key}                   (or Authorization: Bearer {key}, or nothing)
X-Qlar-Agent-Id: {agent id}
X-Qlar-Conversation-Id: {conversation id}
X-Qlar-Request-Id: {correlation id}

{ "query": "How many days of annual leave do I get?", "permissions": ["HR"], "limit": 5 }

Your service answers:

{
  "results": [
    {
      "title": "Employee leave policy",
      "section": "Annual leave",
      "text": "Permanent employees get 15 days of annual leave per year...",
      "chunkCode": "HR-007-1",
      "contentId": "HR-007",
      "distance": 0.18
    }
  ]
}

• Request fields:
  • query: up to 1,000 characters.
  • permissions: up to 50 codes. Return only documents that those codes may see; with no codes, return only public documents.
  • limit: 1 to 20.
• Response fields: only text is required in each result. title and section appear in citations. Other fields are ignored.
• Limits: the answer must be smaller than 1 MB and arrive within 10 seconds. Aim for under 2 seconds: the user is waiting in a chat. Redirects are not followed.
• Errors: answer with a non-2xx status, optionally with { "code": "...", "message": "..." }. A 401 or 403 is reported as a refused key.

This is the same contract as a REST API provider, so one service can serve both.

Logs on the gateway

The gateway writes to the log/ folder in its state directory. You can choose another folder with --log-dir.

The state directory is:

qlar-knowledge-gateway status shows where the logs are, whether the gateway is connected and which search service it calls.

Status in the CMS

To move the gateway to another server, open the provider and select Move to another server. You get a new code, and the new server's fingerprint must be approved. The provider, its settings and its history stay the same.

Removing the provider disconnects the gateway. The program on your server stops and does not restart. Uninstall it there with qlar-knowledge-gateway uninstall-service and delete its files.

Billing

Each successful search through a knowledge gateway costs 1 credit, charged to your agent's organization. A failed search (gateway offline, search service unreachable, timeout) is not charged. When the agent's reranker is on, reranking is charged as for the agent's own knowledge.

Troubleshooting

Related pages

• External Knowledge
• External Knowledge screen reference
• On-Premise Data Gateway: the same idea, for SQL databases.