Investigate failed Microsoft Foundry hosted-agent deployments — MAF SDK breaking changes, ACR push, ACA rollout, BYOK provisioning, and the azd ai agent extension's known envelope and RBAC quirks.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Investigate failed Microsoft Foundry hosted-agent deployments — MAF SDK breaking changes, ACR push, ACA rollout, BYOK provisioning, and the azd ai agent extension's known envelope and RBAC quirks.
hosted_agent_deploy_expert
When to use
A user reports a failed azd up, azd ai agent deploy, or azd deploy for a Foundry hosted agent
A scheduled task flags failed deployments in the monitored Foundry project
A hosted agent starts but the first /invoke returns errors
Investigation flow
Identify the failed deploy — agent name, approximate time, which command the user ran.
Check the Foundry project's deployments:
az ml online-deployment list \
--workspace-name <project> --resource-group <rg> \
--output table
Capture instanceName, provisioningState, failureReason for each failed deployment.
Pull container logs from App Insights for the failure window:
traces
| where timestamp > ago(1h)
| where cloud_RoleName == "<agent-name>"
| where severityLevel >= 2
| project timestamp, message, severityLevel, customDimensions
| top 50 by timestamp desc
Classify by pattern:
Pattern in logs
Root cause
KI
Authentication failed with provider ... (HTTP 401)
Foundry User missing at account scope
foundry-hosted-agents KI-001
cannot import name 'AzureOpenAIChatClient' from 'agent_framework.azure'
MAF SDK 1.4.0 breaking change
foundry-hosted-agents KI-002 (replace with OpenAIChatClient from agent_framework.openai)
SkillsProvider object has no attribute 'skill_paths'
