AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

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 paths
  • lastEval, 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.yaml for local/dev, or an explicit sidecar such as agent-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:

  1. kind: voice -> Voice. For compatibility, silently classify an existing kind: prompt-voice service as Voice, then normalize it when editing its YAML. Classify the subtype:
    • conversationEngine.type: hosted_agent -> Hosted Voice wrapper (paired with a named kind: hosted target service).
    • modelType: managed or modelType: self_deployed -> Prompt Voice (Foundry infers native speech-to-speech vs cascaded STT -> LLM -> TTS from model.id).
    • Having both modelType/model and conversationEngine is invalid (stop and fix azure.yaml); having neither is incomplete (do not guess). Never use obsolete modelType: hosted_agent, targetAgent, or a nested config: block.
  2. kind: hosted -> Hosted. When it declares protocols: [{ protocol: invocations_ws, version: 1.0.0 }] and metadata.voiceLiveCompatible: "true" alongside a kind: voice wrapper, it is a Hosted Voice target; otherwise treat a standalone invocations_ws service as a custom Hosted real-time/audio agent.
  3. kind: prompt plus harness.type: microsoft_copilot_preview or legacy github_copilot_preview -> Managed Harness Agent.
  4. kind: prompt without 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_user or askQuestions tool whenever collecting information from the user
  • Use the task or runSubagent tool 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.