Skip to main content

Knowledge Management

Knowledge is the primary source of guidance the assistant uses to answer questions and propose guided actions. Forms, Controls, and Tools are auxiliary; the live DOM is ground truth. See Authoring for the agent for the mental model behind this priority.

This page is the Backoffice mechanics: how to create, scope, size, and publish entries. For decision rules ("should I author a Knowledge entry for this?") read the mental model first.

Creating a Knowledge entry​

  1. Navigate to Knowledge in the Backoffice for your app/domain.
  2. Click New Knowledge.
  3. Fill in:
    • Title: a noun phrase ("Product creation", not "How to create a product").
    • Description: the body. Markdown. Use inline tokens for action references (see Token reference below).
    • Scope: app_global / domain_global / page. See Scope selection.
    • Views (when scope is page): the View(s) this entry applies to.
    • Visibility: Public / Authenticated / Internal (see Visibility).
    • Status: Draft / In Review / Published. Only Published reaches end users.
  4. Save.

Scope selection​

Each entry has a scope that determines when it loads:

ScopeLoads onWhen to use
app_globalEvery domain in this appTruly app-wide guidance: global search, top navigation, login flow. Use sparingly.
domain_globalEvery page on one domainDomain-wide policy and terminology. Loaded on every turn. Keep this set small (4-8 entries).
pageOnly Views you link via the Views tabThe default. Each entry attaches to one or more Views.

Only app_global, domain_global, and page are valid scopes. Link page-scoped entries via the Views tab to surface them on the right view.

Use Views for page detection and view-scoped knowledge placement. See Managing Views.

Sizing and the pre-loaded budget​

page-scoped entries linked to the current View, plus all domain_global entries, are pre-loaded on every turn. They share a finite context budget with the rest of the agent's prompt. Authoring too much pre-loaded content silently degrades response quality: the agent drops citations, ignores tokens, repeats itself.

The discipline you should follow:

QuestionRule of thumb
Tokens per entry200–500 tokens (~150–400 words). If you exceed 700, split by sub-topic.
Always-loaded domain_global entries4–8 entries across the whole domain. Treat them as gold.
page-scoped entriesAs many as you need, scoped tightly. Only entries linked to the current View load.
Long-form material (manuals, regulations, glossaries)Ingest as RAG files instead. The agent retrieves only the relevant chunks per turn. See RAG files.
Multi-locale tenantsPre-loaded set is read per locale. If you author the same entry in DE + ES + EN, the budget triples. Use locale overrides only for genuinely-differing terminology.

Use the Test Chat to monitor: if your domain feels "forgetful" or stops citing on simple questions, you are likely over-loaded. Pull the per-locale domain_global set under 4,000 tokens total.

Content best practices​

Write for the user, through the agent​

The assistant quotes and paraphrases your Knowledge. Write it so a user reading it would understand:

  • Be specific: "Enter your 10-digit account number without dashes" beats "enter account number".
  • Be actionable: tell the user what to do and why.
  • Be concise: 200–500 tokens per entry. Long prose is a smell.
  • Use structure: numbered steps for procedures; bullets for parallel options.
  • Lead with the why: tab order matters because of dependencies; not just "tab order matters".

Don't duplicate the page​

The assistant already reads the page. Do NOT write:

  • "The Save button saves the form", visible from the label.
  • "The URL field is for the URL", visible from the label.
  • "Click submit when you are done", every user already knows this.

DO write:

  • "Tab ordering matters: Zuständigkeiten must be filled before Zahlungen because the latter depends on the linked Leistung."
  • "The Landesredaktion requires four mandatory parameters before publishing; see the Pflichtparameter entry."
  • "Vertrauensniveau is the official identity verification level, not a model confidence score."

One entry, one topic​

Split mega-guides. A KB titled "Complete guide to file management" is harder for the agent to retrieve and rank than four entries:

  • "Folder creation"
  • "Sharing model"
  • "File list page"
  • "Upload workflow"

Reference, don't duplicate​

If a behaviour is described elsewhere (an app_global entry, another page entry), link to it by name:

  • Good: "Use the global search (see Global search overview) to find files."
  • Bad: duplicating the global-search instructions on every page entry.

Keep content fresh​

Outdated Knowledge is worse than no Knowledge: it erodes user trust. Review and update when:

Token reference​

Knowledge entries reference Forms, Controls, and Tools inline with token syntax. Authors describe the workflow while the runtime resolves locators, labels, URLs, resources, citations, zones, and executable targets. Tokens are opaque handles, not selectors and not URLs.

TokenExpands toWhen to use
{{form:semantic_id}}A structured form-fill step. The runtime materialises fields in order, applies visibility rules and defaults, and keeps field values out of prose.A multi-field workflow lives in an authored Form.
{{control:semantic_id}}A single executable handle on the named Control. The runtime resolves prerequisites and the trusted locator.A one-off action that does not warrant a Form, or an affordance with irreducible prerequisites.
{{tool:semantic_id}}A declared backend capability. The tool's own description and parameter schema guide when and how it is called.A backend lookup, validation, or generator. See Managing Tools.

