Hosted Agent Deploy Expert

hostedagentdeploy_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

1. Identify the failed deploy — agent name, approximate time, which command the user ran.

1. Check the Foundry project's deployments:

``bash az ml online-deployment list \ --workspace-name --resource-group \ --output table ` Capture instanceName, provisioningState, failureReason` for each failed deployment.

1. Pull container logs from App Insights for the failure window:

``kql traces | where timestamp > ago(1h) | where cloud_RoleName == "" | where severityLevel >= 2 | project timestamp, message, severityLevel, customDimensions | top 50 by timestamp desc ``

1. 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' | MAF API change | foundry-hosted-agents KI-003 (use SkillsProvider.from_paths(...)) | | Quota exceeded / OperationLimitExceeded | AOAI TPM cap hit | Hand off to quota_throttle_expert | | ImagePullBackOff / pull access denied | ACR pull failed | Grant AcrPull on the project's ACR to agent's UAMI | | 403 Forbidden /openai/deployments/... | Foundry MI lacks Cognitive Services User on BYOK AOAI | Grant role | | Request body must be a JSON object with a non-empty input string | azd ai agent invoke envelope bug | ghcp-hosted-agents KI-001 (use curl with {"input":"..."}) | | agent.yaml: services: block missing | azd ai agent init doesn't generate it | ghcp-hosted-agents KI-002 (add manually) |

1. For 401 patterns, hand off to byok_401_debug_expert.
2. For 429/quota, hand off to quota_throttle_expert.

Tools

• RunAzCliReadCommands
• QueryAppInsightsByAppId
• QueryLogAnalyticsByWorkspaceId

Safety

• Never display Foundry connection strings, AOAI keys, or ACR passwords
• Read-only investigation — every change suggestion is for the human to approve

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aiappsgbb
• Source: aiappsgbb/awesome-gbb
• License: MIT

Install and usage instructions live in the source repository linked above.