Microsoft Foundry

MicrosoftOfficialCreated by Microsoft

Skill
Workflow
Data and AI
MIT
Low risk
Has scripts

From the author

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

— the description by Microsoft

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

Microsoft Foundry provides a comprehensive framework for the entire AI agent lifecycle. This skill enables developers to scaffold, provision, deploy, and manage agents while integrating evaluation and optimization workflows. It supports various agent types, including prompt-based, managed harness, and voice agents, and provides tools for CI/CD, continuous monitoring, and fine-tuning models. The skill emphasizes a structured approach using workspace-specific metadata and standard Azure Developer CLI (azd) patterns to ensure consistent environment management and deployment.

What it does

Scaffold and create new AI agents with support for various harness types.
Manage the full deployment lifecycle including provisioning and CI/CD integration.
Execute batch and continuous evaluation workflows to monitor agent quality.
Optimize agent prompts and instructions using automated evaluation-driven loops.
Fine-tune models using SFT, DPO, or RFT techniques with dataset curation.
Troubleshoot agent performance through log analysis, telemetry, and trace inspection.

When to use it

When building, deploying, or managing AI agents within the Microsoft Foundry ecosystem.
When you need to evaluate agent performance or optimize prompts based on production traces.
When setting up CI/CD pipelines for automated agent deployment and monitoring.
When fine-tuning models or managing capacity and quotas for AI services.
When troubleshooting deployment failures or agent runtime issues.

Advantages

Provides a unified, end-to-end workflow for the entire agent development lifecycle.
Standardizes project structure and metadata management across different environments.
Integrates seamlessly with Azure Developer CLI (azd) for consistent infrastructure management.
Enables data-driven improvements through automated evaluation and prompt optimization.
Supports advanced model customization including fine-tuning and distillation.

Usage examples

“Create a new hosted Foundry agent from scratch.”: The agent will guide you through the quick-start workflow to scaffold, provision, and deploy a new agent project.
“Optimize the prompt for my existing Python hosted agent.”: The agent will trigger the evaluation-driven optimization workflow to analyze performance and suggest prompt improvements.
“Set up a CI/CD pipeline for my agent.”: The agent will configure the necessary deployment pipeline steps for your Foundry agent project.
“Troubleshoot why my agent deployment is failing.”: The agent will help you inspect logs, telemetry, and quota settings to diagnose and resolve the deployment issue.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/microsoft/microsoft-foundry/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip microsoft-foundry.zip -d .agents/skills

Documentation by Microsoft

Microsoft Foundry Skill

This skill helps developers work with Microsoft Foundry resources, covering model discovery and deployment, complete dev lifecycle of AI agent, evaluation workflows, and troubleshooting.

Pre-Execution Requirements

Follow each applicable subsection below before starting its corresponding action or workflow.

Dependency Check and Setup

MANDATORY: As the first step after this skill loads, run the dependency check and setup script below from this skill's root and wait for it to finish before continuing. The script checks first and installs only missing dependencies; it does not reinstall dependencies that are already available.

You MUST complete this check before reading or entering any sub-skill, workflow, or workflow-specific reference.

./scripts/check-and-setup-dependencies.sh     # macOS / Linux
./scripts/check-and-setup-dependencies.ps1    # Windows (pwsh)

Strictly follow the script output for subsequent actions.

Workflow Guidance

MANDATORY: Before executing ANY workflow-specific steps, you MUST read the corresponding sub-skill document. Do not call workflow-specific MCP tools for a workflow without reading its skill document. This applies even if you already know the MCP tool parameters — the skill document contains required workflow steps, pre-checks, and validation logic that must be followed. This rule applies on every new user message that triggers a different workflow, even if the skill is already loaded.

Foundry MCP

MANDATORY: Before using Foundry MCP operations, call the Azure MCP foundry tool and inspect the available Foundry MCP tools and related parameters. Treat this as the discovery/help step for MCP-based workflows.

azd

MANDATORY: Before executing ANY azd command, you MUST read azd-guidance and strictly follow the shared rules defined in it, especially the AZURE_DEV_USER_AGENT setting rules.

Sub-Skills

This skill includes specialized sub-skills for specific workflows. When a sub-skill matches the task, strictly follow its workflow:

