# Hosted Agent Deploy Expert

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-aiappsgbb-awesome-gbb-hosted-agent-deploy-expert`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [aiappsgbb](https://agentstack.voostack.com/s/aiappsgbb)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aiappsgbb](https://github.com/aiappsgbb)
- **Source:** https://github.com/aiappsgbb/awesome-gbb/tree/main/skills/azure-sre-agent/references/plugins/gbb-foundry/skills/hosted_agent_deploy_expert

## Install

```sh
agentstack add skill-aiappsgbb-awesome-gbb-hosted-agent-deploy-expert
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

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

2. **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.

3. **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
   ```

4. **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) |

5. **For 401 patterns**, hand off to `byok_401_debug_expert`.
6. **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](https://github.com/aiappsgbb)
- **Source:** [aiappsgbb/awesome-gbb](https://github.com/aiappsgbb/awesome-gbb)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-aiappsgbb-awesome-gbb-hosted-agent-deploy-expert
- Seller: https://agentstack.voostack.com/s/aiappsgbb
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.