菜单
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.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Build enterprise RAG with Foundry IQ and Azure AI Search Knowledge Bases using agentic retrieval, multi-hop reasoning, query planning, and citation-backed responses. Distinguishes the stable 2026-04-01 programmatic API from preview portal experiences and preview-only knowledge-source integrations. USE FOR: knowledge base, RAG, agentic retrieval, policy assistant, citations, multi-hop QA, Knowledge Agent, AI Search Knowledge Base, document grounding, semantic retrieval, foundry-iq, knowledge index, hybrid search, vector search, kb-mcp, web iq boundary, serverless knowledge base boundary, purview acl knowledge. DO NOT USE FOR: structured-document extraction (use foundry-doc-vision-speech), standalone Work IQ, Fabric IQ, or Web IQ workloads, MCP server deployment (use foundry-mcp-aca), agent runtime (use foundry-hosted-agents).
Deploy + manage Foundry hosted agents — container deploy via unified azure.yaml is GA; source-code --deploy-mode code is still preview. MAF 1.8.0, azd ext install microsoft.foundry, implicit agent access (no default role grant). Read the body for patterns, identity, runtime, rollout, troubleshooting. USE FOR: deploy foundry agent, hosted agent, container agent, azure.yaml, azd ai agent, microsoft.foundry, MAF, FoundryChatClient, ResponsesHostServer, ACR push, batch eval, agent identity, Foundry User role, entra-agent-id, Responses/Invocations protocols, Activity protocol, blue-green deploy, canary rollout, version rollback, traffic routing, version_selector, agent_endpoint, update_details. DO NOT USE FOR: prompt agents (use foundry-prompt-agents), ACA MCP (use foundry-mcp-aca), GHCP coding agent (use ghcp-hosted-agents), Citadel hub/spoke (use citadel-hub-deploy), pilot pipeline (use threadlight-deploy), continuous eval (use foundry-evals), Routines (use foundry-routines), A2A wiring (use foundry-toolbox).
Tips and patterns for Azure Developer CLI (azd) workflows, ACA job deployment, and infrastructure scripting conventions. USE FOR: azd hooks, postdeploy, postprovision, ACA job deployment, container app job image update, publish_aca, deploy_job, azure.yaml hooks, cross-platform deployment scripts, uv run, azd env, azd conventions, infra scripts, MCAPS subscription, SecurityControl Ignore tag, resource group tagging, Defender for Cloud noise, Azure Policy auto-remediation, AZURE_TAGS, pilot posture, demo subscription tagging, AcrPull, ImagePullError, JSON array param, BCP186, FetchingKeyVaultSecretFailed, dependsOn rbac, image-pull credential, ACA placeholder image, azd env set triple-escape. DO NOT USE FOR: az login, tenant switching, subscription isolation (use azure-tenant-isolation), Foundry agents (use microsoft-foundry).
Deploy custom MCP servers as Azure Container Apps or Azure Functions for use with Foundry hosted agents. Covers Cosmos DB MCPToolKit, Playwright MCP, custom MCP servers, protocol requirements, ACA configuration, and authentication + hardening (ACA built-in auth / Easy Auth, OAuth, managed identity). USE FOR: deploy MCP server, MCP on ACA, Cosmos MCP, Playwright MCP in Foundry, custom MCP server, Azure Functions MCP, MCP ACA deployment, remote MCP endpoint, MCP for hosted agent, connect hosted agent to MCP, secure MCP server, harden MCP server, MCP authentication, MCP OAuth, ACA Easy Auth for MCP. DO NOT USE FOR: deploying the hosted agent itself (use threadlight-deploy), local MCP development (use mcp-config.json directly), general Azure deploy.
Deploy Foundry hosted agents using GitHub Copilot SDK (GHCP) with BYOK authentication and Invocations protocol. Alternative to MAF (Agent + FoundryChatClient + ResponsesHostServer). Use when you need streaming SSE output, progressive skill discovery, or long tool loops (>120s) that hit Foundry gateway timeout with Responses protocol. USE FOR: ghcp sdk, copilot sdk, github copilot agent, CopilotClient, InvocationAgentServerHost, BYOK, bring your own key, invocations protocol, SSE streaming agent, long running agent, send_and_wait timeout, ghcp hosted agent, copilot client foundry. DO NOT USE FOR: MAF agents (use foundry-hosted-agents), prompt agents, declarative agents, general Azure deploy.
Use Microsoft Foundry Toolbox GA to manage versioned multi-tool bundles behind a single MCP endpoint and connect them to hosted agents. Covers stable AIProjectClient.toolboxes CRUD, Toolbox-specific SDK models, agent_framework_foundry_hosting.FoundryToolbox, authentication, immutable-version promotion and rollback, the azd ai toolbox declarative path, and preview Tool Search. Distinguishes the GA Toolbox core from preview A2A, Work IQ, Fabric IQ, Browser Automation, Reminder, skills, and Tool Search; explains that azure_ai_search wraps an index, not a Foundry IQ knowledge base. USE FOR: foundry toolbox, toolbox MCP endpoint, AIProjectClient toolboxes, FoundryToolbox, toolbox version promote, multi-tool MCP endpoint, ToolboxSearchPreviewToolboxTool, kind toolbox, host azure.ai.toolbox, toolbox.yaml. DO NOT USE FOR: building MCP servers (use foundry-mcp-aca), KB-only RAG (use foundry-iq), generic hosted-agent runtime (use foundry-hosted-agents), cross-resource models (use foundry-cross-resource).
| name | hosted_agent_deploy_expert |
| description | 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. |
azd up, azd ai agent deploy, or azd deploy for a Foundry hosted agent/invoke returns errorsIdentify 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' | 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) |
For 401 patterns, hand off to byok_401_debug_expert.
For 429/quota, hand off to quota_throttle_expert.
RunAzCliReadCommandsQueryAppInsightsByAppIdQueryLogAnalyticsByWorkspaceId