1---
2name: microsoft-foundry
3description: "Deploy, evaluate, and manage Foundry agents end-to-end: Docker build, ACR push, hosted/prompt agent create, container start, batch eval, continuous eval, prompt optimizer workflows, agent.yaml, dataset curation from traces. USE FOR: deploy agent to Foundry, hosted agent, create agent, invoke agent, evaluate agent, run batch eval, continuous eval, continuous monitoring, continuous eval status, optimize prompt, improve prompt, prompt optimizer, optimize agent instructions, improve agent instructions, optimize system prompt, deploy model, Foundry project, RBAC, role assignment, permissions, quota, capacity, region, troubleshoot agent, deployment failure, create dataset from traces, dataset versioning, eval trending, create AI Services, Cognitive Services, create Foundry resource, provision resource, knowledge index, agent monitoring, customize deployment, onboard, availability. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare)."
4license: MIT
5metadata:
6  author: Microsoft
7  version: "0.0.0-placeholder"
8---
9 
10# Microsoft Foundry Skill
11 
12This skill helps developers work with Microsoft Foundry resources, covering model discovery and deployment, complete dev lifecycle of AI agent, evaluation workflows, and troubleshooting.
13 
14## Pre-Execution Requirements
15 
16> **MANDATORY: Before executing ANY workflow, you MUST first call the Azure MCP `foundry` tool and inspect the available Foundry MCP tools and related parameters.** Treat this initial `foundry` call as a discovery/help step. For this skill, Azure MCP `foundry` is the required entry point for Foundry-related MCP operations.
17 
18## Sub-Skills
19 
20> **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.
21 
22This skill includes specialized sub-skills for specific workflows. **Use these instead of the main skill when they match your task:**
23 
24| Sub-Skill | When to Use | Reference |
25|-----------|-------------|-----------|
26| **deploy** | Containerize, build, push to ACR, create/update/clone agent deployments | [deploy](foundry-agent/deploy/deploy.md) |
27| **invoke** | Send messages to an agent, single or multi-turn conversations | [invoke](foundry-agent/invoke/invoke.md) |
28| **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](foundry-agent/observe/observe.md) |
29| **trace** | Query traces, analyze latency/failures, correlate eval results to specific responses via App Insights `customEvents` | [trace](foundry-agent/trace/trace.md) |
30| **troubleshoot** | View hosted agent logs, query telemetry, diagnose failures | [troubleshoot](foundry-agent/troubleshoot/troubleshoot.md) |
31| **create** | Create new hosted agent applications. Supports Microsoft Agent Framework, LangGraph, or custom frameworks in Python or C#, across `responses` or `invocations` protocols. | [create](foundry-agent/create/create.md) |
32| **faos-optimize** | Convert existing Python agent code to a FAOS (Foundry Agent Optimization Service) optimization-ready version by wiring evaluator-targeted instructions/model/temperature knobs, then stop for review before deployment. | [faos-optimize](foundry-agent/faos-optimize/faos-optimize.md) |
33| **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](foundry-agent/eval-datasets/eval-datasets.md) |
34| **project/create** | Creating a new Azure AI Foundry project for hosting agents and models. Use when onboarding to Foundry or setting up new infrastructure. | [project/create/create-foundry-project.md](project/create/create-foundry-project.md) |
35| **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](resource/create/create-foundry-resource.md) |
36| **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](resource/private-network/private-network.md) |
37| **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](models/deploy-model/SKILL.md) |
38| **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](quota/quota.md) |
39| **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](rbac/rbac.md) |
40 
41> 💡 **Tip:** For a complete onboarding flow: `project/create` (public) or `private-network` (VNet isolation) → `models/deploy-model` → agent workflows (`create` → `deploy` → `invoke`).
42 
43> 💡 **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.
44 
45> 💡 **Prompt Optimization:** For requests like "optimize my prompt" or "improve my agent instructions," load [observe](foundry-agent/observe/observe.md) and use the `prompt_optimize` MCP tool through that eval-driven workflow.
46 
47## Infrastructure Lifecycle
48 
49Match user intent to the correct infrastructure workflow.
50 
51| User Intent | Workflow |
52|-------------|---------|
53| "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](resource/create/create-foundry-resource.md), (b) → [project/create](project/create/create-foundry-project.md), (c) → [private-network](resource/private-network/private-network.md) |
54| Set up Foundry with VNet isolation | [private-network](resource/private-network/private-network.md) |
55| Create a Foundry project (public) | [project/create](project/create/create-foundry-project.md) |
56| Create a bare Foundry resource | [resource/create](resource/create/create-foundry-resource.md) |
57 
58## Agent Development Lifecycle
59 
60Match user intent to the correct agent workflow. Read each sub-skill in order before executing.
61 
62| User Intent | Workflow (read in order) |
63|-------------|------------------------|
64| Create a new agent from scratch | [create](foundry-agent/create/create.md) → [deploy](foundry-agent/deploy/deploy.md) → [invoke](foundry-agent/invoke/invoke.md) |
65| Make existing Python agent FAOS optimizable | [faos-optimize](foundry-agent/faos-optimize/faos-optimize.md) → review → deploy → invoke |
66| Deploy an agent (code already exists) | deploy → invoke |
67| Update/redeploy an agent after code changes | deploy → invoke |
68| Invoke/test/chat with an agent | invoke |
69| Optimize / improve agent prompt or instructions | observe (Step 4: Optimize) |
70| Evaluate and optimize agent (full loop) | observe |
71| Enable continuous evaluation monitoring | observe (Step 6: CI/CD & Monitoring) |
72| Troubleshoot an agent issue | invoke → troubleshoot |
73| Fix a broken agent (troubleshoot + redeploy) | invoke → troubleshoot → apply fixes → deploy → invoke |
74 
75## Agent: .foundry Workspace Standard
76 
77Every agent source folder should keep Foundry-specific state under `.foundry/`:
78 
79```text
80<agent-root>/
81  .foundry/
82    agent-metadata.yaml
83    agent-metadata.prod.yaml
84    datasets/
85    evaluators/
86    results/
87```
88 
89- `agent-metadata.yaml` is the preferred local/dev metadata file. Optional sidecar files such as `agent-metadata.prod.yaml` can hold a single prod or CI-targeted environment without mixing multiple environments in one file.
90- `datasets/` and `evaluators/` are local cache folders. Reuse them when they are current, and ask before refreshing or overwriting them.
91- See [Agent Metadata Contract](references/agent-metadata-contract.md) for the canonical schema and workflow rules.
92 
93## Agent: Setup References
94 
95- [Standard Agent Setup](references/standard-agent-setup.md) - Standard capability-host setup with customer-managed data, search, and AI Services resources.
96 
97## Agent: Project Context Resolution
98 
99Agent 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.
100 
101### Step 1: Discover Agent Roots
102 
103Search the workspace for `.foundry/` folders that contain `agent-metadata.yaml` or `agent-metadata.<env>.yaml`.
104 
105- **One match** → use that agent root.
106- **Multiple matches** → require the user to choose the target agent folder.
107- **No matches** → for create/deploy workflows, seed a new `.foundry/` folder during setup; for all other workflows, stop and ask the user which agent source folder to initialize.
108 
109After 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.
110 
111### Step 2: Select Metadata File and Resolve Environment
112 
113Inside the selected agent root, choose the metadata file in this order:
1141. Metadata filename or path explicitly provided by the user or workflow
1152. If an explicit environment is already known and `.foundry/agent-metadata.<env>.yaml` exists, use that file
1163. `.foundry/agent-metadata.yaml`
1174. If multiple metadata files remain and no rule above selects one, prompt the user to choose
118 
119Read the selected metadata file and resolve the environment in this order:
1201. Environment explicitly named by the user
1212. If the selected metadata file defines exactly one environment, use it
1223. Environment already selected earlier in the session
1234. `defaultEnvironment` from metadata
124 
125If 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, and environment visible in every workflow summary.
126 
127If 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`.
128 
129### Step 3: Resolve Common Configuration
130 
131Use the selected environment in the selected metadata file as the primary source:
132 
133| Metadata Field | Resolves To | Used By |
134|----------------|-------------|---------|
135| `environments.<env>.projectEndpoint` | Project endpoint | deploy, invoke, observe, trace, troubleshoot |
136| `environments.<env>.agentName` | Agent name | invoke, observe, trace, troubleshoot |
137| `environments.<env>.azureContainerRegistry` | ACR registry name / image URL prefix | deploy |
138| `environments.<env>.evaluationSuites[]` | Dataset + evaluator + tag bundles | observe, eval-datasets |
139 
140### Step 4: Bootstrap Missing Metadata (Create/Deploy Only)
141 
142If create/deploy is initializing a new `.foundry` workspace and metadata fields are still missing, check if `azure.yaml` exists in the project root. If found, run `azd env get-values` and use it to seed `agent-metadata.yaml` by default, or `agent-metadata.<env>.yaml` when the workflow explicitly targets a separate environment-specific file.
143 
144On any metadata write (deploy, auto-setup, dataset refresh, or trace-to-dataset update), persist only `evaluationSuites[]` in the selected metadata file. 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.
145 
146| azd Variable | Seeds |
147|-------------|-------|
148| `AZURE_AI_PROJECT_ENDPOINT` or `AZURE_AIPROJECT_ENDPOINT` | `environments.<env>.projectEndpoint` |
149| `AZURE_CONTAINER_REGISTRY_NAME` or `AZURE_CONTAINER_REGISTRY_ENDPOINT` | `environments.<env>.azureContainerRegistry` |
150| `AZURE_SUBSCRIPTION_ID` | Azure subscription for trace/troubleshoot lookups |
151 
152### Step 5: Collect Missing Values
153 
154Use 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:
155- **Agent root** — Target folder containing `.foundry/agent-metadata*.yaml`
156- **Metadata file** — `agent-metadata.yaml` for local/dev, or an explicit sidecar such as `agent-metadata.prod.yaml`
157- **Environment** — `dev`, `prod`, or another environment key from metadata
158- **Project endpoint** — AI Foundry project endpoint URL
159- **Agent name** — Name of the target agent
160 
161> 💡 **Tip:** If the user already provides the agent path, environment, project endpoint, or agent name, extract it directly — do not ask again.
162 
163## Agent: Agent Types
164 
165All agent skills support two agent types:
166 
167| Type | Kind | Description |
168|------|------|-------------|
169| **Prompt** | `"prompt"` | LLM-based agents backed by a model deployment |
170| **Hosted** | `"hosted"` | Container-based agents running custom code |
171 
172Use `agent_get` MCP tool to determine an agent's type when needed.
173 
174## Tool Usage Conventions
175 
176- Use the `ask_user` or `askQuestions` tool whenever collecting information from the user
177- Use the `task` or `runSubagent` tool to delegate long-running or independent sub-tasks (e.g., env var scanning, status polling, Dockerfile generation)
178- Prefer Azure MCP tools over direct CLI commands when available
179- Reference official Microsoft documentation URLs instead of embedding CLI command syntax
180 
181## Additional Resources
182 
183- [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
184- [Foundry Agent Runtime Components](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/runtime-components?view=foundry)
185 
186## SDK Quick Reference
187 
188- [Python](references/sdk/foundry-sdk-py.md)
189