Sub-Skill	When to Use	Reference
deploy	Deploy hosted agents to Foundry, smoke-test a deployment, create or update prompt agents, and manage agent versions and multi-environment deploys.	deploy
cicd	Set up a CI/CD deployment pipeline for a Foundry agent.	cicd
invoke	Send messages to an agent, single or multi-turn conversations	invoke
routine	Schedule or event-trigger Foundry agents with routines; use `azd` for CRUD, enable/disable, manual dispatch, and viewing past runs, or define routines in `azure.yaml`.	routine
invocations-ws	Build, deploy, and connect to custom Hosted agents that use developer-defined duplex real-time or media streams over `invocations_ws`.	invocations-ws
observe	Evaluate agent quality, run batch evals, analyze failures, optimize prompts, improve agent instructions, compare versions, set up CI/CD monitoring, and enable continuous production evaluation	observe
insights	Pull generated agent insights, evidence, and recommendations from an existing monitor; read-only retrieval, not a new analysis run	insights
trace	Query traces, analyze latency/failures, correlate eval results to specific responses via App Insights `customEvents`	trace
troubleshoot	View hosted agent logs, query telemetry, diagnose failures	troubleshoot
validate	Use only when the user explicitly asks to use this validation sub-skill or to validate Microsoft Foundry hosted-agent code against best practices. Never invoke it proactively or add it to another workflow.	validate
create (quick start)	Create a new hosted Foundry agent from scratch end-to-end — scaffold, provision or use an existing Foundry project, deploy, and smoke-test. Do not use for any work on existing code. For anything not covered by the quickstart, use create.	create/quick-start-hosted.md
create	Use when the standard end-to-end happy path (quick start) doesn't fit. Create a new Foundry agent, update code of an existing agent, continue development of an existing agent, wire connections at scaffold time, use advanced setup or A2A (Agent2Agent), or recover from a failed quickstart run.	create
create managed harness	Create or continue developing a Prompt Agent that explicitly uses the Foundry-managed Copilot harness. Uses `azd` and `azure.yaml`, not the ordinary Prompt Agent MCP workflow.	create-managed-harness
create voice	Create, configure, or extend a Foundry Voice Agent, defaulting generic requests to managed Prompt Voice and supporting self-deployed Prompt Voice or two-agent Hosted Voice.	create-voice
agent-optimizer	Make existing Python hosted-agent code optimization-ready, configure eval.yaml, run Agent Optimizer jobs, apply candidates locally, and deploy through azd after review.	agent-optimizer
eval-datasets	Harvest production traces into evaluation datasets, manage dataset versions and splits, track evaluation metrics over time, detect regressions, and maintain full lineage from trace to deployment. Use for: create dataset from traces, dataset versioning, evaluation trending, regression detection, dataset comparison, eval lineage.	eval-datasets
project/create	Creating a new Microsoft Foundry project for hosting agents and models. Use when onboarding to Foundry or setting up new infrastructure.	project/create/create-foundry-project.md
resource/create	Creating Azure AI Services multi-service resource (Foundry resource) using Azure CLI. Use when manually provisioning AI Services resources with granular control.	resource/create/create-foundry-resource.md
private-network	Answer questions about Foundry network isolation and deploy Foundry with VNet isolation (BYO VNet, Managed VNet, hybrid). Covers architecture concepts, template selection, deployment, and post-deployment validation.	resource/private-network/private-network.md
models/deploy-model	Unified model deployment with intelligent routing. Handles quick preset deployments, fully customized deployments (version/SKU/capacity/RAI), and capacity discovery across regions. Routes to sub-skills: `preset` (quick deploy), `customize` (full control), `capacity` (find availability).	models/deploy-model/SKILL.md
quota	Managing quotas and capacity for Microsoft Foundry resources. Use when checking quota usage, troubleshooting deployment failures due to insufficient quota, requesting quota increases, or planning capacity.	quota/quota.md
rbac	Managing RBAC permissions, role assignments, managed identities, and service principals for Microsoft Foundry resources. Use for access control, auditing permissions, and CI/CD setup.	rbac/rbac.md
finetuning	Fine-tune models on Microsoft Foundry — SFT distillation, DPO preference optimization, RFT with graders and tool calling. Dataset preparation, grader calibration, training, checkpoint selection, deployment, evaluation. Use for: fine-tune, SFT, DPO, RFT, training data, grader, distillation, fine-tuned model, large file upload.	finetuning/SKILL.md
azd-guidance	Provide shared azd knowledge and guidance for managing Foundry agents. Read this first for any workflows related to azd.	azd-guidance

💡 Tip: For a complete onboarding flow: project/create (public) or private-network (VNet isolation) → models/deploy-model → agent workflows (create → deploy → invoke).

