Setting the file. One moment.
Subchapter 10.71
knowledge-bases/create.mdMarkdown8 KBView on GitHub
Create exactly one KB over one verified File, Blob or ADLS Gen2 source. Single-source helper; Azure supports multiple sources.
Not multiple sources, unsupported connectors, classic Search or agents. Never mutate conflicts, select duplicates or call GA extraction synthesis.
Reuse prompt/session/workspace/exact Azure readback; then one focused question. Label sources; silence is not approval. Reads need no approval.
| Input | Why needed | Required? | Discovery order | Safe default | If missing or unanswered | Reconfirmation trigger |
|---|---|---|---|---|---|---|
| Tenant/subscription/group/region | Scope | Yes | Azure/selection | Propose absent group | Ask | Scope |
| Search ID/endpoint | Target | Pre-source | Discovery/bootstrap | Honor reuse/new | Bootstrap absent | Target |
| Source ID/type/boundary/definition | Grounding | Pre-approval | Source GET | None | Create absent; block unverified | Source |
| Base name/owner/purpose | Identity | Yes | Prompt/caller/GET | Azure user | Override | Identity/owner |
| Outcome/API/mode | Response | Yes | Prompt/GET | GA Blob: minimal/extractive | Block unsupported | Outcome/API |
| Effort/model/version/capacity | Preview | Conditional | Choice/bootstrap | Minimal/extractive | Resolve | Model/capacity/region |
| Caller/roles | Retrieval | Pre-query | Discovery/bootstrap | Service reader | Plan missing roles | Identity/scope |
| Network/permissions | Security | Required | Source/Search GET | Preserve | Block | Posture |
| Source identity | Source binding | Required | Source inventory | None | Block | Identity change |
| Acceptance/unrelated questions | Retrieval audit | Opt-in | Authorized evidence | Not requested | Defer audit | Question change |
| Cleanup owner | Recovery | Yes | Prompt, session | Cleanup not approved | Block | Owner change |
Offline audit is opt-in; no Q&A required for creation. Propose title/content questions from authorized content, not filenames/structural facts. No samples/questions: defer audit; separate query consent. Audit/filename.
Default explicitly to minimal/extractive.
Minimal extractive KB adds no model; preview minimal permits synthesis.
Low/medium or synthesis needs a KB model, separate from source CU/embeddings.
Omitted KB/request effort defaults to low, not the portal’s Minimal selection.
Retrieval/answer instructions: optional, preview-only. API auto: explicit handoff.
Select/recheck Search operation first: owner. For low/medium or synthesis, select/reuse chat or bootstrap approved model/version/region/capacity/cost/access. Verify readiness, resume KB creation; never downgrade. Other infrastructure stays shared; no routine policy reads.
Retain source IDs/API/boundary/definition, ownership/health/permissions/reuse,
content assessment/uncertainty, answer needs and ingestion mode through prerequisites;
resume KB plus validated retrieval, not source-only. Readback drift blocks.
Only then present the KB plan; never preapprove a future verified_source
or reuse bootstrap consent for KB mutation.
GET exact name; only FIND paginates. Normalized match: zero-write. Multiple compatible KBs require exact-ID selection. Same-name conflict/inaccessible blocks. Choose:
minimal: direct extractive grounding. Blob-only, non-agentic,
non-permission-preview work defaults to GA 2026-04-01, with no preview-only
fields or synthesized I don't know.intents.extractiveData or answerSynthesis.
Low is one-pass; medium may follow up. Preserve a low miss and ask one tradeoff
question; never auto-escalate.File/synthesis/permissions/low/medium require approved preview. Prompt uses preview; GA MCP is minimal/extractive.
Optional, not a required step for every agent connection; preserve valid KB reasoning/synthesis.
Read the existing GA minimal KB through 2026-08-01-preview; verify its source.
With separate approval, use action: update and the current ETag to set only
outputMode: extractiveData and retrievalReasoningEffort: {kind: minimal}.
Leave models, source contents, RBAC and networking unchanged;
preserve unrelated fields; conflicts block.
Verify agent MCP retrieval; GA isn’t MCP proof.
Read helper contracts before planning.
Use KB intent/wire:
python helpers/search_reconcile.py --plan <intent.json>.
Show IDs/source/owner/API/mode/model, data/access/cost, optional acceptance,
actions/verification/cleanup/retained resources. No write.
Keep immutable proposed mutation plan/plan_fingerprint, cleanup_approved: false.
Approve concrete changes once.
Changed source/mode/model/boundary/access, acceptance or freshness requires review;
never ask users to calculate or repeat hashes.
After approval, invoke:
python helpers/search_reconcile.py --input <approved-envelope.json>reconcile/knowledge-base binds endpoint/name/API/definition/owner,
cleanup_approved: false, verified source name/normalized same-API digest.
Before create/update/reuse, a fresh source GET must match.
Block absent/unreadable/drift, mode/API mixing and extra sources.
Conditional create/ETag-update reads back. Exit 2: blocked/no-write;
3: partial.
Preserve API settings and reuse roles/dependencies. Never overwrite conflicts, add sources, resize models, broaden access or modify source/generated children. Resolve ambiguity on the same identity.
Verify owner/source/API/mode/model/keyless access/roles/network.
Use REST Retrieve with consent; check grounding/native references/activity, no MCP.
Errors remain incomplete.
Without query consent: retrieval_status: not-tested; KB creation is separate.
Requested retrieval stays incomplete until verified.
Default audit_status: not-requested; no paired bundle required.
Opted-in audits: original File path plus file ID or Blob/ADLS URL/path plus
ETag/version; a bare path/URL is insufficient. Missing proof stays unverified.
For authorized unrelated questions, answerSynthesis requires semantic abstention per the
abstention criteria and any explicit exact-output contract.
GA/preview extractiveData requires no supporting extracts.
Recheck stable IDs/zero writes.
Optional: Connect.
Preserve first status/message/request ID. Low failure never authorizes medium.
Citation/access/model/region/definition/source mismatch blocks.
blocked: evidence, no writes, next decision.
partial: writes, unverified state, ownership and separately approved cleanup.
Receipts: retain pre-create.
Separate cleanup plan/approval: run-owned KB before exclusive owned dependencies.
Keep reused resources, source content, retained sources’ children/shared roles.
operation: delete: owned digest/fresh ETag; unclear ownership blocks.
Return status/IDs/API/mode/model, access/data movement, verification, first failure/warnings/ownership/cleanup; hide digests.
Authorities: failure/conflict/uncertainty only.