KB vs Tool description​

Put domain meaning in Knowledge and routing mechanics in Tool metadata:

  • Knowledge explains when a capability matters to the user's workflow, what terms mean, and how to interpret the result.
  • Tool descriptions explain use cases, non-use cases, required parameters, recoverable errors, and what resource kind the tool returns.
  • If no declared tool fits the user intent, the assistant should answer honestly instead of trying a nearby tool.

Authoring rules​

  • Tokens are case-insensitive on the kind ({{Form:...}} works) and lowercase on the semantic id.
  • Tokens inside fenced code blocks (```) are treated as documentation and skipped.
  • Each token's semantic id must exist in the registry; unresolved tokens render in plain prose without an action attached. The Backoffice editor surfaces an "unresolved" badge on save.
  • Listing {{form:online-service-form}} and then {{form:online-service-parameter}} in the same entry tells the assistant that those are consecutive workflow chunks. The model should propose the current-view chunk first unless the user explicitly asks for the whole sequence.

Example:

## Onlinedienst anlegen

1. {{control:action-create}} öffnet ein leeres Formular.
2. Befüllen Sie {{form:online-service-form}} mit den Pflichtfeldern.
3. Fügen Sie vier Pflichtparameter über {{form:online-service-parameter}} hinzu.
4. Speichern über {{control:action-save}}.

Visibility and access control​

Each entry has a visibility setting that controls who can read it (independent of who can edit it; editing is always restricted to your workspace):

VisibilityWho can read it
PublicAnyone visiting your domain, including anonymous extension users and unauthenticated widgets. Best for general FAQs, onboarding, anything you'd publish on a help-centre site.
AuthenticatedMembers of your workspace who are signed in via the Appilot extension (or callers of an authenticated widget key for your org). A visitor signed in to a different org's workspace does not see Authenticated entries on your domain.
InternalAdmins of your workspace only (Backoffice access). Best for troubleshooting notes and operational runbooks you do not want every workspace member to see.

The "Private" chip in the extension​

When a visitor opens the extension on your domain and the page has only Authenticated/Internal entries that they can't read, the chip at the top of the panel reads "Private · N docs" with a tooltip explaining the owner restricted access. The visitor sees the aggregate count (so they know help exists), but never sees titles or content. To make a doc reachable to a general audience, set its visibility to Public.

Setting visibility per entry​

In the content editor, use the Visibility dropdown.

Setting a default for the app​

  1. Go to Apps in the Backoffice → open your app → Settings.
  2. Set Default Visibility for New Entries.

Widget key access level​

Each widget API key has a knowledge_access_level (public or authenticated). A public widget key sees only public entries; an authenticated widget key sees public + authenticated. The widget key carries the workspace identity, so an authenticated widget key always satisfies the ownership check on Authenticated entries. Pick the level that matches your embedding context. See Widget keys.

Importing knowledge from a PDF​

For applications with existing documentation, use the Import from PDF workflow rather than re-typing:

  1. Navigate to Knowledge → Import from PDF.
  2. Select a PDF file (max 50 MB).
  3. Optionally associate with an application and domain.
  4. Click Start Import. The AI processes the document in the background:
    • Splits the PDF into sections by numbered headings.
    • Extracts knowledge entries.
    • Creates entries as drafts (inactive).
  5. Once processing completes, the Review screen lists the extractions. Each shows title, description, scope, and an optional URL pattern.
  6. Deselect low-quality extractions. Click Publish selected to activate.

When to use Import from PDF vs RAG files vs hand-authored Knowledge​

SourceBest forTrade-off
Hand-authoredThe 4–8 core domain_global entries; spine workflowsHighest quality, highest effort
PDF importMining structured user manuals where each heading is a candidate entryLower effort, drafts need editorial review before publishing
RAG filesReference material the agent retrieves on demand: regulations, glossaries, long manualsLowest effort, agent retrieves chunks per turn, never pre-loaded

The right mix: hand-author the spine, PDF-import the rest of your manuals, RAG-ingest your reference library.

Knowledge request workflow​

When users can't find answers, they create requests (Missing Knowledge inbox). An effective weekly cadence:

  1. Triage: review incoming requests.
  2. Prioritise by frequency: if multiple users ask the same thing, address it first.
  3. Create content: write the Knowledge entry that answers the question.
  4. Resolve: mark the request resolved; the user is notified.
  5. Verify coverage: re-check that the new entry answers similar future questions in the Test Chat.

Full workflow: Requests management.

Content organisation​

The Backoffice lets you filter and search Knowledge by:

  • Domain
  • Scope and linked Views
  • Status (draft / in review / published)
  • Visibility
  • Creation or update date

For large knowledge bases across multiple apps, use the Views addressing model to attach entries to the right surfaces; see Managing Views.