💡 Fine-Tuning: Use finetuning for all model customization — SFT distillation, DPO preference optimization, and RFT with graders. Includes quickstart, grader calibration, and training curve analysis.

💡 Model Deployment: Use models/deploy-model for all deployment scenarios — it intelligently routes between quick preset deployment, customized deployment with full control, and capacity discovery across regions.

💡 Prompt Optimization: For requests like "optimize my prompt" or "improve my agent instructions," load observe and use the prompt_optimize MCP tool through that eval-driven workflow.

Infrastructure Lifecycle

Match user intent to the correct infrastructure workflow.

User Intent	Workflow
"Create Foundry" / "Set up Foundry" (ambiguous)	Use `AskUserQuestion`: (a) just an AI Services resource, (b) a project with public access, or (c) a project with network isolation? Route: (a) → resource/create, (b) → project/create, (c) → private-network
Set up Foundry with VNet isolation	private-network
Create a Foundry project (public)	project/create
Create a bare Foundry resource	resource/create

Agent Development Lifecycle

Match user intent to the correct agent workflow. Read each sub-skill in order before executing.

User Intent	Workflow (read in order)
Create or develop a Voice Agent (Prompt Voice or Hosted Voice)	dependency check and setup → azd-guidance → create-voice → deploy → invoke
Create or develop an explicitly requested Managed Harness Agent / Copilot harness agent	dependency check and setup → azd-guidance → create-managed-harness → deploy → invoke
Create a new hosted agent end-to-end (scaffold + deploy + test)	dependency check and setup → azd-guidance → quick-start-hosted (self-contained end-to-end)
Anything beyond the standard quickstart (existing code, migration, re-hosting, deployment customization, scaffold-time connections, A2A (Agent2Agent), recovery)	dependency check and setup → azd-guidance → create → deploy → invoke
Optimize existing Python hosted agent	dependency check and setup → azd-guidance → agent-optimizer → scaffold/review → eval.yaml → optimize → apply candidate → deploy → invoke
Deploy an agent (code already exists)	dependency check and setup → azd-guidance → deploy (includes eval-suite setup) → invoke → observe (evaluate/optimize)
Update/redeploy an agent after code changes	dependency check and setup → azd-guidance → deploy (includes eval-suite setup) → invoke → observe (evaluate/optimize)
Set up a CI/CD deployment pipeline for a hosted agent	dependency check and setup → azd-guidance → cicd
Invoke/test/chat with an agent	dependency check and setup → azd-guidance → invoke
Schedule/event-trigger an agent, or CRUD/enable/disable/dispatch a routine	dependency check and setup → azd-guidance → routine
Optimize / improve agent prompt or instructions	observe (Step 4: Optimize)
Evaluate and optimize agent (full loop)	observe
Enable continuous evaluation monitoring	observe (Step 6: CI/CD & Monitoring)
Pull agent insights / list generated issues and recommendations	dependency check and setup → insights (all pages with expanded evidence; read-only)
Troubleshoot an agent issue	dependency check and setup → azd-guidance → invoke → troubleshoot
Fix a broken agent (troubleshoot + redeploy)	dependency check and setup → azd-guidance → invoke → troubleshoot → apply fixes → deploy → invoke

Agent: .foundry Workspace Standard

Every agent source folder can keep Foundry-specific cache and overlay state under .foundry/:

<agent-root>/
  .foundry/
    agent-metadata.yaml
    agent-metadata.prod.yaml
    suites/
    datasets/
    evaluators/
    results/

In azd projects, derive deployment context (project endpoint, agent name/version, ACR, App Insights) from azure.yaml plus azd env get-values; do not duplicate those values in metadata when azd already provides them.
agent-metadata.yaml is the preferred local/dev overlay for non-azd values, remote Foundry suite references, local cache paths, result summaries, and explicit overrides. Optional sidecar files such as agent-metadata.prod.yaml can hold a single prod or CI-targeted overlay without mixing multiple environments in one file.
suites/, datasets/, and evaluators/ are local cache folders. Reuse them when they are current, and ask before refreshing or overwriting them.
See Agent Metadata Contract for the canonical schema and workflow rules.

Agent: Setup References

Standard Agent Setup — advanced setup for production workloads that need data-residency control (bring-your-own Cosmos DB / Storage / AI Search via a Foundry capability host). The default azd ai agent flow uses Basic Agent Setup and does not provision capabilityHosts/agents — do not flag its absence as a bug. For default post-provision state, see the "Expected env-var fingerprint" section in foundry-agent/create/create-hosted.md.

