Administration
Native execution, UI product metadata and optional document processing have separate operational owners. Deploy and authorize only the surfaces needed by the installation. An operator role is not blanket permission to read every user's transcript, private attachment or source document.
Choose the operational surface
| Area | Responsibility |
|---|---|
| Foundry Hosted | Native application publications, session/workflow state and host telemetry |
| Container Apps and Durable Task Scheduler | Durable worker lifecycle, scheduler connectivity and native run state |
| UI/BFF | Owner mappings, history discovery, feedback and enabled product administration |
| Optional ingestion service | Files, indexing/purge jobs, schedules and allowlisted processing settings |
| App Configuration and Key Vault | Declared settings, supported refresh, scoped access and secret rotation |
Native persistence belongs to the selected execution host. Do not deploy an extra execution or ingestion service to act as a second workflow-state store. If an enabled UI feature requires a metadata store, provision that dependency directly and grant access to its actual consumer.
How to inspect an application
- Select the installation's azd environment in its project directory with
azd env select <environment-name>. Confirm its subscription, resource group and selected execution host before opening an administrative tool. - For Foundry Hosted, open that Foundry project and its Agents view. Select the conversational or workflow publication that handled the request. Use native traces to correlate a real invocation.
- For Container Apps, open the worker's Container App in the Azure portal. Check its active revision and logs, then the deployment's Durable Task Scheduler and task hub for native execution state.
- For a user's conversation or pending decision, use the authenticated application UI. Reopen the owner-bound session and inspect current progress before submitting an action.
- Record the deployment revision, request/run identifier, time and safe failure status. Follow Troubleshooting for the failing boundary rather than retrying a state-changing operation blindly.
Azure resource administration and application-user access are separate permissions. Use the user's approved application path when acting on their session. Use the service's administrative access for resource health and diagnostics.
Inspect Operate and Traces in isolated networks
Human operators inspecting Operate and Traces in the Foundry portal for an isolated deployment need both private DNS resolution and Azure Monitor read RBAC:
- Private DNS and firewall path: resolve AMPLS zones (
privatelink.monitor.azure.com,privatelink.oms.opinsights.azure.com,privatelink.ods.opinsights.azure.com,privatelink.agentsvc.azure-automation.netandprivatelink.blob.core.windows.net) over VPN or ExpressRoute with Private DNS Resolver, and allow outbound HTTPS (443) to Azure Monitor ingestion and query endpoints. See the BYO hub Private DNS checklist. - Operator Azure Monitor RBAC: assign
Log Analytics Readeron Application Insights and the linked Log Analytics workspace, plusPrivileged Monitoring Data ReaderwhenAppGenAIContentisProtected.
Run scheduled trace evaluations on hosted agents
Use scheduled trace evaluations (azure_ai_traces) for hosted agents
instead of responseCompleted continuous evaluation rules, which are not
supported for hosted agents. Check per-item agent version
(gen_ai.agent.version or FOUNDRY_AGENT_VERSION) and non-empty output across
rolling trace lookback windows so older versions or empty warm-up spans do not
skew evaluation scores.
Opt in before azd provision only to the least-privilege evaluation roles
required by the Foundry project managed identity:
GRANT_PROJECT_TRACE_EVALUATION_READER=true(grantProjectTraceEvaluationReader): grants the Foundry project managed identityReaderon Application Insights andLog Analytics Data Readeron the linked Log Analytics workspace.GRANT_PROJECT_PROTECTED_TRACE_CONTENT_READER=true(grantProjectProtectedTraceContentReader): strictly opt-in grant assigningPrivileged Monitoring Data Readerconditioned with Azure ABAC v2.0 restricting workspace table reads toAppGenAIContentwhenProtected. It requiresGRANT_PROJECT_TRACE_EVALUATION_READER=true.
When model calls traverse an AI Gateway, allowlist each hosted agent's
dedicated runtime identity (created on first azd deploy publication) at the
gateway rather than only the Foundry project identity.
Conversations, workflows and feedback
Use the selected host's official client and service operations to inspect native execution. Product-facing reads and actions must pass through the authenticated BFF owner checks; arbitrary run/session IDs are not permission.
Pending human input belongs to the native workflow. An operator UI must not silently convert a pending request into an approval or manufacture a new run after a browser disconnect. See Workflows & human input.
Metadata and native state have distinct lifecycle operations. Define retention, deletion and partial-failure handling for both, including attachments, feedback, audit data and backups. Conversations & files and User feedback explain the product boundaries. Use the ingestion dashboard for corpus processing and jobs. Use the application UI for owner-scoped conversations, workflow actions and response feedback.
Ingestion dashboard
The optional ingestion service manages source processing, not agent/workflow execution. Review Jobs & schedules before starting or changing jobs: startup and scheduled runs can index and delete content.
The ingestion component includes administrative API and dashboard contracts for explicitly managed component deployments. The native platform keeps the aggregate operator surface disabled. Choosing an orchestration host does not activate that dashboard.
For a component deployment that includes administration, build its frontend before backend startup using the local dashboard procedure. The static bundle is needed for the dashboard, not for API routes. Check the mounted routes and authorization independently of UI visibility.
Manual job runs and configuration mutations use the Admin gate when Entra
is configured. Administrative reads and file unblocking do not all share that
unconditional gate. Protect the whole service boundary deliberately, including
the tenant-free development configuration.
The ingestion component's /api/panel/* requires a validated Admin bearer.
These administrative gates are separate from UI user-history access.
The ingestion panel exposes ingestion-specific records and an ingestion
overview. Its conversation-history endpoint returns 501.
Use the ingestion API contracts
to select the supported administration operations.
Operator overview and curation
Before exposing operator routes, a component-managed integration requires
DEPLOY_ADMINISTRATIVE_PANEL=true and PANEL_OPERATOR_SURFACES_ENABLED=true.
The integration also requires an explicit PANEL_OPERATOR_APP_ROLE or
PANEL_OPERATOR_GROUP_ID.
The DATA_INGEST_APP_APIKEY cursor-signing secret must be securely resolved.
Until all of these are present, operator routes return HTTP 503.
These are component contracts, not an activation recipe for the reference
platform: its configuration ownership fixes operator surfaces to false.
Use the application integration procedure to review a separately owned composition, configuration and authorization boundary. Do not override the reference platform's protected value in the portal. Operator routes enforce their bearer/Admin policy without a tenant-free development bypass and accept delegated operator tokens, not app-only tokens. A UI history permission does not grant aggregate access.
Aggregate metrics suppress groups smaller than
PANEL_OVERVIEW_MIN_CARDINALITY, default 5.
Blocked-file curation operates on Blob logs, not conversation messages.
The caller-bound signed cursor expires after PANEL_CURSOR_TTL_SECONDS,
default 600. See operator API contracts.
Configuration writes can partially succeed. A saved value is not undone by a failed local refresh or later schedule-application error. Verify effective settings before retrying.
Configuration changes
How to apply an operational change
- Find the setting in Application settings. Identify its owner, edit location and refresh or restart requirement.
- For history, feedback or private attachments, use the product-feature procedure before provision. The lifecycle applies their metadata resources and grants.
- For an existing operator-managed key, edit the intended App Configuration
resource with label
agent-lzusing the portal or CLI procedure. - Apply the required refresh, provision or redeployment. Check a new operation and its denied-access case before treating the change as effective.
- Record the input change with the installation's configuration so later provisioning reproduces it. Use secret rotation for credentials rather than placing them in ordinary key values.
Use the ownership inventory and Application settings before editing a key. Supported functional parameters refresh through the official provider. Running workflows retain their functional snapshots; current authorization is rechecked separately.
Structural changes to host, graph, identity, persistence, registration names or process bootstrap require compatible deployment. An accepted write is not proof that every affected process loaded it.
Maintenance and recovery
- Monitor requests and audit events.
- Redeploy applications, rotate secrets or review recovery safeguards.
- Diagnose failures with Troubleshooting.
- For infrastructure changes, retain the provider, backend and approved resource-group mapping. Follow Bicep maintenance or Terraform maintenance.
Retries and redeployments must not delete existing user data or resources.
Changing ingestion selection does not remove existing resources or permissions. Environment destruction is a separate authorized operation.