Merge pull request #641 from Azure/placerda-hosted-agent-docs-v2

docs: record hosted readiness blocker

Author: placerda

docs/architecture.md

@@ -7,15 +7,16 @@ deployments retain their persisted topology during upgrade. Network isolation,
 enterprise integration, public ingress, and optional AI capabilities remain
 separate choices.
 
-!!! warning "Exact matrix pinned; live evidence gates remain"
+!!! warning "Exact matrix pinned; runtime validation and release remain blocked"
     UI `v2.6.0`, orchestrator `v4.0.0`, ingestion `v2.7.0`, and AILZ `v2.5.0`
     are pinned by the umbrella integration and implement the delegated
     `x-ms-user-identity` contract. Classic, hosted/no-panel, and explicitly
     selected hosted-panel are supported topologies. Continuity, user-history,
     owner-binding validation, and operator-surface gates remain
-    deployment-published `false`, so their routes stay off/503; no live
-    validation result is implied. See the
-    [hosted-agent supported matrix](hosted_agent_release_matrix.md).
+    deployment-published `false`, so their routes stay off/503. The agent version
+    became active in the latest runtime attempt, but session readiness returned
+    HTTP 424. The integration is not runtime-validated or shipped. See the
+    [hosted-agent integration matrix](hosted_agent_release_matrix.md).
 
 ## Full Zero Trust reference
 
@@ -72,6 +73,9 @@ The lower lane in the diagram shows the planned two-phase hosted image flow:
 provision prerequisites, build through public ACR Tasks or the dedicated
 VNet-connected ACR Tasks agent pool, resolve the hosted image to an immutable
 `sha256` digest, provision the digest-backed hosted handoff, and deploy.
+The child hosted service remains a Docker service with remote build enabled,
+while `AZD_AGENT_SKIP_ACR=true` selects the already-prepared image during the
+child deployment.
 
 ## Complementary modular views
 