Agent: Common Project Context Resolution

Agent skills should run this step only when they need configuration values they don't already have. If a value (for example, agent root, environment, project endpoint, or agent name) is already known from the user's message or a previous skill in the same session, skip resolution for that value.

Step 1: Discover Agent Roots and azd Context

First check whether the workspace has azure.yaml with services using host: azure.ai.agent.

One azd agent service -> classify it from kind, harness, modelType, and conversationEngine, then use that service's project folder or the azure.yaml directory as the agent root.
Multiple azd agent services -> check whether a Voice wrapper references a kind: hosted service via conversationEngine.name:
- Selecting the Hosted Voice wrapper implies its named kind: hosted target as an upstream dependency (uses: [<target>], conversationEngine.name: <target>); deploy and verification must report both services separately.
- Selecting the kind: hosted target alone scopes changes/debugging to the target container and does not automatically modify the wrapper.
- Otherwise -> require the user to choose the target service/folder.
No azd agent service -> search the workspace for .foundry/ folders that contain agent-metadata.yaml or agent-metadata.<env>.yaml.
- One match -> use that agent root.
- Multiple matches -> require the user to choose the target agent folder.
- No matches -> for insights, ask only for missing remote inputs without initializing local files; for create/deploy workflows, seed a new .foundry/ folder during setup; for other workflows, stop and ask the user which agent source folder to initialize.

After selecting an agent root, keep all local .foundry cache inspection, source inspection, evaluator suggestions, dataset suggestions, and prompt-optimization context inside that folder only. Do not scan sibling agent folders unless the user explicitly switches roots.

Step 2: Resolve Environment and Deployment Context

If azure.yaml is present, resolve the azd environment first:

Environment explicitly named by the user
AZURE_ENV_NAME from azd env get-values
azd default environment from .azure/config.json
Environment already selected earlier in the session

Run azd env get-values for the selected environment when project/deployment values are not already known. Prefer azd values for deployment context:

azd Variable	Resolves To
`AZURE_AI_PROJECT_ENDPOINT` or `AZURE_AIPROJECT_ENDPOINT`	Project endpoint
`AGENT_<SERVICE>_NAME`	Agent name for the selected azd service
`AGENT_<SERVICE>_VERSION`	Agent version for the selected azd service
`AZURE_CONTAINER_REGISTRY_NAME` or `AZURE_CONTAINER_REGISTRY_ENDPOINT`	ACR registry name / image URL prefix
`APPLICATIONINSIGHTS_CONNECTION_STRING`	App Insights connection string for trace workflows
`AZURE_SUBSCRIPTION_ID`, `AZURE_RESOURCE_GROUP`, `AZURE_AI_ACCOUNT_NAME`, `AZURE_AI_PROJECT_NAME`	Azure resource lookup and Playground links

When azd supplies these values, use them as the source of truth and do not copy them into .foundry/agent-metadata*.yaml on metadata writes.

Step 3: Select Metadata Overlay and Resolve Environment

Inside the selected agent root, choose the metadata file in this order:

Metadata filename or path explicitly provided by the user or workflow
If an explicit environment is already known and .foundry/agent-metadata.<env>.yaml exists, use that file
.foundry/agent-metadata.yaml
If multiple metadata files remain and no rule above selects one, prompt the user to choose

Read the selected metadata file and resolve any remaining environment choice in this order:

Environment explicitly named by the user
If the selected metadata file defines exactly one environment, use it
Environment already selected earlier in the session
defaultEnvironment from metadata

If the selected metadata file still contains multiple environments and none of the rules above selects one, prompt the user to choose. Keep the selected agent root, metadata file, environment, and whether context came from azd or metadata visible in every workflow summary.

If the selected environment exposes older testSuites[] metadata but not evaluationSuites[], treat testSuites[] as the source for this session and normalize each entry in memory to the evaluationSuites[] shape before continuing. If the metadata is older still and only exposes legacy testCases[], normalize that list the same way. Preserve dataset and evaluator fields, keep any existing tags, and map legacy priority to tags.tier only when tags.tier is missing: P0 -> smoke, P1 -> regression, P2 -> coverage.

Step 4: Resolve eval.yaml Local Evaluation Intent

If eval.yaml exists in the selected agent root, parse it before generating new suites:

