External Knowledge

External Knowledge lets an agent search other knowledge bases during a conversation, next to its own documents, websites, and videos. Each source you add is called a provider. A provider can be:

• Another agent's Search API. The knowledge of another Qlar agent you manage, through its Knowledge Search API. Qlar fills in the endpoint and makes a key for you.
• A REST API. Any search service of your own that takes the same request and returns the same response as the Knowledge Search API. You enter its endpoint and key.
• A knowledge gateway (coming soon). A small program in your own network that answers searches from knowledge that cannot leave it, the way the On-premise Gateway does for databases.

Use it when the knowledge an agent needs is kept somewhere else and copying it would mean keeping two copies in sync, for example:

• A shared knowledge agent. HR keeps one agent with every policy. The front-desk agent, the onboarding agent, and the IT helpdesk agent all search it instead of each holding their own copy.
• Knowledge owned by another team. The sales agent answers product questions from the product team's agent, which that team keeps up to date.
• A search service you already run. Your intranet search already indexes thousands of documents. The agent asks it, instead of you uploading the documents again.

In the Teach Your Agent example, Atlas holds Kirana Group's SOPs. Kirana's customer service agent, Brew, sometimes gets questions about purchase approvals. Instead of uploading the SOPs to Brew too, Brew gets Atlas as a provider described as "Internal SOPs on purchasing, approvals and capex", so it searches Atlas only when a question is about those.

How the agent uses a provider

Each provider that is switched on becomes one tool for the agent, next to its own knowledge base. The agent reads the provider's "What information to look up here" and decides, question by question, whether to search it. A question about something the provider does not cover does not reach it, so it costs nothing.

When the agent searches a provider:

1. Qlar sends the search terms, the provider's permissions, and its number of search results to the provider.
2. The provider answers with the matching chunks, in its own order.
3. If the agent's reranker is on (Knowledge → Retrieval), the results are reranked with the agent's reranker model and cut to the agent's number of search results, exactly like its own knowledge. If the reranker is off, every result the provider returned is used as is. Providers have no reranking setting of their own.
4. The agent answers from the results. When citations are on, a citation shows the provider's name and the chunk's title, for example [Atlas SOPs · Project and Capex Approval Policy · 3. Approval limits]. These citations are not links: the chunk lives in the other knowledge base, not in this agent's.

The agent treats a provider's results as data, never as instructions. If a provider cannot be reached or refuses the search, the agent is told and answers without it; the conversation does not fail.

Before you start

• Who can add providers. Agent contributors and organization Owners and Admins, the same people who manage the agent's knowledge.
• Any agent can use providers, personal or service.
• At most 5 providers per agent.
• For an agent provider, the other agent must be a service agent with its Channels → Search API switched on, and you must be able to manage that agent too. See Knowledge Search API.

Add a provider

In the CMS, open Knowledge → External in your agent's sidebar and select Add provider. First choose the kind of provider, then fill in the form.

Another agent's Search API

1. Choose Another agent's Search API and select Continue.
2. In Agent, pick the agent to search. The list shows the agents you manage whose Search API is switched on, with their organization.
3. The Endpoint is filled in for you. The API key is made automatically when you add the provider (see Keys made for a provider).
4. Fill in the shared fields and select Add provider.

If the other agent enforces permission codes on its Search API, the form tells you: those codes are added to every search anyway.

REST API

1. Choose REST API and select Continue.

2. Fill in:

   Field	What to enter
   Endpoint	The search URL. It must start with https:// and be reachable on the internet: addresses in private or local networks are refused.
   API key	The key the service expects. It is stored encrypted and never shown again; when you edit the provider later, leave it empty to keep the saved key.
   Send the key as	X-Api-Key header (like the Knowledge Search API) or Authorization: Bearer.

3. Fill in the shared fields. You can test before you add it.

4. Select Add provider.

The service must follow this contract (the same as the Knowledge Search API):

POST {endpoint}
X-Api-Key: {key}            (or Authorization: Bearer {key})
Content-Type: application/json

{ "query": "Who approves capex above USD 50,000?", "permissions": ["FINANCE"], "limit": 5 }

{
  "results": [
    {
      "chunkCode": "SOP-FIN-007-0004",
      "title": "Project and Capex Approval Policy",
      "section": "3. Approval limits",
      "text": "Capital expenditure above USD 50,000 requires approval from the Finance Controller...",
      "distance": 0.18
    }
  ]
}

Only text is required in each result; chunkCode, contentId, title, section, and distance are optional. Other fields are ignored. At most 20 results are read, the answer must be smaller than 1 MB, and the service must answer within 15 seconds. Redirects are not followed.

Shared fields

Test a provider

Every provider form has a Test section. Type a question and select Run test: Qlar runs one search with the values in the form and lists the results in the provider's order, with their title, section, and distance. Reranking is not applied in the test.

• A REST provider can be tested before you add it, with the endpoint and key you typed.
• An agent provider can be tested once it is added, because its key is made when it is added. After you add it, the form stays open on the new provider so you can test it right away.
• A failed test says why, for example a refused key, a timeout, or an answer that is not in the expected format.

Testing an agent provider runs a real search on the other agent, so it costs that agent's organization 1 credit and appears in that agent's search log, like any other search.

Keys made for a provider

When you add an agent provider, Qlar makes a key on the other agent only for this provider. You never see or copy it: it is stored encrypted and used only by the agent that searches.

On the other agent, the key appears under Channels → Search API → Access → Used by other agents, with the name of the agent that uses it. The other agent's contributors can revoke it there at any time. Such keys do not take one of the other agent's two key slots.

Permissions

Permission codes work as in the agent's own knowledge: chunks without codes can always be found, and chunks with codes are found only when the search carries one of them. See Knowledge Permissions.

A provider sends the same codes for every search: the ones you set on the provider. They do not change with the user who is chatting. For an agent provider, the other agent also adds its own enforced permissions to every search. Only give a provider the codes that every user of your agent may see.

Billing

A provider is searched only when the agent decides it is relevant, so a well-written What information to look up here also keeps the cost down.

Limits

Searches of another agent also count towards that agent's Search API rate limits.

Troubleshooting

Related pages

• Knowledge Search API: the API an agent provider searches, and how to open your agent's knowledge to other systems.
• Retrieval: the reranker and number of search results that also apply to provider results.
• Knowledge Permissions
• Citations
• External Knowledge screen reference