Choose the workflow, then the provider
The knowledge package contains static and vector retrieval, document processing, embeddings/indexing orchestration and retrieval-augmented queries. Its runtime convenience layer can compose ingest, retrieve and answer using supplied embedding, vector-store and LLM providers. Start with the space and namespace that express the intended source scope. Choose a static retriever for a deterministic source walkthrough or small fixture; choose vector retrieval when the application supplies a suitable indexed store and ingestion lifecycle. Neither choice removes access-policy responsibilities.
Keep the source and retrieval layers connected
The package exposes source-management operations and named knowledge spaces, including support FAQs, uploaded documents and Product Canon. Ingestion produces searchable material; retrieval selects material relevant to a query. Preserve original source identity, version and evidence locators through that transformation so a caller can inspect what supports an answer. Connector readiness manifests are useful for understanding supported composition paths, but the source explicitly distinguishes those manifests from live provider calls and production writes.
Bind access and context before answering
KnowledgeAccessGuard and grounding helpers provide the boundaries for scope-aware retrieval. The query result should remain connected to its allowed sources and citations. An agent context compiler can then enforce required inputs, trust classes and budgets. Avoid treating a retrieved passage as a new instruction authority or as permission to mutate a system. For knowledge mutations, the package separately documents dry runs, approval, idempotency, audit evidence and outbound-send gates; those checks belong to the selected mutation flow.
Follow a practical path.
Trace one source document
Identify its knowledge space, namespace, source policy and original evidence location. Follow processing and indexing into a retrieval result, then check whether the answer preserves a useful citation back to the selected source.
Compare retrieval modes
Use a static fixture to understand expected relevant passages and denied scope. Then inspect the equivalent vector-backed composition: provider selection, collection, ingestion revision and query behavior. Keep storage and model configuration explicit.
Review a stale or removed source
Inspect the owning workflow’s behavior when source content changes, access is revoked or a required item is missing. The appropriate outcome may be reindexing, exclusion or an unavailable-context result rather than an apparently complete answer.