agent.name -> target agent candidate; verify it matches the selected azd/metadata agent before using it.
dataset.local_uri -> local seed dataset candidate; legacy dataset_file may be normalized in memory.
dataset.name / dataset.version -> registered dataset candidate.
validation_dataset -> optional validation dataset candidate.
evaluators[] -> candidate Foundry evaluator names; verify with evaluator_catalog_get before treating them as remote evaluators.
name -> local eval/suite candidate; verify remotely before persisting as suiteName.
options.eval_model, options.optimization_model, options.max_candidates, options.optimization_config.model_search_space, options.pass_threshold, max_samples, trace_days, and generation_instruction -> setup defaults.

Treat eval.yaml as local evaluation intent, not proof that a Foundry suite exists. Persist synced suite/dataset/evaluator references to .foundry only after remote lookup or registration succeeds.

Step 5: Resolve Common Configuration

Layer sources in this order:

Explicit user input and values already selected in the session
azd environment values for deployment context
.foundry/agent-metadata*.yaml overlay values and remote suite/cache references
azure.yaml and eval.yaml local source configuration
User prompts for anything still missing

If azd and metadata both provide the same value and they differ, stop and ask which source is authoritative. If they match, use the azd value and avoid rewriting the duplicate on future metadata writes.

Effective Value	Preferred Source	Used By
Project endpoint	azd env	deploy, invoke, observe, trace, troubleshoot
Agent name/version	azd agent variables, then `azure.yaml`	invoke, observe, trace, troubleshoot
ACR	azd env	deploy
Evaluation suites and cache paths	`.foundry/agent-metadata*.yaml`	observe, eval-datasets
Local seed dataset/evaluator intent	`eval.yaml`	observe, eval-datasets

Step 6: Write Metadata Overlay (Create/Deploy/Observe Only)

On any metadata write (deploy, auto-setup, dataset refresh, or trace-to-dataset update), persist only non-derivable overlay/cache state in the 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:

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.
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.
kind: prompt plus harness.type: microsoft_copilot_preview or legacy github_copilot_preview -> Managed Harness Agent.
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

Azure Authentication Best Practices

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.

Files

foundry-agent/validate/references/default-rules.yaml

version: 1.3.0
scope: Repository review rules, not certification controls.

rules:
- id: TOOL-001
title: Configure and access MCP through Foundry Toolbox
level: recommendation
rationale: Foundry Toolbox centralizes MCP configuration, authentication, credential handling, and policy enforcement while allowing tools to be updated without changing hosted-agent code.
guidance:
- title: "Agent Framework Foundry Toolbox sample"
link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox"
- title: "LangGraph Foundry Toolbox sample"
link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/langgraph/responses/02-langgraph-toolbox"
when: Apply when the hosted agent uses an MCP server; otherwise skip.
checks: >-
Inspect deployed code and configuration to determine whether every MCP connection uses Foundry Toolbox instead of the original MCP server. Evidence can include a local azure.ai.toolbox service, a Foundry Toolbox URL such as /toolboxes/{name}/mcp or /toolboxes/{name}/versions/{version}/mcp, a TOOLBOX-named environment variable connected to the MCP path, or a supported Toolbox SDK or constructor. These examples are not exhaustive; accept any clear repository evidence of Toolbox use.
statusCriteria:
pass: Every deployed MCP connection clearly uses Foundry Toolbox.
fail: A deployed MCP connection clearly accesses an original MCP server directly or configures it outside Toolbox.
inconclusive: MCP use is evident, but repository evidence cannot determine whether every connection uses Toolbox.

- id: AIGW-001
title: Use AI Gateway for required rate limits
level: recommendation
rationale: Azure API Management AI Gateway can enforce model token or request limits and tool-call limits before traffic reaches backends.
guidance:
- title: "APIM hosted-agent solution template"
link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/tree/main/apim-hosted-agent"
when: Apply when repository requirements or configuration specify a model token or request limit or a tool-call rate limit; otherwise skip.
checks: >-
1) Establish a model token, model request, or tool-call rate-limit requirement from repository requirements, configuration, or infrastructure; do not infer one from generic retry or 429 handling. 2) For each affected model or tool call path, trace its runtime endpoint through code, configuration, environment variables, and fallbacks. 3) Verify the endpoint belongs to Azure API Management through an azure-api.net hostname, a linked APIM resource, or infrastructure that maps its custom domain to APIM. Local APIM rate-limit policies are supporting evidence, not required evidence, because policies may be managed externally.
statusCriteria:
pass: Every required rate-limited path is resolved and uses an APIM AI Gateway endpoint.
fail: A fully resolved path with a rate-limit requirement calls its model or tool backend directly.
inconclusive: A rate-limit requirement exists, but the call endpoint or its APIM identity cannot be resolved.

