Setting the file. One moment.
Subchapter 10.21
agents/connect.mdMarkdown8 KBView on GitHub
Connect one Prompt/Hosted Agent; optionally create it if missing. KB: content; project connection: auth; agent MCP tool: versioned use.
Do not replace agents, attach multiple base tools, or handle base-free lifecycle. Permission error is not absence; creation approval is separate.
Resolve prompt, session, workspace, exact Azure readback, default, then one focused question. Label sources; missing input blocks. Reads need no approval; silence approves nothing.
| Input | Why needed | Required? | Discovery order | Safe default | If missing or unanswered | Reconfirmation trigger |
|---|---|---|---|---|---|---|
| Base return/MCP endpoint | Grounding | Required | Session, exact proof | None | Block | Base/API/evidence change |
| Project ID/endpoint | Target | Required | Prompt, workspace, readback | None | Block | ID/tenant change |
| Agent name/inventory/type | Identity | Required | Prompt, readback | Never latest/type | Block ambiguity | Inventory/type |
| Definition/model/baseline; Hosted telemetry | Preservation | By branch | Exact readback | Preserve unrelated fields | Block | Protected state |
| Connection/tool; Hosted toolbox/environment | Binding | By branch | Full readback | One retrieve binding | Block conflict | Binding/endpoint |
| Principal/reader role | Retrieval | Before assignment | Readback | Exact Search scope | Block | Assignment |
| Grounding delta | Evidence | Required | Instructions | Base/citations/I don't know | Block loss | Delta |
| Acceptance/unrelated questions | Verification | Before invocation | Authorized evidence | None | Propose candidate | Questions |
| Cleanup/retention owner | Ownership | Required | Prompt/session | None | Block | Owner |
| Provider/install or CLI choice | Missing agent | Conditional | Runtime, then choice | No automatic fallback | Block | Availability/choice |
Use policy diagnostics only after a creation failure implicates policy, never as a gate.
Read exact IDs/all scoped pages; inaccessible is not absent:
Only for a missing agent, load missing-agent creation
before questions/plans. Prefer microsoft-foundry: delegate approved
identity/configuration and known requirements. Otherwise offer installation
or Prompt CLI creation. Installation refusal is not creation approval.
Require a typed return with project, agent, version/deployment, model/status/identity
and definition/source/config/environment. Independently read back;
use fresh discovery and a new fingerprinted connection plan;
never carry creation approval. Incomplete returns block.
Read the authenticated knowledgebases API, never generated indexes
or foundryextensions_knowledge_index_list. Existing multi-source KBs are valid.
Preserve valid KB effort/output/models; preview MCP supports reasoning/synthesis.
Use the exact preview API in SDK; native GA minimal/extractive MCP exists.
KB model: low or medium with supported output; preview minimal/answerSynthesis is valid.
Use the approved KB transition
only when an explicit model-free normalization is needed.
Never change the KB implicitly or add a model as a workaround.
Only when authenticated Foundry MCP is unavailable or lacks a required operation,
load typed Prompt SDK fallback.
Denial/conflict blocks. Bind the surface; switching requires fresh review, never bypass.
List delta, API, identity/scope, network/data, cost, verification, owner and retained IDs.
Approve concrete changes once; plan_fingerprint stays internal, with
cleanup_approved: false. Delegated creation is separate. A Hosted principal
known only after deploy requires a separate RBAC plan. Material/protected-state
drift invalidates approval; disclose bounded Prompt warnings below.
After confirmation, use exact identities; never retry another name.
Prompt: Use the planned MCP or SDK surface; never invent operations.
Reconcile one 2025-10-01-preview
RemoteTool connection with ProjectManagedIdentity, Search audience, and the
2026-08-01-preview KB MCP endpoint. Require the exact Search-service-scoped
Search Index Data Reader assignment to observed PROJECT identity.principalId,
not agent identity. Preserve all fields; add/switch at most one
same-label MCPTool with exact endpoint/connection,
allowed_tools: ["knowledge_base_retrieve"], and require_approval: "never".
Under the same agent name, require retrieval for every question, including
unrelated questions. Answer from retrieved evidence, not general knowledge;
unsupported answers are exactly I don't know without citations;
retrieval errors must remain errors. Approve exact appended instructions;
preserve previous instructions/versions. Duplicate labels block.
Search provisioning alone is not a connection-write blocker when the KB GET is
healthy; warn, never claim retrieval readiness. Failed/auth/deletion states block.
After exact identity/binding checks, type metadata differences and boolean
isSharedToAll: true-to-false restriction warn without rewriting. Missing/malformed
sharing, broader access, wrong target/auth/audience/category/required metadata
block. Apply the same rules to reuse; require actual agent tests below.
Hosted: Follow the selected Hosted connection procedure. Only approved missing resources, binding differences and required deployments are writes; exact existing state skips them all. Never replace agents; source edits need separate review/handoff.
Verify protected fields, a knowledge_base_retrieve call with original
citations, and unrelated I don't know without citations. Preserve behavior;
rerun with stable IDs and zero configuration writes. Account separately for
requested invocations, conversations/sessions and their usage. Record actual
tool execution and returned evidence separately from answer behavior; unavailable
payloads leave payload-level faithfulness unverified, not an inferred empty result.
Preserve first status/message/request ID. Denial, conflict, incomplete delegation, failed citations, unknown principal or drift blocks. Record writes, evidence, ownership, recovery and warnings; never widen state.
Separate fingerprinted cleanup deletes only run-owned artifacts in reverse.
Prompt uses helpers/prompt_cleanup.py with exact digests. Hosted returns
hosted-cleanup-unsupported, zero writes, retaining all resources.
Unclear ownership blocks.
Return planned/completed/blocked/partial: exact actions/resources,
invocation/readback evidence, ownership, failure, warnings and cleanup status.
Authorities: failure/conflict/uncertainty only.