Setting the file. One moment.
Subchapter 10.14
references/platform-interfaces.mdMarkdown8 KBView on GitHub
| Operation | Contract |
|---|---|
| Search substrate management | management API |
2025-05-01| Resource group prerequisite | ARM 2022-09-01 |
| AI account | ARM 2025-06-01; File CU GET/listKeys 2024-10-01 |
| Search data plane | Entra audience https://search.azure.com/.default |
| File knowledge source and file operations | 2026-08-01-preview |
| Blob knowledge source | GA 2026-04-01; preview for selected preview features |
| ADLS Gen2 knowledge source | This helper uses 2026-08-01-preview |
| Existing Blob validation | Entra audience https://storage.azure.com/.default; Blob x-ms-version: 2025-11-05 |
| Existing Prompt Agent connection | authenticated Foundry MCP preferred; azure-ai-projects>=2.4.0,<3 typed fallback; Agent API v1; project-connection ARM API 2025-10-01-preview; KB MCP endpoint 2026-08-01-preview |
| Existing Hosted Agent connection | GET-only toolbox assessment; source-backed azd recipe; AgenticIdentityToken; KB MCP 2026-08-01-preview |
Execution surfaces:
| Workflow | Surface |
|---|---|
| Missing group/Search/models/RBAC | Conditional references/bootstrap-azure.md: native Azure CLI/ARM; no host fixture |
| File read-only plan / approved source plus upload | helpers/file_source.py --plan request.json / --input approved-envelope.json |
| Blob/ADLS read-only plan / approved application | helpers/blob_source.py --plan intent.json / --input approved.json |
| Source vector verification plan / separately approved query | helpers/source_vector.py --plan verify.json / --input approved-query.json; contract |
| Knowledge-base reconciliation / source or KB cleanup | helpers/search_reconcile.py |
| Existing Prompt fallback connect/delete | helpers/prompt_connect.py / helpers/prompt_cleanup.py |
| Hosted assessment / source-backed connection | helpers/hosted_connect.py --plan intent.json / agents/connect-hosted.md |
Receipts preserve the first nonempty case-insensitive value for
x-ms-request-id or Azure Search’s request-id, preferring the former when
both are present. Client-generated/echoed request IDs are not server provenance; missing server IDs remain missing.
Standalone retrieval uses Entra-authenticated Search REST:
GET /knowledgebases('<escaped-name>')?api-version=<version>, then
POST /knowledgebases/<name>/retrieve?api-version=<version>.
GA and preview minimal use intents; preview low/medium can use messages.
Read the selected definition and preserve its API/mode/effort. See
Retrieve for request construction, permission
forwarding and response verification. No MCP connection is required.
Prompt/Hosted Agent connections still use the exact KB’s native MCP endpoint
(/knowledgebases/<knowledge-base>/mcp?api-version=<api-version>) and
knowledge_base_retrieve. REST retrieval is not proof of agent tool use.
Neither path substitutes the generic Azure MCP Server search_* group or an
index query. Preserve first errors; never persist tokens or use Search/Storage keys.
An azd projection may omit audience; a typed MCP reader may return
UnknownConnectionPropertiesV2 for AgenticIdentityToken. For those schema
gaps, read the observed Microsoft.CognitiveServices/accounts/projects/connections
resource ID without fetching credentials:
az resource show --ids <exact-connection-resource-id> --api-version 2025-10-01-preview --query "{id:id,category:properties.category,authType:properties.authType,target:properties.target,audience:properties.audience}" --output jsonRequire the approved ID, RemoteTool, AgenticIdentityToken, KB MCP target and
https://search.azure.com/ audience. Compare other protected fields when needed.
Never use --show-credentials, keys or secret endpoints. This supported ARM GET
is diagnostic readback, not an alternative mutation surface or an authorization
bypass. Denial, mismatch or missing required fields still blocks.
| Request | Service availability and helper choice |
|---|---|
| File non-image minimal | Service: 2026-05-01-preview/2026-08-01-preview; helper August (multipart metadata, 200 files) |
| File CU or images | 2026-08-01-preview, standard; planner and executor supported. May rejects images; minimal returns 415 in both. CU is independent of source vectors |
| Blob minimal or standard CU | 2026-04-01 GA unless a selected feature requires preview; CU alone does not force preview |
| ADLS in this helper | 2026-08-01-preview; do not describe a helper restriction as a platform prohibition |
| Permission/private ingestion | Preview properties require 2026-08-01-preview; this source planner does not implement either, schedules or user-assigned identities |
| KB low/medium, synthesis or agent connection | Explicit preview configuration; GA helper is minimal/extractive. KB models and source embeddings/CU are separate |
File --plan optional api_version defaults to August; unsupported:
compatible-client handoff, never silent upgrade.
Choose source/KB APIs separately; no GA preview fields, silent downgrade,
unsupported helper features or skillset edits.
Admission is not content fit: owners assess structure/answer needs.
The File service detects content type; MIME cannot override it. Minimal accepts
PDF, DOC/DOCX, PPT/PPTX, XLS/XLSX, JSON, shell scripts and detected text/*,
including TXT/MD/HTML/CSV. The helper preserves bytes and deterministic filename
hints, not detected types. Unknown/extensionless files use application/octet-stream.
Search-detected images need August standard; hints cannot require CU or block minimal.
Upload only selected paths; never execute scripts, unpack archives or auto-include hidden files. Credential targets, including selected root components, are blocked; this is not a secret scan. Preserve tier/count/root/link guards and historical artifact bytes/MIME/fingerprints. Server 415 stops ingestion, retaining earlier writes/source ownership and first failure; never completed.
Blob indexer formats apply to Blob/ADLS knowledge sources: CSV, EML, EPUB, GZ, HTML, JSON, KML, MD, DOC/DOCX/DOCM, XLS/XLSX/XLSM, PPT/PPTX/PPTM, MSG, Word XML 2003/2006, ODT/ODS/ODP, PDF, plain text, RTF, XML and ZIP. Generic Storage MIME is not grounds for rejection. Compound/archives are one blob document before chunking, not one KB document per entry. Never unpack/upload/modify blobs or widen scope. Require successful ingestion, not just source acceptance.
CU skill formats are PDF, JPEG/JPG, PNG, BMP, HEIF, TIFF, DOCX, XLSX, PPTX, HTML, TXT, MD, RTF,
EML. Blob indexer acceptance does not prove CU support for ZIP/legacy Office.
Both limits apply, including the five-minute CU timeout; no universal support.
File follows its detected-type contract, not this Blob CU list.
CU image descriptions/semantic chunking: preview since 2026-05-01-preview;
not exposed by this planner.
Authorities: failure/conflict/uncertainty only.
File (opens in a new tab), Blob indexer (opens in a new tab), CU skill (opens in a new tab). Schemas: RG (opens in a new tab), AI ARM (opens in a new tab). Scope (opens in a new tab) and assignments (opens in a new tab).