- id: OBS-001
title: Enable supported tracing for hosted agents
level: recommendation
rationale: >-
Tracing connects agent, model and tool operations to an inspectable telemetry destination.
guidance:
- title: "Configure hosted-agent telemetry"
link: "https://learn.microsoft.com/azure/foundry/agents/how-to/configure-hosted-agent-telemetry"
- title: "Set up tracing for agents"
link: "https://learn.microsoft.com/azure/foundry/observability/how-to/trace-agent-setup"
when: Apply to every hosted agent configured with host azure.ai.agent.
checks: >-
Read selected service telemetry settings and linked project monitoring. Look for APPLICATIONINSIGHTS_CONNECTION_STRING, OTEL_EXPORTER_OTLP_ENDPOINT or signal-specific OTLP endpoints and their hosting/instrumentation consumer. Inspect matching blocks and directly referenced initialization only. Accept supported automatic hosting or project tracing; do not require explicit instrumentation. An unused setting or library alone is insufficient. If export configuration is external or absent here, stop with inconclusive.
statusCriteria:
pass: A supported tracing path and its export destination are established without contradictory settings.
fail: Active configuration explicitly disables all applicable tracing/export or contradicts its claimed tracing setup.
inconclusive: The supported tracing path or export destination cannot be established locally.

- id: SDK-001
title: Use consistent Microsoft Agent Framework dependencies
level: recommendation
rationale: >-
Consistent Agent Framework declarations and imports prevent avoidable dependency mismatches; other supported frameworks remain valid.
guidance:
- title: "Microsoft Agent Framework SDK overview"
link: "https://learn.microsoft.com/azure/foundry/how-to/develop/sdk-overview#agent-framework"
- title: "Choose a hosted-agent framework"
link: "https://learn.microsoft.com/azure/foundry/agents/quickstarts/quickstart-deploy-own-code#choose-your-framework"
when: Apply only when the hosted agent declares or imports Microsoft Agent Framework; otherwise skip this rule.
checks: >-
Read Agent Framework entries in the selected service's dependency manifests, matching lock/central version declarations and entry-point imports. Exact direct pins establish versions without a lock file. Compare the same package across files, not version numbers of different packages. Record literal package/version evidence. Follow direct local version references only; stop on unresolved ranges or generated declarations. Do not inspect installed packages, whole lock files or SDK internals, require latest versions, or infer API compatibility.
statusCriteria:
pass: Official package-family declarations have determinable direct versions and consistent imports.
fail: An unrelated package is presented as Agent Framework, the same dependency has conflicting effective versions, or source imports contradict the declared family.
inconclusive: Version resolution or import-to-package mapping remains unresolved.

- id: SDK-002
title: Use recommended Foundry hosted-agent SDKs
level: recommendation
rationale: Approved Foundry hosting packages reduce custom protocol code.
guidance:
- title: "Python hosted-agent framework samples"
link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents"
- title: ".NET hosted-agent framework samples"
link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/csharp/hosted-agents"
- title: "Python LangGraph hosting samples"
link: "https://github.com/microsoft-foundry/foundry-samples/tree/main/samples/python/hosted-agents/langgraph"
when: Apply to every hosted agent configured with host azure.ai.agent.
checks: >-
Inspect deployed dependency manifests and lock files only. Require at least one approved hosting dependency: Python agent-framework-foundry-hosting, langchain-azure-ai[hosting] (or resolved lock equivalent), or azure-ai-agentserver-invocations; C# Microsoft.Agents.AI.Foundry.Hosting or Azure.AI.AgentServer.Invocations. Generic web framework dependencies alone do not qualify. Do not inspect source code or protocol wiring.
statusCriteria:
pass: An approved hosting dependency is resolved and no unapproved agent or hosting SDK is declared.
fail: No approved hosting dependency is declared, or dependencies include Python openai-agents or another unapproved agent or hosting SDK.
inconclusive: Dependency files cannot be resolved enough to classify.

