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.
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 <roleKey>
aifabrix upload <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: ""
Leave documentStorageKey empty when the dataplane Assistants settings page already holds the key for that Role Assistant.
- 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 <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.