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 create, create agent, update agent, add tool to agent, invoke agent, agent.yaml, evaluate agent, batch eval, continuous eval, continuous monitoring, agent CI/CD, optimize prompt, improve prompt, prompt optimizer, optimize agent instructions, Agent Optimizer scaffold, 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).

Installation

Summary

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.

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 hosted agents that speak the `invocations_ws` duplex WebSocket protocol — voice agents, real-time streams, and signaling for out-of-band media transports.	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
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
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

"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

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

`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

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

microsoft-foundry

Microsoft Foundry Skill

Pre-Execution Requirements

Dependency Check and Setup

Workflow Guidance

Foundry MCP

azd

Sub-Skills

Infrastructure Lifecycle

Agent Development Lifecycle

Agent: .foundry Workspace Standard

Agent: Setup References

Agent: Common Project Context Resolution

Step 1: Discover Agent Roots and azd Context

Step 2: Resolve Environment and Deployment Context

Step 3: Select Metadata Overlay and Resolve Environment

Step 4: Resolve eval.yaml Local Evaluation Intent

Step 5: Resolve Common Configuration

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

Step 7: Collect Missing Values

Agent: Agent Types

Tool Usage Conventions

Azure Authentication

Additional Resources

Network Isolation Errors