Add system-level and vendor Knowledge packs to a Role Assistant so agents learn substance without treating documents as Evidence or Reality. Knowledge answers “what reusable understanding already exists?” — not “what is true right now?” and not “what gate must fire?”
Why this matters: Governed Runtime without substance invents or stalls. Knowledge packs give reusable vendor and domain understanding — so the assistant can act in your process with shared meaning, stay testable beside Evidence, and never confuse documents with Reality or CIP.
Choose and verify document derivation models using Configure AI models by job. A saved Role Assistant document model applies to its supported document reasoning job; it does not change every workflow or automatically rebuild existing Knowledge.
Prerequisites
- Role Assistant package on disk (Manage Role Assistant packages)
- Domain Evidence (process and asks) already planned where needed — Author Role Assistant Evidence
- Concept background: Enterprise Knowledge
- Optional prove-out after sync: Test Role Assistants
Where it lives
| Artifact | Package path |
|---|---|
| Knowledge markdown packs | knowledge/ under the Role Assistant package |
| Optional storage key | knowledge.documentStorageKey in each dev / tst / pro settings section |
Knowledge describes how a vendor family or organization topic works. It is not Evidence, not current Reality, and not CIP/COM executable mappings.
Learning levels (same machinery, different stores):
| Level | Teaches | Store |
|---|---|---|
| Process / asks | How governed work proceeds; closed questions | Evidence |
| Domain purpose | Why the domain exists; Resource Types | Evidence and/or Knowledge summaries |
| Subject substance | This vendor or org topic | Knowledge packs |
How to set
-
Domain first: reuse shared domain Evidence; add L1 Knowledge only for missing substance on this subject.
-
Author markdown under
knowledge/with clear metadata (system type, vendor family, learning level, aspect). Prefer short guided docs: entities to Resource Types, fields, uniqueness, relationships, anti-patterns.
Example frontmatter shape (names vary by pack — keep product-neutral in customer docs):
title: Entities for acme-crm family
systemType: vendor
vendorFamily: acme-crm
learningLevel: 1
aspect: entities
-
Do not paste full OpenAPI or gold manifests into Knowledge. Quirks belong as short guidance, not dumps. Ask-only lists stay small when Evidence and Knowledge already apply.
-
Sync through the governed document-storage / Builder path for the Role Assistant. There is no public “create Knowledge Asset” CLI — optional later derive is Runtime-owned.
-
Promote settings when the document-storage key changes:
aifabrix validate ra-<roleKey>
aifabrix upload ra-<roleKey> --env dev
Example settings excerpt:
apiVersion: aifabrix.ai/v1
kind: RoleAssistantSettings
roleKey: sales-representative
dev:
runtime:
provider: openai
model: gpt-5-nano
knowledge:
documentStorageKey: ""
The explicit empty documentStorageKey above clears the selected environment’s stored key on upload. Omit the knowledge.documentStorageKey field when you intend Builder to use the key already saved on the Dataplane Assistants settings page. A supplied target must belong to a Connected System declaring the assistant’s business role.
- Prove with lifecycle or cases after Knowledge is available to the running assistant:
aifabrix role-assistant test <roleKey> --env dev
L2/L3 Evidence (domain + process)
→ L1 Knowledge packs (substance)
→ document storage sync
→ role-assistant test
Defaults and examples
| Aspect (examples) | Why it helps |
|---|---|
| Entities → Resource Types | Stops wrong catalog keys |
| Fields / uniqueness | Safer create and update |
| Relationships | Join understanding without inventing FK names |
| Anti-patterns | Known failure modes to avoid |
| Auth pattern | Variables vs secrets — not secret values |
| Phases | Which datasource first; what “later” means |
Filled discovery answers are Knowledge. Question templates remain Evidence.
Second subject in a known domain: reuse L2/L3 Evidence and fill only missing L1 Knowledge.
Validate
| Check | Signal |
|---|---|
| Package validate | aifabrix validate ra-<roleKey> |
| Settings upload | Upload summary for the selected --env |
| Assistant behavior | Fewer redundant asks after Knowledge sync; lifecycle/cases |
| Boundary check | No vendor OpenAPI dumps landed under evidence/ |
If asks still fire for facts already covered in Knowledge, check sync and metadata filters (vendor family / system type) before rewriting Evidence.
Common mistakes
| Mistake | Fix |
|---|---|
| Storing Knowledge as Evidence | Keep substance under knowledge/ |
| Inventing a Knowledge Asset create CLI | Use document-storage sync; derive is Runtime-owned |
| Pasting full OpenAPI | Summarize quirks; keep contracts in Connected System manifests |
| Skipping domain Evidence | Reuse L2/L3; fill only missing L1 |
| Putting secrets in Knowledge markdown | Use secret store / env templates |
Limits
- Exact sync commands and storage keys follow your Builder and dataplane deployment.
- Vendor family names in local packs are for that subject only — do not treat them as platform-wide Product names in customer narrative.
- Knowledge does not certify Evidence or replace Operational Trust gates.
- This page does not create Role Assistants from scratch.