@@ -98,11 +102,11 @@ Use the table below for the deployment parameters behind each layer, and the [De
 
 | Layer | Posture | Controlled by | Include when |
 | --- | --- | --- | --- |
-| UI, chat runtime, ingestion | Mode-selected baseline | Canonical `DEPLOYMENT_TOPOLOGY`; materialized `DEPLOY_HOSTED_AGENT_ORCHESTRATION`, `DEPLOY_ADMINISTRATIVE_PANEL`, `CHAT_BACKEND`; `manifest.json` components; `containerAppsList` | The umbrella manifest pins the exact supported matrix. Existing topologies stay sticky, `classic` selects the Container Apps fallback, hosted/no-panel is the fresh default, and hosted-panel requires explicit operator selection while its independent evidence gates remain off/503. |
+| UI, chat runtime, ingestion | Mode-selected baseline | Canonical `DEPLOYMENT_TOPOLOGY`; materialized `DEPLOY_HOSTED_AGENT_ORCHESTRATION`, `DEPLOY_ADMINISTRATIVE_PANEL`, `CHAT_BACKEND`; `manifest.json` components; `containerAppsList` | The umbrella manifest pins the exact integration matrix. Existing topologies stay sticky, `classic` selects the Container Apps fallback, hosted/no-panel is the fresh default, and hosted-panel requires explicit operator selection while its independent evidence gates remain off/503. Runtime readiness is not yet validated. |
 | AI Foundry account, project, and model deployments | Required AI control plane | `deployAiFoundry`, `deployAfProject`, `deployAAfAgentSvc`, `modelDeploymentList` | Provisioning Azure AI Foundry / Azure OpenAI and the model deployments used by GPT-RAG. |
 | AI Foundry associated resources | Default-created or BYO-capable | `aiSearchResourceId`, `aiFoundryStorageAccountResourceId`, `aiFoundryCosmosDBAccountResourceId`, `keyVaultResourceId`, `aiFoundryStorageSku` | Letting the AI Foundry module create its required Storage, Search, Cosmos DB, and Key Vault resources, or reusing existing ones. |
-| RAG workload data services | Mode-selected, parameter-controlled | `deploySearchService`, `deployStorageAccount`, `deployCosmosDb`, `storageAccountContainersList`, `databaseContainersList` | Running indexed-document and file-storage paths. Hosted/no-panel uses Foundry managed Conversations and omits panel-only Cosmos DB; classic preserves its existing state path. |
-| App Configuration, identity / RBAC, Container Apps, Container Registry | Required platform capabilities, topology varies by mode | `deployAppConfig`, `deployContainerApps`, `deployContainerEnv`, `deployContainerRegistry`, `useUAI`, service role lists | Publishing the sticky topology and runtime contract, hosting UI/ingestion, and preparing immutable images. Hosted/no-panel does not provision an orchestrator Container App. Delegated continuity grants the two exact direct agent-scoped roles only to the UI BFF after protocol and owner-binding validation. |
+| RAG workload data services | Mode-selected, parameter-controlled | `deploySearchService`, `deployStorageAccount`, `deployCosmosDb`, `storageAccountContainersList`, `databaseContainersList`, `SEARCH_SERVICE_UAI_RESOURCE_ID` | Running indexed-document and file-storage paths. Private Search uses its explicit Search UAI. Hosted/no-panel uses Foundry managed Conversations and omits panel-only Cosmos DB; classic preserves its existing state path. |
+| App Configuration, identity / RBAC, Container Apps, Container Registry | Required platform capabilities, topology varies by mode | `deployAppConfig`, `deployContainerApps`, `deployContainerEnv`, `deployContainerRegistry`, `useUAI`, service role lists | Publishing the sticky topology and runtime contract, hosting UI/ingestion, and preparing immutable images. Hosted/no-panel does not provision an orchestrator Container App. Hosted-panel resolves exactly one managed-identity principal per Container App and limits Cosmos grants to frontend Contributor plus ingestion Reader on the two panel containers. Delegated continuity grants the two exact direct agent-scoped roles only to the UI BFF after protocol and owner-binding validation. |
 | Workload Key Vault and observability | Default support, parameter-controlled or reusable | `deployKeyVault`, `deployLogAnalytics`, `deployAppInsights`, `EXISTING_LOG_ANALYTICS_WORKSPACE_RESOURCE_ID`, `EXISTING_APPLICATION_INSIGHTS_RESOURCE_ID`, `EXISTING_APPLICATION_INSIGHTS_CONNECTION_STRING` | Storing workload secrets and capturing telemetry. The delegated primary continuity path does not provision or require a capability key or dedicated continuity vault; those inputs remain disabled fallback-only. Application Insights is created or wired only when an effective Log Analytics workspace is available. |
 | Zero Trust private networking | Optional security posture | `networkIsolation`, `allowedIpRanges`, `useExistingVNet`, `deploySubnets`, `policyManagedPrivateDns`, `EXISTING_PRIVATE_DNS_ZONE_*` | Requiring private endpoints, private DNS, VNet integration, NSGs, and internal Container Apps ingress. |
 | Azure Firewall, Jumpbox, Bastion, NAT Gateway, private ACR build pool | Zero Trust operations/build options | `DEPLOY_AZURE_FIREWALL`, `DEPLOY_JUMPBOX`, `DEPLOY_BASTION`, `DEPLOY_NAT_GATEWAY`, `DEPLOY_ACR_TASK_AGENT_POOL`, `EXISTING_JUMPBOX_RESOURCE_ID`, `EXISTING_BASTION_RESOURCE_ID`, `EXISTING_NAT_GATEWAY_RESOURCE_ID` | Operating inside the VNet or reusing central access/egress resources. The gated hosted flow uses the dedicated VNet-connected ACR Tasks agent pool for private builds; shared ACR Tasks cannot reach a private endpoint. |

docs/deploy.md

@@ -53,15 +53,17 @@ ingestion services in the classic Container Apps topology.
 
 ### Chat runtime modes
 
-!!! warning "Exact matrix pinned; evidence-gated surfaces remain off"
+!!! warning "Exact matrix pinned; runtime validation and release remain blocked"
     UI `v2.6.0`, orchestrator `v4.0.0`, ingestion `v2.7.0`, and AILZ `v2.5.0`
     are pinned by the umbrella integration at their exact release commits.
     Classic, hosted/no-panel, and explicitly selected hosted-panel are supported
     topologies. The manifest's umbrella tag remains `unreleased`; use a GPT-RAG
     source or release that contains these pins. Continuity, user-history,
     owner-binding validation, and operator-surface evidence gates remain
-    deployment-published `false`; no live validation result is implied. See the
-    [exact supported matrix](hosted_agent_release_matrix.md).
+    deployment-published `false`. The agent version became active in the latest
+    runtime attempt, but session readiness returned HTTP 424. The integration is
+    not runtime-validated or shipped. See the
+    [exact integration matrix](hosted_agent_release_matrix.md).
 
 The platform implementation resolves one canonical topology before provisioning
 and materializes the corresponding legacy flags and App Configuration values.
@@ -93,6 +95,7 @@ Configuration label `gpt-rag`:
 | `HOSTED_AGENT_AUTH_MODE` | `user_delegated` is the default and required continuity path. Under OQ-OWN, it means the trusted UI BFF derives `x-ms-user-identity`; it does not mean an OBO token is sent to the agent. OBO remains a separate retrieval flow. `service_identity` is an explicit reviewed exception that is incompatible with owner-bound continuity, so continuity stays off/503 in that mode. |
 | `HOSTED_AGENT_SSE_IDLE_TIMEOUT_SECONDS` | Finite positive wait for the next SSE event. The UI default is `60`; an infinite timeout is rejected. |
 | `HOSTED_AGENT_IMAGE_VERSION` | Canonical lowercase immutable digest in `sha256:<64-hex-characters>` form. Mutable tags are rejected. |
+| `SEARCH_SERVICE_UAI_RESOURCE_ID` | Required identity boundary for private Search. Post-provisioning preserves an explicit value or resolves the single Search user-assigned identity from the Search resource; it must not publish an empty replacement. |
 | `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT` | Generative-AI prompt and completion telemetry capture. Defaults to `false`. Set to `true` only when the deployment's data-handling policy explicitly permits sensitive content telemetry. |
 
 Hosted configuration, authentication, connection, timeout, protocol, and
@@ -243,6 +246,14 @@ This composes UI and ingestion plus only the two panel metadata containers.
 override them before their separate evidence and authorization procedures
 complete. The corresponding routes return HTTP 503 while disabled.
 
+Panel post-provisioning resolves exactly one managed-identity principal from the
+frontend Container App and exactly one from ingestion. It then creates only
+container-scoped Cosmos SQL grants on `panel-conversation-owner-index` and
+`panel-feedback`: **Cosmos DB Built-in Data Contributor** for frontend and
+**Cosmos DB Built-in Data Reader** for ingestion. Missing or ambiguous
+Container App identities fail setup. Do not substitute account-scope grants,
+grant ingestion write access, or grant the hosted agent any panel Cosmos role.
+
 The first provision creates hosted prerequisites with image preparation
 enabled but hosted deployment disabled. The preparation command clones and
 verifies the manifest-pinned orchestrator source, builds the standard image and
@@ -257,6 +268,21 @@ private endpoint. Operators may pass an already-built immutable
 `sha256:<64-hex-characters>` digest to the preparation command to skip builds.
 No lifecycle hook recursively invokes `azd provision`.
 
+The child `hosted-agent/azure.yaml` service definition is part of the prebuilt
+handoff contract. It must declare `language: docker` and
+`docker.remoteBuild: true`. The parent pre-deploy hook sets
+`AZD_AGENT_SKIP_ACR=true` in the child azd environment before
+`azd deploy orchestrator-agent`, so the already-prepared immutable image is used
+instead of triggering another ACR build. Do not remove any of these three
+settings from a prebuilt hosted deployment.
+
+!!! danger "Current runtime readiness blocker"
+    The latest implementation validation activated the agent version, but a new
+    session readiness request returned HTTP 424. This is not a successful hosted
+    runtime validation. Keep continuity and panel evidence gates false/off/503,
+    keep the classic rollback available, and do not describe the integrated
+    matrix as shipped until readiness and the remaining live checks pass.
+
 #### Explicit classic fallback
 
 Fallback is a deployment operation, not a request-time retry:

docs/hosted_agent_release_matrix.md

@@ -1,10 +1,10 @@
-# Hosted-agent supported release matrix
+# Hosted-agent integration matrix
 
 This page records the exact hosted-agent component releases pinned by the
 GPT-RAG umbrella integration on 2026-08-07 and the independent evidence gates
 that remain fail closed.
 
-!!! warning "Pins are integrated; live evidence gates remain closed"
+!!! warning "Pins are integrated; runtime validation and release remain blocked"
     The umbrella `manifest.json` pins all four exact releases below and explicit
     `hosted-panel` topology selection is supported. The manifest's umbrella tag
     remains `unreleased`; use only a GPT-RAG source or release that contains
@@ -13,9 +13,12 @@ that remain fail closed.
     `PANEL_HISTORY_OWNER_BINDING_VALIDATED`, and
     `PANEL_OPERATOR_SURFACES_ENABLED` remain deployment-published `false`.
     This documentation does not claim that their separate live evidence and
-    authorization procedures have completed.
+    authorization procedures have completed. The hosted agent version became
+    active during validation, but session readiness returned HTTP 424. Treat the
+    matrix as implemented configuration, not as a validated or shipped umbrella
+    release.
 
-## Exact published matrix
+## Exact integrated matrix
 
 | Component | Release | Reviewed release commit | Relevant contract |
 | --- | --- | --- | --- |
@@ -221,6 +224,23 @@ Managed Conversations is the only chat-content store for the hosted design.
 - The hosted runtime identity has no Conversations role, impersonation role,
   capability key, or panel Cosmos role.
 
+### Deployment identity boundaries
+
+- A private Azure AI Search deployment uses its explicit Search user-assigned
+  identity. `postProvision` preserves `SEARCH_SERVICE_UAI_RESOURCE_ID` when
+  already supplied or resolves it from the Search resource; it must not replace
+  the value with an empty identity.
+- Panel setup resolves exactly one managed-identity principal from each target
+  Container App. Zero or multiple distinct principals fail setup rather than
+  guessing.
+- The frontend principal receives **Cosmos DB Built-in Data Contributor** and
+  the ingestion principal receives **Cosmos DB Built-in Data Reader**, each
+  scoped separately to only `panel-conversation-owner-index` and
+  `panel-feedback`.
+- Neither principal receives panel access at Cosmos account scope. Ingestion
+  receives no panel write access, and the hosted agent receives no panel Cosmos
+  role.
+
 ## Operator verification and rollback
 
 The matrix and all three topologies are composed by the umbrella integration.
@@ -244,6 +264,23 @@ hosted handoff. UI and ingestion are deployed, but the orchestrator Container
 App is omitted. Do not override the deployment-published panel or continuity
 evidence flags: their routes intentionally remain off/503.
 
+The generated `hosted-agent/azure.yaml` prebuilt-image path must retain:
+
+```yaml
+services:
+  orchestrator-agent:
+    host: azure.ai.agent
+    language: docker
+    docker:
+      remoteBuild: true
+```
+
+Before the child project runs `azd deploy orchestrator-agent`, the pre-deploy
+hook sets `AZD_AGENT_SKIP_ACR=true` alongside the immutable
+`HOSTED_AGENT_IMAGE_VERSION`. These settings tell the `azure.ai.agent` host to
+deploy the prepared digest without replacing the reviewed Docker service
+contract or launching a second ACR build.
+
 Before those independent live surfaces can be enabled, validation must:
 
 1. deploy the immutable hosted image and verify the live Responses protocol;
@@ -261,6 +298,11 @@ Before those independent live surfaces can be enabled, validation must:
 8. separately validate panel user auth and the ingestion browser operator-token
    path before enabling panel flags.
 
+The latest runtime attempt does not satisfy item 1: the agent version reached
+active state, but session readiness returned HTTP 424. Preserve the fail-closed
+flags and do not describe this integration as runtime-validated or shipped until
+readiness and the remaining evidence steps succeed.
+
 The configuration contract uses:
 
 | Key | Required value or default |

docs/howto_dashboard_signin.md

@@ -6,10 +6,12 @@ If you are looking for the wider authentication picture (chat UI sign-in, On-Beh
 
 This procedure applies to the orchestrator dashboard in the currently released
 classic Container Apps topology and in the explicit classic fallback. The
-[hosted supported matrix](hosted_agent_release_matrix.md) keeps hosted/no-panel
+[hosted integration matrix](hosted_agent_release_matrix.md) keeps hosted/no-panel
 as the fresh default and supports explicit hosted-panel selection. The
 hosted-panel user-history and operator routes remain off/503 because their
-independent evidence gates are deployment-published `false`.
+independent evidence gates are deployment-published `false`. This describes the
+integrated configuration, not a shipped hosted runtime; session readiness
+currently remains blocked by HTTP 424.
 
 ## What this is
 

docs/index.md

@@ -20,13 +20,14 @@ chat runtime and retains the Container Apps orchestrator as an explicit
 fallback. See the [Architecture](architecture.md) page for the mode contract
 and required-vs-configurable deployment table.
 
-!!! warning "Exact matrix pinned; evidence gates remain fail closed"
+!!! warning "Exact matrix pinned; runtime validation and release remain blocked"
     The umbrella integration pins UI `v2.6.0`, orchestrator `v4.0.0`, ingestion
     `v2.7.0`, and AILZ `v2.5.0`. Explicit hosted-panel topology selection is
     supported, but continuity, user-history, owner-binding validation, and
-    operator-surface gates remain deployment-published `false`; this page does
-    not claim live validation has completed. See the
-    [hosted-agent supported release matrix](hosted_agent_release_matrix.md) for
+    operator-surface gates remain deployment-published `false`. The latest
+    runtime attempt activated the agent version but session readiness returned
+    HTTP 424, so the integration is not validated or shipped. See the
+    [hosted-agent integration matrix](hosted_agent_release_matrix.md) for
     the exact runtime, identity, RBAC, panel, data, and rollback contracts.
 
 ![Chat runtime modes and hosted deployment lifecycle](media/architecture_chat_runtime_modes.svg)

docs/quickstart_simple_rag.md

@@ -76,7 +76,7 @@ azd provision
   - **Microsoft Foundry** - Foundry Account and project for agent orchestration
   - **OpenAI Models** - GPT-4o and text-embedding-3-large deployments
   - **Container Registry** - Stores Docker images
-  - **Container Apps (4)** - UI, orchestrator, ingestion, MCP in the currently released classic topology. The [hosted-agent supported matrix](hosted_agent_release_matrix.md) pins UI, orchestrator runtime, ingestion, and AILZ releases; hosted/no-panel and explicit hosted-panel keep UI and ingestion in Container Apps and omit the orchestrator Container App from the hosted chat path.
+  - **Container Apps (4)** - UI, orchestrator, ingestion, MCP in the currently released classic topology. The [hosted-agent integration matrix](hosted_agent_release_matrix.md) pins UI, orchestrator runtime, ingestion, and AILZ releases; hosted/no-panel and explicit hosted-panel keep UI and ingestion in Container Apps and omit the orchestrator Container App from the hosted chat path. The hosted integration is not yet shipped because runtime session readiness remains blocked.
   - **App Configuration** - Centralized configuration store
   - **Key Vault** - Secrets management
   - **Cosmos DB** - Agent state and metadata