SKILL.md · 24000
he selected metadata file:
- azd binding (
azd.environmentName,azd.service) when useful for future resolution evaluationSuites[]with remote suite/dataset/evaluator references and local cache pathslastEval, result files, comparison summaries, or explicit non-azd overrides
Do not copy azd-owned deployment values into metadata when azd already provides them. If the selected file is a preferred single-environment file, rewrite only that one environment block. If the selected file is a legacy multi-environment file, rewrite only the selected environment block. Never copy or merge environments across sibling metadata files automatically. If the selected environment still uses older testSuites[] or legacy testCases[], rewrite it to evaluationSuites[] and remove migrated priority fields from the rewritten entries.
Step 7: Collect Missing Values
Use the ask_user or askQuestions tool only for values not resolved from the user's message, session context, metadata, or azd bootstrap. Common values skills may need:
- Agent root — Target azd service project folder or folder containing
.foundry/agent-metadata*.yaml - Metadata file —
agent-metadata.yamlfor local/dev, or an explicit sidecar such asagent-metadata.prod.yaml - Environment — azd environment,
dev,prod, or another environment key from metadata - Project endpoint — Microsoft Foundry project endpoint URL
- Agent name — Name of the target agent
💡 Tip: If the user already provides the agent path, environment, project endpoint, or agent name, extract it directly — do not ask again.
Agent: Agent Types
Agent workflows distinguish four first-class agent types:
| Type | Kind | Description |
|------|------|-------------|
| Prompt | "prompt" | LLM-based agents backed by a model deployment; managed via Foundry MCP or SDK |
| Hosted | "hosted" | Container-based agents running custom code; developed and deployed via azd |
| Managed Harness Agent | "prompt" with harness.type: "microsoft_copilot_preview" for new authoring | Prompt Agent running on the Foundry-managed Copilot harness; developed and deployed via azd |
| Voice | "voice" | Managed real-time Voice Agent — either Prompt Voice (1 agent, modelType: managed or self_deployed) or Hosted Voice (2 agents: kind: voice wrapper with conversationEngine.type: hosted_agent + kind: hosted target over invocations_ws 1.0.0 and Voice Live Bridge 1.0); developed and deployed via azd and verified over the voice WebSocket endpoint |
Classify an azure.yaml service by its definition in this exact order, not by host alone:
kind: voice-> Voice. For compatibility, silently classify an existingkind: prompt-voiceservice as Voice, then normalize it when editing its YAML. Classify the subtype:conversationEngine.type: hosted_agent-> Hosted Voice wrapper (paired with a namedkind: hostedtarget service).modelType: managedormodelType: self_deployed-> Prompt Voice (Foundry infers native speech-to-speech vs cascaded STT -> LLM -> TTS frommodel.id).- Having both
modelType/modelandconversationEngineis invalid (stop and fixazure.yaml); having neither is incomplete (do not guess). Never use obsoletemodelType: hosted_agent,targetAgent, or a nestedconfig:block.
kind: hosted-> Hosted. When it declaresprotocols: [{ protocol: invocations_ws, version: 1.0.0 }]andmetadata.voiceLiveCompatible: "true"alongside akind: voicewrapper, it is a Hosted Voice target; otherwise treat a standaloneinvocations_wsservice as a custom Hosted real-time/audio agent.kind: promptplusharness.type: microsoft_copilot_previewor legacygithub_copilot_preview-> Managed Harness Agent.kind: promptwithout that harness -> ordinary Prompt Agent.
Use agent_get only when the type cannot be resolved from project context. Preserve the harness discriminator already authored on an existing Managed Harness Agent; do not migrate it during ordinary edits or redeploys. Do not convert an existing Agent between Prompt, Hosted, Managed Harness Agent, and Voice types; create a new Agent instead. Before creating any Voice Agent, determine the model strategy first per create-voice.
Tool Usage Conventions
- Use the
ask_useroraskQuestionstool whenever collecting information from the user - Use the
taskorrunSubagenttool to delegate long-running or independent sub-tasks (e.g., env var scanning, status polling, Dockerfile generation) - Prefer azd for Hosted Agents, Managed Harness Agents, and Voice Agents; prefer Foundry MCP for ordinary Prompt Agents.
- Reference official Microsoft documentation URLs instead of embedding CLI command syntax
Azure Authentication
Additional Resources
Network Isolation Errors
Applies to any call against a Foundry project or its parent Foundry account — Foundry MCP tools, azd, az CLI, curl, REST, or SDK.
If an error matches Public access is disabled / PublicNetworkAccessDisabled / 403 Forbidden from a private endpoint / connection timeout / the project endpoint FQDN resolves to a public IP, this typically means the parent Foundry account has publicNetworkAccess=Disabled or Enabled from selected IP addresses, and the current shell is outside its VNet.
Only if the error is ambiguous, confirm against the Foundry account using a management-plane call (works from anywhere with reader access):
az cognitiveservices account show \
--name <account> --resource-group <rg> \
--query "properties.{publicNetworkAccess:publicNetworkAccess, networkAcls:networkAcls, privateEndpointConnections:privateEndpointConnections[].properties.privateLinkServiceConnectionState.status}"
publicNetworkAccess: "Disabled" — or "Enabled" together with non-empty networkAcls.ipRules / virtualNetworkRules — confirms isolation. If publicNetworkAccess: "Enabled" and networkAcls is empty, the failure is a caller-side network issue (e.g. Private DNS resolving the FQDN to a public IP from inside a VNet with a private endpoint), not an account-config issue.
If it's indeed a network isolation issue, supported connection options are documented in Choose a secure connection method to Foundry.
ℹ️ Foundry MCP tools cannot reach a VNet-isolated project even from inside the VNet.