- id: AGT-001
title: Do not instruct agents to bypass controls or fabricate success
level: warning
rationale: Operative agent instructions must not authorize fabricated outcomes, unrestricted consequential actions, or bypasses of runtime controls and required approvals.
guidance:
- title: "Tool best practices for agents"
link: "https://learn.microsoft.com/azure/foundry/agents/concepts/tool-best-practice"
- title: "Responsible AI transparency note for agents"
link: "https://learn.microsoft.com/azure/foundry/responsible-ai/agents/transparency-note"
when: Apply when the repository stores or references instructions that govern the hosted agent at runtime; otherwise skip this rule.
checks: >-
Read instructions/system-prompt arguments from the selected entry point or configuration and directly referenced local prompt definitions. Locate named symbols rather than reading all Markdown. Flag explicit fabrication, representing failure as success, bypassing controls/approvals, or unrestricted consequential action. Exclude bounded automation, retries, documentation, tests and quoted counterexamples. Stop with inconclusive for unresolved remote/dynamic operative prompts; missing recommended wording alone is not a failure.
statusCriteria:
pass: Operative instructions do not require or permit fabrication, control or approval bypass, treating failure as success, or unrestricted consequential action.
fail: Operative instructions explicitly require or permit at least one of those behaviors.
inconclusive: Potentially unsafe wording is ambiguous, or repository evidence cannot establish whether the identified instructions are operative.

- id: AUTH-001
title: Use Microsoft Entra authentication for Azure AI Search
level: recommendation
rationale: Microsoft Entra authentication avoids distributing Search API keys and supports identity-based access control for hosted-agent retrieval.
guidance:
- title: "Azure AI Search role-based access control"
link: "https://learn.microsoft.com/azure/search/search-security-rbac"
- title: "Enterprise knowledge-agent connection configuration"
link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/blob/main/enterprise-knowledge-agent/scripts/provision.py"
when: >-
Apply to an established runtime Azure AI Search client or linked Search tool/connection. Skip inactive examples and generic APIs without Search evidence; unresolved relevant references are inconclusive.
checks: >-
Inspect actual Search client credential arguments, directly referenced credential factories, or linked Search connection auth types. A manifest hook creating the runtime connection is valid evidence: locate the referenced connection name or variable and its auth-type/authenticationType declaration, including agentic-identity or managed identity. Entra token credentials and Entra-based connections qualify; AzureKeyCredential, api-key headers or API-key connections fail even when keys come from Key Vault. Search environment names are locators only. Toolbox authentication alone and credentials used solely to run provisioning do not prove runtime Search auth. Stop at unavailable downstream auth configuration; do not inspect indexes, secrets or proxy internals.
statusCriteria:
pass: Every established Search runtime path uses Entra with no key fallback.
fail: Any established Search runtime path uses a key or active key fallback, even if other paths are unresolved.
inconclusive: No key violation is proven, but relevant runtime Search authentication remains unresolved.

- id: IMG-001
title: Pin prebuilt hosted-agent images by digest
level: recommendation
rationale: An immutable image digest makes hosted-agent deployments reproducible and prevents a mutable tag from silently selecting different image contents.
guidance:
- title: "Azure Container Registry image tagging and versioning"
link: "https://learn.microsoft.com/azure/container-registry/container-registry-image-tag-version"
- title: "Private-network hosted-agent existing ACR scenario"
link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/tree/main/private-network-hosted-agent/scenarios/existing-private-acr"
when: >-
Apply when the selected service consumes a prebuilt image. Skip source/remote-build services without an image and Dockerfile base images; unresolved deployment mode is inconclusive.
checks: >-
Start with the selected service image field. A final @sha256:<64 hexadecimal characters> reference passes; a final tag-only reference fails. Resolve directly referenced local variables. Follow a pipeline only if selected by the caller or explicitly linked by active configuration. Accept digest resolution or a gate that validates and deploys the same value; possible manual bypass is outside that scoped result. State the entry point. Unresolved values/transformations are inconclusive; do not search unrelated CI or treat standalone validators as enforced gates.
statusCriteria:
pass: The submitted image is digest-pinned or the selected entry point enforces pinning of that same value.
fail: The selected resolved deployment submits a tag-only or implicit-latest image.
inconclusive: Deployment mode, final image or selected pipeline pinning cannot be resolved.

