Knowledge

Introduction

Knowledge is retrieval you own: a search index, a vector store, an API. The kit asks it for passages and puts them in the agent’s system prompt. Use it when answers must come from your documents rather than from the model alone.

Providing a knowledge source

Implement retrieve over your index.

import type { KnowledgeSource } from '@pilotoo/agent-runtime';

const knowledge: KnowledgeSource = {
  retrieve: ({ query, knowledge, caller, signal }) =>
    search.passages({ query, collections: knowledge, caller, signal }),
};

Pass it as the knowledge option of PilotooModule.forRoot (token KNOWLEDGE_SOURCE) or in AgentRunnerOptions. There is none by default. In the local backend it goes in host.knowledge.

Choosing which agents use it

Only an agent whose definition lists runtime.knowledge ids is asked.

runtime:
  knowledge: [help-center, release-notes]

The ids are opaque to the kit. Use them as collection names, tenant spaces, or whatever your index understands.

What you receive and return

In	Meaning
`query`	What to look up, from the user’s message.
`knowledge`	The ids from the agent’s `runtime.knowledge`.
`caller`	The identity and credentials, so you can authorize the search as that caller. See Authenticating users.
`signal`	Abort signal; the retrieval is bounded by a timeout.

Return { text, source, score? }[].

What the kit guarantees

The answer is validated.
Passages are packed whole under a 2000-token budget into the system prompt.
A source that throws, answers anything else or exceeds 3 s is logged by error class only, and the turn runs without passages.

Next steps

Agents for runtime.knowledge.
Authenticating users to authorize a search per caller.
Skills for instructions rather than documents.