- id: NET-001
title: Preserve private-only access in repository-managed recovery
level: warning
rationale: Automatically opening public access or sending private workload data to a public fallback during recovery defeats an explicitly configured private-only access boundary.
guidance:
- title: "Foundry hosted-agent virtual networks"
link: "https://learn.microsoft.com/azure/foundry/agents/how-to/virtual-networks"
- title: "Private-network hosted-agent security boundaries"
link: "https://github.com/microsoft/Foundry-Agent-Solution-Templates/blob/main/private-network-hosted-agent/docs/security.md"
when: >-
Apply when linked active resource configuration or an explicit resource contract establishes private-only access. Skip permitted public access, including deployments with optional Private Endpoints. Names alone are insufficient; unresolved boundaries are inconclusive.
checks: >-
Locate publicNetworkAccess=Disabled, public_network_access_enabled=false or the explicit private-only contract. Inspect selected deployment hooks and resource-call error handlers plus directly called local recovery helpers; locate matching blocks, not whole libraries. Fail only for reachable recovery that opens the same resource publicly or sends its protected data to a public alternative. Same-endpoint retries, VPN, identity/control-plane access and documented platform exceptions are allowed. Hostnames alone do not prove routing. Stop on unresolved helpers. State inspected executable paths and excluded external image internals; this is not live network assurance.
statusCriteria:
pass: At least one associated executable local runtime/deployment path is resolved and all inspected paths preserve the boundary or stop. IaC/manifest settings alone cannot establish pass; state coverage and exclusions.
fail: A reachable recovery action opens the private resource publicly or redirects its protected data to a public alternative; proven violations take precedence.
inconclusive: No violation is proven, but the boundary or an invoked recovery helper is unresolved, or no associated executable local path is inspectable.

- id: CFG-001
title: Do not override platform-managed runtime configuration
level: warning
rationale: >-
Overriding platform-injected FOUNDRY_* or AGENT_* runtime variables can break hosted-agent behavior.
guidance:
- title: "Review platform environment variables"
link: "https://learn.microsoft.com/azure/foundry/agents/how-to/configure-hosted-agent-env-variables#review-platform-environment-variables"
when: Apply when hosted-agent runtime or deployment configuration is present.
checks: >-
Check selected service environmentVariables, linked container ENV, and entry-point/startup environment assignments for FOUNDRY_* or AGENT_*, including deprecated FOUNDRY_TOOLBOX_ENDPOINT. Follow direct assignment sources only. Reads, platform outputs and deployment-tool values do not violate this rule unless assigned into the hosted process. Exclude local-only development settings. Unresolved injection or precedence is inconclusive; do not search unrelated scripts.
statusCriteria:
pass: Inspected deployed runtime configuration does not assign reserved variables.
fail: Repository configuration assigns a reserved FOUNDRY_* or AGENT_* variable into the hosted runtime.
inconclusive: Runtime injection or configuration precedence cannot be resolved.

- id: PROTO-001
title: Keep declared protocols consistent with runtime handlers
level: warning
rationale: >-
Declared hosted-agent protocols must match the deployed handlers.
guidance:
- title: "Hosted-agent protocol endpoints"
link: "https://learn.microsoft.com/azure/foundry/agents/concepts/hosted-agent-contract#protocol-endpoints"
- title: "Add a protocol adapter"
link: "https://learn.microsoft.com/azure/foundry/agents/how-to/add-protocol-adapter"
when: Apply when the hosted-agent service declares the Responses or Invocations protocol in azure.yaml; otherwise skip this rule.
checks: >-
Compare selected service protocols[].protocol with its entry point and directly referenced registrations. Examples: responses uses ResponsesHostServer, ResponsesAgentServerHost or POST /responses; invocations uses InvocationsHostServer, InvocationAgentServerHost or POST /invocations. Accept equivalent official wiring and valid custom handlers, not just these names. An official host wired to an agent/handler suffices without inspecting SDK internals. Fully resolved mismatches fail; unresolved or dynamic registration is inconclusive. Do not run the server.
statusCriteria:
pass: Every declared Responses/Invocations protocol maps to a statically identifiable host and handler.
fail: A resolved entry point maps a declared protocol incorrectly or its complete static registrations omit the endpoint.
inconclusive: Entry point, adapter or handler registration cannot be resolved.

Requirements and compatibility

Written for: Claude Code

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Names Claude Code tools, Needs a command-line tool, Needs Python

Security

What our scanner noticed· Low risk

Phrasing that asks for actions without confirmation
Instructions that use the network
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Microsoft

Publisher

Microsoft (Official)

Source

microsoft/skills · .github/plugins/azure-skills/skills/microsoft-foundry · commit 0696600

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from .github/plugins/azure-skills/LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

Also distributed in

microsoft/azure-skills

AutoGineer is not affiliated with or endorsed by Microsoft or Microsoft.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download microsoft-foundry.zip